@umacloud/knowledge 1.0.14 → 1.0.16

package/testing/01-standards/ci-test-gates-and-coverage.md

@@ -0,0 +1,93 @@
+---
+id: ci-test-gates-and-coverage
+title: CI 测试门禁与覆盖率规范（商业级必读）
+domain: testing
+category: 01-standards
+difficulty: intermediate
+tags: [ci, quality-gate, coverage, flaky, required-checks, mutation-testing, pipeline, 门禁, 覆盖率, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# CI 测试门禁与覆盖率规范（商业级必读）
+
+> 写了测试但不在 CI 里强制跑、不阻断合并，等于没写。商业级交付要求：**每次改动都自动验证，红就不能合**。
+> 本规范定义哪些检查在哪个阶段跑、覆盖率怎么卡、flaky 怎么治，让"绿色"真正可信。
+
+## 1. 门禁原则
+
+- **快速反馈分层**：把检查按"快→慢"分层，快的先挂、早失败（fail fast），别让开发者等 30 分钟才看到一个拼写错。
+- **必过即阻断**：被列为"required check"的项失败，PR **不可合并**——靠分支保护强制，而不是靠自觉。
+- **可信的绿**：绿色必须代表"真的没问题"。flaky（随机红/绿）会侵蚀信任，让人习惯性"重跑一下"，必须当一类缺陷治理。
+- **可复现**：CI 跑的就是别人本地能跑的同一套命令；锁依赖版本、固定随机种子与时钟。
+
+## 2. 分阶段执行什么
+
+| 阶段 | 触发 | 跑什么 | 目标时长 |
+|---|---|---|---|
+| 提交前 / 本地钩子 | commit/push | 格式化、lint、改动文件的快速单测 | 秒级 |
+| PR（必过门禁）| 每次 PR & 更新 | lint + 类型检查 + 全量单测 + 集成测 + 契约校验 + 构建 + SAST/依赖扫描 | < 10 分钟 |
+| 合并到主干 | merge | 上面全部 + 关键路径 E2E 冒烟 | < 20 分钟 |
+| 夜间 / 定时 | 定时 | 全量 E2E、性能基准、变异测试、可视回归、SCA 全扫 | 不阻断开发 |
+
+要点：**慢而全的**（完整 E2E、性能、变异测试）放夜间，避免拖慢每次 PR；**快而关键的**（单测、集成、契约、lint、构建）进 PR 必过门禁。
+
+## 3. PR 必过检查清单（required checks）
+
+每个 PR 合并前必须全绿：
+- [ ] 代码格式化无 diff（formatter 干净）。
+- [ ] Lint 0 错误（pedantic/严格级别，警告即错误）。
+- [ ] 静态类型检查通过。
+- [ ] 全量单元测试通过。
+- [ ] 集成测试通过（含真实 DB/依赖的关键读写）。
+- [ ] 接口契约校验通过（见 `contract-testing-and-api-contracts`）。
+- [ ] 项目构建成功（产物可生成）。
+- [ ] 依赖漏洞扫描 + 静态安全扫描（SAST）无新增高危。
+- [ ] 覆盖率达标（见 §4），且**新增/改动代码**覆盖率达阈值。
+- [ ] 无密钥/凭据泄漏（secret 扫描）。
+
+## 4. 覆盖率怎么卡
+
+覆盖率是**护栏不是目标**——100% 行覆盖也能全是无断言的假测试。正确用法：
+
+- **关注变更覆盖（diff/patch coverage）**：本次改动的新增/修改代码覆盖率必须达阈值（如 ≥ 80%）。这比"全库总覆盖率"更能防止"新代码不写测试"。
+- **设全局下限 + 禁止下降**：总覆盖率有底线（如关键模块 ≥ 80%、整体 ≥ 70%），且 PR 不得让覆盖率**净下降**。
+- **分层看覆盖**：核心领域逻辑/计费/权限要求高覆盖（含分支）；UI 胶水、生成代码、配置可豁免。
+- **分支覆盖 > 行覆盖**：行覆盖会漏掉未走到的条件分支；对关键逻辑要求分支覆盖。
+- **变异测试做抽查（夜间）**：行覆盖只证明"代码被执行"，变异测试改变代码看测试是否能发现，证明"断言真的有效"。对核心模块定期跑，揪出"覆盖了但没断言"的空测试。
+
+覆盖率反模式：为冲数字写无断言测试、把难测代码排除统计、只看总数不看变更覆盖。
+
+## 5. Flaky 测试治理
+
+flaky 是 CI 的头号信任杀手，按缺陷对待：
+- **检测**：同一提交多次运行结果不一致即 flaky；记录失败率。
+- **隔离（quarantine）**：确认 flaky 后立刻移出必过门禁（打标隔离）、建工单限期修，**但不允许**长期挂着无人管。
+- **根因**：常见是时间/随机/并发顺序依赖、共享可变状态、真网络、未等待异步、测试间数据污染。修复方向：注入可控时钟与种子、每用例独立数据与事务回滚、显式等待替代 sleep、并行安全。
+- **禁止"重跑掩盖"**：把"重试直到绿"当默认策略会永久隐藏真 bug；自动重试只用于明确隔离区，且计数告警。
+
+## 6. 测试数据与环境
+
+- 集成测试用**一次性真实依赖**（容器化 DB/内存库），每用例自带数据、跑完清理或事务回滚，互不污染。
+- 不依赖共享/生产测试库；不依赖"先跑某测试"的隐式顺序。
+- 测试可**并行**：无全局可变状态、无固定端口冲突、数据隔离。
+- 确定性：固定随机种子、可注入时钟、稳定排序，杜绝时序/时区导致的 flaky。
+
+## 7. 反模式（出现即不合格）
+
+1. **写了测试不进 CI**：本地偶尔跑，主干随时可坏。
+2. **检查非必过**：失败也能合并（没接分支保护）。
+3. **覆盖率只看总数**：新代码零测试但总数没掉，蒙混过关。
+4. **为覆盖率写无断言测试**：数字漂亮，实则没验证任何行为。
+5. **flaky 长期隔离无人修**：隔离区变垃圾堆，真问题被埋。
+6. **全量慢测试塞进每个 PR**：反馈 40 分钟，没人愿等，干脆跳过。
+7. **CI 与本地命令不一致**：本地绿 CI 红，无法复现。
+
+## 8. 最低交付 checklist
+
+- [ ] 分支保护开启，关键检查设为 required，红则不可合。
+- [ ] PR 门禁 < 10 分钟，包含 lint/类型/单测/集成/契约/构建/安全扫描。
+- [ ] 慢测试（全 E2E/性能/变异/可视回归）放夜间，不拖 PR。
+- [ ] 变更覆盖率达阈值 + 总覆盖率不下降，核心模块要分支覆盖。
+- [ ] flaky 有检测、隔离、限期修流程，不靠"重跑"掩盖。
+- [ ] 测试数据隔离、可并行、确定性（固定种子/时钟）。
+- [ ] CI 跑的命令与本地一致、可复现。

package/testing/01-standards/contract-testing-and-api-contracts.md

@@ -0,0 +1,102 @@
+---
+id: contract-testing-and-api-contracts
+title: 契约测试与接口契约规范（商业级必读）
+domain: testing
+category: 01-standards
+difficulty: intermediate
+tags: [contract-testing, consumer-driven, api-contract, schema-validation, integration, ci-gate, 契约测试, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 契约测试与接口契约规范（商业级必读）
+
+> 前后端、服务与服务之间靠"接口契约"协作。只跑各自的单测，无法发现"后端悄悄改了字段、前端还在用旧字段"这类**集成断裂**。
+> 契约测试用机器可验证的方式锁住接口形状：一方改了不兼容的契约，CI 立刻红，而不是等到联调或生产才炸。
+
+## 1. 契约测试解决什么
+
+- **集成断裂在合并前暴露**：消费方（前端/下游服务）对提供方（API/上游服务）的期望被固化成可执行契约；提供方改坏了，提供方的 CI 就失败。
+- **不必拉起整套环境**：契约测试用契约 + 桩，比端到端联调快得多、稳得多，可在每次 PR 跑。
+- **明确的责任边界**：契约是双方共同签署的事实来源；谁破坏谁负责。
+
+契约测试**不替代**集成/E2E，它补在金字塔的"集成层"，专门保接口对齐（见 `testing/01-standards/test-strategy-and-layering`）。
+
+## 2. 两种契约校验
+
+### A. 模式契约（Schema Contract）
+以接口定义文件（OpenAPI / GraphQL SDL / protobuf）为单一事实来源，校验**真实流量**符合模式：
+- **提供方**：集成测试里，断言每个端点的真实响应满足声明的模式（字段、类型、必填、状态码）。响应多/少/错字段即失败。
+- **消费方**：从前端代码里抽取所有 `fetch`/HTTP 调用，断言每个被调用的"路径+方法+请求/响应形状"都存在于契约中——杜绝"调了一个契约里不存在的端点"或"端点在活跃消费方下被悄悄改形状"。
+- **破坏性 diff**：把新契约与上一发布版对比，删字段/改类型/收紧校验/改状态码语义=破坏性变更，未升版本则阻断合并。
+
+### B. 消费者驱动契约（Consumer-Driven Contract）
+当多个消费方依赖同一提供方时，让**消费方**声明"我实际用到的请求/响应子集"，汇总成提供方必须满足的契约：
+```
+1. 每个消费方写出它对提供方的期望（请求样例 → 期望响应样例）。
+2. 这些期望被收集（共享契约仓/broker），形成提供方的契约集合。
+3. 提供方在 CI 回放所有消费方期望：任一不满足即失败。
+4. 部署前用"能否部署(can-i-deploy)"判定：该版本是否兼容当前所有线上消费方。
+```
+价值：提供方只需保证"被真正用到的部分"稳定，敢于删改无人使用的字段；消费方不会被上游静默破坏。
+
+## 3. 工作流
+
+```
+契约先行（见 experts/architect/contract-first-api-design）
+      │
+      ├─ 提供方：实现 → 契约校验测试（真实响应 vs 模式）→ 回放消费方期望
+      │
+      └─ 消费方：对着契约/Mock 开发 → 用契约桩做集成测试（不打真实提供方）
+                                  │
+                          CI 门禁：契约 lint + 双向校验 + 破坏性 diff + can-i-deploy
+```
+
+- 消费方测试用**契约生成的 Mock/桩**代替真实提供方，既快又能在提供方未就绪时并行开发。
+- 提供方测试用**真实实现**回放契约，确保不是"对着自己的假设测自己"。
+
+## 4. 契约必须锁住的内容
+
+| 维度 | 校验点 |
+|---|---|
+| 路径 / 方法 | 每个被消费的端点都存在 |
+| 请求 | 必填/可选字段、类型、格式、枚举、范围 |
+| 响应（按状态码）| 成功与各错误码的 body 形状 + 示例 |
+| 状态码集合 | 200/201/204/400/401/403/404/409/422/429/5xx 按操作声明 |
+| 错误信封 | 全局统一的错误结构（code/message/details） |
+| 鉴权 | 哪些端点需鉴权、需要的 scope/role |
+| 分页 / 幂等 | 集合的分页契约、不安全操作的幂等键 |
+| 版本 | 破坏性变更的信号与版本策略 |
+
+## 5. 兼容性规则
+
+- **加字段、加端点、放宽校验 = 兼容**（消费方须容忍未知字段——收到多余字段不报错）。
+- **删/改字段、改类型、收紧校验、改状态码语义 = 破坏**：必须升主版本 + 走弃用流程（标记弃用 → 公告 → sunset 日期 → 旧版本流量耗尽后再删）。
+- 把"契约破坏性 diff"做成 CI 检查：未升版本的破坏性变更直接 fail。
+
+## 6. CI 门禁（契约相关）
+
+每次 PR 应执行：
+- [ ] **契约 lint**：模式合法、命名一致、每个操作带示例。
+- [ ] **提供方响应校验**：集成测试断言真实响应符合契约。
+- [ ] **消费方调用校验**：前端/下游调用的路径与形状都在契约内。
+- [ ] **消费者期望回放**：提供方满足所有已注册消费方契约。
+- [ ] **破坏性 diff**：对比上一发布契约，破坏未升版即阻断。
+- [ ] **can-i-deploy**：发布前确认该版本兼容当前线上各消费方。
+
+## 7. 反模式（出现即不合格）
+
+1. **只有单测、无契约校验**：前后端各自绿，集成处断裂。
+2. **契约是写完代码后补的文档**：从未被任何 CI 检查，与代码漂移。
+3. **消费方对着真实提供方做集成**：慢、脆、提供方未就绪就卡住；该用契约桩。
+4. **提供方对着自己的假设测自己**：没回放真实消费方期望。
+5. **静默破坏性变更**：改字段不升版本，线上消费方被打挂。
+6. **不容忍未知字段**：提供方加个可选字段，消费方就崩——脆契约。
+
+## 8. 最低交付 checklist
+
+- [ ] 接口有机器可读契约（OpenAPI/SDL/proto）作为单一事实来源。
+- [ ] 提供方有"真实响应 vs 契约"的自动化校验测试。
+- [ ] 消费方有"调用 vs 契约"的自动化校验，且用契约桩做集成。
+- [ ] 多消费方场景启用消费者驱动契约 + can-i-deploy。
+- [ ] 破坏性变更检测进 CI，未升版本即阻断合并。
+- [ ] 弃用走"标记→公告→sunset→下线"流程，不静默删改。

package/testing/01-standards/test-data-and-ephemeral-environments.md

@@ -0,0 +1,105 @@
+---
+id: test-data-and-ephemeral-environments
+title: 测试数据管理与临时环境规范（商业级必读）
+domain: testing
+category: 01-standards
+difficulty: intermediate
+tags: [test-data, fixtures, factories, seeding, ephemeral-environment, preview-environment, anonymization, isolation, 测试数据, 临时环境, 预览环境, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 测试数据管理与临时环境规范（商业级必读）
+
+> 测试不可信，往往不是因为代码错，而是因为**数据脏、环境脏**：上一条用例残留的数据污染下一条、用生产真实个人数据跑测试、几十个分支抢同一个共享 staging。
+> 商业级团队把"测试数据如何造、如何隔离、用完如何清"和"每个改动跑在自己的一次性环境里"当成工程能力来建，而不是靠人手摆数据。
+
+## 1. 核心原则
+
+- **确定性**：同一套用例每次跑的数据状态一致，结果可复现；不依赖"今天库里恰好有什么"。
+- **隔离**：每个用例/每条流水线/每个分支拥有自己的数据与环境，互不串味，可并行。
+- **自给自足**：用例自己准备所需数据（前置），不假设环境里已经存在某条记录。
+- **用完即清**：数据和环境都有明确的销毁路径，绝不无限堆积、绝不长期占用。
+- **绝不用真实个人数据**：测试库里不放生产 PII，用脱敏或合成数据（见 `compliance/01-standards/privacy-and-compliance-readiness`）。
+
+## 2. 测试数据的四种来源
+
+| 方式 | 做法 | 适用 | 注意 |
+|---|---|---|---|
+| 工厂/构建器（factory）| 用代码按需生成对象，字段给合理默认、按用例覆盖关键字段 | 单元/集成测试首选 | 默认值要合法，只显式写"与本用例相关"的字段 |
+| 固定夹具（fixture）| 预定义一组静态数据集，测试前加载 | 参照数据、枚举、种子账号 | 易腐化，变更要同步；别塞进巨型共享夹具 |
+| 合成数据（synthetic）| 按规则/分布批量生成仿真数据 | 性能/容量/边界测试 | 要覆盖边界与异常分布，不只是"理想数据" |
+| 脱敏生产数据 | 取生产快照后**不可逆脱敏/掩码**再用 | 需要真实形态/规模时 | 脱敏必须在数据离开生产边界前完成；保留引用完整性 |
+
+要点：优先工厂法（表达力强、随用例演进）；固定夹具只放稳定的参照数据；**绝不**直接拷生产库进测试环境。
+
+## 3. 数据脱敏与合成
+
+- **脱敏规则**：姓名/邮箱/手机/证件/卡号等可识别字段一律替换、掩码或令牌化；保留格式有效性（邮箱仍是邮箱）和**引用完整性**（外键仍能对上）。
+- **不可逆**：脱敏后不能反推回真人——别用可逆加密冒充脱敏。
+- **一致性**：同一真实值在多表脱敏成同一假值，避免 join 断裂。
+- **合成优先**：能用规则造的就别取生产；合成数据零隐私风险、可覆盖边界，是长期方向。
+
+## 4. 测试数据生命周期（每条用例必须闭环）
+
+```
+准备(setup) → 执行(act) → 断言(assert) → 清理(teardown)
+```
+
+- **准备**：用例自己创建所需数据，带唯一标识（如随机后缀）避免与并发用例撞键。
+- **清理**：优先用**事务回滚**（用例跑在事务里，结束回滚，最快最干净）；不能回滚时用显式删除或在隔离的库/schema 里跑。
+- **不依赖执行顺序**：用例之间无隐式依赖，任意打乱/单独跑都通过。
+- **不留垃圾**：失败的用例也要能清理（teardown 放在 finally/fixture 析构里）。
+
+## 5. 隔离级别（从强到弱）
+
+| 级别 | 隔离手段 | 并行度 | 成本 |
+|---|---|---|---|
+| 进程内 | 内存库/事务回滚 | 高 | 低 |
+| schema/库级 | 每个 worker 一套 schema 或独立库 | 高 | 中 |
+| 容器级 | 每条流水线起一套临时容器栈 | 中 | 中 |
+| 环境级 | 每个分支/PR 一套临时环境 | 中 | 高 |
+
+原则：能用更轻的隔离就别上更重的；CI 里并行跑的测试**必须**至少做到 schema/库级隔离，否则互相污染、随机翻红。
+
+## 6. 临时/预览环境（ephemeral / preview）
+
+- **定义**：为一次改动（一个 PR/一个分支）**自动拉起、用完自动销毁**的完整运行环境，让评审者和 QA 能在合并前看到真实运行效果。
+- **声明式 + 自动化**：环境由代码/配置定义（基础设施即代码），从零一键重建；**绝不**手工攒环境。
+- **自动生命周期**：PR 打开 → 自动部署预览环境 → 评论里回链接；PR 合并/关闭 → 自动销毁，绝不遗留。
+- **种子数据**：预览环境用脱敏/合成种子数据自动初始化，达到可演示状态，不连生产数据。
+- **隔离与成本**：每个预览环境互相隔离；设**TTL 自动回收**和资源上限，防止环境无限堆积烧钱。
+- **与渐进式发布衔接**：预览环境用于"合并前看效果"，与上线后的金丝雀放量是两件事（见 `release-engineering/01-standards/progressive-delivery-and-release`）。
+
+## 7. 环境分层与数据策略
+
+| 环境 | 数据 | 持久性 |
+|---|---|---|
+| 本地/单测 | 工厂生成 + 事务回滚 | 即用即弃 |
+| CI 集成测试 | 容器内临时库 + 种子 | 流水线结束即销毁 |
+| 预览（每 PR）| 脱敏/合成种子 | PR 关闭即销毁 |
+| staging | 接近生产的脱敏数据 | 长期，但定期刷新与清理 |
+| 生产 | 真实数据 | 受合规与保留策略约束 |
+
+staging 不是垃圾场：定期刷新脱敏数据、清理过期记录，让它真正"接近生产"。
+
+## 8. 反模式（出现即不合格）
+
+1. **测试间共享可变数据**：用例 A 造的数据被用例 B 读，顺序一变就翻红。
+2. **生产数据直灌测试**：把真实 PII 拷进测试/预览环境，隐私事故。
+3. **不清理**：用例只建不删，库越跑越脏，最后只能"重建环境"。
+4. **巨型共享夹具**：一个庞大夹具喂所有用例，改一处崩一片，没人敢动。
+5. **手工长寿 staging**：靠人手摆的"祖传环境"，没人能从零重建。
+6. **抢占共享环境**：几十个分支共用一个 staging，互相覆盖、排队等待。
+7. **预览环境不回收**：临时环境只建不销，资源无限堆积。
+8. **依赖隐式现存数据**：用例假设"库里本来就有 id=1 的用户"。
+
+## 9. 最低交付 checklist
+
+- [ ] 测试数据用工厂/构建器按需生成，带唯一标识，不撞键。
+- [ ] 每条用例自给自足、不依赖执行顺序、用完即清（优先事务回滚）。
+- [ ] CI 并行测试至少做到 schema/库级隔离，互不污染。
+- [ ] 测试/预览环境绝不使用生产真实个人数据，统一脱敏或合成。
+- [ ] 脱敏不可逆、保持格式有效与引用完整、跨表一致。
+- [ ] 预览环境由 IaC 定义，PR 打开自动拉起、关闭自动销毁，带 TTL 回收。
+- [ ] 预览环境自动种子数据到可演示状态。
+- [ ] staging 数据定期刷新与清理，保持接近生产。

package/testing/02-playbooks/e2e-testing-playbook.md

@@ -10,7 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
+# E2E 测试作战手册
 # 功能：E2E 测试全流程作战手册
 # 作用：指导团队建立和维护高质量的 E2E 测试体系
 # 创建时间：2026-03-28

package/testing/risk-based-test-matrix.md

@@ -8,7 +8,7 @@ tags: [based, matrix, risk, test, testing, 风险驱动测试矩阵]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# risk-based-test-matrix
 
 ## 风险驱动测试矩阵
 

package/testing/testing-strategy-deep-dive.md

@@ -8,7 +8,7 @@ tags: [deep, dive, strategy, testing, 测试环节深度知识库]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# testing-strategy-deep-dive
 
 ## 测试环节深度知识库