chore: deploy 触发分支改 master,竞品调研/原型/色板/i18n/分享组件/文档等成果入库
This commit is contained in:
1 parent
5a97e6124e
commit
40e2342a02
75 files changed
+6848
-540
No files matched your search
+222
@@ -0,0 +1,222 @@
|
||||
# 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 修复后复测。
|
||||
Reference in new issue
Block a user