# v2.7 端到端测试方案

> 日期：2026-05-18
> 作者：司马懿
> 环境：真实部署（`~/.sanguo_projects/sanguo_moziplus_v2/`）+ 真实 Agent

---

## 一、测试策略

- **框架**：pytest + FastAPI TestClient（直接挂载 app，绕过网络层，但走完整业务逻辑）
- **数据隔离**：每个测试 class 用独立项目 ID，测试前创建、测试后清理
- **Agent 策略**：E1-E8 不启动真实 Agent（只验证 API + DB），E9-E10 启动真实 Agent 执行简单任务
- **Ticker**：手动调用 `ticker.tick()` 而非等待 30s 循环
- **测试项目**：统一前缀 `e2e-v27-`，便于识别和清理

## 二、场景清单

### E1: 项目管理（4 个测试）
- E1.1 创建项目（POST /api/projects）
- E1.2 项目列表（GET /api/projects）
- E1.3 自动发现（含 blackboard.db 的目录）
- E1.4 归档项目（status=archived，目录不移动）

### E2: Task CRUD + 状态机（5 个测试）
- E2.1 创建 Task（POST /api/projects/{pid}/tasks）
- E2.2 查询 Task（GET，expand=all）
- E2.3 合法状态转换（pending → claimed → working → review → done）
- E2.4 非法转换拒绝（409 + valid_transitions）
- E2.5 列表筛选（status/assignee/parent_task）

### E3: SubTask 父子关系（4 个测试）
- E3.1 创建父 Task + 3 个子 Task
- E3.2 list_subtasks 验证
- E3.3 top_level_tasks 排除子 Task
- E3.4 子 Task 的 stage 字段

### E4: Stage 进度（3 个测试）
- E4.1 带 stages_json 的父 Task → 子 Task 分配到各 stage → progress 端点
- E4.2 空 stage 的父 Task 进度
- E4.3 stage 分组统计验证

### E5: 父 Task 状态聚合（6 个测试）
- E5.1 all done → 父 done
- E5.2 has review → 父 review
- E5.3 has working → 父 working
- E5.4 all pending → 父 pending
- E5.5 cancelled 子 Task 排除
- E5.6 手动状态（cancelled 父 Task）不被覆盖

### E6: 依赖链（3 个测试）
- E6.1 Task B depends_on Task A，A done 后 B 自动 pending（Ticker 推进）
- E6.2 A 未完成时 B 保持 blocked
- E6.3 多层依赖（A → B → C）

### E7: 超时回收（2 个测试）
- E7.1 claimed 超时 → pending
- E7.2 working 超时 → failed

### E8: Mail Tab 6 端点（7 个测试）
- E8.1 发送 Mail（inform 类型 → 自动 done）
- E8.2 发送 Mail（task-assign 类型 → pending）
- E8.3 Mail 列表 + 筛选（from/to/unread）
- E8.4 Mail 详情（含 comments）
- E8.5 标记已读
- E8.6 标记已执行
- E8.7 Mail summary + agents 列表

### E9: 真实 Agent 调度（2 个测试）
- E9.1 创建简单 Task → Ticker 调度 → Agent spawn → Agent 回写 working → 完成任务
- E9.2 创建 review 类型 Task → 调度到 simayi-challenger → 回写 review 结果
- **Agent 任务内容**：简单的"echo hello"级别任务，10-30 秒完成

### E10: 全链路集成（1 个测试）
- E10.1 创建项目 → 创建父 Task（stages_json）+ 3 个子 Task → Ticker tick → 依赖推进 → 聚合刷新 → Mail 通知 → 验证完整状态链

## 三、通过标准

- **P0 必须全部通过**：E1-E8 + E10
- **P1 通过率 ≥ 80%**：E9（依赖真实 Agent，可能受网络/环境干扰）
- **总测试用例**：约 37 个

## 四、清理策略

测试完成后：
1. 删除测试项目目录（`data/e2e-v27-*`）
2. 清理 `_mail` 项目中测试数据
3. 不影响已有项目数据
