@umacloud/knowledge 1.0.15 → 1.0.17

package/product/kpi-and-metric-tree.md

@@ -1,37 +1,80 @@
 ---
 id: kpi-and-metric-tree
-title: kpi-and-metric-tree
+title: KPI 与指标树方法库（商业级必读）
 domain: product
-category: kpi-and-metric-tree.md
+category: 02-playbooks
 difficulty: intermediate
-tags: [and, kpi, metric, product, tree, 与指标树方法库]
-quality_score: 70
-last_updated: 2026-06-15
+tags: [指标, kpi, 北极星, metric-tree, 指标树, 漏斗, 任务成功率, 口径, 数据驱动, 增长, 产品, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
 ---
-# 开发：Excellent（11964948@qq.com）
 
-## KPI 与指标树方法库
+# KPI 与指标树方法库（商业级必读）
 
-### 目标
-- 建立从战略目标到页面行为指标的可追踪链路。
+> 没有指标树的产品，"做得好不好"只能靠感觉和嗓门吵出来。最常见的失败有两种：一是只盯**虚荣指标**（PV/UV/下载量），看着涨却和价值无关；二是各团队**口径打架**，同一个"活跃用户"三套算法，开会先吵定义。指标树的作用是把一个模糊的战略目标，**逐层拆成可观测、可归因、有人负责的具体指标**，让每个功能上线后都能回答"它到底有没有用、用在哪"。本方法库给出指标分层、构建步骤、口径治理与验收门禁。
 
-### 指标层级
-- 北极星指标：反映核心价值交付。
-- 一级指标：新增、活跃、留存、收入、成本。
-- 二级指标：转化率、漏斗流失率、成功率、时延、错误率。
-- 过程指标：页面点击、操作耗时、失败类型分布。
+## 1. 指标分层（从战略到行为，逐层可拆）
 
-### 指标树构建步骤
-- 明确业务目标与目标时间窗。
-- 拆解关键用户行为路径。
-- 为每个路径节点定义成功与失败指标。
-- 绑定阈值与预警规则。
+| 层级 | 作用 | 示例 |
+|---|---|---|
+| **北极星指标** | 全公司/产品线唯一对齐的核心价值度量 | 周活跃创作数、成功交易额、完成核心任务的用户数 |
+| **一级指标（输入）** | 直接驱动北极星的可拆解因子 | 新增、激活、留存、收入、成本 |
+| **二级指标（健康度）** | 反映各环节质量与效率 | 转化率、漏斗流失率、任务成功率、P95 时延、错误率 |
+| **过程指标（行为）** | 最细粒度的可观测行为，用于定位 | 页面点击、操作耗时、失败类型分布、空结果率 |
 
-### 指标验收规则
-- 每个新功能至少绑定 1 个业务指标和 2 个质量指标。
-- 指标必须有口径说明、数据源、更新频率、负责人。
-- 指标上生产前必须完成一次历史基线对齐。
+**北极星指标的判定**：它涨，用户拿到的价值就真的涨（不是仅仅"用得更久")；它能被一级指标解释；它不能靠刷量伪造。下载量、PV 几乎都不合格。
 
-### 常见失败模式
-- 指标只统计访问量，不统计任务成功率。
-- 指标口径跨团队不一致，导致决策冲突。
+## 2. 指标树构建步骤
+
+1. **锚定北极星 + 时间窗**：先定义"我们为用户创造的核心价值"，再选一个能代表它的可度量量，明确统计窗口（日/周/月）。
+2. **按驱动关系拆一级指标**：把北极星写成乘法/加法分解（如 收入 = 活跃用户 × 付费转化率 × 客单价），每个因子就是一级指标。
+3. **沿关键用户路径拆二级/过程指标**：对每条核心任务流（注册→激活→留存→付费），在每个节点定义成功指标与失败指标。
+4. **为每个叶子节点定义口径与阈值**：口径说明、数据源、更新频率、负责人、健康/告警阈值。
+5. **反向校验**：每个一级/二级指标都要能回答"它服务于哪个上层指标"，挂不上北极星的指标要么删掉，要么补一层。
+
+## 3. 成功指标 vs 失败指标（必须成对定义）
+
+只统计"做成了多少"会掩盖问题，每个关键环节都要同时盯失败面：
+
+| 环节 | 成功指标 | 失败指标 |
+|---|---|---|
+| 搜索 | 搜索后点击率 | 空结果率、零点击率 |
+| 表单/结算 | 提交成功率 | 字段报错率、放弃率、超时率 |
+| 任务流 | 端到端完成率 | 中途流失节点分布、平均重试次数 |
+| 服务质量 | P50/P95 时延达标率 | 错误率、超时率、降级触发次数 |
+
+## 4. 口径治理（指标可信的前提）
+
+每个指标必须登记为一条可治理的元数据，否则不予上线：
+
+- **口径定义**：精确到"谁、在什么时间窗、满足什么条件算一次"——"活跃"是打开 App 还是完成一次核心动作，必须写死。
+- **数据源 + 计算逻辑**：来源表/事件、过滤条件、去重规则、时区，全部明确，可复算。
+- **更新频率 + 负责人**：实时/小时/天级，谁对这个数负责、谁有权改口径。
+- **跨团队唯一口径**：同一指标名全公司只能有一套定义；要拆分必须改名（如"登录活跃"vs"创作活跃"），禁止同名异义。
+- **历史基线对齐**：上生产前用历史数据跑一遍，确认数值落在合理区间、与已有口径不冲突。
+
+## 5. 指标验收门禁（功能上线前）
+
+- 每个新功能上线前**至少绑定 1 个业务指标 + 2 个质量指标**，并预设预期变化方向与幅度。
+- 指标缺口径说明 / 数据源 / 负责人任意一项 → 不允许进生产。
+- 关键指标必须配**告警阈值**与异常下钻路径，能从二级指标一路下钻到过程指标定位根因。
+- 上线后设**验证窗口**：到期用绑定指标判定功能成败，达不到预期触发迭代或回滚，而不是"上了就不管"。
+
+## 反模式
+
+- **虚荣指标驱动**：只看 PV/UV/下载量等看着好看、与价值无关的数，掩盖真实的任务失败。
+- **只统计成功面**：盯着提交成功率却不看放弃率/报错率，问题被平均数藏住。
+- **口径跨团队打架**：同名指标多套算法，开会先吵定义，决策建立在不可比的数上。
+- **指标挂不上北极星**：堆了一屏指标，没人能说清它服务于哪个上层目标，沦为数据噪声。
+- **无负责人无更新频率**：指标没人维护，口径悄悄漂移，数据慢慢失真却无人察觉。
+- **上线即弃**：功能上线绑了指标却不设验证窗口，从不回看到底有没有效果。
+
+## 最低交付 checklist
+
+- [ ] 产品/产品线有唯一北极星指标，且能被一级指标解释、不可刷量伪造。
+- [ ] 指标树自上而下分层（北极星 → 一级 → 二级 → 过程），每个下层指标可追溯到上层。
+- [ ] 关键环节均成对定义成功指标与失败指标。
+- [ ] 每个指标登记了口径、数据源、计算逻辑、更新频率、负责人，且跨团队口径唯一。
+- [ ] 所有指标上生产前完成历史基线对齐。
+- [ ] 每个新功能绑定 ≥1 业务指标 + ≥2 质量指标，并预设预期方向与验证窗口。
+- [ ] 关键指标配置告警阈值与从二级到过程指标的下钻定位路径。

