# 专项 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（前端真实联调验收深化）