# 代码实现与测试先行规范（必须遵守）

> 全局规则。规定何时必须写测试 + 怎么写（ATDD：验收测试驱动开发）。与 [04-研发工单全流程规范.md](./04-研发工单全流程规范.md) 配套：04 管工单拆分，本规范管实现与验收。

---

## 一、触发条件（什么时候必须写测试）

用户表述满足以下任一条件时，**必须**执行测试先行：

| 触发条件 | 示例 |
|---|---|
| 明确指出 bug（"修正"/"修复"/"不应该"/"404"） | "登录按钮点不了""/sync 404""数据丢了" |
| 要求新增功能 | "加一个导出按钮""新增 XX 端点" |
| 要求修改现有行为 | "把优先级改成默认高""去掉确认弹窗" |

**豁免**（无需测试先行，但改动后必须跑已有测试）：

| 场景 | 示例 |
|---|---|
| 纯配置 | `appsettings.json` 默认值、连接字符串 |
| 纯格式化/注释 | ESLint 自动修复、XML doc 补充 |
| 依赖升级无 API 变更 | NuGet/npm 补丁版本 |
| 文档/规则更新 | 新增 `.trae/rules/` 文件 |

> 判定原则：改动出错用户能感知 → 不可豁免。

---

## 二、强制流程

1. **提炼验收点**：从用户描述提取 Given-When-Then 验收场景（主:分支:异常 ≈ 1:2:2）
2. **RED**：写验收测试，实跑确认失败（失败原因 = 被测功能缺失，非 setup 错误）
3. **GREEN**：写最小量代码使测试通过
4. **REFACTOR**：重构优化，重跑测试仍 GREEN

**不得跳过任何步骤。**

## 三、验收测试用例规范

格式（Given-When-Then）：

```
Given [前置条件]
When  [操作]
Then  [预期结果]
```

示例：`Given 本地 3 个未完成待办 / When POST /api/task 创建"写周报" / Then 返回 201 且共 4 条`

要求：
- 命名体现场景：`CreateTask_EmptyTitle_Returns400`
- 一个测试只验证一个行为点
- 断言可量化
- 至少覆盖集成测试层（不满足于纯单元测试）

## 四、工单完成判定（全部满足才标记"已完成"）

1. 所有验收测试通过
2. 原有测试无回归
3. [04-即时状态记忆.md](../项目/04-即时状态记忆.md) 或 `00-工单总览.md` 待验证表标注"已验证"
4. 按 [03-文档同步规范.md](./03-文档同步规范.md) 同步文档

## 五、Git Checkpoint 提交（推荐）

| 阶段 | 提交信息 |
|---|---|
| RED | `test(workitem): 为 <工单> 添加失败的验收测试` |
| GREEN | `feat(workitem): 实现 <工单> 使验收测试通过` |
| REFACTOR | `refactor(workitem): 重构 <模块> 保持测试通过` |

流程完成前不得 squash。提交信息禁用歧义"任务"二字。

## 六、检查清单

- [ ] 触发条件满足？豁免类是否确认无行为变更？
- [ ] 提炼了 Given-When-Then 验收场景？
- [ ] RED 实跑确认失败，失败原因 = 功能缺失？
- [ ] GREEN 最小代码通过测试？
- [ ] REFACTOR 后测试仍 GREEN？
- [ ] 场景覆盖主/分支/异常？
- [ ] 原有测试无回归？
- [ ] 工单完成四条件全部满足？

---

**关联**：[04-研发工单全流程规范.md](./04-研发工单全流程规范.md)、[03-文档同步规范.md](./03-文档同步规范.md)、[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)