Files
perler-lab/docs/QA-SOP.md
T

223 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PERLER LAB 验收标准操作规程(QA-SOP.md)
> 版本: 1.0 | 执行人: QA-Tester-Agent(唯一验收方) | 关联: TEST-PLAN.md / E2E-REPORT.md / T-082 / T-083
> 用途: 定义"只有 QA 验收"的完整流程,含验收权责、触发条件、分级标准、执行步骤、证据要求、抽检与复审机制。
> 约束: taskboard.js 的状态流转为固定实现,本文档**不新增命令、不修改状态机**,仅规范 QA 的操作行为。
---
## 0. 任务状态机(固定,不可变更)
```
pending(待处理) → in_progress(开发中) → review(待验收) → approved(验收通过)
│
└→ rejected(不合格) ─→ 自动生成 BUG-xxx → pending
approve/rejected → closed(已关闭,归档)
```
| 动作 | 命令 | 前置状态 | 结果 |
|---|---|---|---|
| 认领 | `node taskboard.js claim <id> --agent "<名>"` | pending | in_progress |
| 提交验收 | `node taskboard.js submit <id> --note "<提交说明>"` | in_progress | review |
| 验收通过 | `node taskboard.js test <id> --pass --note "<证据>"` | review | approved |
| 验收不合格 | `node taskboard.js test <id> --fail --note "<原因>"` | review | rejected + 自动生成 BUG |
| 归档 | `node taskboard.js close <id> --note "<说明>"` | rejected/approved/closed | closed |
> 命令一律在 `D:\拼豆\taskboard` 目录下执行。
---
## 1. 验收权责
| 角色 | 允许 | 禁止 |
|---|---|---|
| **QA-Tester-Agent** | 唯一可执行 `test --pass / --fail`;记录验收证据;执行抽检与复审 | 不得让出验收权;不得使用空备注验收(见 §5) |
| **主代理(Sisyphus)** | 发布任务、调度认领、生成看板、监督巡检 | **执行 `test --pass`**。主代理只调度不验收,一切通过/不合格决策归 QA |
| **开发者/实施 Agent** | 开发、`submit` 提交验收、认领 BUG 修复 | 对自己交付的任务执行 `test`(禁止自测自通);验收权限不随实施移交 |
> 例外说明:若 QA 自身为交付人(如 T-083 流程文档类任务),交付物验收仍须以验收视角执行,`--pass` 的备注必须附带**可复核的文件证据**(文件路径 + 抽查结果),并记入 §9 执行记录,供第三方复核。
---
## 2. 验收触发(QA 接手流程)
1. 开发者执行 `submit` → 任务进入 `review`(待验收)
2. QA 定期拉取待验收队列,找到本次任务
3. QA 接手:阅读任务 `desc`、提交说明、交付物路径
4. 按 §3 分级 → §4 执行 → §5 留证据 → 判定
**待验收队列检查命令**
```powershell
cd D:\拼豆\taskboard
node taskboard.js list --status review # 查看待验收队列
node taskboard.js stats # 各状态数量总览
node taskboard.js board # 生成看板(board.md / board.html)
node taskboard.js serve # 实时看板(默认 8787)
```
> 注:`claim` 命令仅对 `pending` 任务生效;`review` 任务由 QA 直接执行 `test` 即视为接手,无需也无法 claim(状态机固定)。
---
## 3. 验收分级
| 分级 | 适用交付物 | 必做动作 | 判定标准 | 参照用例 |
|---|---|---|---|---|
| **P0 代码类** | 算法 / API / UI(支付模块、chibi 生成、前端页面等) | 跑测试套件 + 功能实测 | 单测全绿 + 真实请求/操作全部达到预期 | TEST-PLAN TC-01~08、TC-22 |
| **P1 文档类** | 设计/运营/文案文档(DESIGN.md、LAUNCH.md、copy-library.md 等) | 完整性核对(章节 / 数据 / 一致性) | 章节齐全、关键数据与代码一致、文档间无冲突 | TEST-PLAN TC-09~17 |
| **P2 工程类** | CI/CD、构建配置、脚本、依赖 | 命令实测(build / test / git 等) | 命令真实执行成功,产物与配置符合预期 | TEST-PLAN TC-18~21 |
### 3.1 P0 代码类验收清单
- [ ] `npm test`(vitest run)前后端全部通过
- [ ] `npm run typecheck`(tsc --noEmit)无错误
- [ ] 服务启动实测:`npx tsx src/server.ts` 监听 8788
- [ ] 关键接口真实请求(参考 E2E-REPORT.md 复现步骤),断言状态码 + 关键字段
- [ ] 错误路径实测:非法参数返回 4xx、支付回调幂等、不落脏数据
### 3.2 P1 文档类验收清单
- [ ] 必需章节齐全(对照任务 desc 与 TEST-PLAN 范围表)
- [ ] 关键数据核对:价格/次数/套餐与代码 `PACKAGE_DEFINITIONS` 一致
- [ ] 文档间一致性:LAUNCH.md §3.1 ↔ AGENT.md §4 ↔ copy-library.md ↔ 代码
- [ ] 可直接使用性抽查:话术 / FAQ 复制即可用,非碎片笔记
### 3.3 P2 工程类验收清单
- [ ] `npx actionlint .github/workflows/deploy.yml`(或 yamllint)无语法错误
- [ ] 触发条件、构建步骤、测试阶段、部署动作逐项核对
- [ ] 相关命令真实执行并记录输出(如 `npm run build`)
---
## 4. 验收步骤与判定树
### 四步法
1. **阅读交付物**:任务 `desc` + `submit` 提交说明 + 交付文件路径
2. **跑测试/命令**:按 §3 分级执行清单,PowerShell 实测
3. **记录证据**:真实命令输出或文件证据(§5)
4. **判定**:按决策树输出通过 / 不合格
### 判定树
```text
任务在 review?
├─ 否 → 报错:「只有待验收任务可测试」(状态机固定)
└─ 是 → 按任务 desc 判定分级
├─ P0 代码类
│ ├─ 测试套件全绿 且 功能实测符合预期?
│ │ ├─ 是 → test --pass(附真实证据)
│ │ └─ 否 → test --fail(附具体原因)→ 自动生成 BUG → 修复后重新 submit → 再验收
├─ P1 文档类
│ ├─ 章节/数据/一致性全部核对通过?
│ │ ├─ 是 → test --pass(附核对项)
│ │ └─ 否 → test --fail(指明缺失/不一致的章节与数据)
└─ P2 工程类
├─ 命令实测全部成功且配置正确?
│ ├─ 是 → test --pass(附命令输出)
│ └─ 否 → test --fail(附报错输出)
```
### 判定命令
```powershell
cd D:\拼豆\taskboard
# 通过(note 必须含真实证据,格式见 §5)
node taskboard.js test T-024 --pass --note "QA验收:vitest 36/36 PASS;tsc --noEmit 0错误;POST /api/orders 返回 200 status=pending amountCents=1290;pay-callback 重复 2 次 access_code 不变(见 E2E-REPORT.md)"
# 不合格(note 写具体原因,可加 --priority 调整 BUG 优先级)
node taskboard.js test T-024 --fail --note "TC-03 失败:pay-callback 返回 500 且 access_code 为空,服务日志见 perler-lab-server/logs/…"
```
### 不合格的闭环
- `test --fail` 自动生成 `BUG-xxx`(进入 pending,未认领)
- 开发者认领 BUG → 修复 → `submit` → 进入 review
- QA 验收该 BUG `--pass` → **自动联动**:父任务从 rejected 重置为 review,重新进入验收
---
## 5. 验收证据要求
> 核心规则:**每个 `--pass` 的备注必须包含真实命令输出或文件证据;禁止空备注、禁止"看起来没问题"式描述。**
| 证据类型 | 合格示例 | 不合格示例 |
|---|---|---|
| 命令输出 | `vitest run 通过 36/36` | `测试通过` |
| 接口响应 | `POST /api/orders → 200, status=pending, amountCents=1290, orderNo=PL…` | `接口正常` |
| 文件证据 | `docs/E2E-REPORT.md 步骤 5-6 断言 PASS` | `详见报告` |
| 数据核对 | `LAUNCH.md §3.1 与 PACKAGE_DEFINITIONS 三档价格完全一致` | `价格一致` |
| 命令实测 | `npx actionlint 退出码 0,无语法错误` | `workflow 正常` |
**推荐备注格式**(一行为一类证据,可读性优先):
```
QA验收:<测试套件结果>;<类型检查结果>;<功能实测 1~N 条断言>;<文件证据路径>
```
**硬性禁止**:`--note "通过"`、`--note ""`、`--note "验收通过"` 等无实质证据的备注。违反即视为验收无效,需补测。
---
## 6. 抽检机制
- **批次定义**:每批交付按 ≥10 个任务计,或按一次看板生成周期内的验收批次计
- **抽检比例**:每批抽 **20%**(不足 10 个任务的批次至少抽 1 个)已 approved 任务复测
- **复测方法**:重跑该任务验收时使用的命令与用例,比对验收备注与当前实测结果
- **触发全量复审**:抽查不合格率 **>10%**(FAIL 样本数 / 抽样数 > 0.1)→ 对该批**全部 approved 任务逐一复审**
- 抽查记录写入 §9 执行记录表
**示例**:一批 20 个任务 → 抽 4 个复测;若 ≥1 个不合格(25% > 10%)→ 全量复审全部 20 个。
---
## 7. 复审规则(历史任务)
- 依据 **T-082**:QA 对主代理此前直接验收的 **36 个任务**做批量复审
- 复审口径:按 TEST-PLAN.md 用例逐条抽查(抽样 ≥20%),重点核对验收备注是否含真实证据
- 处理结果:合格项维持 approved;不合格项记录证据并退回修复(关联 BUG),结论记入 T-082 的验收记录
---
## 8. 快速参考(命令速查表)
### 8.1 任务板命令(在 `D:\拼豆\taskboard` 下执行)
| 场景 | 命令 |
|---|---|
| 查看待验收队列 | `node taskboard.js list --status review` |
| 总览状态统计 | `node taskboard.js stats` |
| 生成看板 | `node taskboard.js board` |
| 启动实时看板 | `node taskboard.js serve [port]` |
| 查看在册 Agent | `node taskboard.js agents` |
| 认领任务 | `node taskboard.js claim <id> --agent "<名>"` |
| 提交验收(开发者) | `node taskboard.js submit <id> --note "<提交说明>"` |
| 验收通过(仅 QA) | `node taskboard.js test <id> --pass --note "QA验收:<证据>"` |
| 验收不合格(仅 QA) | `node taskboard.js test <id> --fail --note "<具体原因>" [--priority high\|medium\|low]` |
| 归档 | `node taskboard.js close <id> --note "<说明>"` |
### 8.2 工程实测命令(P0 / P2 用)
| 场景 | 命令 |
|---|---|
| 后端单测 | `cd D:\拼豆\perler-lab-server && npm test` |
| 后端类型检查 | `cd D:\拼豆\perler-lab-server && npm run typecheck` |
| 后端构建 | `cd D:\拼豆\perler-lab-server && npm run build` |
| 后端启动(实测 8788) | `cd D:\拼豆\perler-lab-server && npm start`(或 `npx tsx src/server.ts`) |
| 前端单测 | `cd D:\拼豆\perler-lab && npm test` |
| 前端构建 | `cd D:\拼豆\perler-lab && npm run build` |
| Workflow 校验 | `npx actionlint .github/workflows/deploy.yml` |
---
## 9. 执行记录
| 日期 | 任务 | 分级 | 结论 | 证据摘要 | 执行人 |
|---|---|---|---|---|---|
| (待填写) | | | | | QA-Tester-Agent |
> 通过标准:每项验收须同时满足「分级清单全过 + 证据真实 + 状态机正确」;任一 FAIL 需记录现象并转 BUG 修复后复测。