From 33521b8b39463a25d4a884bab6c3fb51e5cf85dd Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sun, 14 Jun 2026 13:56:47 +0800 Subject: [PATCH] =?UTF-8?q?[moz]=20docs:=20=C2=A718=20=E8=81=8C=E8=B4=A3?= =?UTF-8?q?=E5=88=86=E7=A6=BB=20=E2=80=94=20=E6=B5=8B=E8=AF=95=E8=AF=A6?= =?UTF-8?q?=E7=BB=86=E4=BB=A3=E7=A0=81=E7=A7=BB=E5=85=A5=2018-test-design.?= =?UTF-8?q?md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 主文档 §6 只保留概要表格 + 文件指向 - 测试 fixture/完整代码/覆盖矩阵 → 18-test-design.md - 删除误加的 GATE/委派/wiki 章节 - CI 集成改为表格格式 + 引用 --- .../18-api-refactor-and-toolchain-tab.md | 142 ++++-------------- 1 file changed, 29 insertions(+), 113 deletions(-) diff --git a/docs/design/18-api-refactor-and-toolchain-tab.md b/docs/design/18-api-refactor-and-toolchain-tab.md index abf81ef..f46b03a 100644 --- a/docs/design/18-api-refactor-and-toolchain-tab.md +++ b/docs/design/18-api-refactor-and-toolchain-tab.md @@ -381,81 +381,31 @@ fi ### 6.2 expand 聚合测试 -**测试文件**：`tests/integration/test_api.py` 新增 `TestExpandAPI` +**测试文件**：`tests/unit/test_expand_api.py` -```python -class TestExpandAPI: - """expand 聚合接口测试""" - - def test_expand_comments_limit(self, client, project_env): - """comments 返回 limit 20 + total_count""" - # 创建 1 个 task + 25 条 comment - bb = Blackboard(...) - task = bb.create_task(Task(id="t1", ...)) - for i in range(25): - bb.add_comment("t1", agent="a1", comment_type="general", - content=f"comment {i}") - - resp = client.get(f"/api/projects/test-proj/tasks/t1?expand=comments") - data = resp.json() - - assert len(data["comments"]["items"]) == 20 # limit - assert data["comments"]["total_count"] == 25 - assert data["comments"]["limit"] == 20 - - def test_expand_events_limit(self, client, project_env): - """events 返回 limit 30 + total_count""" - # 创建 1 个 task + 35 条 event - ... - - def test_expand_outputs_full(self, client, project_env): - """outputs 全量返回（不限制）""" - ... - - def test_expand_multiple(self, client, project_env): - """expand=comments,outputs 组合""" - ... - - def test_expand_all_compat(self, client, project_env): - """expand=all 向后兼容（返回全部，格式是 list 不是 {items, total_count}）""" - ... - - def test_no_expand(self, client, project_env): - """不传 expand 只返回基本 task""" - ... - - def test_expand_invalid_field_ignored(self, client, project_env): - """expand=invalid_field 不报错，忽略无效字段""" - ... -``` +| 测试用例 | 验证点 | +|---------|--------| +| test_expand_comments_limit | comments 返回最新 20 条 + total_count=25 | +| test_expand_comments_are_latest | 验证返回的是最新 20 条（index 5-24） | +| test_expand_events_limit | events 返回最新 30 条 + total_count=35 | +| test_expand_outputs_full | outputs 全量返回（list 格式，不分页） | +| test_expand_reviews_full | reviews 全量返回 | +| test_expand_decisions_full | decisions 全量返回 | +| test_expand_multiple_fields | expand=comments,outputs,reviews 组合，未请求的不返回 | +| test_expand_all_compat | expand=all 向后兼容 | +| test_no_expand | 不传 expand 只返回基本 task | +| test_expand_invalid_field_ignored | 无效字段静默忽略 | ### 6.3 搜索测试 -```python -class TestTaskSearch: - def test_search_by_title(self, client, project_env): - """q 参数标题模糊搜索""" - bb = Blackboard(...) - bb.create_task(Task(id="t1", title="[moz] bug: Mail API 500")) - bb.create_task(Task(id="t2", title="[moz] feat: new dashboard")) +**测试文件**：`tests/unit/test_task_routes.py` 内 `TestTaskListRoutes` - resp = client.get("/api/projects/test-proj/tasks?q=Mail") - data = resp.json() - assert len(data["tasks"]) == 1 - assert "Mail" in data["tasks"][0]["title"] - - def test_search_case_insensitive(self, client, project_env): - """大小写不敏感""" - ... - - def test_search_empty_q(self, client, project_env): - """q 为空返回全部""" - ... - - def test_search_no_match(self, client, project_env): - """无匹配返回空列表""" - ... -``` +| 测试用例 | 验证点 | +|---------|--------| +| test_list_tasks_with_search | q 参数标题模糊搜索 | +| test_list_tasks_search_case_insensitive | 大小写不敏感 | +| test_list_tasks_search_no_match | 无匹配返回空列表 | +| test_list_tasks_search_empty_q | q 为空返回全部 | ### 6.4 前端测试（手动验证） @@ -469,50 +419,16 @@ class TestTaskSearch: ### 6.5 CI 集成 -新增测试运行命令： +| 命令 | 说明 | +|------|------| +| `bash tests/scripts/verify_api_compat.sh` | 路由兼容性验证（CI 必跑） | +| `pytest tests/unit/test_task_routes.py tests/unit/test_expand_api.py tests/integration/test_api.py -m "not e2e" -v` | 新增单元 + 集成测试 | -```bash -# API 拆分兼容性（CI 必跑） -bash tests/scripts/verify_api_compat.sh - -# 新增单元 + 集成测试 -pytest tests/unit/test_task_routes.py tests/integration/test_api.py -m "not e2e" -v -``` +> 测试用例详细设计（fixture + 完整代码 + 覆盖矩阵）见 `docs/design/18-test-design.md` --- -## 7. 实施约束 - -### 7.1 GATE 门控铁律 - -本任务为 L3（5+ 文件、跨后端重构 + 前端新增），必须遵守： - -1. **需求不清不动手** — 列出假设让用户确认 -2. **方案未定不实现** — 先出方案等确认（本文档即为方案产出） -3. **评估过影响范围才动手** — 见 §8 风险评估 -4. **使用 plan-act-verify skill** — GATE → PLAN → ACT → VERIFY 全流程 - -L1 小改动（单文件 <50 行，做错代价低）可跳过 GATE。 - -### 7.2 委派原则 - -1. **main session 负责**：理解意图、澄清需求、方案决策、结果审查 -2. **需求明确后的所有执行工作 → 通过 subagent-delegation skill 委派**，先阅读 skill 全文再使用 -3. **委派时 task 描述必须自包含**：目标、输入、输出路径、验收标准、关键上下文 -4. **sub 完成后审查产出质量**，发现问题让 sub 修，不自己动手 -5. 保持 main session context 清晰，避免 compact 丢信息 - -### 7.3 wiki 查询规则 - -- 做方案前先查 wiki-vault，有 1% 相关就要查 -- 路径：`/Volumes/KnowledgeBase/wiki-vault/` -- 检索顺序：index.md → grep 关键词 → summary 字段 → 按需读全文 -- 查不到在 `_meta/knowledge-gaps.md` 记录 -- 本设计已查询（无 FastAPI 路由拆分相关实践，已记录 gap） - ---- - -## 8. 实施计划 +## 7. 实施计划 ### Phase 1: 后端 API 拆分（不含功能变更） @@ -554,7 +470,7 @@ L1 小改动（单文件 <50 行，做错代价低）可跳过 GATE。 --- -## 9. 风险评估 +## 8. 风险评估 | 风险 | 级别 | 缓解 | |------|------|------| @@ -565,7 +481,7 @@ L1 小改动（单文件 <50 行，做错代价低）可跳过 GATE。 --- -## 10. 评审记录 +## 9. 评审记录 ### 司马懿 mail-1781415763066（2026-06-14） @@ -580,7 +496,7 @@ L1 小改动（单文件 <50 行，做错代价低）可跳过 GATE。 --- -## 11. 变更记录 +## 10. 变更记录 | 日期 | 版本 | 内容 | |------|------|------|