xiaoxia-saas/docs/专项B-全仓主线路径澄清-规划.md

专项 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 小时

---

状态：✅ 已完成

---

七、完成总结

已交付文档

1. docs/API-MAINLINE.md

   • 列出所有 68+ 个 API endpoints
   • 按模块分类（认证/工作空间/项目/素材/生成等）
   • 标注状态和对应的 use case
   • 提供 Phase 7 主链路流程图

2. docs/CODE-STATUS.md

   • 标注所有代码文件状态（ACTIVE/COMPAT/DEPRECATED/MIGRATE）
   • 提供快速定位指南
   • 测试分类清单
   • 清理计划

3. README.md

   • 修复编码问题（UTF-8 乱码）
   • 更新项目状态
   • 添加 Phase 7 完成标记
   • 更新文档链接

4. docs/saas-index.md

   • 重构为现代导航结构
   • 添加快速导航入口
   • 更新文档清单
   • 标注归档文档

关键成果

• ✅ 新人可以通过文档快速找到主线代码
• ✅ 所有 API endpoints 有清晰的清单
• ✅ 兼容层/旧代码都有明确状态标注
• ✅ README 和索引文档与现实一致
• ✅ 测试已分类，知道哪些是主线测试

后续建议

专项 B 已完成，建议：

• 下一个可以做专项 C（文档入口质量修复）
• 或者专项 D（生成链生产化深化）
• 或者专项 E（前端真实联调验收深化）