auto-sync: 2026-05-18 13:30:01

docs/test-plan-e2e-v27.md

@@ -0,0 +1,88 @@
+# 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. 不影响已有项目数据