3.9 KiB
3.9 KiB
专项 B：全仓主线路径澄清 - 规划文档
专项负责人：小虾 🦐
创建时间：2026-06-19 09:56 GMT+8
状态：🔄 进行中
一、专项目标
消除"旧文档 / 旧测试 / 当前主线"并存带来的认知混乱，让代码库有清晰的主线路径。
二、当前问题
问题 1：多代实现并存
- 旧素材链：
domain/asset.py,domain/asset_library.py,ports/asset_repository.py,adapters/postgres/asset_repository.py - 新素材链：
domain/entities.py,application/assets.py,adapters/sqlalchemy_impl/asset_repository.py - 当前已通过兼容层压平，但文档未同步
问题 2：测试覆盖不清晰
- 哪些测试是针对当前主线的？
- 哪些是历史遗留的？
- 哪些需要重写？
问题 3：文档与现实不一致
- README 可能包含过期信息
saas-index.md需要核对- API 文档需要更新
三、执行计划
Step 1：列出当前真实主线
- 扫描
apps/api/app/api/routes/所有路由 - 列出所有 active API endpoints
- 标注每个 endpoint 的：
- 状态（稳定/实验/废弃）
- 对应的 use case
- 对应的 repository
- 是否有测试覆盖
- 创建
docs/API-MAINLINE.md✅
Step 2：标记旧代码状态
- 列出所有兼容层文件
- 标记每个文件：
[COMPAT]- 兼容层，保留[DEPRECATED]- 已废弃，待删除[MIGRATE]- 待迁移到新主线[ACTIVE]- 当前主线
- 创建
docs/CODE-STATUS.md✅
Step 3：测试分类
- 扫描
tests/所有测试 - 按主线分类：
- 当前主线测试
- 历史主线测试
- 需要重写的测试
- 在
CODE-STATUS.md中标注 ✅
Step 4：文档同步
- 更新
README.md- 修复编码问题并更新内容 ✅ - 更新
docs/saas-index.md- 重构为现代导航 ✅ - 创建
docs/API-MAINLINE.md- 当前主线清单 ✅ - 创建
docs/CODE-STATUS.md- 代码状态标注 ✅
四、验收标准
- 有一份清晰的"当前主线 API 清单"文档
- 所有兼容层/旧代码都有明确状态标注
- 测试已分类，知道哪些是主线测试
- README 和索引文档与现实一致
- 新人能通过文档快速找到主线代码
五、专项边界
只做：
- 梳理、标注、文档化
- 不改变任何功能行为
- 不删除任何代码
不做：
- 实际迁移旧代码
- 重写测试
- 新功能开发
六、预计工作量
- Step 1-2：1-2 小时
- Step 3：1 小时
- Step 4：1 小时
总计：3-4 小时
状态：✅ 已完成
七、完成总结
已交付文档
-
- 列出所有 68+ 个 API endpoints
- 按模块分类（认证/工作空间/项目/素材/生成等）
- 标注状态和对应的 use case
- 提供 Phase 7 主链路流程图
-
- 标注所有代码文件状态（ACTIVE/COMPAT/DEPRECATED/MIGRATE）
- 提供快速定位指南
- 测试分类清单
- 清理计划
-
- 修复编码问题（UTF-8 乱码）
- 更新项目状态
- 添加 Phase 7 完成标记
- 更新文档链接
-
- 重构为现代导航结构
- 添加快速导航入口
- 更新文档清单
- 标注归档文档
关键成果
- ✅ 新人可以通过文档快速找到主线代码
- ✅ 所有 API endpoints 有清晰的清单
- ✅ 兼容层/旧代码都有明确状态标注
- ✅ README 和索引文档与现实一致
- ✅ 测试已分类，知道哪些是主线测试
后续建议
专项 B 已完成，建议：
- 下一个可以做专项 C（文档入口质量修复）
- 或者专项 D（生成链生产化深化）
- 或者专项 E（前端真实联调验收深化）