@umacloud/knowledge 1.0.14 → 1.0.16

package/compliance/01-standards/privacy-and-compliance-readiness.md

@@ -0,0 +1,119 @@
+---
+id: privacy-and-compliance-readiness
+title: 隐私与合规就绪规范（商业级必读）
+domain: compliance
+category: 01-standards
+difficulty: intermediate
+tags: [privacy, pii, data-classification, consent, retention, audit, data-residency, dsar, 合规, 隐私, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 隐私与合规就绪规范（商业级必读）
+
+> 处理用户数据就要承担法律与信任责任。商业级产品在写第一行处理个人数据的代码之前，
+> 就要把"收集什么、为什么、存多久、谁能看、用户能不能删"想清楚并落到工程里。
+> 合规不是上线前补的文档，而是从数据模型就内建的能力（privacy by design）。
+
+## 1. 核心原则
+
+- **数据最小化**：只收集达成目的**必需**的数据，不"先存着以后也许有用"。字段越少，风险越小。
+- **目的限定**：数据只能用于收集时声明的目的；换用途要重新取得依据/同意。
+- **默认隐私（privacy by default）**：默认采集最少、默认最严权限、默认不共享；让用户主动开启而非默认开启。
+- **可问责**：能证明你做了合规（记录、审计、控制映射），而不只是声称。
+- **设计即合规**：在数据模型、接口、日志设计阶段就考虑分类、保留、删除、最小化，而非事后补。
+
+## 2. 数据分类与盘点
+
+先盘清"系统里有哪些数据、敏感度多高"，否则无从保护。
+
+| 分级 | 示例 | 处理要求 |
+|---|---|---|
+| 公开 | 营销文案、公开文档 | 无特殊要求 |
+| 内部 | 业务配置、聚合统计 | 访问控制 |
+| 个人数据（PII）| 姓名、邮箱、手机、地址、设备/账号标识 | 加密、最小化、可删除、可导出 |
+| 敏感个人数据 | 支付卡、健康、生物特征、精确位置、身份证件、未成年人数据 | 强化加密、严格最小授权、单独同意、更短保留 |
+| 凭据/密钥 | 密码、token、API key | 单向哈希/密管，绝不明文、绝不入日志 |
+
+要点：维护**数据盘点（哪些字段属于哪级、存在哪、流向哪）**；新增字段时定级。**绝不**记录密码/卡号/token 明文；日志/报错里对 PII 脱敏。
+
+## 3. 同意与合法依据
+
+- 收集个人数据要有**合法依据**（用户同意、履行合同所必需、法定义务等），并能说明是哪一种。
+- 同意要**明确、可知情、可撤回**：默认不勾选、分用途细分、撤回和给予一样容易。
+- 记录同意：谁、何时、对什么版本的条款、通过什么方式同意——可审计。
+- 对未成年人、敏感数据有更严格的同意与年龄校验要求。
+
+## 4. 数据主体权利（必须工程化实现）
+
+用户对自己的数据有这些权利，产品要有**真实可执行的流程**，而非客服手动翻库：
+
+| 权利 | 工程实现 |
+|---|---|
+| 访问/导出 | 能按用户聚合其所有个人数据并以通用格式导出（数据可携带） |
+| 更正 | 用户可更新其数据，且更新传播到副本/缓存 |
+| 删除（被遗忘）| 能定位某用户的所有数据（含备份、日志、下游、缓存）并删除/匿名化；记录删除完成 |
+| 限制/反对 | 能停止特定处理（如停止精准营销）而不删账号 |
+| 撤回同意 | 撤回后停止相应处理 |
+
+难点：删除要覆盖**所有副本**（备份、数据仓库、日志、第三方）。设计阶段就要让"按用户删除"可行——用户ID贯穿、可定位、可级联，而不是数据散落无法回收。
+
+## 5. 保留与生命周期
+
+- 每类数据定**保留期限**，到期自动删除或匿名化，**不无限留存**。
+- 实现 TTL/定期清理任务；备份也要遵守保留策略（不能"主库删了备份留十年"）。
+- 区分"删除"与"匿名化"：统计需要保留时，做**不可逆匿名化/去标识**（去掉可识别字段，确保不能反推个人）。
+- 账号注销要触发其个人数据的删除/匿名化流程，并给用户确认。
+
+## 6. 安全与加密
+
+- **传输加密**：所有个人数据传输用 TLS。
+- **静态加密**：个人/敏感数据落库加密；敏感字段做字段级加密或令牌化（tokenization），密钥与数据分离托管。
+- **最小授权**：按角色/属性最小授权访问个人数据；访问要鉴权、要留痕。
+- **脱敏**：日志、报错、分析、测试数据中对 PII 脱敏/掩码；测试环境绝不用真实个人数据。
+- 与安全基线协同：见 `security/01-standards/secure-coding-baseline`、`security/01-standards/data-protection-gdpr`。
+
+## 7. 数据驻留与跨境
+
+- 明确数据**存储与处理的地理位置**；某些数据有"必须留在特定地区"的驻留要求。
+- 跨境传输个人数据要有合法机制与记录；选择第三方/云区域时考虑数据驻留。
+- 维护**数据流向图**：数据从哪进、存哪、流向哪些第三方/区域——出事和审计都要它。
+
+## 8. 审计与可追溯
+
+- 对敏感操作（访问/导出/修改/删除个人数据、权限变更、登录）记**审计日志**：谁、何时、对什么、从哪、结果。
+- 审计日志要**防篡改、可追溯、有保留期**；审计日志本身也要对 PII 脱敏。
+- 保留**合规证据**：数据盘点、同意记录、删除完成记录、访问评审记录、控制落实证据——可应对认证审计与监管问询。
+- 定期做**访问评审**（谁有权访问敏感数据，是否仍需要）。
+
+## 9. 第三方与供应链
+
+- 引入处理个人数据的第三方（分析、支付、云、SaaS）前评估其安全与合规，签订数据处理约定，明确各自责任。
+- 维护第三方数据处理清单（处理什么、为什么、在哪）。
+- 第三方也要遵守你的保留/删除/驻留要求；用户删除要能传导到下游。
+
+## 10. 事件响应
+
+- 个人数据泄露要有**响应预案**：发现→遏制→评估影响范围→按法定时限通知监管/用户→复盘整改。
+- 明确"什么算可上报的泄露"、通知时限、责任人；提前演练（见 `incident/` 与 `security/02-playbooks/incident-response-security-playbook`）。
+
+## 11. 反模式（出现即不合格）
+
+1. **过度采集**：能要的全要、留着以后也许有用。
+2. **删不掉**：数据散落各处，"按用户删除"做不到。
+3. **PII 入日志/明文存储**：密码/卡号/token 明文，日志含个人数据。
+4. **无保留策略**：所有数据永久留存。
+5. **同意走过场**：默认勾选、不可撤回、不记录。
+6. **合规当文档补**：上线前补 PDF，工程里没有任何对应能力。
+7. **忽略数据驻留/第三方**：把个人数据随手发给未评估的第三方/任意区域。
+
+## 12. 最低交付 checklist
+
+- [ ] 有数据分类与盘点；每个字段定级，新增字段定级。
+- [ ] 只采集必需数据；同意明确、可撤回、可审计。
+- [ ] 访问/导出/更正/删除/限制等数据主体权利有可执行的工程实现。
+- [ ] 删除能覆盖所有副本（备份/日志/下游/缓存）。
+- [ ] 每类数据有保留期与自动清理；统计数据做不可逆匿名化。
+- [ ] 个人/敏感数据传输与静态加密，最小授权，日志脱敏。
+- [ ] 明确数据驻留与跨境，维护数据流向图与第三方清单。
+- [ ] 敏感操作有防篡改审计日志；保留合规证据。
+- [ ] 有数据泄露响应预案与通知时限。

package/data/data-governance-and-modeling-deep-dive.md

@@ -8,7 +8,7 @@ tags: [and, data, deep, dive, governance, modeling, 数据环节深度知识库]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# data-governance-and-modeling-deep-dive
 
 ## 数据环节深度知识库
 

package/design/ux-system-deep-dive.md

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

package/development/00-governance/document-template.md

@@ -8,7 +8,7 @@ tags: [development, document, template, 失败模式, 执行步骤, 检查清单
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# document-template
 
 ```yaml
 id: KB-DEV-XXXX

package/development/01-standards/code-review-and-pr-hygiene.md

@@ -0,0 +1,85 @@
+---
+id: code-review-and-pr-hygiene
+title: 代码评审标准与 PR 卫生规范（商业级必读）
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [code-review, pr, pull-request, review-standards, small-pr, blocking-vs-nit, review-sla, atomic-commit, 代码评审, 评审, pr卫生, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 代码评审标准与 PR 卫生规范（商业级必读）
+
+> 代码评审不是挑刺仪式，也不是橡皮图章。它是**在缺陷进入主干前**拦住它、并让知识在团队里扩散的工程动作。
+> 评审能不能起作用，一半取决于**作者把 PR 准备得多好评审**，一半取决于**评审者关注什么、用什么口吻**。
+> 商业级团队对两端都有硬标准：小而聚焦的 PR + 有重点、可执行、对事不对人的评审。
+
+## 1. 评审到底在查什么（优先级从高到低）
+
+| 关注点 | 看什么 |
+|---|---|
+| **正确性** | 逻辑对不对、边界/错误/并发有没有处理、会不会破坏现有行为 |
+| **安全** | 越权、注入、输入校验、敏感信息泄露、危险默认配置 |
+| **测试** | 改动有没有对应测试，测试是否覆盖关键路径与边界，而非只测 happy path |
+| **可维护性** | 命名、结构、复杂度、是否引入难以理解或难以删除的耦合 |
+| **契约/兼容** | 接口/数据变更是否破坏消费方、是否需要版本化与迁移 |
+| **可观测性** | 关键路径有没有日志/指标，错误是否可定位 |
+| **风格** | 一致性——但**自动化能管的（格式化/lint）不靠人评审** |
+
+把人力评审用在机器查不了的地方（正确性、设计、安全语义），格式/风格交给自动化。
+
+## 2. 作者侧：把 PR 准备到"好评审"
+
+- **小而聚焦**：一个 PR 只做一件事。大 PR 评审质量断崖式下降——评审者看不动就只能盖章。难以拆分的大改动要拆成一串可独立评审、可独立回滚的小 PR。
+- **自审先行**：提交前自己先过一遍 diff，删调试代码、补测试、跑通构建+lint+测试，别把机器能发现的问题丢给评审者。
+- **说清楚 why**：PR 描述写"为什么这么改、影响范围、如何验证、如何回滚"，而不是把标题复述一遍。让评审者**不用猜**。
+- **关联需求**：链接到对应需求/任务/缺陷，让改动可追溯（见 `experts/product-manager/prd-template-and-structure` 的可追溯矩阵）。
+- **标注重点**：主动指出"这块我不确定""这里请重点看",引导评审注意力。
+- **绿灯再请评**：CI 没过别请人评审；让评审者帮你跑 lint 是浪费。
+
+## 3. 评审者侧：有效且尊重
+
+- **及时**：评审是阻塞别人的事，设 SLA（如一个工作日内首轮响应），别让 PR 烂在队列里。评审优先级高于自己写新代码。
+- **分清阻塞与建议**：明确标注哪些是**必须改（blocking）**、哪些是**可选建议（nit/suggestion）**。不要用一堆口味问题卡住一个正确的 PR。
+- **具体、可执行**：指出问题要给出原因和（可能的）改法，"这里不好"不是有效评审。
+- **问而非命令**：用"这里在 X 情况下会不会 Y？"代替"改成 Z"，把判断权留给作者、把上下文逼出来。
+- **对事不对人**：评审代码不评审人；任何人都会写 bug，评审是协作不是审判。
+- **该夸就夸**：好的设计/测试值得肯定，评审不只是找问题。
+- **认知边界**：看不懂的地方要问，不假装看懂盖章；批准 = 你为这段代码的正确性背了书。
+
+## 4. PR / 提交卫生
+
+- **原子提交**：每个提交是一个自洽的逻辑单元，信息说清"做了什么、为什么"，便于排查与回滚。
+- **干净历史**：合并前清理无意义的 "fix typo"、"wip" 提交噪音，让历史可读。
+- **不夹带**：重构和功能改动分开 PR——把格式化大改和逻辑改动混在一个 PR 里，评审者根本看不出真正的变化。
+- **改动可回滚**：PR 粒度要让"出事单独回滚这一个改动"成为可能。
+
+## 5. 自动化兜底（人只做机器做不了的）
+
+- **格式/lint/类型/测试/安全扫描**进 CI 必过门禁，**不进人工评审**（见 `testing/01-standards/ci-test-gates-and-coverage`）。
+- **必评审 + 必过 CI** 作为合并保护：主干受保护，绕不过。
+- **覆盖关键变更**：安全/支付/权限等高风险路径要求更强评审（如指定领域评审人）。
+- 评审清单可参考 `development/03-checklists/pr-checklist`。
+
+## 6. 反模式（出现即不合格）
+
+1. **巨型 PR**：上千行混合改动，评审者看不动只能盖章，缺陷直接漏进主干。
+2. **橡皮图章**："LGTM" 秒批，根本没看；批准却不负责。
+3. **风格暴政**：用一堆个人口味的 nit 卡住正确的 PR，不分阻塞与建议。
+4. **人肉跑 lint**：把格式化/风格交给人评审，浪费人力还不一致。
+5. **对人不对事**：评审带情绪、贬低作者，让人不敢提 PR。
+6. **PR 无上下文**：描述空白或只复述标题，评审者全靠猜。
+7. **重构夹带功能**：格式化与逻辑改动混一个 PR，真正的变化被淹没。
+8. **评审烂队列**：PR 几天没人看，阻塞交付、催生"绕过评审直接合"。
+9. **作者不自审**：把调试代码、未过 CI 的改动丢给评审者收拾。
+
+## 7. 最低交付 checklist
+
+- [ ] PR 小而聚焦，一个 PR 一件事；大改动拆成可独立评审/回滚的小 PR。
+- [ ] 作者提交前自审、补测试、本地构建+lint+测试通过，CI 绿灯再请评。
+- [ ] PR 描述写清 why/影响范围/如何验证/如何回滚，并关联需求。
+- [ ] 评审有 SLA，及时响应，不阻塞队列。
+- [ ] 评审区分 blocking 与建议，意见具体、可执行、对事不对人。
+- [ ] 格式/lint/类型/测试/安全扫描走 CI 门禁，不占人工评审。
+- [ ] 主干受"必评审 + 必过 CI"保护；高风险路径加强评审。
+- [ ] 提交原子、历史干净，重构与功能改动分离。

package/development/03-checklists/production-readiness-checklist.md

@@ -5,8 +5,8 @@ domain: development
 category: 03-checklists
 difficulty: intermediate
 tags: [checklist, development, production, readiness, 可靠性与容灾, 合规与审计, 基础设施与部署, 安全]
-quality_score: 70
-last_updated: 2026-06-15
+quality_score: 90
+last_updated: 2026-06-29
 ---
 # 生产就绪检查清单 (Production Readiness Checklist)
 
@@ -169,11 +169,11 @@ last_updated: 2026-06-15
 
 ---
 
-## 参考
+## 相关规范
 
-- Google SRE Book: Production Readiness Review — https://sre.google/sre-book/evolving-sre-engagement-model/
-- AWS Well-Architected Framework — https://aws.amazon.com/architecture/well-architected/
-- The Twelve-Factor App — https://12factor.net/
+- 服务级一次性 go/no-go 决策门：`operations/01-standards/production-readiness-review`
+- 每次发布的 pass/fail 门禁：`cicd/release-readiness-gate`
+- 配置与环境治理：`architecture/01-standards/configuration-and-environment-management`
 
 ---
 

package/development/09-maturity/quarterly-audit-template.md

@@ -8,7 +8,7 @@ tags: [audit, development, quarterly, template, 季度审计模板]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# quarterly-audit-template
 
 ## 季度审计模板
 

package/development/11-ui-excellence/ui-aesthetic-system.md

@@ -8,7 +8,7 @@ tags: [aesthetic, development, system, ui美学系统总册]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# ui-aesthetic-system
 
 ## UI美学系统总册
 

package/development/13-implementation-assets/knowledge-gates-execution.md

@@ -8,7 +8,7 @@ tags: [development, execution, gates, knowledge, 知识门禁执行手册]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# knowledge-gates-execution
 
 ## 知识门禁执行手册
 

package/development/api-contract-and-versioning-guide.md

@@ -8,7 +8,7 @@ tags: [and, api, contract, development, guide, versioning, 契约与版本治理
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# api-contract-and-versioning-guide
 
 ## API 契约与版本治理指南
 

package/development/api-governance-complete.md

@@ -8,7 +8,7 @@ tags: [api, api治理完整知识库, complete, development, governance]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# api-governance-complete
 
 ## API治理完整知识库
 

package/development/backend-engineering-complete.md

@@ -8,7 +8,7 @@ tags: [backend, complete, development, engineering, 后端工程完整知识库]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# backend-engineering-complete
 
 ## 后端工程完整知识库
 

package/development/code-review-quality-complete.md

@@ -1,43 +1,20 @@
 ---
 id: code-review-quality-complete
-title: code-review-quality-complete
+title: 代码评审与质量（已并入：代码评审标准与 PR 卫生规范）
 domain: development
-category: code-review-quality-complete.md
+category: development
 difficulty: intermediate
-tags: [code, complete, development, quality, review, 代码评审与质量完整知识库]
-quality_score: 70
-last_updated: 2026-06-15
+tags: [code-review, pr, quality, superseded, pointer, 代码评审, 已并入]
+quality_score: 60
+last_updated: 2026-06-29
 ---
-# 开发：Excellent（11964948@qq.com）
+# 代码评审与质量（本文档已并入）
 
-## 代码评审与质量完整知识库
+> 本文档原为占位草稿，内容已被更完整、可落地的标准取代，不再单独维护。
 
-### 1. 评审原则
-- 评审关注正确性、可维护性、安全性、性能、可观测性。
-- 评审意见必须具体、可执行、可验证。
-- 对高风险变更执行严格评审等级。
+**权威文档：[`development/01-standards/code-review-and-pr-hygiene.md`](01-standards/code-review-and-pr-hygiene.md)**
+——代码评审标准与 PR 卫生规范（商业级必读）。
 
-### 2. PR质量标准
-- PR必须聚焦单一主题。
-- 变更必须包含测试与文档更新。
-- 变更说明需覆盖影响范围与回滚策略。
+它覆盖并超出了本文档原有的全部内容：评审优先级（正确性/安全/测试/可维护性/契约/可观测性/风格）、作者侧把 PR 准备到"好评审"、评审者侧有效且尊重、PR/提交卫生、自动化兜底、反模式与最低交付 checklist。
 
-### 3. 安全评审清单
-- 是否存在越权风险与输入校验缺失。
-- 是否可能泄露敏感信息。
-- 是否存在危险默认配置。
-
-### 4. 性能评审清单
-- 是否引入额外高复杂度计算。
-- 是否增加高频链路IO与序列化开销。
-- 是否影响缓存命中与数据库负载。
-
-### 5. 可运维性评审清单
-- 是否补充关键日志与指标。
-- 是否可在异常时快速定位问题。
-- 是否可安全回滚到上一个稳定版本。
-
-### 6. 评审闭环
-- 阻断级问题必须修复后才可合并。
-- 复发问题应沉淀到评审清单与模板。
-- 评审质量按缺陷逃逸率持续优化。
+配套清单见 [`development/03-checklists/pr-checklist.md`](03-checklists/pr-checklist.md)。

package/development/concurrency-reliability-complete.md

@@ -8,7 +8,7 @@ tags: [complete, concurrency, development, reliability, 并发与稳定性完整
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# concurrency-reliability-complete
 
 ## 并发与稳定性完整知识库
 

package/development/database-engineering-complete.md

@@ -8,7 +8,7 @@ tags: [complete, database, development, engineering, 数据库工程完整知识
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# database-engineering-complete
 
 ## 数据库工程完整知识库
 

package/development/engineering-effectiveness-complete.md

@@ -8,7 +8,7 @@ tags: [complete, development, effectiveness, engineering, 工程效能完整知
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# engineering-effectiveness-complete
 
 ## 工程效能完整知识库
 

package/development/engineering-standards-deep-dive.md

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

package/development/frontend-engineering-complete.md

@@ -8,7 +8,7 @@ tags: [complete, development, engineering, frontend, 前端工程完整知识库
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# frontend-engineering-complete
 
 ## 前端工程完整知识库
 

package/development/performance-capacity-complete.md

@@ -8,7 +8,7 @@ tags: [capacity, complete, development, performance, 性能与容量完整知识
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# performance-capacity-complete
 
 ## 性能与容量完整知识库
 

package/development/refactor-migration-complete.md

@@ -8,7 +8,7 @@ tags: [complete, development, migration, refactor, 重构与迁移完整知识
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# refactor-migration-complete
 
 ## 重构与迁移完整知识库
 

package/development/refactoring-and-techdebt-playbook.md

@@ -8,7 +8,7 @@ tags: [and, development, playbook, refactoring, techdebt, 重构与技术债治
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# refactoring-and-techdebt-playbook
 
 ## 重构与技术债治理手册
 

package/development/security-in-development-complete.md

@@ -8,7 +8,7 @@ tags: [complete, development, security, 开发安全完整知识库]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# security-in-development-complete
 
 ## 开发安全完整知识库
 

package/experts/architect/contract-first-api-design.md

@@ -0,0 +1,140 @@
+---
+id: contract-first-api-design
+title: Architect — Contract-First / API-First Workflow
+domain: experts
+category: architect
+difficulty: intermediate
+tags: [api, architecture, contract, design, experts, integration, openapi, schema, versioning]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# Architect — Contract-First / API-First Workflow
+
+> The API contract is the **single source of truth** that frontend, backend,
+> QA, and external integrators all build against. Write the contract **before**
+> writing implementation code. A contract authored after the code merely
+> documents whatever was built; a contract authored first becomes a design tool,
+> a parallelization enabler, and an automated gate.
+
+## 1. Why contract-first
+
+- **Parallel work** — once the schema is agreed, frontend and backend build
+  simultaneously against the same definition instead of waiting on each other.
+- **One source of truth** — the machine-readable schema (OpenAPI / GraphQL SDL /
+  protobuf) is generated from nothing else and nothing is generated without it.
+- **Early design feedback** — interface mistakes (chatty endpoints, leaking the
+  data model, wrong resource granularity) surface in review of a 1-page schema,
+  not after a sprint of code.
+- **Automated alignment** — the contract becomes a test fixture: mock servers,
+  client/server stubs, request/response validators, and a CI gate all derive
+  from it (see `testing/01-standards/contract-testing-and-api-contracts`).
+
+## 2. The workflow
+
+```
+1. Model the resources + operations from the requirements (not the DB tables).
+2. Write the contract: paths, methods, request/response schemas, error model, auth.
+3. Review the contract with consumers (frontend, integrators, QA) — sign off the shape.
+4. Generate: a mock server (consumers unblock) + server stubs + typed clients.
+5. Implement against the contract; validate every request/response in tests.
+6. Evolve only through additive change + explicit versioning + deprecation.
+```
+
+The contract is a **reviewable artifact** that lands in the repo
+(`openapi.yaml` / `schema.graphql` / `*.proto`) and is diffed on every change.
+
+## 3. Designing the resource model
+
+- Model **resources and operations**, not your storage schema. The API is a
+  product surface; the database is an implementation detail. Never expose ORM
+  entities or column names directly.
+- Use **nouns for resources** (`/orders`), HTTP methods for verbs. Keep nesting
+  to ≤2 levels; flatten deeper relationships with query filters or links.
+- Choose **granularity by use case**: avoid chatty designs (N calls to render
+  one screen) and avoid god-endpoints that return everything. Provide
+  field selection / expansion where payloads vary by caller.
+- Make **read and write shapes explicit**: a create request is not the same
+  schema as the resource it returns. Define request DTOs and response DTOs separately.
+
+## 4. Mandatory contract elements
+
+Every contract must pin down, before code:
+
+| Element | Requirement |
+|---|---|
+| Resources & paths | Every path, method, and path/query parameter typed. |
+| Request schema | Required vs optional fields, types, formats, ranges, enums. |
+| Response schema | Success body shape per status code, with examples. |
+| Status codes | The full set per operation (200/201/204/400/401/403/404/409/422/429/5xx). |
+| Error model | One consistent error envelope across all endpoints (see §5). |
+| Auth | Which endpoints require auth and the scheme (bearer token, scopes/roles). |
+| Pagination | The pagination contract (cursor preferred) where collections are returned. |
+| Idempotency | Idempotency-key header on unsafe operations that may be retried. |
+| Rate limits | Documented limits + `429` + `Retry-After` semantics. |
+| Versioning | The version strategy and how breaking change is signalled. |
+
+## 5. Standard error envelope (define once, use everywhere)
+
+A single error shape lets every client handle failures uniformly:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable, safe to display",
+    "details": [{ "field": "email", "message": "Invalid email format" }],
+    "requestId": "req_abc123"
+  }
+}
+```
+
+- `code` is a stable machine string clients branch on; `message` is for humans.
+- Never leak stack traces, SQL, or internal identifiers in error bodies.
+- Map every failure mode in the contract to a code, so QA can assert on them.
+
+## 6. Versioning and evolution
+
+- **Additive change is safe**: adding an optional field or a new endpoint does
+  not break existing clients. Make every consumer tolerant of unknown fields.
+- **Breaking change requires a new version**: removing/renaming a field,
+  changing a type, tightening validation, or changing status-code semantics.
+- Carry the major version in the URL prefix (`/api/v1/...`) for cache- and
+  test-friendliness; increment only on breaking change.
+- **Deprecate, don't delete**: announce, mark deprecated in the contract, emit a
+  deprecation signal (header), set a sunset date, and keep the old version until
+  consumer traffic drains.
+- Treat the contract diff as the **breaking-change detector** in CI — a removed
+  field or narrowed type fails the build unless the version is bumped.
+
+## 7. Contract as a CI gate
+
+The contract is only worth writing if it is enforced. Wire it up so drift fails the build:
+
+- **Lint the contract**: schema validity, naming consistency, required examples.
+- **Validate runtime traffic**: the server's real responses must satisfy the
+  schema (response validation in integration tests).
+- **Cross-check the frontend**: extract the client's `fetch`/HTTP calls and
+  assert every called path/method/shape exists in the contract — no call to an
+  undefined endpoint, no endpoint silently changed under a live consumer.
+- **Detect breaking diffs**: compare the new contract to the last released one;
+  block merge on a breaking change without a version bump.
+
+## 8. Architect checklist (before implementation starts)
+
+- [ ] Contract authored and committed before non-trivial endpoint code.
+- [ ] Resources modeled from use cases, not from database tables.
+- [ ] Request/response/error schemas fully typed, with examples per operation.
+- [ ] One consistent error envelope across all endpoints.
+- [ ] Auth, pagination, idempotency, and rate-limit semantics specified.
+- [ ] Versioning strategy and deprecation policy stated.
+- [ ] Mock server generated so frontend can build in parallel.
+- [ ] CI validates server responses and frontend calls against the contract.
+
+## 9. Anti-patterns
+
+1. **Code-first, document-later** — generating docs from finished code, so the API shape was never reviewed.
+2. **Exposing the data model** — returning ORM entities / DB column names as the API.
+3. **Inconsistent errors** — every endpoint inventing its own error shape.
+4. **Silent breaking change** — renaming a field in v1 and hoping clients cope.
+5. **Chatty or god endpoints** — N calls to render a screen, or one endpoint returning everything.
+6. **Unenforced contract** — a beautiful schema that nothing in CI checks, so code and contract drift apart.