dreamweaver/docs/planning/weekend-handoff-2026-04-17.md

DreamWeaver Weekend Handoff - 2026-04-17

Purpose

这份文档用于周末在另一台电脑上继续推进 DreamWeaver 时快速接手，不需要先重新阅读大量聊天记录或从工作区猜测上下文。

---

What Is Already On Remote

当前远端 main 已经包含两个连续 checkpoint：

• Commit: a97a2fe
• Message: feat: persist story generation states and cache audio

这个 checkpoint 覆盖的主线如下：

• 新增并落地统一生成状态字段：

  • generation_status
  • image_status
  • audio_status
  • last_error

• Storybook 阅读页支持按 ID 恢复

• 故事列表页、故事详情页、绘本阅读页接入统一状态展示

• 音频首次生成后缓存落盘并可复用

• 统一状态语义中 degraded_completed 已和错误展示保持一致

• Commit: b8d3cb4

• Message: wip: snapshot full local workspace state

这个 checkpoint 已把 2026-04-17 晚间的工作区快照同步到远端，包括：

• 新增 AGENTS.md
• 整理 docs/ 文档信息架构
• 新增求职版 PRD、统一生成工作流 PRD、Week 1 backlog 与文档盘点
• 归档旧 backend docs 到 docs/archive/、docs/technical/、docs/operations/
• 补齐 Storybook 带 ID 路由恢复相关前端改动

注意：b8d3cb4 是一次 WIP 快照提交，原始 diff 中包含大量行尾/格式噪音。继续开发时应以当前 main 代码与 docs/ 中 Active 文档为准，不需要再回到 a97a2fe 重新整理。

---

Current Local Status On 2026-04-18

2026-04-18 在个人电脑接手后已确认：

• 本地 main 与 origin/main 对齐到 b8d3cb4
• 工作树起始状态干净
• 已配置 Gitea HTTPS 推送凭据，并通过 git push --dry-run origin HEAD:main
• 后端本地虚拟环境可用：backend/.venv
• 主前端与管理端依赖已安装到各自 node_modules

---

Recommended Reading Order

周末继续前，建议先阅读：

1. docs/product/job-search-relaunch-prd.md
2. docs/product/unified-generation-workflow-prd.md
3. docs/planning/week-1-execution-backlog.md
4. docs/planning/document-status-inventory.md

---

Environment Setup On The Next Machine

建议接手后先完成以下动作：

1. git pull
2. cd backend && alembic upgrade head
3. cd backend && .venv/bin/python -m pytest -q（macOS/Linux）
4. cd frontend && npm install
5. cd frontend && ./node_modules/.bin/vue-tsc --noEmit

如果主前端完整构建失败，优先检查 Rollup 可选原生包是否正常安装，而不是先怀疑本轮代码逻辑。

---

Current Product / Engineering Position

当前阶段不是“继续加功能”，而是把 DreamWeaver 收敛成可讲述、可演示、可恢复的求职版产品。

已经完成的关键支点：

• 状态模型已落地，不再只是文档概念
• Storybook 恢复能力已补上
• 音频体验开始形成闭环

还没完成的关键工作：

• 普通故事、完整生成、绘本生成仍是多条 service 路径
• 缺少统一资产重试入口
• 缺少更清晰的统一 workflow 编排边界
• admin-frontend 范围和 Provider 边界仍未收束

---

Best Next Step

周末最值得继续做的第一优先级：

P0: 统一资产补全过程

目标：

• 抽出封面生成和音频生成的共同步骤
• 让图片 / 音频共享一套资产状态回写逻辑
• 为后续“统一重试入口”打基础

为什么先做：

• 它直接承接已经落地的状态模型
• 它比继续加页面更能体现系统设计能力
• 它能把当前三条生成路径往统一 workflow 再推近一步

P1: 统一重试入口

目标：

• 至少设计出一个清晰的 retry API 方向
• 即使不一次性重命名为 /api/generations/...，也先做到内部统一

P1: 收敛 service workflow

目标：

• 梳理普通故事 / 完整生成 / 绘本生成的共同步骤
• 把“验证上下文 -> 生成主内容 -> 保存主记录 -> 补全资产 -> 状态回写”整理成更明确的共享流程

---

Important Reminder

如果周末是在另一台电脑上继续，不要默认“今天下午所有本地修改”都已经上远端。当前最可靠的 source of truth 是：

• 远端代码：以 commit b8d3cb4 为准
• 产品目标：以 docs/product/job-search-relaunch-prd.md 为准
• 当前执行主线：以 docs/product/unified-generation-workflow-prd.md 与 docs/planning/week-1-execution-backlog.md 为准