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，再把旧入口降级为带迁移信号的兼容层，最后通过测试和调用方收敛来决定删除时机。