feat: add generation trace and partial-ready workflow status

docs/technical/generation-job-state.md

@@ -12,26 +12,37 @@
 
 - `stories` 继续承载用户可见结果和当前状态。
 - `generation_jobs` 记录一次生成或资产补全尝试。
-- `generation_job_events` 记录关键步骤事件，例如 `request_accepted`、`generation_completed`、`asset_retry_started`、`asset_retry_completed`。
+- `generation_job_events` 记录关键步骤事件，例如 `request_accepted`、`context_prepared`、`narrative_generated`、`story_saved`、`cover_image_succeeded`、`storybook_page_image_succeeded`、`audio_succeeded`、`provider_call_succeeded`、`asset_retry_completed`。
+
+当前已提供三个查询入口：
+
+- `GET /api/generations/jobs/{job_id}`：查询单次生成/补全任务及其事件流。
+- `GET /api/generations/{story_id}/jobs`：查询某个故事或绘本的生成与重试历史。
+- `GET /api/generations/{story_id}/provider-stats`：按故事聚合 Provider 调用成功率、平均耗时、预估成本和 adapter 明细。
+
+job 响应会返回 `progress_percent`、`progress_label` 和 `is_terminal`，用户端与管理端已经消费这些查询入口，在故事详情页和绘本阅读页展示最近任务、任务历史、事件时间线、进度条和 Provider 聚合指标。
 
 ## 现有状态模型
 
 当前 `stories` 表已承载演示所需状态：
 
-- `generation_status`: 主流程状态，例如 `narrative_ready`、`assets_generating`、`completed`、`degraded_completed`、`failed`
+- `generation_status`: 主流程状态，例如 `narrative_ready`、`partial_ready`、`assets_generating`、`completed`、`degraded_completed`、`failed`
+- `text_status`: 主文本或绘本结构状态，当前用于区分主内容是否已经可读
 - `image_status`: 封面或绘本插图状态
 - `audio_status`: 语音状态
 - `last_error`: 最近一次资产失败原因
 
-这些字段足够支撑前端展示、smoke 检查、失败降级和资产重试。
+`partial_ready` 表示主内容已经可读、但仍有封面、插图或音频可以继续补全；`degraded_completed` 表示主内容可读但至少一个资产失败。两者的区分能让前端把“正常待补全”和“需要重试失败资源”分开展示。
+
+这些字段足够支撑前端展示、smoke 检查、失败降级、资产重试和生成轨迹解释。
 
 ## 什么时候需要落库 job
 
 如果后续进入真实生产化，需要扩展当前 job/event 模型：
 
-- 生成流程改成真正异步，前端需要轮询 job 进度。
-- 单个故事会产生多次生成尝试，需要审计每次 provider 调用。
-- 需要展示更细颗粒度步骤，例如 prompt 构建、文本生成、封面生成、每页插图、TTS。
+- 生成流程改成真正异步，前端需要轮询后台 worker 的实时进度。
+- 单个故事会产生多次生成尝试，需要对比每次任务的 provider 表现、重试原因和资产结果。
+- 需要展示比当前事件更细颗粒度的步骤，例如 prompt 构建、provider 选择依据、provider failover 原因、每次调用 token/图片/语音成本。
 - 需要按 provider、成本、延迟和失败原因做运营分析。
 - 需要断点续跑，避免 Worker 重启后丢失中间状态。
 
@@ -39,9 +50,9 @@
 
 当前已有两层记录，未来可以继续扩展字段和事件颗粒度：
 
-- 在 `generation_job_events` 中补 provider、耗时、成本和错误摘要。
-- 对绘本逐页插图、TTS、后处理任务记录更细事件。
-- 为前端提供 job 查询接口，用于真正异步生成时轮询进度。
+- 将 job/event 查询继续接入真正异步生成时的进度条。
+- 将当前按故事聚合的 provider 指标扩展为跨用户、跨时间窗口的运营分析。
+- 将当前同步生成请求迁移到后台 worker 后，复用现有 job 查询接口做轮询进度。
 
 ## 面试表达