# 七步法深度评审：TODO系统迁移方案（第二版）

**评审人**: agent1 (oc-collab产品经理)
**日期**: 2026-02-23
**评审commit**: b846e12b
**提案**: PROPOSAL_TODO_migration_to_oc_collab.md

---

## 一、问题定义 (Problem Definition)

### 1.1 核心问题
pm-agent 存在两套 TODO 系统：
- 现有系统: JSON 文件存储 (`pm-agent/state/TODO-*.json`)
- 目标系统: oc-collab SQLite 数据库

### 1.2 问题根源
- oc-collab 原本仅支持 agent1/2，不支持 agent3-9
- pm-agent 只能自建 TODO 系统来管理 agent3-4 的任务

### 1.3 问题影响
- 数据孤岛：TODO 信息分散在两个系统
- 维护成本：需维护两套系统
- 跨系统协作困难：pm-agent ↔ oc-collab 无法互通

---

## 二、现状分析 (Current State Analysis)

### 2.1 pm-agent TODO 现状
| 指标 | 值 |
|------|-----|
| 存储方式 | JSON 文件 |
| 文件位置 | pm-agent/state/TODO-*.json |
| 支持的Agent | agent3, agent4 |
| 创建方式 | 直接写文件 |
| 历史数据量 | 3+ 文件 |

### 2.2 oc-collab TODO 现状
| 指标 | 值 |
|------|-----|
| 存储方式 | SQLite 数据库 |
| 文件位置 | oc-collab/state/todos.db |
| 支持的Agent | agent1-9 (已修复) |
| 创建方式 | CLI 命令 |
| 跨系统能力 | ✅ 已实现 |

### 2.3 差距分析
| 维度 | pm-agent | oc-collab | 差距 |
|------|----------|-----------|------|
| 跨系统互通 | ❌ | ✅ | 需要迁移 |
| 统一管理 | ❌ | ✅ | 需要迁移 |
| 维护成本 | 高 | 低 | 需要优化 |

---

## 三、目标设定 (Goal Setting)

### 3.1 直接目标
1. **统一存储**: 所有 TODO 存储到 oc-collab
2. **统一接口**: 使用 `oc-collab todowrite` 创建 TODO
3. **平滑过渡**: 历史 TODO 可查

### 3.2 量化目标
| 指标 | 当前 | 目标 |
|------|------|------|
| TODO 系统数量 | 2 | 1 |
| 跨系统 TODO | 0 | 100% |
| 维护代码量 | 两套 | 一套 |

### 3.3 成功标准
- [ ] pm-agent 创建的 TODO 写入 oc-collab
- [ ] 历史 TODO 可迁移
- [ ] 无数据丢失
- [ ] 切换期间不影响业务
- [ ] 测试覆盖完整

---

## 四、方案设计 (Solution Design)

### 4.1 技术方案 ✅

**OcCollabClient 封装**
- 扩展现有 `pm-agent/backend/services/oc_collab_client.py`
- 添加 `create_todo()` 方法
- 复用已有 CLI 调用逻辑

### 4.2 新增内容（根据agent6评审）

#### 测试控制（第八章）
| 内容 | 评价 |
|------|------|
| 测试用例清单 | ✅ 清晰，P0/P1分级 |
| 单元测试用例 | ✅ 5个核心用例 |
| 集成测试用例 | ✅ 覆盖完整流程 |
| 灰度发布方案 | ✅ 3阶段 |
| 回滚操作 | ✅ 具体步骤 |
| 数据校验 | ✅ 脚本完整 |

### 4.3 流程变更

**当前流程**:
```
agent3 → 构造JSON → 写入文件 → git commit
```

**目标流程**:
```
agent3 → 调用OcCollabClient → oc-collab todowrite → 写入SQLite
```

### 4.4 方案评估

| 评估维度 | 评分 | 说明 |
|----------|------|------|
| 技术可行性 | 5/5 | 已有API，复用成本低 |
| 业务影响 | 4/5 | 需切换，有过渡期 |
| 测试完整性 | 5/5 | 单元+集成+灰度 |
| 实施难度 | 4/5 | 改动点明确 |
| 长期收益 | 5/5 | 统一架构，减少维护 |

---

## 五、风险评估 (Risk Assessment)

### 5.1 识别风险

