---
name: tdd-workflow
description: >-
  仅当用户显式要求写测试时的 TDD 全流程。触发场景只有：用户明确说了
  「加测试」「写测试用例」「补测试」「补一条回归用例」「TDD」「测试先行」等，
  明确表示要写测试代码时才触发本 Skill。其他情况下收到新需求/功能开发，
  一律走 /visual-report 的可视化验证流程，禁止本 Skill 被默认触发。
  触发后严格按：需求记录→确认版本→测试先行→基线回归→实现代码→全量回归→上线前回归，七步执行。
---

# TDD 开发流程

⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `tdd-workflow`，用户显式要求写测试，按 TDD 七步流程开发...」然后严格按照以下步骤执行，不得跳过。**

⚠️ 只有在用户显式要求「写测试 / TDD」时才进入本流程。若用户只是说「做功能 / 开发需求 / 改代码」，而未提测试，第一反应是走 `/visual-report` 的可视化验证流程，不触发本 Skill。

测试驱动开发，每次接收新需求时强制遵循（前提：用户已显式要求写测试）。

## 七步流程

### 第 1 步：需求记录（留痕）

在 `docs/` 目录下新建需求文档（HTML 格式，中文命名），记录：
- 需求背景
- 功能范围
- 验收标准
- 所属版本号（未说明则归「全量测试」）

### 第 2 步：确认归属版本

明确写入：「归属版本：XXX」或「归属范围：全量测试」。

### 第 3 步：测试先行

⚠️ 先写测试用例，再写业务代码：

| 类型 | 位置 |
|------|------|
| Go 后端 | `app/supply/`、`app/controller/` 下写 `_test.go` |
| 前端 UI | `admin_web/e2e/` 或 `user_web/e2e/` 下写 Playwright E2E |
| API 接口 | `scripts/regression-api-smoke.js` 加冒烟子命令 |

然后在 `scripts/superpowers-regression-runner.js` 的 `TEST_CASES` 中注册新用例。
测试用例描述、断言必须使用中文。

**测试用例编写规范**：
- 先写主流程（happy path），再写边界情况
- 必须模拟真实用户操作：打开页面 → 查看状态 → 点击/填写 → 提交 → 验证结果
- 覆盖：新建、编辑、删除、查看/搜索、状态流转、异常操作
- 每条测试用例必须附带对应步骤的截图

**⚠️ 用户视角先行（写用例前强制）**：
1. **先列「用户操作路径清单」**：这个功能的用户（不是开发）在哪个页面、依次点了什么按钮、填了什么表单、提交后页面变成什么样。清单写出来之前，禁止动笔写测试代码。
2. **前端可操作功能必须页面驱动**：用 Playwright E2E / agent-browser 模拟真实点击、填写、提交、等待渲染，断言页面上的可见结果（元素、状态、提示），并逐步骤截图。禁止用 `curl` 直接调 API 代替页面操作——API 通不等于用户点按钮能用，中间隔着 JS 报错、参数拼错、字段绑定、权限拦截、渲染失败等风险。
3. **API 冒烟测试只给纯后端接口**：只有无页面入口的纯接口 / 定时任务链路，才允许写 `regression-api-smoke.js` 冒烟用例；且只能作为「数据准备」或「结果核验」的辅助手段，不能代替页面主验证。
4. **能手动操作就手动**：编写测试时，凡能用真实浏览器手动点一遍验证的，先手动点一遍确认页面真实行为，再据此写自动化用例，不要凭空猜页面行为。

### 第 4 步：跑基线回归

⚠️ 改代码之前，先跑一次全量回归建立基线：

```bash
pnpm run regression:open
```
确认改动前所有已有用例全部通过。

### 第 5 步：实现业务代码

按需求文档和测试用例实现功能，持续跑新增测试用例。

### 第 6 步：跑全量回归

⚠️ 改完代码后跑全量回归，确认：
- 新增用例全部通过
- 所有已有用例仍然通过

### 第 7 步：上线前回归

⚠️ 每次部署生产前，必须跑：
```bash
node 上线回归测试点.js
```

## 重要规则

- ⚠️ 本流程仅在用户显式要求测试时才触发（见文件头部触发条件）
- ⚠️ 改动必须有迹可循：需求文档 → 测试用例 → 回归报告 → 代码改动
- 如果用户说「直接改就行不用测试」，尊重用户决定，不写测试用例，改用 `/visual-report` 的可视化验证
- 测试用例命名含需求关键词，方便追溯