# 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 --agent "<名>"` | pending | in_progress | | 提交验收 | `node taskboard.js submit --note "<提交说明>"` | in_progress | review | | 验收通过 | `node taskboard.js test --pass --note "<证据>"` | review | approved | | 验收不合格 | `node taskboard.js test --fail --note "<原因>"` | review | rejected + 自动生成 BUG | | 归档 | `node taskboard.js close --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 --agent "<名>"` | | 提交验收(开发者) | `node taskboard.js submit --note "<提交说明>"` | | 验收通过(仅 QA) | `node taskboard.js test --pass --note "QA验收:<证据>"` | | 验收不合格(仅 QA) | `node taskboard.js test --fail --note "<具体原因>" [--priority high\|medium\|low]` | | 归档 | `node taskboard.js close --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 修复后复测。