451 lines
18 KiB
Markdown
451 lines
18 KiB
Markdown
# 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 问题说明项目还没完成最后一轮收尾。
|
||
|
||
因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。
|