jsharness 1.0.0

package/.harness/docs/team-guidelines/qa-team.md

@@ -0,0 +1,562 @@
+# 测试团队 (QA) Harness 使用规范
+
+> **适用角色**: 测试工程师、QA 工程师、SDET  
+> **对应 Agent**: 测试验证 Agent (tester)  
+> **模型档位**: Strong（强模型，确保测试深度）  
+> **参考契约**: `.harness/agents/tester/contract.yaml`  
+> **参考 Prompt**: `.harness/agents/prompt-templates.md` → 测试验证 Agent 部分  
+> **技能参考**: `skills/test-unit.md` / `skills/test-e2e.md` / `skills/test-api.md`  
+
+---
+
+## 一、角色定位：你是质量的最终守门员
+
+### 1.1 核心职责
+
+```
+┌────────────────────────────────────────────────┐
+│          QA 团队的五大核心职责                   │
+├────────────────────────────────────────────────┤
+│  ① 制定测试策略 — 根据需求和风险规划测试方案      │
+│  ② 设计测试用例 — 基于验收标准设计全面用例        │
+│  ③ 执行测试 — 按计划执行各类测试                 │
+│  ④ 缺陷管理 — 发现、记录、跟踪、验证缺陷           │
+│  ⑤ 质量评估 — 输出 PASS/FAIL 结论和测试报告       │
+└────────────────────────────────────────────────┘
+```
+
+### 1.2 绝对禁止做的事
+
+| # | 禁止行为 | 后果 |
+|---|---------|------|
+| 1 | **降低验收标准以通过** | 严重违规，测试结果作废 |
+| 2 | **省略必测项目**（如跳过 E2E） | 测试报告无效 |
+| 3 | **修改被测代码**来让测试通过 | 致命违规，通报处理 |
+| 4 | **隐瞒已知缺陷** | 绩效一票否决 |
+| 5 | **P0/P1 缺陷不立即阻断升级** | 追究责任 |
+| 6 | **无测试依据地给出 PASS 结论** | 测试无效重做 |
+
+---
+
+## 二、测试覆盖矩阵
+
+### 2.1 测试分层与责任划分
+
+```
+                    ┌─────────────────────┐
+                    │    生产环境监控      │
+                    │   (线上告警/日志)    │
+                    └─────────┬───────────┘
+                              │
+                    ┌─────────▼───────────┐
+                    │   E2E 关键路径测试    │ ◀── QA 负责（预发布前）
+                    │   (真实用户场景模拟)  │
+                    └─────────┬───────────┘
+                              │
+           ┌──────────────────┼──────────────────┐
+           │                  │                   │
+    ┌──────▼──────┐   ┌───────▼───────┐   ┌──────▼──────┐
+    │ API 集成测试 │   │  单元测试      │   │  静态检查    │
+    │ (接口契约)   │   │ (逻辑正确性)   │   │ (Lint/安全)  │
+    └──────┬──────┘   └───────┬───────┘   └──────┬──────┘
+           │                  │                   │
+        QA 负责            Dev 负责           Gate 自动化
+       (PR 前)           (开发时)           (每次 commit)
+```
+
+### 2.2 各层测试详细要求
+
+| 测试类型 | 执行时机 | 执行者 | 通过标准 | 参考技能文档 |
+|---------|---------|--------|---------|-------------|
+| **静态检查** | 每次 commit | Gate 自动 | 零 error | `skills/lint-check.md` |
+| **单元测试** | 开发阶段 | Developer | 覆盖率达标 + 全部通过 | `skills/test-unit.md` |
+| **API 集成测试** | PR 合并前 | **QA** | 无破坏性变更 + 全部通过 | `skills/test-api.md` |
+| **E2E 关键路径** | 预发布前 | **QA** | 核心路径 100% 通过 | `skills/test-e2e.md` |
+| **安全扫描** | 每次 build | Gate 自动 | 零 HIGH/CRITICAL | `gate/checks/security-quality.js` |
+| **性能测试** | 发布前（按需） | **QA** | 满足 NFR 指标 | 自定义方案 |
+| **回归测试** | 发布前 | **QA** | 零 P0/P1 回归 | `skills/test-e2e.md` |
+
+---
+
+## 三、测试工作流详解
+
+### 3.1 ⑥ 测试验证阶段 — 主流程
+
+```
+进入测试阶段
+    │
+    ▼
+① 阅读需求文档 + 验收标准 + 设计文档
+    │
+    ▼
+② 制定测试计划（test-plan.md）
+    │
+    ▼
+③ 设计测试用例（基于 Given/When/Then）
+    │
+    ▼
+④ 设置测试环境和测试数据
+    │
+    ▼
+⑤ 执行测试（按优先级顺序）
+    │
+    ├─ P0 用例 → 全部通过?
+    │   └─ NO → 🔴 立即阻断，报 P0 缺陷
+    │
+    ├─ P1 用例 → 全部通过?
+    │   └─ NO → 🟠 报 P1 缺陷，打回开发修复
+    │
+    ├─ P2/P3 用例 → 通过?
+    │   └─ NO → 🟡 记录缺陷，可后续修复
+    │
+    ▼
+⑥ 执行回归测试
+    │
+    ▼
+⑦ 运行 Gate 安全+一致性检查
+    │
+    ▼
+⑧ 输出测试报告
+    │
+    ▼
+⑨ 做出 PASS/FIX_AND_RETEST 裁决
+```
+
+### 3.2 测试计划模板
+
+```markdown
+# 测试计划: {任务名称}
+
+## 基本信息
+- **任务ID**: TASK-YYYY-NNN
+- **测试负责人**: {姓名}
+- **计划开始日期**: YYYY-MM-DD
+- **预计完成日期**: YYYY-MM-DD
+- **关联需求**: {requirements-{id}.md}
+- **关联设计**: {design-{id}.md}
+
+## 测试范围
+### 包含
+- 功能模块 A：xxx
+- 功能模块 B：xxx
+- API 端点：GET /api/xxx, POST /api/xxx
+- E2E 场景：用户注册→登录→下单
+
+### 不包含
+- （明确写出本次不测什么及原因）
+- 第三方支付回调（依赖外部环境）
+- 性能测试（单独安排）
+
+## 测试策略
+| 层级 | 方法 | 工具 | 用例数估计 |
+|-----|------|-----|-----------|
+| API 集成测试 | 契约测试 | Jest/Supertest | ~XX |
+| E2E 测试 | 关键路径 | Playwright/Cypress | ~XX |
+| 回归测试 | 冒烟+全量 | 组合工具 | ~XX |
+| 安全扫描 | 自动化 | npm audit/Snyk | 自动 |
+
+## 测试环境
+- **前端地址**: http://localhost:{port}
+- **后端地址**: http://localhost:{port}
+- **数据库**: {类型}://{host}:{port}/{db}
+- **测试数据**: 使用 seed 脚本初始化
+
+## 准入条件
+- [ ] 代码审查通过（PASS 或 条件 PASS）
+- [ ] 开发自检通过（Build/Test/Lint）
+- [ ] 部署到测试环境成功
+- [ ] 测试数据准备完毕
+
+## 风险与应对
+| 风险 | 影响 | 概率 | 应对措施 |
+|-----|------|-----|---------|
+| 环境不稳定 | 测试误判 | 中 | 重试机制 + 环境检查脚本 |
+| 第三方服务不可用 | 部分用例跳过 | 低 | Mock 方案 |
+```
+
+### 3.3 测试用例设计规范
+
+#### 基于 Given/When/Then 格式
+
+```markdown
+## TC-{编号}: {用例名称}
+
+**优先级**: P0/P1/P2/P3  
+**前置条件**: {测试前的系统状态}  
+**验收标准关联**: AC-{编号}
+
+### Given（给定）
+{系统处于某个状态 / 某些数据已存在 / 用户已登录等}
+
+### When（当）
+{执行某个操作 / 调用某个 API / 点击某个按钮}
+
+### Then（那么）
+{期望的结果 / 返回值 / 状态变化}
+
+### 示例数据
+```json
+{"input": "...", "expected_output": "..."}
+```
+```
+
+**具体示例**：
+
+```markdown
+## TC-001: 用户使用有效凭证成功登录
+
+**优先级**: P0  
+**前置条件**: 用户已在系统中注册且状态正常  
+**验收标准关联**: AC-01
+
+### Given
+- 系统正常运行
+- 数据库中存在用户：username="testuser", password="Test@123456"
+- 该用户状态为"正常"
+
+### When
+- 用户访问登录页面 `/login`
+- 输入用户名："testuser"
+- 输入密码："Test@123456"
+- 点击"登录"按钮
+
+### Then
+- 页面跳转到首页 `/dashboard`
+- 显示欢迎信息："你好，testuser"
+- 返回 HTTP 200
+- Response Body 包含有效的 token
+- token 有效期为 24 小时
+```
+
+### 3.4 缺陷管理规范
+
+#### 缺陷分级标准
+
+| 等级 | 定义 | 响应时间 | 修复时限 | 示例 |
+|-----|------|---------|---------|------|
+| **P0 致命** | 系统崩溃、数据丢失、安全漏洞 | 立即阻断 | 立即 | 生产宕机、DB 删除错乱、SQL 注入 |
+| **P1 严重** | 核心功能不可用、无 workaround | 24h 内修复 | 24h | 登录失败、支付失败、关键 API 500 |
+| **P2 一般** | 功能异常但有 workaround | 本迭代内 | 3-5 天 | 搜索结果排序错误、样式偏移 |
+| **P3 轻微** | UI 瑕疵、体验问题 | 下版本 | 下迭代 | 按钮 hover 颜色不一致 |
+| **P4 建议** | 优化项、锦上添花 | 待定 | 待定 | 加载动画不够流畅 |
+
+#### 缺陷报告模板
+
+```markdown
+# 缺陷报告: DEF-{YYYY}-{NNN}
+
+## 基本信息
+- **标题**: {简洁描述缺陷}
+- **严重程度**: P0/P1/P2/P3/P4
+- **优先级**: 紧急/高/中/低
+- **状态**: 新建/已确认/修复中/待验证/已关闭/重新打开
+- **报告人**: {姓名}
+- **报告日期**: YYYY-MM-DD HH:MM
+- **指派给**: {开发者姓名}
+- **关联任务**: TASK-YYYY-NNN
+- **关联用例**: TC-XXX
+
+## 环境
+- **浏览器**: Chrome 120.0 / Firefox 121.0 / Safari 17.1
+- **操作系统**: Windows 11 / macOS 14 / Ubuntu 22.04
+- **设备**: Desktop / iPhone 15 Pro / Android 14
+- **测试环境**: staging / test
+- **应用版本**: v1.x.x (commit: abc1234)
+
+## 复现步骤
+1. 打开页面 `{URL}`
+2. 操作：{具体操作步骤}
+3. 输入：{具体输入数据}
+4. 点击：{按钮/链接}
+
+## 期望结果
+{描述预期的正确行为}
+
+## 实际结果
+{描述观察到的错误行为}
+
+## 附件
+- 截图: {截图文件}
+- 日志: {日志片段}
+- 录屏: {GIF/视频链接}
+
+## 根因分析（可选）
+{初步判断的可能原因}
+
+## 建议
+{给开发者的修复建议（可选）}
+```
+
+#### 缺陷生命周期
+
+```
+新建 → QA确认有效性 → 指派给开发者 → 开发者修复 
+  → 修复完成 → QA回归验证 
+    ├── 通过 → 关闭缺陷 ✓
+    └── 未通过 → 重新打开 → 回到开发者
+```
+
+### 3.5 PASS 条件
+
+**测试阶段 PASS 的必要条件（全部满足）**：
+
+| 条件 | 标准 | 检查方式 |
+|-----|------|---------|
+| P0 缺陷 | **= 0** | 缺陷列表统计 |
+| P1 缺陷 | **= 0** | 缺陷列表统计 |
+| 核心 E2E 路径 | **100% 通过** | E2E 测试报告 |
+| API 契约 | **无破坏性变更** | API 对比测试 |
+| 测试覆盖率 | **不低于基线** | Gate C 类报告 |
+| 安全扫描 | **零 HIGH/CRITICAL** | Gate D 类报告 |
+
+**任一条件不满足 → FIX_AND_RETEST（打回开发修复后重测）**
+
+---
+
+## 四、特殊场景处理
+
+### 4.1 发现安全漏洞时的处理
+
+```
+发现疑似安全问题
+    │
+    ▼
+立即停止当前测试
+    │
+    ▼
+记录详细信息（复现步骤、证据截图）
+    │
+    ▼
+1小时内升级到闸门总控(Gate Controller)
+    │
+    ▼
+等待安全评估结论
+    │
+    ├── 确认为漏洞 → 进入安全修复流程
+    └── 排除 → 继续正常测试（记录备案）
+```
+
+**安全漏洞报告特殊要求**：
+- 标题必须加 `[SECURITY]` 前缀
+- 严禁在公开渠道（普通 Issue/群聊）讨论详情
+- 仅限发送给安全负责人和闸门总控
+
+### 4.2 发现设计缺陷导致无法验收
+
+```
+测试中发现功能无法按验收标准验证
+    │
+    ▼
+排除环境/数据/操作问题（确认为设计问题）
+    │
+    ▼
+记录具体哪些验收标准无法满足
+    │
+    ▼
+发起 DESIGN_ISSUE 上游请求
+    │
+    → 回退到方案设计阶段
+    → 方案设计师修改设计
+    → 重新进入开发→审查→测试流程
+```
+
+### 4.3 回归风险管理
+
+**每次测试必须执行的回归检查**：
+
+| 检查项 | 方法 | 判断标准 |
+|-------|------|---------|
+| 已修复缺陷是否复发 | 执行该缺陷的复现步骤 | 不再出现 |
+| 相关功能是否受影响 | 执行相邻功能的冒烟测试 | 正常工作 |
+| 核心链路是否正常 | 执行核心 E2E 场景 | 全部通过 |
+| 性能无明显退化 | 对比上次基准数据 | 波动 < 10% |
+
+**回归风险评估矩阵**：
+
+```markdown
+## 回归风险评估: {任务名称}
+
+| 影响域 | 影响范围 | 风险等级 | 回归测试策略 |
+|-------|---------|---------|------------|
+| 用户认证模块 | 登录/注册/密码重置 | 高 | 全量回归 |
+| 订单模块 | 下单/支付/退款 | 高 | 全量回归 |
+| 通知模块 | 邮件/短信推送 | 中 | 冒烟+关键路径 |
+| 静态页面 | 关于我们/帮助中心 | 低 | 抽样检查 |
+```
+
+---
+
+## 五、测试报告规范
+
+### 5.1 测试报告模板
+
+```markdown
+# 测试报告: {任务名称}
+
+## 报告概要
+- **任务ID**: TASK-YYYY-NNN
+- **测试负责人**: {姓名}
+- **测试日期范围**: YYYY-MM-DD ~ YYYY-MM-DD
+- **测试结论**: ✅ PASS / ❌ FIX_AND_RETEST
+
+## 执行汇总
+| 指标 | 数值 |
+|-----|------|
+| 计划用例总数 | XX |
+| 已执行用例数 | XX |
+| 通过 | XX (XX%) |
+| 失败 | XX (XX%) |
+| 阻塞 | XX (XX%) |
+| 跳过 | XX (XX%) |
+
+## 缺陷汇总
+| 等级 | 新发现 | 已修复 | 待修复 | 仍开放 |
+|-----|-------|-------|-------|-------|
+| P0 | 0 | 0 | 0 | **0** |
+| P1 | X | X | X | **0** (PASS 要求) |
+| P2 | X | X | X | X |
+| P3 | X | X | X | X |
+
+## Gate 检查结果
+| 检查类别 | 结果 | 详情 |
+|---------|------|------|
+| 静态检查(A) | PASS/WARNING/FAIL | |
+| 构建检查(B) | PASS/FAIL | |
+| 测试合规(C) | PASS/FAIL | 覆盖率 XX% |
+| 安全扫描(D) | PASS/FAIL | X 个 HIGH, Y 个 CRITICAL |
+| 工程一致性(E) | PASS/WARNING/FAIL | |
+
+## 各层级测试详情
+
+### 单元测试（Dev 负责）
+- 状态: ✅ PASS / ❌ FAIL
+- 覆盖率: XX%
+- 备注:
+
+### API 集成测试
+- 状态: ✅ PASS / ❌ FAIL
+- 用例数: XX / XX 通过
+- 失败详情:
+
+### E2E 关键路径测试
+- 状态: ✅ PASS / ❌ FAIL
+- 核心场景: XX / XX 通过
+- 失败详情:
+
+### 安全扫描
+- 状态: ✅ PASS / ❌ FAIL
+- CVE 数量: X (HIGH: Y, CRITICAL: Z)
+- 详情:
+
+### 回归测试
+- 状态: ✅ PASS / ❌ FAIL
+- 回归用例: XX / XX 通过
+- 新发现问题: X
+
+## 遗留问题清单
+（如有 P2/P3/P4 未修复缺陷，在此列出让步接受的理由）
+
+## 测试结论与建议
+
+### 结论: ✅ PASS / ❌ FIX_AND_RETEST
+
+### 理由:
+（基于数据和证据给出结论）
+
+### 建议:
+（对后续发布的建议）
+
+## 签署
+- **测试负责人**: _______________ 日期: _______
+```
+
+---
+
+## 六、与其他团队的协作规范
+
+### 6.1 与开发者的协作
+
+| 场景 | QA 做 | QA 不做 |
+|-----|------|--------|
+| 报告缺陷 | 提供完整的复现步骤和数据 | 不要只说"它坏了" |
+| 缺陷讨论 | 基于事实和验收标准争论 | 不做个人攻击 |
+| 修复验证 | 及时验证修复（24h内） | 不无限拖延验证 |
+| 需求澄清 | 向 PM/需求分析师提问 | 不自行解释需求含义 |
+
+### 6.2 与 PM 的协作
+
+| 场景 | QA 做 | QA 不做 |
+|-----|------|--------|
+| 验收标准质疑 | 基于可测试性提出修改建议 | 不自行降低标准 |
+| 优先级争议 | 用数据说话（用户影响面） | 不被"赶进度"压力妥协 |
+| 上线决策支持 | 提供客观的质量评估 | 不做商业判断 |
+
+### 6.3 与闸门总控的协作
+
+- **安全漏洞**: 必须在 1 小时内升级报告
+- **设计缺陷**: 通过正式流程发 DESIGN_ISSUE
+- **质量数据**: 提供准确的数据支撑裁决
+
+---
+
+## 七、绩效考核关联指标
+
+| 指标 | 目标值 | 权重 | 数据来源 |
+|-----|-------|------|---------|
+| 缺陷漏测率（上线后发现 P0/P1） | ≤ 5% | 25%（关键） | 线上故障追踪 |
+| 测试用例覆盖率（需求→用例映射） | ≥ 95% | 15% | 测试计划 vs 需求 |
+| 缺陷报告质量（一次确认率） | ≥ 85% | 15% | 开发者反馈 |
+| 测试执行及时性 | 按计划完成 | 15% | TaskBoard |
+| 安全漏洞识别率 | 100% | 15%（关键） | 安全审计 |
+| 测试文档完整性 | 100% | 10% | 抽查 |
+| 回归测试有效性（不引入新回归） | 0 P0/P1 回归 | 5% | 回归报告 |
+
+---
+
+## 八、常用命令与工具
+
+```bash
+# === 运行各类测试 ===
+npm run test                # 单元测试（Dev 负责，QA 可复查）
+npm run test:e2e            # E2E 测试
+npm run test:api            # API 集成测试
+npm run test:regression     # 回归测试套件
+
+# === Gate 检查 ===
+node .harness/gate/index.js                      # 完整质量门禁
+node .harness/gate/index.js --baseline           # 对比基线（检测回归）
+
+# === 安全扫描 ===
+npm audit                                          # CVE 依赖审计
+npx snyk test                                      # Snyk 安全扫描
+
+# === 查看参考文档 ===
+cat .harness/skills/test-e2e.md                   # E2E 测试技能
+cat .harness/skills/test-api.md                   # API 测试技能
+cat .harness/agents/tester/contract.yaml          # 测试契约
+```
+
+---
+
+## 九、QA 每日/每周 Checklist
+
+### 每日开工
+- [ ] 查看 TaskBoard，了解今日到期任务
+- [ ] 检查昨日缺陷的修复状态
+- [ ] 确认测试环境可用性
+- [ ] 安排当日测试执行计划
+
+### 每日下班
+- [ ] 更新缺陷状态
+- [ ] 更新测试进度到 TaskBoard
+- [ ] 记录发现的阻塞点
+
+### 每周五
+- [ ] 汇总本周缺陷统计
+- [ ] 评估各任务测试进度
+- [ ] 识别下周风险点
+- [ ] 更新回归风险登记表
+
+---
+
+*本规范是测试团队在 Harness 体系中的完整操作指南。请牢记：你是质量的最后守门员，坚持标准就是保护产品和用户。*