dev-playbooks-cn 1.0.0

package/skills/devbooks-test-owner/references//345/217/230/346/233/264/351/252/214/350/257/201/344/270/216/350/277/275/346/272/257/346/250/241/346/235/277.md

@@ -0,0 +1,228 @@
+# verification.md 模板（变更包内）
+
+> 推荐路径：`<change-root>/<change-id>/verification.md`
+>
+> 目标：把“完成定义”落到可执行锚点与证据上，并提供 `AC-xxx -> Requirement/Scenario -> Test IDs -> Evidence` 的追溯。
+
+---
+
+## 元信息
+
+- Change ID：`<change-id>`
+- 状态：`Draft | Ready | Done | Archived`
+- 关联：
+  - Proposal：`<change-root>/<change-id>/proposal.md`
+  - Design：`<change-root>/<change-id>/design.md`
+  - Tasks：`<change-root>/<change-id>/tasks.md`
+  - Spec deltas：`<change-root>/<change-id>/specs/**`
+- 维护者：`<you>`
+- 更新时间：`YYYY-MM-DD`
+- Test Owner（独立对话）：`<session/agent>`
+- Coder（独立对话）：`<session/agent>`
+- Red 基线证据：`<change-root>/<change-id>/evidence/`
+
+---
+
+========================
+A) 测试计划指令表
+========================
+
+### 主线计划区 (Main Plan Area)
+
+- [ ] TP1.1 `<一句话目标>`
+  - Why：
+  - Acceptance Criteria（引用 AC-xxx / Requirement）：
+  - Test Type：`unit | contract | integration | e2e | fitness | static`
+  - Non-goals：
+  - Candidate Anchors（Test IDs / commands / evidence）：
+
+### 临时计划区 (Temporary Plan Area)
+
+- （留空/按需）
+
+### 断点区 (Context Switch Breakpoint Area)
+
+- 上次进度：
+- 当前阻塞：
+- 下一步最短路径：
+
+---
+
+========================
+B) 追溯矩阵（Traceability Matrix）
+========================
+
+> 建议按 AC-xxx 为主键；如果你维护了 Requirements/Scenarios 规格条目，可同时列出对应项。
+>
+> **追溯完整性要求**：每个 AC 必须能追溯到完整链条 `AC → Requirement/Scenario → Test IDs → Evidence`。
+
+| AC | Requirement/Scenario | Test IDs / Commands | Evidence / MANUAL-* | Status | 因果链完整性 |
+|---|---|---|---|---|---|
+| AC-001 | `<capability>/Requirement...` | `TEST-...` / `pnpm test ...` | `MANUAL-001` / link | TODO | [ ] 完整 |
+
+### 追溯矩阵完整性检查清单
+
+- [ ] **无孤儿 AC**：每个 AC 都有对应的 Test IDs 或 MANUAL-* 条目
+- [ ] **无孤儿测试**：每个 Test ID 都能追溯到 AC 或 Requirement
+- [ ] **无无证据 DONE**：每个 Status=DONE 的条目都有 Evidence 链接
+- [ ] **Red 基线存在**：`evidence/` 目录包含初始失败证据（证明测试有效）
+- [ ] **Green 证据存在**：`evidence/` 目录包含最终通过证据
+
+### 追溯链示例
+
+```
+AC-001 (design.md)
+  ├── Requirement: REQ-ORDER-001 (specs/order-query/spec.md)
+  │   └── Scenario: SC-001 "分页参数非法时返回 400"
+  ├── Test IDs:
+  │   ├── TEST-001-a: unit test (tests/unit/order_test.py::test_invalid_page)
+  │   └── TEST-001-b: contract test (tests/contract/order_api_test.py::test_400)
+  └── Evidence:
+      ├── Red: evidence/red-baseline-2024-01-05.log
+      └── Green: evidence/green-final-2024-01-06.log
+```
+
+---
+
+========================
+C) 执行锚点（Deterministic Anchors）
+========================
+
+### 1) 行为（Behavior）
+
+- unit：
+- integration：
+- e2e：
+
+### 2) 契约（Contract）
+
+- OpenAPI/Proto/Schema：
+- contract tests：
+
+### 3) 结构（Structure / Fitness Functions）
+
+- 分层/依赖方向/禁止循环：
+
+### 4) 静态与安全（Static/Security）
+
+- lint/typecheck/build：
+- SAST/secret scan：
+- 报告格式：`json|xml`（优先机器可读）
+- 质量闸门：复杂度/重复度/依赖规则（如有）
+
+---
+
+========================
+D) MANUAL-* 清单（人工/混合验收）
+========================
+
+> 只收录“无法稳定自动化”的验收项；每条必须写清证据要求。
+
+- [ ] MANUAL-001 `<验收项>`
+  - Pass/Fail 判据：
+  - Evidence（截图/录像/链接/日志）：
+  - 责任人/签字：
+
+---
+
+========================
+E) 风险与降级（可选）
+========================
+
+- 风险：
+- 降级策略：
+- 回滚策略：
+
+========================
+F) 结构质量守门记录（可选）
+========================
+
+> 若本次变更涉及“代理指标驱动”的要求或潜在结构风险，请记录决策与替代闸门。
+
+- 冲突点：
+- 评估影响（内聚/耦合/可测试性）：
+- 替代闸门（复杂度/耦合/依赖方向/测试质量）：
+- 决策与授权：
+
+========================
+G) 价值流与度量（可选，但必须显式填"无"）
+========================
+
+> 目的：把"交付更快/更稳/更有价值"的判断落到可观测口径；避免只看局部写码速度。
+
+- 目标价值信号：`<填"无"或写明指标/看板/日志/业务事件>`
+- 价值流瓶颈假设（哪里会堵）：`<填"无"或写明 PR review / tests / 发布 / 手工验收 的排队点>`
+- 交付与稳定性指标（可选 DORA）：`<填"无"或写明 Lead Time / Deploy Frequency / Change Failure Rate / MTTR 的观测口径>`
+- 观测窗口与触发点：`<填"无"或写明上线后多久、观察哪些告警/报表>`
+- Evidence：`<填"无"或写明链接/截图/报表路径（建议落到 evidence/）>`
+
+========================
+H) 审计与证据管理（推荐）
+========================
+
+> 目的：确保变更过程可追溯、可审计，满足合规要求。
+
+### 证据目录结构
+
+```
+<change-root>/<change-id>/evidence/
+├── red-baseline/           # Red 基线证据（必须）
+│   ├── test-failures-<timestamp>.log
+│   └── test-failures-<timestamp>.json
+├── green-final/            # Green 最终证据（必须）
+│   ├── test-results-<timestamp>.log
+│   └── test-results-<timestamp>.json
+├── performance/            # 性能测试证据（如有）
+│   └── benchmark-<timestamp>.json
+├── manual-acceptance/      # 人工验收证据（如有）
+│   ├── MANUAL-001-screenshot.png
+│   └── MANUAL-001-signoff.md
+└── audit-log.md           # 审计日志（推荐）
+```
+
+### 审计日志模板（audit-log.md）
+
+```markdown
+# 变更审计日志
+
+## 元信息
+- Change ID: <change-id>
+- 创建时间: YYYY-MM-DD HH:MM
+- Test Owner: <name/session>
+- Coder: <name/session>
+
+## 关键事件记录
+
+| 时间 | 事件 | 操作者 | 证据链接 |
+|------|------|--------|----------|
+| YYYY-MM-DD HH:MM | Red 基线建立 | Test Owner | evidence/red-baseline/xxx.log |
+| YYYY-MM-DD HH:MM | 首次 Green | Coder | evidence/green-final/xxx.log |
+| YYYY-MM-DD HH:MM | 人工验收签核 | Reviewer | evidence/manual-acceptance/xxx.md |
+
+## 变更决策记录
+
+| 时间 | 决策内容 | 原因 | 影响范围 |
+|------|----------|------|----------|
+| YYYY-MM-DD | 调整 AC-002 验收标准 | 发现边界条件遗漏 | tests/unit/xxx_test.py |
+```
+
+### 证据采集命令（推荐使用脚本）
+
+```bash
+# 采集 Red 基线
+change-evidence.sh <change-id> --label red-baseline --project-root "$(pwd)" --change-root <change-root> -- <test-command>
+
+# 采集 Green 最终结果
+change-evidence.sh <change-id> --label green-final --project-root "$(pwd)" --change-root <change-root> -- <test-command>
+
+# 采集性能测试结果
+change-evidence.sh <change-id> --label performance --project-root "$(pwd)" --change-root <change-root> -- <benchmark-command>
+```
+
+### 审计完整性检查清单
+
+- [ ] **Red 基线存在**：`evidence/red-baseline/` 有失败日志
+- [ ] **Green 证据存在**：`evidence/green-final/` 有通过日志
+- [ ] **时间戳可追溯**：证据文件名包含时间戳
+- [ ] **审计日志完整**：`audit-log.md` 记录关键事件
+- [ ] **人工验收有签核**：MANUAL-* 条目有责任人签字

