151 lines
3.9 KiB
Markdown
151 lines
3.9 KiB
Markdown
# 专项 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：列出当前真实主线
|
||
- [x] 扫描 `apps/api/app/api/routes/` 所有路由
|
||
- [x] 列出所有 active API endpoints
|
||
- [x] 标注每个 endpoint 的：
|
||
- 状态（稳定/实验/废弃）
|
||
- 对应的 use case
|
||
- 对应的 repository
|
||
- 是否有测试覆盖
|
||
- [x] 创建 `docs/API-MAINLINE.md` ✅
|
||
|
||
### Step 2：标记旧代码状态
|
||
- [x] 列出所有兼容层文件
|
||
- [x] 标记每个文件：
|
||
- `[COMPAT]` - 兼容层，保留
|
||
- `[DEPRECATED]` - 已废弃，待删除
|
||
- `[MIGRATE]` - 待迁移到新主线
|
||
- `[ACTIVE]` - 当前主线
|
||
- [x] 创建 `docs/CODE-STATUS.md` ✅
|
||
|
||
### Step 3：测试分类
|
||
- [x] 扫描 `tests/` 所有测试
|
||
- [x] 按主线分类：
|
||
- 当前主线测试
|
||
- 历史主线测试
|
||
- 需要重写的测试
|
||
- [x] 在 `CODE-STATUS.md` 中标注 ✅
|
||
|
||
### Step 4：文档同步
|
||
- [x] 更新 `README.md` - 修复编码问题并更新内容 ✅
|
||
- [x] 更新 `docs/saas-index.md` - 重构为现代导航 ✅
|
||
- [x] 创建 `docs/API-MAINLINE.md` - 当前主线清单 ✅
|
||
- [x] 创建 `docs/CODE-STATUS.md` - 代码状态标注 ✅
|
||
|
||
---
|
||
|
||
## 四、验收标准
|
||
|
||
- [ ] 有一份清晰的"当前主线 API 清单"文档
|
||
- [ ] 所有兼容层/旧代码都有明确状态标注
|
||
- [ ] 测试已分类，知道哪些是主线测试
|
||
- [ ] README 和索引文档与现实一致
|
||
- [ ] 新人能通过文档快速找到主线代码
|
||
|
||
---
|
||
|
||
## 五、专项边界
|
||
|
||
**只做**：
|
||
- 梳理、标注、文档化
|
||
- 不改变任何功能行为
|
||
- 不删除任何代码
|
||
|
||
**不做**：
|
||
- 实际迁移旧代码
|
||
- 重写测试
|
||
- 新功能开发
|
||
|
||
---
|
||
|
||
## 六、预计工作量
|
||
|
||
- Step 1-2：1-2 小时
|
||
- Step 3：1 小时
|
||
- Step 4：1 小时
|
||
|
||
总计：3-4 小时
|
||
|
||
---
|
||
|
||
**状态**：✅ 已完成
|
||
|
||
---
|
||
|
||
## 七、完成总结
|
||
|
||
### 已交付文档
|
||
|
||
1. **[docs/API-MAINLINE.md](API-MAINLINE.md)**
|
||
- 列出所有 68+ 个 API endpoints
|
||
- 按模块分类（认证/工作空间/项目/素材/生成等）
|
||
- 标注状态和对应的 use case
|
||
- 提供 Phase 7 主链路流程图
|
||
|
||
2. **[docs/CODE-STATUS.md](CODE-STATUS.md)**
|
||
- 标注所有代码文件状态（ACTIVE/COMPAT/DEPRECATED/MIGRATE）
|
||
- 提供快速定位指南
|
||
- 测试分类清单
|
||
- 清理计划
|
||
|
||
3. **[README.md](../README.md)**
|
||
- 修复编码问题（UTF-8 乱码）
|
||
- 更新项目状态
|
||
- 添加 Phase 7 完成标记
|
||
- 更新文档链接
|
||
|
||
4. **[docs/saas-index.md](saas-index.md)**
|
||
- 重构为现代导航结构
|
||
- 添加快速导航入口
|
||
- 更新文档清单
|
||
- 标注归档文档
|
||
|
||
### 关键成果
|
||
|
||
- ✅ 新人可以通过文档快速找到主线代码
|
||
- ✅ 所有 API endpoints 有清晰的清单
|
||
- ✅ 兼容层/旧代码都有明确状态标注
|
||
- ✅ README 和索引文档与现实一致
|
||
- ✅ 测试已分类，知道哪些是主线测试
|
||
|
||
### 后续建议
|
||
|
||
专项 B 已完成，建议：
|
||
- 下一个可以做专项 C（文档入口质量修复）
|
||
- 或者专项 D（生成链生产化深化）
|
||
- 或者专项 E（前端真实联调验收深化）
|