11 KiB
11 KiB
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 接手流程)
- 开发者执行
submit→ 任务进入review(待验收) - QA 定期拉取待验收队列,找到本次任务
- QA 接手:阅读任务
desc、提交说明、交付物路径 - 按 §3 分级 → §4 执行 → §5 留证据 → 判定
待验收队列检查命令
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. 验收步骤与判定树
四步法
- 阅读交付物:任务
desc+submit提交说明 + 交付文件路径 - 跑测试/命令:按 §3 分级执行清单,PowerShell 实测
- 记录证据:真实命令输出或文件证据(§5)
- 判定:按决策树输出通过 / 不合格
判定树
任务在 review?
├─ 否 → 报错:「只有待验收任务可测试」(状态机固定)
└─ 是 → 按任务 desc 判定分级
├─ P0 代码类
│ ├─ 测试套件全绿 且 功能实测符合预期?
│ │ ├─ 是 → test --pass(附真实证据)
│ │ └─ 否 → test --fail(附具体原因)→ 自动生成 BUG → 修复后重新 submit → 再验收
├─ P1 文档类
│ ├─ 章节/数据/一致性全部核对通过?
│ │ ├─ 是 → test --pass(附核对项)
│ │ └─ 否 → test --fail(指明缺失/不一致的章节与数据)
└─ P2 工程类
├─ 命令实测全部成功且配置正确?
│ ├─ 是 → test --pass(附命令输出)
│ └─ 否 → test --fail(附报错输出)
判定命令
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 修复后复测。