feat: add generation trace and partial-ready workflow status

docs/product/unified-generation-workflow-prd.md

@@ -17,7 +17,7 @@ DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本
 
 ## Implementation Snapshot
 
-**Updated**: 2026-04-18 afternoon
+**Updated**: 2026-04-18 evening
 
 当前代码已经从“纯目标态设计”进入“部分落地”阶段，主要进展如下：
 
@@ -25,10 +25,12 @@ DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本
 
 - `Story` 主记录已持久化以下统一状态相关字段：
   - `generation_status`
+  - `text_status`
   - `image_status`
   - `audio_status`
   - `last_error`
   - `audio_path`
+- `partial_ready` 已在服务层、迁移、API schema、用户端与管理端状态展示中落地，用于表达“主内容可读，但仍有封面、插图或音频可补全”
 - 已新增轻量可查询的生成过程记录：
   - `generation_jobs`
   - `generation_job_events`
@@ -42,25 +44,39 @@ DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本
   - `POST /api/generations`
   - `GET /api/generations/{story_id}`
   - `POST /api/generations/{story_id}/retry-assets`
+  - `GET /api/generations/jobs/{job_id}`
+  - `GET /api/generations/{story_id}/jobs`
+  - `GET /api/generations/{story_id}/provider-stats`
 - 用户前端与 admin 前端创建弹窗已切换到 `POST /api/generations`
 - service 内部已开始收束统一工作流步骤：
   - 上下文准备：档案/宇宙校验 + memory context 构建
   - 主记录保存：文本故事与绘本统一持久化入口
   - 资产补全：普通故事封面、绘本缺失插图、故事音频缓存/生成统一封装
 - 已引入首版服务层 `AssetCompletionResult`，用于表达资产补全类型、状态、结果值、错误信息和是否阻塞主结果
+- `generation_job_events` 已从首版请求/完成事件扩展到关键 workflow 节点：
+  - `context_prepared`
+  - `narrative_generated`
+  - `story_saved`
+  - 普通故事封面开始/成功/失败
+  - 绘本封面与逐页插图成功/失败
+  - 音频缓存命中、生成开始、成功和失败
+- Provider failover 已记录到 job event，包含 capability、adapter、strategy、latency 和 estimated cost
+- Provider 调用已可按故事聚合为成功率、平均耗时、预估成本和 adapter 明细
+- generation job 响应已提供 `progress_percent`、`progress_label` 和 `is_terminal`，前端可直接用于进度条和轮询
+- `POST /api/generations` 响应已返回 `generation_job_id`，smoke 脚本会验证 job 查询与 story job history
+- 用户端与管理端的故事详情页、绘本阅读页已接入生成轨迹，展示生成/重试任务、关键事件、Provider 调用结果和聚合指标
 - 故事详情页封面补全已切换到统一资产重试入口
 - 管理端前端构建阻塞已修复，主前端与 admin 前端均可完成生产构建
 
-### Still Missing
+### Remaining Production Work
 
-- 普通故事、完整生成、绘本生成已有统一外部入口，内部 workflow 已开始抽取公共步骤，但旧 service 函数仍作为兼容层保留
-- 统一资产重试入口仍是首版：已覆盖普通故事封面、绘本缺失插图、故事音频，并已抽出 asset completion helper 与 `AssetCompletionResult`
-- `generation_jobs` 已记录请求、完成、失败和资产重试事件，但尚未扩展到逐 provider 调用、逐页面资产步骤和完整运营分析
-- `partial_ready`、`text_status` 等更细粒度状态仍停留在目标态
+- 普通故事、完整生成、绘本生成已有统一外部入口，内部 workflow 仍可继续减少兼容层分支
+- 统一资产重试入口已覆盖普通故事封面、绘本缺失插图和故事音频，后续可继续扩展更细的资产级审计
+- 后台异步 worker 进度流、跨故事 Provider 运营分析和断点续跑仍属于后续生产化增强
 
 ### What This Means
 
-这份 PRD 仍然是目标态文档，但它对应的主干方向已经不是纸面方案。当前最适合的继续方式，不是重写文档，而是继续把 service workflow 和资产补全过程收拢成统一实现。
+这份 PRD 仍然保留目标态设计，但主干能力已经可在当前代码中演示。当前最适合的继续方式，是继续把同步请求迁移到可复用的后台任务与运营分析视角，而不是继续扩大功能范围。
 
 ---
 
@@ -71,13 +87,13 @@ DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本
 DreamWeaver 当前存在以下工作流层面问题：
 
 1. **生成入口已建立，内部路径正在收束**
-   当前前端已切到 `/api/generations`，旧的 `/api/stories/generate`、`/api/stories/generate/full`、`/api/storybook/generate` 仍作为兼容入口保留。service 内部已抽取上下文准备、主记录保存、封面补全、绘本插图补全和音频补全 helper，并用 `AssetCompletionResult` 表达资产补全结果。下一步重点是决定这些结果是否需要进一步沉淀为可查询的 generation job。
+   当前前端已切到 `/api/generations`，旧的 `/api/stories/generate`、`/api/stories/generate/full`、`/api/storybook/generate` 仍作为兼容入口保留。service 内部已抽取上下文准备、主记录保存、封面补全、绘本插图补全和音频补全 helper，并用 `AssetCompletionResult` 表达资产补全结果。generation job/event 已落库并可查询，Provider 调用轨迹和聚合指标也已进入用户端与管理端展示。下一步重点是为后台异步 worker 与运营成本分析复用这些事件。
 
 2. **保存与资产补全过程正在统一**
