docs: sync workflow progress and weekend handoff

docs/planning/document-status-inventory.md

@@ -0,0 +1,450 @@
+# DreamWeaver 文档状态盘点表
+
+**Version**: 1.0  
+**Date**: 2026-04-17  
+**Author**: Sarah (Product Owner) / Codex  
+**Document Type**: Documentation Audit / Source-of-Truth Inventory
+
+---
+
+## 1. 盘点目的
+
+这份文档不是新的 PRD，也不是新的技术方案，而是一份“项目资产盘点文档”。它解决三个问题：
+
+1. 让团队快速分清楚 `docs/` 里哪些文件是当前有效文档，哪些只是历史材料。
+2. 让产品文档与代码现实建立映射，避免“文档看起来很完整，但代码并没有落地”的错觉。
+3. 在重新启动项目时，为后续改代码提供明确起点，减少无效重构和重复讨论。
+
+对于求职版 DreamWeaver，这份盘点文档的价值在于：它帮助你把“会写需求文档”进一步提升为“会管理文档体系、会判断 source of truth、会做项目现状诊断”。
+
+---
+
+## 2. 盘点范围与判定口径
+
+### 2.1 盘点范围
+
+本次盘点覆盖以下对象：
+
+- `docs/` 当前全部文档
+- 后端核心实现：`backend/app/api/`、`backend/app/services/`、`backend/app/db/`
+- 前端关键体验：`frontend/src/components/`、`frontend/src/views/`、`frontend/src/stores/`
+- 运维相关配置：`docker-compose.ha.yml`、`backend/app/core/`
+- 构建与验证结果：后端测试、后端 lint、主前端构建、管理端构建
+
+### 2.2 文档状态定义
+
+| 文档状态 | 含义 |
+| --- | --- |
+| Active | 当前有效，应作为近期工作的参考依据 |
+| Reference | 有参考价值，但不能直接视为最新实现说明 |
+| Archived | 保留历史价值，但不再作为现行 source of truth |
+
+### 2.3 代码落地状态定义
+
+| 落地状态 | 含义 |
+| --- | --- |
+| 非实现类文档 | 文档本身是产品/规划/治理文档，不直接对应“已实现/未实现” |
+| 已实现 | 文档描述的主体能力已在代码中形成闭环，且验证结果基本通过 |
+| 部分实现 | 已有主干能力，但关键路径、恢复能力、状态模型或工程质量仍未闭环 |
+| 未实现 | 文档描述的主体仍是目标态，当前代码尚未形成有效落地 |
+| 历史文档 | 文档描述对应的是过去的设计/阶段，部分内容已落地，但已不适合作为现行依据 |
+
+### 2.4 本次验证快照
+
+截至 2026-04-17 evening，本次盘点同步得到以下验证结果：
+
+- 后端测试通过：`backend/` 下 `pytest -q` 结果为 `53 passed`
+- 主前端类型检查通过：`frontend/` 下 `vue-tsc --noEmit` 成功
+- 主前端完整构建在当前环境受 Rollup 可选原生包缺失影响，属于环境依赖问题，不是本轮状态模型改动直接引起
+- 管理端范围仍未明确，不适合作为当前求职版稳定演示链路
+- 后端 lint 仍有历史债务，尚未完成最后一轮收尾
+
+这意味着：项目并不是“不能运行”，而是“核心主链路可用，但工程完备度和演示稳定性还没到求职成品状态”。
+
+---
+
+## 3. 文档状态总表
+
+| 文档 | 分类 | 文档状态 | 代码落地状态 | 盘点结论 | 建议动作 |
+| --- | --- | --- | --- | --- | --- |
+| `docs/README.md` | 文档治理 | Active | 非实现类文档 | 当前 docs 分类规则清晰，已成为文档入口页 | 保留并持续维护 |
+| `docs/product/job-search-relaunch-prd.md` | 产品 PRD | Active | 非实现类文档 | 是当前“求职版产品重启”的核心 source of truth | 保留，作为产品总纲 |
+| `docs/product/unified-generation-workflow-prd.md` | 功能 PRD | Active | 部分实现 | 目标方向明确，但“统一工作流”目标态尚未真正落地 | 保留，作为改代码主依据 |
+| `docs/planning/week-1-execution-backlog.md` | 执行规划 | Active | 非实现类文档 | 是执行计划，不应用它判断是否“已经做完” | 保留，并按完成情况更新 |
+| `docs/planning/document-status-inventory.md` | 项目盘点 | Active | 非实现类文档 | 当前文档体系与代码现实的映射表 | 保留，后续按阶段更新 |
+| `docs/technical/memory-system-dev.md` | 技术设计 | Reference | 部分实现 | 记忆系统主干已存在，但文档中不少内容仍是增强设计 | 保留，开发前逐条核验 |
+| `docs/operations/ha-runbook.md` | 运维 Runbook | Reference | 部分实现 | Docker HA、Redis Sentinel、备份与 Celery Sentinel 支持已存在，但仍属基础版 | 保留，按真实环境演练继续校正 |
+| `docs/archive/provider-system-legacy.md` | 历史技术文档 | Archived | 历史文档 | 部分设计已落地，但命名与架构描述已过时 | 继续归档，不再扩写 |
+| `docs/archive/refactoring-plan-legacy.md` | 历史实施计划 | Archived | 历史文档 | 反映旧阶段重构过程，部分 checklist 已完成 | 继续归档，仅供回溯 |
+| `docs/archive/stories-split-analysis-legacy.md` | 历史分析 | Archived | 历史文档 | 拆分分析对应的主要重构已发生 | 继续归档，仅供理解演进过程 |
+
+---
+
+## 4. 逐份文档判定说明
+
+### 4.1 `docs/README.md`
+
+**判定**  
+当前有效，属于“文档治理入口”。
+
+**证据**
+
+- 已明确区分 `product / planning / technical / operations / archive`
+- 已写清删除与归档规则
+- 已能帮助团队快速识别 source of truth
+
+**结论**  
+这份文档不是实现说明，但它已经承担“文档信息架构”角色，应继续保留并作为 docs 首页。
+
+### 4.2 `docs/product/job-search-relaunch-prd.md`
+
+**判定**  
+当前有效，属于产品总纲文档。
+
+**证据**
+
+- 文档明确提出求职版产品定位、成功指标、P0/P1/P2 取舍
+- 文档中的问题诊断与当前代码现实一致，包括：
+  - Storybook 恢复能力不足
+  - Provider 体系职责混杂
+  - Admin 构建问题影响演示
+  - 前端状态设计薄弱
+
+**结论**  
+这份 PRD 不用于判断“是否已实现”，而用于回答“现在应该把项目做成什么样”。它是当前最重要的产品 source of truth。
+
+### 4.3 `docs/product/unified-generation-workflow-prd.md`
+
+**判定**  
+当前有效，但对应能力仅部分实现。
+
+**证据**
+
+- 当前后端仍保留多条生成路径：
+  - `POST /api/stories/generate`
+  - `POST /api/stories/generate/full`
+  - `POST /api/storybook/generate`
+- 相关实现仍分别落在 `backend/app/api/stories.py` 与 `backend/app/services/story_service.py`
+- 当前 `Story` 模型已具备统一主记录的基础字段：
+  - `story_text`
+  - `pages`
+  - `cover_prompt`
+  - `image_url`
+  - `mode`
+- 当前已经落地的统一状态模型包括：
+  - `generation_status`
+  - `image_status`
+  - `audio_status`
+  - `last_error`
+  - `degraded_completed`
+- 但更完整的工作流目标仍未完全实现，例如：
+  - `partial_ready`
+  - `retryable_assets`
+  - 统一资产重试入口
+  - 单一 generation service workflow
+
+**结论**  
+这份文档对应的是“当前核心改造主线”。它已经不再只是方向性文档，因为统一状态模型和恢复能力已经开始落地；但它仍不是“已完成实现说明”，因为统一工作流入口和统一资产补全过程还未真正收束。
+
+### 4.4 `docs/planning/week-1-execution-backlog.md`
+
+**判定**  
+当前有效，属于执行计划文档。
+
+**证据**
+
+- 文档将工作拆成产品聚焦、工作流定义、Storybook 恢复、Admin 处理、Provider 边界梳理等任务
+- 这些任务与盘点出的真实缺口一致
+- 但多数事项仍未被代码完成，因此不能把这份文档当作“实现说明”
+
+**结论**  
+这是一份“该做什么”的文档，不是“已经做了什么”的文档。后续应在每个任务完成后更新状态，而不是继续长期停留在初始 backlog。
+
+### 4.5 `docs/technical/memory-system-dev.md`
+
+**判定**  
+技术参考文档，部分实现。
+
+**已落地部分证据**
+
+- `backend/app/db/models.py` 中存在 `MemoryItem`、`ChildProfile`、`StoryUniverse`
+- `backend/app/services/memory_service.py` 中已实现：
+  - 记忆类型定义
+  - 时效衰减评分
+  - Prompt 注入格式化
+  - TTL 清理
+  - recent story / favorite character / scary element 创建
+- `backend/app/api/memories.py` 已提供记忆查询、创建、删除相关接口
+- `backend/app/api/profiles.py` 已提供 `GET /profiles/{profile_id}/timeline`
+- `backend/app/tasks/memory.py` 和 `backend/app/core/celery_app.py` 已接入每日清理任务
+
+**未完全落地部分**
+
+- 文档规划的反馈接口 `POST /api/memories/{id}/feedback` 当前不存在
+- 更复杂的“长期印象总结”“通知机制”“更丰富的结构化 schema”尚未形成闭环
+- 时间线目前主要由档案创建、故事记录、宇宙成就拼装而成，还不是完整的成长操作系统
+
+**结论**  
+记忆系统不是“没做”，而是“已经有主干，但还停在可用原型阶段”。这份文档应该被保留为技术参考，但开发时必须逐条核验，不可直接按文档默认其已落地。
+
+### 4.6 `docs/operations/ha-runbook.md`
+
+**判定**  
+运维参考文档，部分实现。
+
+**已落地部分证据**
+
+- `docker-compose.ha.yml` 已提供：
+  - PostgreSQL 主库
+  - PostgreSQL 从库
+  - 定时备份容器
+  - Redis 主从
+  - 3 个 Sentinel 节点
+- `backend/app/core/config.py` 已支持 Sentinel 相关配置解析
+- `backend/app/core/redis.py` 已支持通过 Sentinel 获取 Redis master
+- `backend/app/core/celery_app.py` 已支持 Celery broker/result backend 走 Sentinel
+
+**未完全落地部分**
+
+- 仍停留在 Docker Compose 层的基础 HA 演练，不是成熟生产级方案
+- 尚未看到读写分离、连接池代理、监控告警等更完整设施
+- 这份 runbook 更适合作为“基础 HA 实验手册”，而不是正式生产运维规范
+
+**结论**  
+该文档不应删除，因为它对应的基础设施确实存在；但也不能对外表述成“完整 HA 能力已成熟上线”。
+
+### 4.7 `docs/archive/provider-system-legacy.md`
+
+**判定**  
+历史文档，部分内容已落地，但整体已过时。
+
+**证据**
+
+- 文档提到的 provider failover、metrics、secret management、admin console 等能力，在代码中能找到对应实现：
+  - `backend/app/services/provider_router.py`
+  - `backend/app/services/provider_metrics.py`
+  - `backend/app/services/secret_service.py`
+  - `backend/app/api/admin_providers.py`
+- 但文档中的部分命名与现状不一致，例如仍提到 `app/admin_app.py`，而当前入口为 `backend/app/admin_main.py`
+- 当前 provider router 同时承担默认配置、凭据映射、路由策略、熔断、成本记录等多项职责，说明体系已继续演化，不再等同于这份旧文档
+
+**结论**  
+这份文档值得保留用于理解历史，但不能作为现行 provider 体系说明书。
+
+### 4.8 `docs/archive/refactoring-plan-legacy.md`
+
+**判定**  
+历史计划文档，部分任务已完成。
+
+**证据**
+
+- 文档中提到的 `stories.py` 拆分，目前已经有明显落地：
+  - `backend/app/services/story_service.py`
+  - `backend/app/schemas/story_schemas.py`
+  - `backend/app/api/stories.py`
+- 文档中提到的 Redis / HA 方向也已有基础实现
+- 但它描述的是更早阶段的改造路线，与当前“求职版重启”的产品目标已不是同一语境
+
+**结论**  
+保留在 `archive/` 是合理的。它是“项目曾经怎么想”的材料，不是“现在应该怎么做”的材料。
+
+### 4.9 `docs/archive/stories-split-analysis-legacy.md`
+
+**判定**  
+历史分析文档，核心分析目的已经完成。
+
+**证据**
+
+- 文档聚焦 `stories.py` 过重的问题
+- 当前已形成更合理的拆分：
+  - API 层保留路由
+  - schema 独立
+  - service 独立
+- 说明它的主要使命已经完成
+
+**结论**  
+应继续归档，用于未来解释“为什么会有现在的结构”，但不再参与当前需求决策。
+
+---
+
+## 5. 当前已落地的核心能力
+
+以下能力已经具备“代码存在且主链路可验证”的基础：
+
+### 5.1 内容生成基础能力
+
+- 普通故事生成、完整故事生成、绘本生成均存在可调用接口
+- `Story` 模型已能同时承载文本故事与分页绘本
+- 封面图生成与成就提取已接入后处理链路
+
+### 5.2 个性化上下文基础能力
+
+- 孩子档案、故事宇宙、记忆系统、成长时间线均已有基础模型和接口
+- Prompt 侧已接入记忆上下文构建
+- 成就可回写到 `StoryUniverse.achievements`
+
+### 5.3 Provider 管理基础能力
+
+- Provider Router 已支持 failover
+- Provider 管理、密钥管理、成本汇总等管理 API 已存在
+- 默认 provider 列表与数据库 provider 配置可共存
+
+### 5.4 运维与异步基础能力
+
+- Celery + Redis 已接入
+- Redis Sentinel 与 Celery Sentinel 配置已实现
+- PostgreSQL 主从与备份的 Compose 级实验环境已存在
+
+### 5.5 工程可运行性
+
+- 后端测试通过：`53 passed`
+- 主前端构建通过
+
+---
+
+## 6. 当前“部分实现 / 未实现”的关键缺口
+
+这些缺口正是接下来改代码最应该优先处理的地方。
+
+### 6.1 统一生成工作流尚未真正落地
+
+虽然 PRD 已经明确目标，但当前系统仍是多入口、多响应模型、多处理路径并存。它们共享了一些底层能力，但还没有收束为统一 workflow。
+
+### 6.2 Storybook 恢复能力不完整
+
+当前前端仍依赖 `frontend/src/stores/storybook.ts` 暂存数据，`frontend/src/views/StorybookViewer.vue` 在刷新或直接访问时无法按 ID 恢复。这是最明显的“演示链路不稳”问题之一。
+
+### 6.3 音频体验未形成闭环
+
+当前 `GET /api/audio/{id}` 会在请求时即时生成音频，但没有持久化缓存与复用策略，既影响用户体验，也影响成本控制。
+
+### 6.4 Provider 体系职责边界仍然混杂
+
+当前 `provider_router.py` 既负责默认 provider、凭据映射、策略排序，又承担 metrics、熔断、成本记录等职责。功能虽强，但不利于后续持续演进，也不利于你在面试中清晰讲解。
+
+### 6.5 管理端尚未达到“可展示成品”标准
+
+`admin-frontend` 当前构建失败，说明管理端虽然概念上存在，但还不适合作为稳定演示链路的一部分。
+
+### 6.6 工程质量信号还不统一
+
+后端测试是加分项，但 lint 未通过会削弱成熟度观感。对于求职版项目，测试通过但 lint 大量报错，会让项目显得“能跑，但还没收尾”。
+
+---
+
+## 7. 推荐下一步编码切入点
+
+如果目标是“尽快把项目恢复到可演示、可讲清、可继续迭代”的状态，建议按以下顺序推进。
+
+### 7.1 第一优先级：补齐 Storybook 按 ID 恢复
+
+**为什么先做**
+
+- 改动范围相对可控
+- 用户价值直观
+- 修完后演示稳定性立刻提升
+- 很适合作为“重新启动项目后的第一场胜仗”
+
+**目标**
+
+- `StorybookViewer` 不再只依赖 Pinia
+- 支持通过 `story_id` 拉取 `Story.pages`
+- 刷新页面后仍能继续阅读
+
+### 7.2 第二优先级：抽出统一生成状态模型
+
+**为什么第二个做**
+
+- 这是“统一工作流”真正开始落地的最小切口
+- 它能先统一语言，再统一代码
+- 前端状态设计、后端任务编排、部分完成/降级完成，都会以它为中心展开
+
+**目标**
+
+- 先在服务层定义统一状态
+- 再决定是否扩展数据库字段
+- 让故事、绘本、图片、音频都能共享一套状态表达
+
+### 7.3 第三优先级：清理 Provider 边界并决定 Admin 范围
+
+**为什么第三个做**
+
+- 这是系统长期可解释性的关键
+- 但它比 Storybook 恢复和状态模型更抽象，适合在主链路稳定后推进
+
+**目标**
+
+- 先梳理 Capability / Provider / Routing Policy 三层概念
+- 再判断管理端是修复、降级，还是缩小到只保留必要接口
+
+---
+
+## 8. 建议保留、更新、删除动作汇总
+
+### 8.1 建议保留
+
+- `docs/README.md`
+- `docs/product/job-search-relaunch-prd.md`
+- `docs/product/unified-generation-workflow-prd.md`
+- `docs/planning/week-1-execution-backlog.md`
+- `docs/technical/memory-system-dev.md`
+- `docs/operations/ha-runbook.md`
+- `docs/archive/*`
+
+### 8.2 建议更新
+
+- `docs/planning/week-1-execution-backlog.md`
+  - 需要随着任务推进更新完成状态，不应长期停留在纯规划状态
+- `docs/technical/memory-system-dev.md`
+  - 后续开发时应补充“已实现”和“待实现”标记，减少误读
+- `docs/operations/ha-runbook.md`
+  - 后续若做真实演练，应把演练结果写回文档
+
+### 8.3 当前不建议再删除
+
+本轮分类整理后，`docs/` 目录中没有新的“应该直接删除”的文档。剩余历史文件都具备学习价值或项目演进价值，适合继续保留在 `archive/`。
+
+---
+
+## 9. PM 学习笔记：为什么要写这种盘点文档
+
+很多初级产品文档只会写“要做什么”，但不会回答：
+
+- 现在手里的文档哪些是真的有效
+- 哪些是目标态，哪些是现状
+- 哪些能力已经能演示，哪些只是概念
+- 哪些问题适合现在改，哪些问题应该晚一点改
+
+“文档状态盘点表”就是用来解决这些问题的。它本质上是产品管理中的三项能力训练：
+
+1. **Source of Truth 管理**  
+   你要知道团队现在到底该信哪份文档。
+2. **现状诊断能力**  
+   你要把 PRD、代码、构建结果、运维配置放在一起看，而不是只看其中一边。
+3. **优先级判断能力**  
+   你要判断什么是“现在最值得做的第一件事”。
+
+以后你在写自己的项目盘点时，可以直接复用这套结构：
+
+1. 盘点目的
+2. 判定口径
+3. 状态总表
+4. 逐项证据
+5. 已落地能力
+6. 关键缺口
+7. 下一步建议
+
+---
+
+## 10. 本次盘点结论
+
+DreamWeaver 当前不是“半成品废案”，而是“有明显实现基础、但还缺一轮产品收束与关键链路补完”的项目。
+
+更准确地说：
+
+- 产品层面，方向已经比以前清楚，现有 PRD 可以继续作为重启依据。
+- 技术层面，后端主能力、记忆系统、Provider 管理、异步任务和基础 HA 都不是空白。
+- 体验层面，Storybook 恢复、音频闭环、前端状态设计已明显推进，但统一工作流与统一重试入口仍是关键缺口。
+- 工程层面，主前端与后端可用，但 admin-frontend 与 lint 问题说明项目还没完成最后一轮收尾。
+
+因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。