diff --git a/.spec/specs/2026-10-25_add-terminal-books-admin/spec.md b/.spec/specs/2026-10-25_add-terminal-books-admin/spec.md new file mode 100644 index 0000000..9fbe405 --- /dev/null +++ b/.spec/specs/2026-10-25_add-terminal-books-admin/spec.md @@ -0,0 +1,71 @@ +# Phase 5b:/terminal 彩蛋 + /books 书评画廊 + Sveltia 管理台试水 - 项目范围 + + + +## 1. 问题定义 +- **项目目标**:三个预研方案落地——终端彩蛋(极客人格记忆点)、书评索引画廊(阅读轨策展面)、Sveltia 管理台(照片上传/编辑体验升级试水) +- **目标用户**:站长(写作/管理体验)与读者(浏览乐趣) +- **核心价值**:二期池前三项交付;Sveltia 试水失败可全身而退 + +## 2. 假设与待确认 + +### 2.1 已确认事实 +- 三方案预研完成(op-artalk A+B / op-gitea Sveltia,含坑清单与工作量) +- Sveltia 机制全对上:整文件 JSON=sidecar 同构、media_folder '' 裸文件名、token 登录、保存即 commit→webhook 自动构建 +- gitea CORS 未配是唯一硬前置 + +### 2.2 关键假设 +- Sveltia 内建图片优化保持关闭(开了会抹 EXIF 断构建期提取管线) +- 书评 description 由正文首段精炼可接受(用户后续可自行策展润色) + +### 2.3 待确认问题 +- [ ] Sveltia 试水体验是否合手 → 冒烟后用户/团队评估定去留 + +### 2.4 可选解释与取舍 +- /books 不进主导航(书评列表行内入口)> 导航加第五项 -> 防膨胀 +- 色脊排版卡 > 满色书封卡(mood 深浅不一跨亮暗风险)-> 色脊 + +### 2.5 已证伪路径 +- 无 + +## 3. 功能范围 + +### 3.1 核心功能(MVP) +- [ ] T1 /terminal 彩蛋页 +- [ ] T2 /books 书评画廊(zh/en) +- [ ] T3 Sveltia 管理台试水(含 gitea CORS) +- [ ] T4 验证收官 + +### 3.2 扩展功能 +- /books 进导航(若用户要求) + +### 3.3 不在范围内 +- moments PWA 上传端点、/stack·/colophon 页(后续池) + +## 4. 最小实现路径 +- 最简单可行方案:三车道并行按预研方案实施;Sveltia 试水不改现有任何流(只加不改) +- 暂不引入:终端插件化命令系统、书封真实图片扫描 +- 不做的抽象/配置化:多管理后端适配 + +## 5. 技术决策 +- 技术栈:预研方案原样(vanilla TS 终端 / 色脊卡静态页 / Sveltia 官方集成) +- 证据协议:evidence: runs +- 本轮允许改动:src/pages/、src/content.config.ts、content/posts/(五篇补字段)、public/admin/、infra/gitea/README、gitea 运行时 [cors] +- 本轮不应触碰:content/photos 既有 sidecar 结构、发布链、生产 nginx +- Git integration branch:`spec/2026-10-25_add-terminal-books-admin` + +### 5.1 验证策略 +- 范围级别:package +- 变更对象:两个新页面、posts schema 扩展、admin 静态目录、gitea 运行时 +- 快速检查:`pnpm astro build` +- 集成检查:terminal/books 产物断言 + Sveltia 双冒烟走通 commit→webhook→build +- 全项目检查:E2E 30 项 + 新页视觉复核;仅在 gitea 运行时或发布链变更时升级范围 +- 升级触发:只有 Sveltia 冒烟引发 gitea 行为异常时,才升级验证范围并记录理由 + +## 6. 成功标准与验证方式 +- [ ] /terminal 可交互(help/ls/theme/sudo 彩蛋实跑) -> verify: task_0004 +- [ ] /books zh/en 五书呈现(色脊+mood) -> verify: task_0002 +- [ ] Sveltia 冒烟双通过(改+建全链) -> verify: task_0003 + +## 7. 风险与约束 +- gitea restart 窗口(秒级,公告无需);Sveltia 保存直连 main——已有 webhook 管线为安全网 diff --git a/.spec/specs/2026-10-25_add-terminal-books-admin/tasks.md b/.spec/specs/2026-10-25_add-terminal-books-admin/tasks.md new file mode 100644 index 0000000..df26eb9 --- /dev/null +++ b/.spec/specs/2026-10-25_add-terminal-books-admin/tasks.md @@ -0,0 +1,31 @@ +# Phase 5b:/terminal 彩蛋 + /books 书评画廊 + Sveltia 管理台试水 - 任务拆解 + +## 使用规则 +- boundary/verify 齐备;verify 只读断言;三车道并行(mesh_reserve 各自路径) + +## 阶段一:实现 + +- [ ] T1 /terminal 终端彩蛋页 + - claim: op-artalk(预研方案 A 已在案:命令注册表/真实 input/历史翻阅/Tab 补全/sudo 彩蛋/XSS=textContent 纪律/isComposing 守卫) + - boundary: 新建 src/pages/terminal.astro 单文件组件(--code-bg 恒深色例外区);不进主导航(? 帮助浮层加一行暗入口提示);零外部依赖 + - verify: `pnpm astro build && grep -q "terminal" dist/terminal/index.html` + +- [ ] T2 /books 书评画廊 + - claim: orchestrator(预研方案 B 在案:色脊排版卡/年份分组/规整网格) + - boundary: posts schema 加可选 description/book_author 两字段;新建 src/pages/books.astro(+en/books);五篇书评补字段(description 用正文首段精炼,book_author 按书实填);导航"文章"旁不加新项——/books 从书评列表行入口链接(防导航膨胀) + - verify: `pnpm astro build && test -f dist/books/index.html -a -f dist/en/books/index.html` + +- [ ] T3 Sveltia 管理台试水 + - claim: op-gitea(预研方案在案:CORS 前置/config.yml 草案/双冒烟/五坑清单) + - boundary: gitea app.ini 加 [cors] 段并重启(运行时操作,README 台账补记);public/admin/{index.html,config.yml,sveltia 本地 js};双冒烟(改旧 sidecar 补 alt / 新建条目传图走全链);不加站内链接(试水期) + - verify: `test -f public/admin/config.yml && docker exec gitea grep -q "cors" /data/gitea/conf/app.ini` + +- [ ] T4 验证收官 + - depends-on: task_0001, task_0002, task_0003 + - claim: orchestrator + - boundary: E2E 复跑 + terminal/books 截图视觉复核 + Sveltia 冒烟结论 + 归档推送 + - verify: `node tests/e2e.mjs 2>&1 | grep -q "30/30 PASS"` + +--- + +**当前进度**:由脚本计算,无需手动维护