package/product/product-discovery-and-prd-deep-dive.md

@@ -1,16 +1,14 @@
 ---
 id: product-discovery-and-prd-deep-dive
-title: product-discovery-and-prd-deep-dive
+title: 产品环节深度知识库
 domain: product
-category: product-discovery-and-prd-deep-dive.md
+category: 01-standards
 difficulty: intermediate
-tags: [and, deep, discovery, dive, prd, product, 产品环节深度知识库]
+tags: [产品, prd, 需求发现, discovery, 产品设计, product]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## 产品环节深度知识库
+# 产品环节深度知识库
 
 ### 目标
 - 把业务目标转化为可执行需求，保证“价值、可行性、可验收”一致。

package/release-engineering/01-standards/feature-flag-lifecycle.md

@@ -0,0 +1,92 @@
+---
+id: feature-flag-lifecycle
+title: 功能开关全生命周期规范（创建/灰度/清理，商业级必读）
+domain: release-engineering
+category: 01-standards
+difficulty: intermediate
+tags: [feature-flag, toggle, kill-switch, rollout, flag-debt, cleanup, experiment, ab-test, 功能开关, 特性开关, 灰度, 开关债, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 功能开关全生命周期规范（商业级必读）
+
+> 功能开关是把"部署"和"发布"解耦的核心工具：代码先上、功能后开、出事即关。
+> 但开关用不好会变成最隐蔽的技术债——代码里堆满永不删除的死分支、谁也不敢动的"祖传开关"、测试矩阵指数爆炸。
+> 商业级团队把开关当**有生命周期、要被回收**的资产管理，而不是随手 `if` 一下。
+
+## 1. 开关的四种类型（寿命与纪律不同）
+
+| 类型 | 用途 | 寿命 | 纪律 |
+|---|---|---|---|
+| 发布开关（release）| 新功能藏在后面先部署，再灰度打开 | **临时**，上线稳定后清理 | 必须设清理期限，否则成债 |
+| 实验开关（experiment / A-B）| 按人群分流做对比实验 | 临时，实验结束即清理 | 实验有明确结束条件 |
+| 运营开关（ops / kill-switch）| 应急熔断、降级、限流 | **长期**保留 | 默认安全态，变更要审计 |
+| 权限开关（permission）| 按租户/套餐/地域控制可见性 | 长期，随业务存在 | 与计费/权限系统对齐 |
+
+**先分类再创建**：一个开关是"临时发布开关"还是"长期运营开关"决定了它要不要被清理。把临时开关当长期用 = 开关债的源头。
+
+## 2. 生命周期五阶段
+
+```
+创建 → 灰度放量 → 全量稳定 → 清理 → 归档
+```
+
+| 阶段 | 关键动作 |
+|---|---|
+| 创建 | 登记开关（名称、类型、负责人、目的、预期清理日期）；默认值设为**安全态** |
+| 灰度放量 | 按比例/人群/地域逐步打开（1%→5%→25%→100%），每步看指标 |
+| 全量稳定 | 100% 打开并观察足够时间，确认无回退需求 |
+| 清理 | 删除开关判断 + 旧分支代码，只留新路径 |
+| 归档 | 记录开关曾存在（审计/复盘可查），从活跃清单移除 |
+
+临时开关的**清理是交付的一部分**，不是"以后有空再说"——开关进了代码，对应的清理任务就要进待办。
+
+## 3. 创建规范
+
+- **登记**：每个开关有名称、类型、负责人、目的、创建日期、**预期清理日期**（临时开关必填）。
+- **命名清晰**：从名字能看出它控什么、是临时还是长期（如 `release_new_checkout`、`ops_payment_killswitch`）。
+- **默认安全**：默认值是"出问题也安全"的那个态——新功能默认关、熔断默认不触发。
+- **单一职责**：一个开关控一件事，别让一个开关同时管三个无关功能。
+
+## 4. 灰度与定向
+
+- **维度**：按百分比、用户ID哈希、租户、套餐、地域、内部员工等定向放量。
+- **稳定分桶**：同一用户每次落同一桶（基于稳定哈希），避免功能"忽闪忽现"破坏体验。
+- **逐步放量 + 看板**：每放量一档看错误率/延迟/核心指标，异常即回退（关开关，无需发版）。
+- **应急可关**：任何放量中的开关都能一键关回安全态，这是开关相对"重新发版回滚"的核心价值。
+
+## 5. 与代码的纪律
+
+- **开关判断集中**：开关读取走统一接口，不在代码各处散落硬编码字符串；便于盘点和清理。
+- **避免嵌套开关**：多个开关嵌套组合 → 测试路径指数爆炸、行为不可预测。尽量扁平、互不依赖。
+- **两条路径都要能跑**：开关开/关两个分支都要被测试覆盖（至少冒烟），别只测打开态。
+- **开关不替代版本兼容**：开关控制的是"行为是否可见"，破坏性的对外接口变更仍要走版本化（见 `release-engineering/01-standards/progressive-delivery-and-release`、`api/01-standards/api-versioning-and-deprecation-policy`）。
+
+## 6. 清理（对抗开关债）
+
+- **到期回收**：临时开关到预期清理日仍未清，触发提醒/拦截；把"过期开关数"当技术债指标盯。
+- **清理即删码**：删开关不是把它常开，而是**删掉判断和已废弃的旧分支**，让代码只剩胜出的那条路径。
+- **定期盘点**：周期性扫描所有开关，标记"长期 100% 打开的临时开关"——它们就是该清理的死分支。
+- **审计长期开关**：运营/权限类长期开关的变更（谁、何时、改成什么）要留痕，尤其 kill-switch。
+
+## 7. 反模式（出现即不合格）
+
+1. **开关债**：临时开关上线后从不清理，代码堆满永久死分支。
+2. **僵尸开关**：长期 100% 打开却没人敢删，因为不知道关掉会怎样。
+3. **默认不安全**：默认开 / 默认放量，新代码一上即全量暴露，失去"先部署后发布"的意义。
+4. **嵌套开关地狱**：开关层层嵌套，组合爆炸，没人能推断真实行为。
+5. **散落硬编码**：开关名字符串散落各处，无法盘点、无法统一清理。
+6. **只测打开态**：关闭分支从不测，回退时才发现旧路径早已不工作。
+7. **无登记无负责人**：开关没人负责、没清理日期，成无主孤儿。
+8. **kill-switch 无审计**：应急开关被改了也查不到谁改的。
+
+## 8. 最低交付 checklist
+
+- [ ] 每个开关先分类（发布/实验/运营/权限），临时开关设预期清理日期。
+- [ ] 开关已登记：名称、类型、负责人、目的、默认安全态。
+- [ ] 灰度按稳定分桶逐步放量，每步看指标，可一键关回安全态。
+- [ ] 开关读取走统一接口，不散落硬编码，避免嵌套。
+- [ ] 开关开/关两条分支都有测试覆盖。
+- [ ] 临时开关上线稳定后及时清理（删判断 + 删旧分支），不留死分支。
+- [ ] 定期盘点开关，过期/僵尸开关纳入技术债跟踪。
+- [ ] 长期运营/权限开关变更留审计，kill-switch 默认安全态。

package/release-engineering/01-standards/progressive-delivery-and-release.md

@@ -0,0 +1,92 @@
+---
+id: progressive-delivery-and-release
+title: 渐进式发布与版本交付规范（商业级必读）
+domain: release-engineering
+category: 01-standards
+difficulty: intermediate
+tags: [release, versioning, semver, feature-flag, canary, blue-green, rollback, changelog, 发布, 灰度, 回滚, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 渐进式发布与版本交付规范（商业级必读）
+
+> "全量上线、出事再说"是业余做法。商业级发布把风险**逐步释放、随时可回退**：
+> 先小流量验证、再放量、出问题秒回滚。发布是一次可控、可观测、可逆的工程动作，不是一次祈祷。
+
+## 1. 发布原则
+
+- **可逆优先**：任何发布都要有明确、已验证的**回滚路径**。不可逆的变更（数据迁移、删字段）单独走、提前演练。
+- **小步快跑**：小批量、高频次发布，比大版本一次性上线风险低、定位快。
+- **渐进释放**：新版本流量从 0 逐步放大（金丝雀→放量→全量），每一步看指标再决定继续还是回退。
+- **可观测**：每次发布都能从监控看出"是否变坏"——错误率、延迟、关键业务指标必须在发布前就接好。
+- **解耦部署与发布**：先把代码**部署**上去（对用户不可见），再用开关**发布**（对用户可见）——两者分离让上线更安全、回退更快。
+
+## 2. 版本与变更记录
+
+- **语义化版本（主.次.修订）**：破坏性变更升**主**版本，向后兼容的新功能升**次**版本，修复升**修订**版本。对外 API 的破坏性变更必须升主版本（见 `experts/architect/contract-first-api-design`）。
+- **变更日志（changelog）**：每个版本记录"新增/变更/修复/破坏性/弃用"，面向使用者写，而非堆 commit。
+- **不可变制品**：构建一次产出带版本号的不可变制品，各环境晋级用**同一个**制品（dev→staging→prod 不重新构建），杜绝"环境间不一致"。
+- **可追溯**：制品能追到 commit、构建记录、依赖清单，便于事故定位与合规取证。
+
+## 3. 渐进式发布策略
+
+| 策略 | 做法 | 适用 | 回滚 |
+|---|---|---|---|
+| 金丝雀（Canary）| 新版本先接 1%→5%→25%→100% 流量，逐步放量 | 大多数无状态服务 | 把流量切回旧版本 |
+| 蓝绿（Blue-Green）| 旧(蓝)/新(绿)两套并存，流量整体切到绿，旧的留作回退 | 需快速整体切换/回退 | 流量切回蓝 |
+| 滚动（Rolling）| 实例分批替换为新版本 | 资源受限、可容忍混跑 | 暂停并回滚批次 |
+| 影子（Shadow）| 把真实流量复制给新版本但不返回给用户 | 验证性能/正确性、零用户风险 | 直接停影子 |
+
+每一步都设**晋级判据**（错误率、延迟、业务指标在阈值内）和**自动回退条件**（超阈值自动回滚/暂停），别靠人盯。
+
+## 4. 功能开关（Feature Flag）
+
+- **部署 ≠ 发布**：新功能藏在开关后先部署，灰度时按用户/比例/地域逐步打开，出问题**关开关即回退**（无需重新发版）。
+- 开关类型：发布开关（临时，上线后清理）、实验开关（A/B）、运营开关（长期，应急熔断）、权限开关（按租户/套餐）。
+- **纪律**：临时开关上线稳定后**及时清理**，否则代码里堆满死分支（开关债）；开关默认值要安全（默认关）；关键开关变更要审计。
+- 开关与契约：开关控制的是行为可见性，不替代版本兼容——破坏性接口变更仍需版本化。
+
+## 5. 数据库变更与发布解耦
+
+- 变更要**向后兼容、可分步**：先加（可空列/新表）→ 双写/回填 → 切读 → 清理旧结构。**绝不**在一次发布里"改表结构 + 改代码"强耦合。
+- **扩展-收缩（expand-contract）**：先扩展兼容新旧两版代码的 schema，部署新代码，确认稳定后再收缩删旧结构。这样应用回滚时 schema 仍兼容。
+- 大回填/迁移与发布分离、可中断、可重入、限速，避免锁表拖垮线上。
+- 数据变更前**备份/快照**，并明确"能否回滚数据"——很多数据变更不可逆，要在发布计划里标红。
+
+## 6. 回滚
+
+- 回滚是**一等公民**：每个发布计划必须写明回滚步骤，并在演练/staging 验证过。
+- **快速止血优先**：出事先回滚/关开关恢复用户，再慢慢查根因——别在生产上边查边修。
+- 回滚要考虑"前向不兼容"：若新版本已写入旧版本读不了的数据，回滚会出错——这正是要求 schema 扩展-收缩、消息向后兼容的原因。
+- 定义自动回滚触发：关键指标超阈值，自动回退当前批次并告警。
+
+## 7. 发布门禁（can-i-deploy）
+
+发布前必须全绿（参见 `testing/01-standards/ci-test-gates-and-coverage`）：
+- [ ] 所有必过 CI 检查通过（测试/契约/构建/安全扫描）。
+- [ ] 契约兼容当前线上所有消费方（无未升版的破坏性变更）。
+- [ ] 监控/告警/日志已接好，发布后能立刻看出好坏。
+- [ ] 回滚步骤已写明并验证。
+- [ ] 数据库变更向后兼容、可回滚或已评估不可逆风险。
+- [ ] 高风险时段/变更冻结窗口已规避。
+- [ ] 发布负责人 + 回退负责人明确，发布有记录（谁、何时、什么版本）。
+
+## 8. 反模式（出现即不合格）
+
+1. **全量直发**：100% 流量一把切，无灰度无观测。
+2. **无回滚预案**：出事现想办法，止血慢。
+3. **部署即发布、强耦合**：代码与不兼容的 schema 一次性上，回滚就坏数据。
+4. **开关债**：临时开关从不清理，代码堆满死分支。
+5. **环境间重新构建**：staging 和 prod 跑的不是同一个制品。
+6. **发布无观测**：上完线靠用户投诉才知道坏了。
+7. **不可逆变更不预警**：删字段/数据迁移混在普通发布里。
+
+## 9. 最低交付 checklist
+
+- [ ] 语义化版本 + 面向用户的 changelog；制品不可变、跨环境晋级同一份。
+- [ ] 采用金丝雀/蓝绿等渐进式策略，按指标分步放量。
+- [ ] 用功能开关解耦部署与发布，开关可应急关闭且会清理。
+- [ ] 数据库变更走扩展-收缩、向后兼容、与发布解耦。
+- [ ] 每次发布有验证过的回滚路径与自动回退触发。
+- [ ] 发布前过 can-i-deploy 门禁；发布后有监控可判好坏。
+- [ ] 发布可追溯（版本→commit→制品→负责人）。

package/release-engineering/02-playbooks/release-rollback-and-recovery-playbook.md

@@ -0,0 +1,99 @@
+---
+id: release-rollback-and-recovery-playbook
+title: 发布回滚与恢复操作手册（playbook，商业级必读）
+domain: release-engineering
+category: 02-playbooks
+difficulty: intermediate
+tags: [rollback, recovery, release, hotfix, roll-forward, incident, kill-switch, runbook, 回滚, 恢复, 止血, 发布, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 发布回滚与恢复操作手册（商业级必读）
+
+> 发布出事时，**最贵的是犹豫**。"再观察五分钟"往往把 5 分钟的故障拖成 1 小时。
+> 这份手册是发布劣化时**照着做**的剧本：先止血、再定位、最后复盘。目标——任何人在凌晨被叫醒，照此执行也能在几分钟内让用户恢复，而不是临场发挥。
+
+## 1. 黄金法则
+
+- **先恢复用户，再查根因**：止血 > 调查。绝不在生产上边查边修。
+- **回滚是默认动作**：发布后指标劣化，**默认回滚**，而不是默认"再看看"。回滚不需要理解根因，恢复不能等。
+- **决策要预先授权**：谁有权拍板回滚、触发条件是什么，发布前就写死，事发时不用临时拉群讨论。
+- **每个发布都自带回滚预案**：没有验证过的回滚路径的发布，不允许上线（见 §发布门禁）。
+
+## 2. 止血手段优先级（从快到慢）
+
+| 手段 | 适用 | 生效速度 | 前提 |
+|---|---|---|---|
+| 关功能开关（kill-switch）| 新功能藏在开关后 | 秒级 | 上线时就把功能放开关后 |
+| 流量切回旧版本 | 金丝雀/蓝绿 | 秒级~分钟 | 旧版本仍在运行 |
+| 回滚到上一个制品 | 滚动/常规部署 | 分钟级 | 制品不可变、可重新部署 |
+| 向前修复（roll-forward）| 回滚不可行（如已改库结构）| 取决于修复 | 仅当回滚比修复更危险时 |
+| 限流/降级 | 过载或部分依赖故障 | 秒级 | 预置限流/降级开关 |
+
+原则：**能关开关就别回滚，能回滚就别向前修**——开关最快、最局部、风险最小。
+
+## 3. 标准回滚流程（runbook）
+
+```
+0. 确认劣化   —— 看监控：错误率↑ / 延迟↑ / 核心业务指标↓，确认与本次发布相关（时间吻合）
+1. 宣布并定责 —— 指定指挥(IC)，开事故频道，记录时间线（谁、何时、做了什么）
+2. 立即止血   —— 按 §2 优先级选最快手段：先关开关 / 切流量 / 回滚制品
+3. 验证恢复   —— 确认指标回到发布前基线；抽样验证核心用户流程真的好了
+4. 稳定观察   —— 保持回滚态，禁止再次发布，直到根因清楚
+5. 通告       —— 同步状态给相关方/用户（如有外部影响）
+6. 复盘       —— 无指责复盘，输出根因 + 修复 + 防再发（见 incident/ 域）
+```
+
+每一步都**记时间戳**：何时发现、何时止血、何时恢复——这是事后算 MTTR 和复盘的依据。
+
+## 4. 触发条件（自动 + 人工）
+
+- **自动回滚/暂停**：金丝雀阶段关键指标（错误率、延迟 p95/p99、核心转化）超阈值，自动回退当前批次并告警——别靠人盯屏。
+- **人工回滚**：自动没覆盖到的劣化（用户投诉激增、数据异常、下游告警）由 IC 拍板。
+- **预设阈值**：发布前就定好"什么数值持续多久就回滚"，写进发布计划，事发时直接对照，不临场争论。
+
+## 5. 数据相关发布的回滚（最危险）
+
+代码可秒回，**数据不能**。涉及库结构/数据变更的发布要特别处理：
+
+- **扩展-收缩护航**：变更走"先扩展（兼容新旧）→ 部署 → 稳定后再收缩"，这样代码回滚时 schema 仍兼容旧代码（见 `release-engineering/01-standards/progressive-delivery-and-release` §5）。
+- **前向不兼容数据要标红**：若新版本写入了旧版本读不了的数据，**直接回滚会出错**——这类发布要么不可回滚（只能向前修），要么必须先做好双读/兼容。发布计划里提前标注"能否回滚数据"。
+- **回滚前先评估数据**：执行代码回滚前，确认回滚后旧代码能否正确读取新版本期间写入的数据；不能则走向前修复。
+- **变更前快照**：高风险数据变更前做备份/快照，并演练过恢复路径（光有备份没验证过恢复 = 没有备份）。
+
+## 6. 向前修复（roll-forward）何时用
+
+回滚**不是**永远最优。以下情况向前修复更安全：
+
+- 已发生**不可逆**的数据写入，回滚会破坏数据一致性。
+- 回滚需要的旧依赖/旧契约已不存在。
+- 故障是配置/数据问题，一个小热修（hotfix）比整版回滚更快更准。
+
+向前修复要走**最小变更 + 加速通道**：只改导致故障的那一点，走精简但必过的门禁（关键测试 + 安全扫描），不走完整发布流程，但**绝不**裸推未经测试的代码。
+
+## 7. 演练（rollback drill）
+
+- 回滚路径**必须在 staging/演练中验证过**才算数——没演练过的回滚，事发时大概率不灵。
+- 定期做"假装发布劣化→执行回滚"的演练，校准 MTTR 和 runbook。
+- 每次真实回滚后更新 runbook：哪步慢了、哪步缺工具、哪个开关没接。
+
+## 8. 反模式（出现即不合格）
+
+1. **舍不得回滚**：在生产上边查根因边修，把短故障拖成长事故。
+2. **无验证回滚路径**：回滚预案只写在纸上，从没演练，事发时发现不灵。
+3. **代码与不兼容数据强耦合发布**：一次性改 schema + 改代码，回滚即坏数据。
+4. **回滚后立刻重发**：根因没清楚就再发一版，二次翻车。
+5. **无 kill-switch**：新功能没放开关后，唯一止血手段是整版回滚，慢且影响面大。
+6. **触发条件临场争论**：没预设阈值，事发时拉群讨论"算不算严重"，错过止血窗口。
+7. **回滚不记时间线**：事后复盘无据可查，MTTR 算不出，问题反复发生。
+
+## 9. 最低交付 checklist
+
+- [ ] 每个发布自带**已演练**的回滚路径；未验证不允许上线。
+- [ ] 新功能放在 kill-switch 后，可秒级关闭止血。
+- [ ] 预设自动回滚/暂停阈值，金丝雀阶段超标自动回退。
+- [ ] 回滚 runbook 明确、任何人可照做，每步记时间戳。
+- [ ] 数据相关发布走扩展-收缩，前向不兼容数据已标红并评估可回滚性。
+- [ ] 高风险数据变更前有备份且恢复路径演练过。
+- [ ] 明确回滚决策授权人与触发条件，事发不临时讨论。
+- [ ] 回滚后稳定观察、禁止盲目重发，事后做无指责复盘。

package/release-engineering/03-checklists/release-rollback-readiness-checklist.md

@@ -0,0 +1,61 @@
+---
+id: release-rollback-readiness-checklist
+title: 发布回滚就绪 checklist（上线前逐条过）
+domain: release-engineering
+category: 03-checklists
+difficulty: intermediate
+tags: [rollback, checklist, release-readiness, can-i-deploy, recovery, 回滚, 就绪, 发布门禁, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 发布回滚就绪 checklist（上线前逐条过）
+
+> 这是发布"放行"前必须逐条勾过的清单，配套手册见 `release-engineering/02-playbooks/release-rollback-and-recovery-playbook`。
+> 任何一条没勾，发布**不放行**。回滚能力不是事后补的，是上线的入场券。
+
+## 1. 回滚路径
+
+- [ ] 本次发布的回滚方式已明确（关开关 / 切流量 / 回滚制品 / 向前修复中的哪一种）。
+- [ ] 回滚路径已在 staging 或演练中**实际执行验证过**，不是纸面计划。
+- [ ] 回滚预计耗时已知（秒级 / 分钟级），并满足止血时效要求。
+- [ ] 旧版本制品仍可用、可重新部署（制品不可变、有版本号）。
+
+## 2. 开关与流量
+
+- [ ] 新功能藏在功能开关（kill-switch）后，可独立于发版秒级关闭。
+- [ ] 开关默认值安全（默认关 / 灰度），关闭路径已测试。
+- [ ] 采用金丝雀/蓝绿，旧版本在回滚窗口内保持可承接流量。
+
+## 3. 自动触发
+
+- [ ] 已设自动回滚/暂停阈值（错误率、p95/p99 延迟、核心业务指标）。
+- [ ] 金丝雀各放量步骤有晋级判据与自动回退条件，不靠人盯。
+- [ ] 告警已接好，发布后能立刻从监控看出好坏。
+
+## 4. 数据安全
+
+- [ ] 库结构/数据变更走扩展-收缩，向后兼容，回滚后旧代码仍能读。
+- [ ] 是否存在"前向不兼容数据"（新版写入旧版读不了）已评估并标注。
+- [ ] 不可回滚的数据变更已单独标红，并准备了向前修复方案。
+- [ ] 高风险数据变更前已备份/快照，且恢复路径演练过。
+
+## 5. 人员与流程
+
+- [ ] 回滚决策授权人明确（谁有权拍板）。
+- [ ] 触发回滚的条件/阈值已预先写定，事发无需临时讨论。
+- [ ] 发布负责人 + 回退负责人 + on-call 明确，联系方式可达。
+- [ ] runbook 任何 on-call 可照做，无需作者在场。
+
+## 6. 门禁（与 can-i-deploy 一致）
+
+- [ ] 所有必过 CI 检查通过（测试 / 契约 / 构建 / 安全扫描）。
+- [ ] 契约兼容当前线上所有消费方，无未升版的破坏性变更。
+- [ ] 跨环境晋级的是**同一个**不可变制品（未重新构建）。
+- [ ] 高风险时段 / 变更冻结窗口已规避。
+- [ ] 发布有记录（谁、何时、什么版本、对应 commit）。
+
+## 7. 发布后（回滚演练复盘前置）
+
+- [ ] 发布后保留观察窗口，期间禁止叠加新发布。
+- [ ] 若发生回滚，记录完整时间线（发现→止血→恢复）。
+- [ ] 回滚后根因未清前不重发；复盘输出修复 + 防再发项。

package/release-engineering/04-antipatterns/release-antipatterns.md

@@ -0,0 +1,63 @@
+---
+id: release-antipatterns
+title: 发布与回滚反模式（出现即不合格）
+domain: release-engineering
+category: 04-antipatterns
+difficulty: intermediate
+tags: [release, rollback, antipatterns, deployment, feature-flag, 发布, 回滚, 反模式, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 发布与回滚反模式（出现即不合格）
+
+> 发布事故大多不是新故障，而是同一批老毛病反复犯。把它们列成"出现即不合格"的清单，评审/门禁直接拦。
+> 配套规范见 `release-engineering/01-standards/progressive-delivery-and-release` 与回滚手册 `02-playbooks/release-rollback-and-recovery-playbook`。
+
+## 1. 发布动作类
+
+| 反模式 | 为什么危险 | 正解 |
+|---|---|---|
+| **全量直发** | 100% 流量一把切，无灰度无观测，出事即全员受影响 | 金丝雀/蓝绿分步放量，按指标晋级 |
+| **大爆炸发布** | 攒一个月一次性上，变更面巨大，出事无法定位 | 小步快跑、高频小发布 |
+| **周五/深夜大发布** | 出事时人最少、响应最慢 | 规避高风险时段，留足值守 |
+| **环境间重新构建** | staging 和 prod 跑的不是同一个制品 | 一次构建、不可变制品、跨环境晋级同一份 |
+| **发布无观测** | 上完线靠用户投诉才知道坏了 | 发布前接好错误率/延迟/业务指标 |
+| **手工发布步骤** | 靠人记命令，易漏易错、不可复现 | 发布自动化、声明式、可重复 |
+
+## 2. 回滚类
+
+| 反模式 | 为什么危险 | 正解 |
+|---|---|---|
+| **无回滚预案** | 出事现想办法，止血慢 | 每个发布自带已验证回滚路径 |
+| **回滚没演练** | 纸面计划事发不灵 | staging/演练实际跑过回滚 |
+| **舍不得回滚** | 在生产边查边修，短故障拖成长事故 | 默认回滚，先恢复用户再查根因 |
+| **回滚后立刻重发** | 根因没清就再发，二次翻车 | 稳定观察、禁止盲目重发 |
+| **触发条件临场争论** | 没预设阈值，错过止血窗口 | 发布前写死触发阈值与授权人 |
+| **回滚不记时间线** | 复盘无据，问题反复 | 每步记时间戳，事后复盘 |
+
+## 3. 数据与耦合类
+
+| 反模式 | 为什么危险 | 正解 |
+|---|---|---|
+| **部署即发布、强耦合** | 代码与不兼容 schema 一次性上，回滚即坏数据 | 解耦部署与发布，schema 走扩展-收缩 |
+| **不可逆变更混进普通发布** | 删字段/数据迁移和常规发版一起上，回不去 | 不可逆变更单独走、提前演练、标红 |
+| **前向不兼容数据不评估** | 新版写入旧版读不了的数据，回滚出错 | 发布前评估可回滚性，必要时双读兼容 |
+| **大回填阻塞线上** | 迁移锁表/打满 IO 拖垮生产 | 回填与发布分离，可中断、可重入、限速 |
+| **备份没验证恢复** | 有备份但恢复路径从没跑通 = 没有备份 | 恢复路径定期演练 |
+
+## 4. 功能开关类
+
+| 反模式 | 为什么危险 | 正解 |
+|---|---|---|
+| **开关债** | 临时开关从不清理，代码堆满死分支 | 上线稳定后及时清理临时开关 |
+| **无 kill-switch** | 新功能没放开关后，唯一止血是整版回滚 | 风险功能上线即放开关后 |
+| **开关默认不安全** | 默认开 / 默认放量，新代码一上即全量暴露 | 默认关 / 默认灰度 |
+| **关键开关无审计** | 谁改了开关、何时改，无记录 | 关键开关变更留审计 |
+
+## 5. 版本与契约类
+
+| 反模式 | 为什么危险 | 正解 |
+|---|---|---|
+| **破坏性变更不升版** | 直接改线上契约，消费方大面积中断 | 破坏性变更升主版本 + 过渡期 |
+| **changelog 堆 commit** | 使用者读不懂，升级风险不明 | 面向使用者写新增/变更/修复/破坏性/弃用 |
+| **制品不可追溯** | 出事查不到对应 commit/构建 | 制品可追溯到 commit、构建、依赖清单 |

package/security/01-standards/authorization-and-access-control.md

@@ -0,0 +1,94 @@
+---
+id: authorization-and-access-control
+title: 授权与访问控制模型规范（商业级必读）
+domain: security
+category: 01-standards
+difficulty: advanced
+tags: [授权, authorization, 访问控制, rbac, abac, rebac, 多租户, multi-tenancy, 越权, idor, 最小权限, 策略引擎, policy, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+
+# 授权与访问控制模型规范（商业级必读）
+
+> 认证（你是谁）只是门票，**授权（你能做什么、能动哪条数据）才是商业级安全的真正战场**。越权（Broken Access Control）长期是 Web 应用头号风险。本规范是框架无关的硬性约束：每个写操作要鉴权限、鉴资源归属、鉴租户；授权决策要集中、可审计、默认拒绝。认证实现见 `development/01-standards/authentication-patterns-complete.md`，本篇只讲授权。
+
+## 1. 三个绝不能省的检查（每个敏感请求都要过）
+
+每个访问受保护资源的请求，服务端必须独立验证三件事——**前端隐藏按钮不算授权**：
+
+1. **能力检查（Permission）**：当前主体是否有执行该动作的权限（`order:cancel`）。
+2. **资源归属检查（Ownership / Tenancy）**：该资源是否属于当前主体/租户（防 IDOR——改 URL 里的 id 就看到别人的单）。
+3. **状态/条件检查（Context）**：当前业务状态是否允许（已发货的单不能改地址；超额度不能审批）。
+- **默认拒绝（deny by default）**：没有明确 allow 就是 deny。新增端点默认无人可访问，再按需放开。
+- 授权在**服务端 + 数据访问层**双重落地，绝不信任客户端传来的角色/租户字段。
+
+## 2. 主流模型与选型（RBAC / ABAC / ReBAC）
+
+- **RBAC（基于角色）**：用户→角色→权限。简单、好理解、好审计，适合**角色清晰、扁平、单租户**的后台。缺点：层级、共享、跨租户场景会"角色爆炸"。
+- **ABAC（基于属性）**：用主体属性（部门、等级）+ 资源属性（密级、归属）+ 环境（时间、IP）+ 动作，写成策略规则求值。适合**动态、细粒度、条件式**的访问（"同部门且工作时间可读"）。缺点：策略多了难审计"谁能看这条"。
+- **ReBAC（基于关系）**：用实体间关系判定权限（"X 是该文档所在文件夹的 editor"→可编辑）。天然支持**层级继承、资源共享、嵌套组织**，是协作类/多层级资源产品的最佳解；它是 RBAC 的超集，属性表达为关系时也能覆盖 ABAC 场景。缺点：需要一套关系存储与图查询。
+- **选型基线**：
+  - 角色固定的内部后台 → **RBAC** 足够。
+  - 规则随属性/条件变化 → **RBAC 打底（粗粒度） + ABAC 细化**。
+  - 文档/项目/组织树这类"谁能访问取决于关系" → **ReBAC**。
+  - 别一上来就追最复杂的；**从 RBAC 起步，按真实需求向 ABAC/ReBAC 演进**，三者可组合。
+
+## 3. 权限模型设计要点
+
+- 权限粒度用 **`资源:动作`**（`invoice:read` / `invoice:approve`），不要用"页面"做权限单位。
+- 角色是**权限的集合**，给用户配角色，不直接配权限；角色要贴业务（`finance.approver`），别叫 `role1`。
+- 区分**全局角色**与**资源域角色**（在 A 项目是 admin、在 B 项目是 viewer）——多数 SaaS 需要后者，提前设计。
+- 维护**权限矩阵**（角色 × 资源 × 动作）作为评审与测试的依据；它也是测试用例的来源。
+- 危险动作（删除、导出、提权、改权限、转账）要**额外门槛**：二次确认 / 审批流 / 重新认证（step-up auth）。
+- **最小权限 + 职责分离**：默认给最小集；申请提权要审批、要到期回收；申请者≠审批者。
+
+## 4. 集中式授权：策略与执行点分离
+
+商业级系统不要把授权逻辑散在每个 `if` 里——**集中决策、分散执行**：
+
+- **决策点（PDP）**与**执行点（PEP）**分离：业务代码只问"这个主体能否对这个资源做这个动作？"，由统一的授权组件/策略引擎回答。
+- 策略**外置、可版本化、可测试**（策略即代码）：策略变更走 PR + 测试，而非改散落代码。
+- 决策要**可解释**：能回答"为什么 allow/deny"，便于排障与审计。
+- 性能：授权在每个请求热路径上，**缓存关系/角色解析结果**（带失效），批量端点要批量鉴权，避免 N 次远程策略调用。
+- **fail-closed**：授权服务/策略求值异常时**拒绝**而非放行（与治理类 fail-open 相反——授权必须保守）。
+
+## 5. 多租户隔离（SaaS 必做）
+
+- **每个查询都带租户维度**：`WHERE tenant_id = ? AND id = ?`，绝不只按主键查。强烈建议在数据访问层/ORM 统一注入租户过滤，靠人工每次加 where 必出事。
+- 隔离强度按敏感度选：共享库共享表（行级 + 强制租户过滤）→ 共享库独立 schema → 独立库。金融/医疗类倾向更强隔离。
+- 数据库层加固：行级安全（RLS）作为最后一道防线，即使应用漏加 where 也兜底。
+- **跨租户访问是默认禁止的**；平台超级管理员的跨租户操作要单独审计、单独提权、单独留痕。
+- 缓存键、文件路径、消息队列、搜索索引**都要带租户隔离**——别只防住了数据库却在缓存/对象存储里串号。
+
+## 6. 令牌、会话与权限传播
+
+- 访问令牌里只放**稳定的身份与粗粒度授权**（user_id、tenant_id、roles/scopes），细粒度资源权限运行时查，避免令牌过期信息滞后。
+- 权限/角色变更要能**快速生效**：缩短访问令牌有效期 + 刷新令牌可吊销 + 必要时维护吊销列表；高危场景用即时校验。
+- `scope`（OAuth）控制"第三方应用代表用户能做什么"，与用户自身权限是**两层**，最终权限取两者交集。
+- 服务间调用要传播并**重新校验**调用方身份与权限，不要因为"内网调用"就默认可信（零信任，见 `security/01-standards/zero-trust-architecture.md`）。
+
+## 7. 反模式（出现即不合格）
+
+- **只在前端控制**：靠隐藏按钮/路由守卫，后端不校验——改请求即越权。
+- **缺资源归属校验（IDOR）**：`GET /api/orders/{id}` 只查主键不查归属，遍历 id 就能拖库。
+- **默认放行**：新端点忘了加鉴权就对所有人开放（应默认拒绝）。
+- **角色硬编码散落**：`if user.role == "admin"` 满天飞，改权限要全局搜代码。
+- **多租户漏租户过滤**：查询只按主键，靠开发记得加 `tenant_id`。
+- **越权信息泄露**：用"403 vs 404"或错误文案暴露"该资源存在但你没权限"，给攻击者枚举线索（按策略统一处理）。
+- **授权 fail-open**：策略服务超时就放行。
+- **提权不回收**：临时提权/借权没到期机制，权限只增不减。
+- **批量/导出/GraphQL 绕过**：单条鉴权了，批量接口或嵌套查询没逐条鉴权。
+
+## 8. Agent Checklist（接口/数据访问前必过）
+
+- [ ] 每个敏感请求是否在服务端做了能力 + 资源归属 + 状态三重校验？
+- [ ] 是否默认拒绝（新端点不显式放开即不可访问）？
+- [ ] 授权模型是否与业务匹配（RBAC 起步，按需 ABAC/ReBAC），而非过度或不足？
+- [ ] 权限是否为 `资源:动作` 粒度，有可评审的权限矩阵？
+- [ ] 授权决策是否集中（PDP/PEP 分离）、策略可测试、可解释、fail-closed？
+- [ ] 多租户：每个查询/缓存/文件/索引是否都带租户隔离，DB 是否有 RLS 兜底？
+- [ ] 高危动作是否有二次确认/审批/step-up？职责分离是否落实？
+- [ ] 权限变更能否快速生效（短令牌 + 可吊销）？
+- [ ] 批量/导出/嵌套查询是否逐条鉴权，未被绕过？
+- [ ] 越权与不存在是否统一响应，未泄露资源存在性？