package/skills/devbooks-test-owner/references//345/274/202/346/255/245/347/263/273/347/273/237/346/265/213/350/257/225/347/255/226/347/225/245.md

@@ -0,0 +1,316 @@
+# 异步系统测试策略
+
+> 适用场景：测试涉及消息队列、事件驱动、最终一致性、分布式事务的系统时，使用本清单设计测试策略。
+>
+> 本文档为**可选参考**，仅当项目涉及异步/事件驱动架构时使用。
+
+---
+
+## 1) 异步系统的测试挑战
+
+### 1.1 核心难点
+
+| 挑战 | 描述 | 测试策略 |
+|------|------|----------|
+| 非确定性时序 | 消息到达顺序不确定 | 使用显式等待 + 超时，避免 sleep |
+| 最终一致性 | 系统状态需要时间收敛 | 轮询验证 + 明确收敛条件 |
+| 幂等性验证 | 重复消息不应产生重复副作用 | 发送相同消息多次，验证结果一致 |
+| 故障注入困难 | 网络分区、消息丢失难以模拟 | 使用可控的测试替身（Test Double） |
+| 状态散布 | 状态分布在多个服务/存储中 | 定义清晰的"系统状态快照"方法 |
+
+### 1.2 测试金字塔调整
+
+异步系统的测试金字塔与同步系统不同：
+
+```
+        /\
+       /  \  E2E（最小化，只验证关键链路）
+      /----\
+     /      \  Contract Tests（重点：消息契约）
+    /--------\
+   /          \  Integration Tests（重点：消息处理逻辑）
+  /------------\
+ /              \  Unit Tests（纯逻辑，无 IO）
+/----------------\
+```
+
+**关键差异**：
+- Contract Tests 更重要：验证消息格式、事件信封、schema 兼容性
+- Integration Tests 需要覆盖：超时、重试、幂等、乱序处理
+- E2E Tests 要谨慎：异步系统的 E2E 容易产生 Flaky Tests
+
+---
+
+## 2) 最终一致性测试
+
+### 2.1 测试模式：轮询等待（Polling）
+
+```python
+# 推荐模式：显式轮询 + 超时
+def wait_for_eventual_consistency(
+    condition_fn,      # 返回 True 表示状态已收敛
+    timeout_ms=5000,   # 最大等待时间
+    poll_interval_ms=100  # 轮询间隔
+):
+    start = time.now()
+    while time.now() - start < timeout_ms:
+        if condition_fn():
+            return True
+        sleep(poll_interval_ms)
+    return False
+
+# 示例：等待订单状态同步到查询服务
+assert wait_for_eventual_consistency(
+    lambda: query_service.get_order(order_id).status == "PAID",
+    timeout_ms=3000
+)
+```
+
+### 2.2 测试检查清单
+
+- [ ] 定义"状态收敛"的明确条件（不是"等 N 秒"）
+- [ ] 设置合理的超时时间（不要太短导致 Flaky，不要太长拖慢测试）
+- [ ] 测试覆盖"收敛失败"场景（超时后系统行为是什么？）
+- [ ] 验证中间状态是否可接受（最终一致性过程中用户看到什么？）
+
+### 2.3 design.md 应声明
+
+```markdown
+### 最终一致性约束
+- 一致性窗口：< 5 秒（99% 场景）
+- 中间状态用户可见行为：显示"处理中"
+- 收敛失败处理：触发补偿/告警
+```
+
+---
+
+## 3) 幂等性测试
+
+### 3.1 幂等性测试模式
+
+```python
+# 测试：同一消息消费 N 次，副作用只产生 1 次
+def test_idempotent_message_processing():
+    message_id = "msg-001"
+    order_id = "order-001"
+
+    # 发送相同消息 3 次
+    for _ in range(3):
+        send_message(CreateOrderEvent(
+            message_id=message_id,
+            order_id=order_id,
+            amount=100
+        ))
+
+    # 等待处理完成
+    wait_for_eventual_consistency(...)
+
+    # 验证：只创建了 1 个订单
+    assert order_count(order_id) == 1
+    # 验证：金额正确（不是 300）
+    assert get_order(order_id).amount == 100
+```
+
+### 3.2 幂等性检查清单
+
+- [ ] 每条消息有唯一 `message_id` / `idempotency_key`
+- [ ] 测试覆盖"完全相同消息重复消费"
+- [ ] 测试覆盖"部分处理后重试"（模拟处理中途失败）
+- [ ] 验证幂等键存储（Redis/DB）的过期策略
+- [ ] 验证并发重复消息的处理（两条相同消息同时到达）
+
+### 3.3 幂等性实现检查
+
+| 检查点 | 通过条件 |
+|--------|----------|
+| 幂等键生成 | 由客户端生成，不依赖服务端 |
+| 幂等键存储 | 有持久化存储，有合理 TTL |
+| 幂等检查时机 | 在业务处理**之前**检查 |
+| 重复请求响应 | 返回与首次相同的结果（不是错误） |
+
+---
+
+## 4) 消息顺序与乱序处理测试
+
+### 4.1 乱序场景
+
+| 场景 | 示例 | 处理策略 |
+|------|------|----------|
+| 事件乱序 | 先收到"订单发货"，后收到"订单创建" | 缓冲 + 重排序 / 拒绝 + 重试 |
+| 版本冲突 | 收到旧版本更新覆盖新版本 | 版本号检查（Last-Write-Wins 或 拒绝） |
+| 因果乱序 | 子事件先于父事件到达 | 依赖追踪 + 延迟处理 |
+
+### 4.2 测试模式
+
+```python
+# 测试：乱序消息能正确处理
+def test_out_of_order_events():
+    order_id = "order-001"
+
+    # 故意按错误顺序发送
+    send_message(OrderShippedEvent(order_id=order_id, version=2))
+    send_message(OrderCreatedEvent(order_id=order_id, version=1))
+
+    wait_for_eventual_consistency(...)
+
+    # 验证：最终状态正确
+    order = get_order(order_id)
+    assert order.status == "SHIPPED"
+    assert order.version == 2
+```
+
+### 4.3 乱序处理检查清单
+
+- [ ] 定义消息是否需要保序（全局有序 / 分区有序 / 无序）
+- [ ] 若需要保序：使用分区键保证同一实体的消息有序
+- [ ] 若允许乱序：实现版本号/时间戳检查
+- [ ] 测试覆盖"乱序到达"场景
+- [ ] 测试覆盖"版本冲突"场景
+
+---
+
+## 5) 超时与重试测试
+
+### 5.1 超时测试模式
+
+```python
+# 测试：下游超时时的处理
+def test_downstream_timeout():
+    with mock_timeout(payment_service, timeout_ms=100):
+        result = order_service.process_order(order_id)
+
+    # 验证：超时后降级行为
+    assert result.status == "PENDING_PAYMENT"
+    assert result.retry_scheduled == True
+```
+
+### 5.2 重试测试模式
+
+```python
+# 测试：重试逻辑正确
+def test_retry_with_exponential_backoff():
+    attempt_times = []
+
+    with mock_failure(payment_service, fail_count=2):
+        with capture_attempts(payment_service, attempt_times):
+            result = order_service.process_order(order_id)
+
+    # 验证：重试了 3 次（1 初始 + 2 重试）
+    assert len(attempt_times) == 3
+    # 验证：重试间隔符合指数退避
+    assert attempt_times[1] - attempt_times[0] >= 100  # 第一次重试
+    assert attempt_times[2] - attempt_times[1] >= 200  # 第二次重试
+```
+
+### 5.3 超时/重试检查清单
+
+- [ ] 每个异步操作都有显式超时设置
+- [ ] 重试有最大次数限制（防止无限重试）
+- [ ] 重试使用指数退避（防止重试风暴）
+- [ ] 测试覆盖"超时后降级"场景
+- [ ] 测试覆盖"重试成功"场景
+- [ ] 测试覆盖"重试耗尽"场景
+- [ ] 验证重试时的幂等性（重试不产生重复副作用）
+
+---
+
+## 6) 补偿事务测试（Saga Pattern）
+
+### 6.1 补偿测试模式
+
+```python
+# 测试：部分失败时正确补偿
+def test_saga_compensation():
+    order_id = "order-001"
+
+    # 模拟：库存扣减成功，支付失败
+    with mock_success(inventory_service):
+        with mock_failure(payment_service):
+            result = order_service.create_order(order_id)
+
+    wait_for_eventual_consistency(...)
+
+    # 验证：订单状态为失败
+    assert get_order(order_id).status == "FAILED"
+    # 验证：库存已回滚
+    assert get_inventory_reserved(order_id) == 0
+    # 验证：补偿记录存在
+    assert compensation_log_exists(order_id, "INVENTORY_ROLLBACK")
+```
+
+### 6.2 补偿测试检查清单
+
+- [ ] 每个可补偿操作都有对应的补偿操作
+- [ ] 补偿操作本身是幂等的
+- [ ] 测试覆盖"链路中间失败"的每个节点
+- [ ] 测试覆盖"补偿操作失败"场景
+- [ ] 验证补偿操作的执行顺序（逆序执行）
+- [ ] 验证补偿日志/审计记录
+
+---
+
+## 7) 测试替身（Test Doubles）设计
+
+### 7.1 消息队列测试替身
+
+| 替身类型 | 用途 | 实现建议 |
+|----------|------|----------|
+| In-Memory Queue | 单元/集成测试 | 内存队列，同步处理 |
+| Controllable Queue | 故障注入 | 可控制延迟、丢失、重复 |
+| Record & Replay | 回归测试 | 记录生产消息，离线回放 |
+
+### 7.2 测试替身检查清单
+
+- [ ] 测试替身与真实实现有相同的接口
+- [ ] 可以控制消息延迟
+- [ ] 可以控制消息丢失
+- [ ] 可以控制消息重复
+- [ ] 可以控制消息乱序
+- [ ] 可以注入处理失败
+
+---
+
+## 8) verification.md 补充模板
+
+在 `verification.md` 的测试计划中，若涉及异步系统，增加以下检查：
+
+```markdown
+### 异步系统测试检查（如适用）
+
+#### 最终一致性
+- [ ] 定义一致性窗口：< X 秒
+- [ ] 测试覆盖"状态收敛成功"
+- [ ] 测试覆盖"状态收敛超时"
+
+#### 幂等性
+- [ ] 消息包含 `idempotency_key`
+- [ ] 测试覆盖"重复消息只处理一次"
+- [ ] 测试覆盖"并发重复消息"
+
+#### 消息顺序
+- [ ] 声明保序要求：全局有序 / 分区有序 / 无序
+- [ ] 测试覆盖"乱序消息处理"
+
+#### 超时与重试
+- [ ] 声明超时时间：X ms
+- [ ] 声明重试策略：最多 N 次，指数退避
+- [ ] 测试覆盖"超时降级"
+- [ ] 测试覆盖"重试成功/耗尽"
+
+#### 补偿事务（如适用）
+- [ ] 定义补偿操作
+- [ ] 测试覆盖"部分失败时补偿"
+- [ ] 验证补偿操作幂等性
+```
+
+---
+
+## 9) 常见 Flaky Test 模式与修复
+
+| Flaky 模式 | 原因 | 修复方法 |
+|------------|------|----------|
+| 固定 sleep | 时间不够或过长 | 改用轮询等待 + 超时 |
+| 依赖消息顺序 | 并行消费导致乱序 | 使用幂等设计或显式排序 |
+| 共享测试状态 | 测试间互相影响 | 每个测试使用独立数据 |
+| 时间敏感断言 | 依赖系统时钟 | 注入可控时钟 |
+| 资源竞争 | 端口/文件冲突 | 使用动态分配或隔离环境 |