Files

11 KiB
Raw Permalink Blame History

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 留证据 → 判定

待验收队列检查命令

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. 判定:按决策树输出通过 / 不合格

判定树

任务在 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 修复后复测。