DreamWeaver/dreamweaver
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
b8d3cb4644a651b146a7087981cb21fef0f8731c
dreamweaver/docs/planning/document-status-inventory.md

18 KiB
Raw Blame History

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 问题说明项目还没完成最后一轮收尾。

因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。

Reference in New Issue View Git Blame Copy Permalink