-   文本故事和绘本已拥有更清晰的主记录保存 helper；普通故事封面、绘本缺失插图、故事音频生成/缓存已共用各自的 asset completion helper。服务层已经能表达资产任务结果，剩余差异集中在还没有持久化 job 对象。
+   文本故事和绘本已拥有更清晰的主记录保存 helper；普通故事封面、绘本缺失插图、故事音频生成/缓存已共用各自的 asset completion helper。服务层已经能表达资产任务结果，并会把统一入口、资产重试、绘本逐页插图和音频生成的关键节点写入 job event。
 
-3. **状态表达不统一**  
-   系统缺少标准的“生成中、部分完成、已完成、失败、可重试”等状态定义，导致前端难以做出成熟体验。
+3. **状态表达已基本统一，仍需生产化扩展**
+   当前已经能用 `generation_status`、`text_status`、`image_status`、`audio_status` 和 `retryable_assets` 表达生成中、部分可读、完成、降级完成、失败和可重试。后续重点是让后台 worker、运营分析和通知系统复用同一套状态语义。
 
 4. **失败处理策略不统一**  
    图片、音频、绘本页生成失败时，系统没有统一的降级定义，用户体验和技术行为都不够稳定。
@@ -165,9 +181,9 @@ DreamWeaver 当前存在以下工作流层面问题：
 
 **Acceptance Criteria**
 
-- [ ] 创建入口支持选择输出类型：普通故事或绘本
-- [ ] 系统能根据输入类型走统一流程，而不是完全独立逻辑
-- [ ] 用户提交后立即看到生成状态
+- [x] 创建入口支持选择输出类型：普通故事或绘本
+- [x] 系统能根据输入类型走统一流程，而不是完全独立逻辑
+- [x] 用户提交后立即看到生成状态
 
 ### Story 2: 获得可用结果
 
@@ -177,9 +193,9 @@ DreamWeaver 当前存在以下工作流层面问题：
 
 **Acceptance Criteria**
 
-- [ ] 文本生成完成后，主记录应被保存
-- [ ] 图片、音频、绘本页可后续补全
-- [ ] 即使部分资产失败，用户仍可查看文本结果
+- [x] 文本生成完成后，主记录应被保存
+- [x] 图片、音频、绘本页可后续补全
+- [x] 即使部分资产失败，用户仍可查看文本结果
 
 ### Story 3: 恢复历史结果
 
@@ -189,9 +205,9 @@ DreamWeaver 当前存在以下工作流层面问题：
 
 **Acceptance Criteria**
 
-- [ ] 故事详情页支持按 ID 加载
-- [ ] 绘本阅读器支持按 ID 加载
-- [ ] 刷新页面不会导致内容丢失
+- [x] 故事详情页支持按 ID 加载
+- [x] 绘本阅读器支持按 ID 加载
+- [x] 刷新页面不会导致内容丢失
 
 ### Story 4: 理解系统状态
 
@@ -201,9 +217,9 @@ DreamWeaver 当前存在以下工作流层面问题：
 
 **Acceptance Criteria**
 
-- [ ] 前端展示统一状态模型
-- [ ] 失败原因对用户可解释
-- [ ] 可补全资产应有独立重试入口
+- [x] 前端展示统一状态模型
+- [x] 失败原因对用户可解释
+- [x] 可补全资产应有独立重试入口
 
 ### Story 5: 以统一方式扩展能力
 
@@ -213,9 +229,9 @@ DreamWeaver 当前存在以下工作流层面问题：
 
 **Acceptance Criteria**
 
-- [ ] 工作流步骤具备清晰边界
+- [x] 工作流步骤具备清晰边界
 - [x] 新能力接入时能挂入现有状态模型
-- [ ] 不需要再新增完全平行的一套生成接口
+- [x] 不需要再新增完全平行的一套生成接口
 
 ---
 
@@ -263,6 +279,8 @@ DreamWeaver 当前存在以下工作流层面问题：
 - 每个状态必须有明确进入条件
 - 前端可根据状态做 UI 展示
 - `degraded_completed` 必须代表“主结果可用，部分资产失败”
+- `partial_ready` 必须代表“主结果可读，资产尚未全部完成但没有失败”
+- `text_status` 必须只表达主文本或绘本结构是否可读，不被图片、音频状态覆盖
 
 ### Feature 3: 统一主记录保存
 
@@ -466,7 +484,7 @@ DreamWeaver 当前存在以下工作流层面问题：
 |------|------------|--------|---------------------|
 | 工作流抽象过度 | Medium | High | 先围绕现有故事/绘本/音频场景做最小抽象 |
 | 历史接口兼容性问题 | Medium | Medium | 保留兼容入口，内部统一服务实现 |
-| 前后端状态模型理解不一致 | High | High | 先写清统一状态表，再进入实现 |
+| 前后端状态模型理解不一致 | Medium | High | 通过共享状态 helper、API schema 和回归测试保持一致 |
 | Storybook 恢复实现不彻底 | Medium | High | 把“按 ID 加载”作为硬性验收项 |
 | 资产状态字段新增引发迁移成本 | Medium | Medium | 允许先在服务层实现，再视需要落库 |
 
@@ -483,7 +501,7 @@ DreamWeaver 当前存在以下工作流层面问题：
 
 **Known Blockers**
 
-- 统一入口尚未建立
+- 当前没有阻塞 MVP 演示的已知问题；后续生产化主要受后台异步化与运营分析范围影响
 - 多条生成链路重复实现
 
 ---