feat: polish generation demo workflow

docs/technical/api-compatibility.md

@@ -0,0 +1,48 @@
+# API 兼容层策略
+
+这份文档用于说明 DreamWeaver 求职版如何处理旧生成接口。目标不是立刻删除所有旧 API，而是把主线收敛到统一生成工作流，并让历史入口变成可迁移、可监控、可解释的兼容层。
+
+## 背景
+
+项目早期分别提供过普通故事、完整故事、绘本、封面生成和资产重试接口：
+
+- `POST /api/stories/generate`
+- `POST /api/stories/generate/full`
+- `POST /api/storybook/generate`
+- `POST /api/image/generate/{story_id}`
+- `POST /api/stories/{story_id}/assets/retry`
+
+这些接口都能工作，但对前端和面试讲解不够友好：故事、绘本和资产补全看起来像多条产品链路，容易掩盖真正的核心能力。
+
+## 目标入口
+
+求职版主入口统一为：
+
+- `POST /api/generations`
+- `GET /api/generations/{story_id}`
+- `POST /api/generations/{story_id}/retry-assets`
+
+前端创建弹窗、绘本阅读器、故事详情页的资产重试应优先使用这些入口。
+
+## 当前策略
+
+1. 保留旧接口，避免破坏已有测试和潜在调用方。
+2. 旧接口内部继续复用同一套 service workflow，不复制业务逻辑。
+3. 旧接口响应增加迁移提示 header：
+   - `Deprecation: true`
+   - `X-DreamWeaver-Successor-Endpoint: <target>`
+   - `Link: <target>; rel="successor-version"`
+4. 新前端不再新增对旧生成接口的依赖。
+
+## 删除条件
+
+旧接口可以在同时满足以下条件后删除：
+
+- 用户端和管理端都已切到 `/api/generations`。
+- smoke 脚本只依赖统一入口。
+- 后端测试覆盖统一入口的故事、绘本、资产重试和失败降级。
+- 至少一个迭代周期没有发现旧接口新增调用。
+
+## 面试表达
+
+我不会为了“代码看起来干净”直接删掉旧接口，因为这会引入不可见风险。更稳妥的做法是先定义目标 API，再把旧入口降级为带迁移信号的兼容层，最后通过测试和调用方收敛来决定删除时机。

docs/technical/generation-job-state.md

@@ -0,0 +1,43 @@
+# Generation Job 状态落库决策
+
+这份文档用于回答一个关键技术债问题：DreamWeaver 是否需要为每次 AI 生成单独建立 `generation_jobs` 表。
+
+## 当前结论
+
+短期不新增 `generation_jobs` 表，继续把求职版状态落在 `stories` 主记录上。
+
+原因是当前 MVP 的生成方式仍然以同步请求为主：后端在一次请求中完成主内容保存，再补全封面、绘本插图或语音。用户最关心的是“这个故事现在能不能读、哪些资产可补全”，而不是一个独立 job 的生命周期。
+
+## 现有状态模型
+
+当前 `stories` 表已承载演示所需状态：
+
+- `generation_status`: 主流程状态，例如 `narrative_ready`、`assets_generating`、`completed`、`degraded_completed`、`failed`
+- `image_status`: 封面或绘本插图状态
+- `audio_status`: 语音状态
+- `last_error`: 最近一次资产失败原因
+
+这些字段足够支撑前端展示、smoke 检查、失败降级和资产重试。
+
+## 什么时候需要落库 job
+
+如果后续进入真实生产化，需要重新评估 `generation_jobs`：
+
+- 生成流程改成真正异步，前端需要轮询 job 进度。
+- 单个故事会产生多次生成尝试，需要审计每次 provider 调用。
+- 需要展示更细颗粒度步骤，例如 prompt 构建、文本生成、封面生成、每页插图、TTS。
+- 需要按 provider、成本、延迟和失败原因做运营分析。
+- 需要断点续跑，避免 Worker 重启后丢失中间状态。
+
+## 推荐未来结构
+
+未来可以新增两层记录：
+
+- `generation_jobs`: 一次用户发起的生成任务，记录输入、状态、耗时、错误和关联 story。
+- `generation_job_events`: 任务事件流，记录每一步开始、成功、失败、provider、耗时和错误摘要。
+
+这会把“用户可见结果”和“系统执行过程”分开，但目前还不是求职版的最高优先级。
+
+## 面试表达
+
+我现在没有急着加 job 表，是因为 MVP 首要目标是让故事结果稳定可读，并让资产失败可恢复。等生成链路变成真正异步、需要审计和运营指标时，再把执行过程拆到 job/event 表，会比现在提前设计复杂表结构更稳。