| 风险ID | 风险描述 | 影响程度 | 发生概率 |
|--------|---------|---------|---------|
| R1 | oc-collab CLI 不可用 | 高 | 低 |
| R2 | 迁移丢失数据 | 高 | 低 |
| R3 | 切换期间业务中断 | 中 | 低 |
| R4 | 兼容性问题 | 中 | 中 |
| R5 | 测试覆盖不足 | 中 | 低 |
| R6 | 回滚失败 | 高 | 低 |
| R7 | 数据不一致 | 中 | 低 |

### 5.2 缓解措施

| 风险ID | 缓解措施 | 责任人 |
|--------|---------|--------|
| R1 | 保留本地 JSON 作为 fallback | agent4 |
| R2 | 迁移前完整备份 | agent3 |
| R3 | 灰度切换，先试运行 | agent4 |
| R4 | 充分测试验证 | agent3 |
| R5 | 补充单元测试、集成测试 | agent6 |
| R6 | 完善回滚操作文档 | agent4 |
| R7 | 增加数据校验脚本 | agent3 |

### 5.3 应急预案

- 如迁移失败，回退到 JSON 模式
- 保留原文件 30 天

---

## 六、实施计划 (Implementation Plan)

### 6.1 时间安排（更新版）

| 阶段 | 任务 | 工期 | 负责人 | 依赖 |
|------|------|------|--------|------|
| 准备 | 环境检查、备份 | 0.5h | agent3 | - |
| 开发 | OcCollabClient.create_todo() | 0.5h | agent4 | - |
| 开发 | 编写单元测试用例 | 1h | agent4 | 开发完成 |
| 开发 | 替换 TODO 创建逻辑 | 1h | agent4 | 开发完成 |
| 测试 | 编写集成测试用例 | 1h | agent6 | 开发完成 |
| 迁移 | 迁移历史数据 | 0.5h | agent3 | 测试通过 |
| 校验 | 数据校验 | 0.5h | agent3 | 迁移完成 |
| 发布 | 灰度发布验证 | 0.5h | agent4 | 校验完成 |
| 文档 | 更新文档 | 0.5h | agent3 | 发布完成 |

**总工期**: 5.5h（较初版增加2.5h，补充测试）

### 6.2 里程碑

| 里程碑 | 验收标准 | 时间 |
|--------|---------|------|
| M1: 开发完成 | create_todo() + 单元测试 | D1 |
| M2: 测试通过 | 集成测试 100% | D1 |
| M3: 迁移完成 | 历史数据已迁移 | D1 |
| M4: 校验通过 | 数据一致性验证 | D1 |
| M5: 上线 | 灰度发布完成 | D1 |

---

## 七、决策确认 (Decision Making)

### 7.1 评审结论

| 评审项 | 结论 | 备注 |
|--------|------|------|
| 问题定义 | ✅ 清晰 | 两套系统需要统一 |
| 现状分析 | ✅ 完整 | 差距分析到位 |
| 目标设定 | ✅ 明确 | 量化目标清晰 |
| 方案设计 | ✅ 优秀 | 测试控制完整 |
| 风险评估 | ✅ 充分 | 7个风险+缓解措施 |
| 实施计划 | ✅ 详细 | 5.5h工期 |
| 决策确认 | ✅ 通过 | 建议执行 |

### 7.2 第二版改进点

| 改进项 | 说明 |
|--------|------|
| 测试控制 | 新增第八章 |
| 单元测试 | 5个核心用例 |
| 集成测试 | 3个用例 |
| 灰度发布 | 3阶段 |
| 回滚操作 | 详细步骤 |
| 数据校验 | 完整性验证 |
| 工期调整 | 3h → 5.5h |

### 7.3 决策

| 决策项 | 决定 |
|--------|------|
| 是否批准迁移方案 | ✅ 批准 |
| 实施时间 | 尽快（建议 D1） |
| 优先级 | 高 |

### 7.4 建议

1. **建议**: 实施前确认 oc-collab CLI 在 pm-agent 环境中可用
2. **建议**: 灰度发布前在测试环境完整演练
3. **建议**: 备份文件妥善保存

---

## 八、确认签字

| 角色 | 姓名 | 日期 | 确认 |
|------|------|------|------|
| oc-collab PM | Agent1 | 2026-02-23 | ✅ |
| pm-agent PM | 待确认 | - | - |
| test-agent | 待确认 | - | - |

---

**评审结论**: ✅ **通过，建议执行**

---

## 九、附录：评审历史

| 版本 | Commit | 评审人 | 结论 |
|------|--------|--------|------|
| v1 | 33cf1fd4 | agent1 | 通过 |
| v1 | - | agent6 | 需补充测试 |
| v2 | b846e12b | agent1 | 通过 |
