@umacloud/knowledge 1.0.15 → 1.0.17

package/ai/prompt-and-tool-guardrails.md

@@ -1,16 +1,14 @@
 ---
 id: prompt-and-tool-guardrails
-title: prompt-and-tool-guardrails
+title: Prompt 与工具调用护栏规范
 domain: ai
-category: prompt-and-tool-guardrails.md
+category: 01-standards
 difficulty: intermediate
-tags: [ai, and, guardrails, prompt, tool, 与工具调用护栏规范]
+tags: [prompt, 护栏, guardrails, 工具调用, 安全边界, 结构化输出, ai]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## Prompt 与工具调用护栏规范
+# Prompt 与工具调用护栏规范
 
 ### 目标
 - 防止模型越权操作、错误调用工具或输出不可信内容。

package/api/01-standards/api-versioning-and-deprecation-policy.md

@@ -0,0 +1,100 @@
+---
+id: api-versioning-and-deprecation-policy
+title: API 版本与弃用治理规范（商业级必读）
+domain: api
+category: 01-standards
+difficulty: intermediate
+tags: [api, versioning, deprecation, sunset, breaking-change, backward-compatible, semver, migration, consumer, 版本, 弃用, 废弃, 破坏性变更, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# API 版本与弃用治理规范（商业级必读）
+
+> 接口一旦有人调用，它就是**契约**，不再是你一个人能随便改的代码。
+> 商业级团队对外接口的演进遵循一条铁律：**老调用方不许被你的改动搞挂**。
+> 版本化解决"如何在不破坏现有消费方的前提下演进"，弃用治理解决"如何**有序、可预期地**让老版本退场"——两者缺一，要么永远不敢改，要么一改就出事故。
+
+## 1. 核心原则
+
+- **兼容优先**：能向后兼容就别升版本。新增是兼容的，删改是破坏的。
+- **破坏性变更必须版本化**：永远不在同一版本里做破坏性变更（见 §3 判定）。
+- **弃用要可预期**：老版本退场要提前公告、给迁移期、给信号，而不是某天突然 404。
+- **消费方视角**：以"现有调用方会不会挂"为唯一判据，而不是"我代码改得爽不爽"。
+- **支持窗口有限且明确**：不无限维护所有历史版本，但退场节奏要写明、要守约。
+
+## 2. 版本化方式（选一种，全项目统一）
+
+| 方式 | 形态 | 优点 | 取舍 |
+|---|---|---|---|
+| URL 路径 | `/api/v1/orders` | 直观、易路由、缓存友好 | 版本粒度粗（整套接口）|
+| 请求头 | `API-Version: 2` | URL 稳定、灵活 | 不直观、调试需看 header |
+| 日期版本 | `API-Version: 2026-06-29` | 渐进、精确到每次变更 | 管理成本高 |
+| 媒体类型 | `Accept: application/vnd.x.v2+json` | 符合 HTTP 语义 | 客户端支持参差 |
+
+要点：**对外公开 API 推荐 URL 路径版本**（最直观、最少踩坑）；选定后全项目统一，别混用。主版本号对应破坏性变更（语义化版本，见 `release-engineering/01-standards/progressive-delivery-and-release`）。
+
+## 3. 破坏性 vs 兼容性变更（判定表）
+
+| 破坏性（必须升主版本）| 兼容性（不升版本）|
+|---|---|
+| 删除字段 / 端点 | 新增**可选**字段 / 新端点 |
+| 重命名字段 | 新增可选请求参数（有安全默认）|
+| 改字段类型 / 取值含义 | 放宽校验（接受更多输入）|
+| 把可选参数改为必填 | 新增枚举值（**需消费方容忍未知值**）|
+| 改默认行为 / 改错误码语义 | 新增响应头 |
+| 收紧校验（拒绝原本接受的输入）| bug 修复（不改契约语义）|
+| 改认证 / 分页 / 排序契约 | 性能优化（行为不变）|
+
+判定底线：**任何让现有调用方的正确请求开始失败、或让它依赖的返回结构变形的改动，都是破坏性的。** 新增枚举值是否破坏，取决于你是否在契约里要求消费方"忽略未知值"——要求了才算兼容。
+
+## 4. 弃用生命周期（三阶段，可预期）
+
+```
+公告(announce) → 过渡(transition) → 下线(sunset)
+```
+
+| 阶段 | 动作 |
+|---|---|
+| 公告 | 在文档/changelog 标记弃用，给出替代方案、迁移指南、**明确下线日期** |
+| 过渡 | 老版本继续可用但返回弃用信号（见 §5），主动联系高频调用方，监控剩余用量 |
+| 下线 | 用量降到可接受阈值且过了承诺期后，停用老版本并返回明确错误 |
+
+铁律：**先有替代、再宣弃用**——没有可迁移的新版本，不准弃用老版本。给足真实的迁移窗口（按受众，常以季度/年计），不是说下线就下线。
+
+## 5. 弃用信号（让调用方提前知道）
+
+- **`Deprecation` 头**：标记该端点/版本已弃用（可带弃用时间）。
+- **`Sunset` 头**：标明计划下线时间，让调用方有据可依地排期迁移。
+- **`Link` 头 / 文档**：指向替代端点与迁移指南。
+- **可观测**：服务端监控老版本调用量与调用方，弃用进度数据驱动，而不是猜。
+- **changelog**：每次版本变更面向使用者写清"新增/变更/弃用/破坏性/迁移方式"。
+
+## 6. 治理与协同
+
+- **契约即真相**：接口契约（OpenAPI 等）是版本化和兼容性校验的依据；契约变更要过契约测试（见 `testing/01-standards/contract-testing-and-api-contracts`）。
+- **兼容性门禁**：CI 中校验新契约对现有消费方兼容（无未升版的破坏性变更），不兼容则拦住发布（见 `testing/01-standards/ci-test-gates-and-coverage`）。
+- **消费方清单**：维护"谁在调哪个版本"，弃用前能精准触达，下线前能确认无活跃调用。
+- **内部 vs 外部**：内部接口可更快迭代、更短窗口；公开/合作方接口要更长支持期与更正式公告。
+- **与开关的边界**：功能开关控行为可见性，**不替代**版本化（见 `release-engineering/01-standards/feature-flag-lifecycle`）。
+
+## 7. 反模式（出现即不合格）
+
+1. **破坏性变更不升版**：直接改线上契约，老调用方批量 500/解析失败。
+2. **静默弃用 / 突然下线**：不公告、不给迁移期，某天直接 404。
+3. **无替代就弃用**：宣布老版本退场却没有可迁移的新版本。
+4. **无限维护所有版本**：从不下线，版本越堆越多，维护成本失控。
+5. **版本方式混用**：URL、header、query 各处混搭，调用方无所适从。
+6. **不知道谁在调**：没有消费方与用量数据，不敢动也不敢下线。
+7. **把收紧校验当兼容**：以为"只是更严格"，其实让原本合法的请求开始被拒。
+8. **changelog 堆 commit**：使用者看不懂变了什么、要不要迁移。
+
+## 8. 最低交付 checklist
+
+- [ ] 选定一种版本化方式并全项目统一；破坏性变更升主版本。
+- [ ] 明确区分破坏性/兼容性变更，破坏性绝不进同版本。
+- [ ] 弃用走公告→过渡→下线三阶段，**先有替代再弃用**，给足迁移窗口。
+- [ ] 弃用时返回 `Deprecation`/`Sunset` 信号，文档给出迁移指南。
+- [ ] 监控各版本调用量与消费方，弃用/下线数据驱动、可精准触达。
+- [ ] 契约为准，CI 做兼容性门禁，破坏性变更被拦截。
+- [ ] changelog 面向使用者写清变更与迁移方式。
+- [ ] 明确版本支持窗口，到期有序下线、守约不突袭。

package/architecture/01-standards/configuration-and-environment-management.md

@@ -0,0 +1,104 @@
+---
+id: configuration-and-environment-management
+title: 配置与环境管理规范（配置即代码/环境对等/启动校验，商业级必读）
+domain: architecture
+category: 01-standards
+difficulty: advanced
+tags: [configuration, environment, 12-factor, config-as-code, secret-management, env-parity, config-validation, fail-fast, config-drift, promotion, 配置管理, 环境对等, 配置校验, 配置漂移, 密钥分离, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 配置与环境管理规范（商业级必读）
+
+> 一份代码要跑在 dev / staging / prod 多个环境，环境之间**只有配置不同、代码完全一致**。配置一旦失控——硬编码环境分支、密钥进仓库、环境之间偷偷不一样、缺配置跑到一半才崩——线上事故里有相当一部分根本不是代码 bug，而是"配置在这个环境是错的"。
+> 商业级系统把配置当成**一等交付物**来治理：配置与代码分离、配置与密钥分离、环境严格对等、启动即校验、变更可审计可回滚。本规范给出可落地的配置纪律，不绑定任何具体配置中心产品（产品选型见 `architecture/configuration-management`）。
+
+## 1. 三条分离原则（地基）
+
+| 分离 | 含义 | 违反的后果 |
+|---|---|---|
+| 配置与代码分离 | 环境差异（地址、开关、阈值、外部 URL）从外部注入，绝不写死在代码里按环境 `if` | 改一个环境的值要改代码、重新构建、重新走发布 |
+| 配置与密钥分离 | 普通配置（可入仓库的非敏感项）与密钥（token/私钥/口令）分两套管理 | 密钥混进配置仓库 → 泄露面无限扩大 |
+| 构建产物与环境无关 | 同一个制品（镜像/包）不改一行就能部署到任意环境 | 每个环境单独构建 → "在 staging 是好的，prod 这个包不一样" |
+
+核心判据：**同一份构建产物 + 不同配置 = 不同环境**。如果切环境需要重新构建，说明配置没真正外置。
+
+## 2. 配置分类与来源优先级
+
+把配置按性质分类，每类有明确的来源与生命周期：
+
+| 类别 | 例子 | 来源 | 是否敏感 | 变更频率 |
+|---|---|---|---|---|
+| 基础设施配置 | DB 地址、缓存地址、队列地址 | 环境变量 / 配置中心 | 否 | 低 |
+| 密钥 | DB 口令、API 私钥、签名密钥 | 密钥管理（KMS/Vault/云 secret） | 是 | 中（轮换） |
+| 业务参数 | 超时、重试次数、限流阈值、分页大小 | 配置文件 / 配置中心 | 否 | 中 |
+| 功能开关 | 灰度开关、降级开关 | 功能开关系统（见 `release-engineering/feature-flag-lifecycle`） | 否 | 高 |
+| 环境标识 | 环境名、区域、版本号 | 注入环境变量 | 否 | 部署时定 |
+
+**来源优先级要确定且唯一**：约定一个清晰的覆盖顺序（如 默认值 < 配置文件 < 环境变量 < 启动参数），写进文档；同一个键绝不允许两处都"可能生效"导致猜不到实际取了哪个值。配置解析后应能**打印生效配置快照**（脱敏）便于排障。
+
+## 3. 启动即校验（fail-fast）
+
+配置错误必须在**进程启动的最初几秒**暴露，而不是跑到第一个用到该配置的请求才崩——那时已经在线上了。
+
+- **必需项缺失即拒绝启动**：所有 required 配置在 boot 阶段检查，缺一个就打印清晰错误并退出非零码，绝不带病启动。
+- **类型与取值域校验**：端口必须是数字、超时必须为正、URL 必须可解析、枚举必须在允许集合内——用 schema（如结构化配置类型 + 校验器）统一校验，不要散落在各处 `parseInt`。
+- **依赖连通性可选探活**：对关键依赖（DB/缓存）在 readiness 前做一次连通探测，把"配错地址"挡在接流量之前（见 `backend/01-standards/config-and-observability` 的健康检查）。
+- **校验信息可读**：错误要说清"哪个键、期望什么、实际拿到什么、从哪个来源读的"，让人 5 秒定位，而不是一个裸 `NullPointerException`。
+
+## 4. 环境对等（dev / staging / prod parity）
+
+环境之间差异越小，"本地好的、线上挂的"越少。
+
+- **同构而非异构**：各环境用**相同的**依赖种类与版本（同样的数据库引擎、同样的队列、同样的运行时版本），差异只在规格与数据量，不在技术栈。staging 必须尽可能贴近 prod。
+- **配置键集合一致**：所有环境拥有**相同的配置键集合**，只是值不同。新增一个配置项，必须同时为所有环境提供值（哪怕是默认），杜绝"prod 少配了一个键"。
+- **用 .env.example 锁定契约**：仓库里提供 `.env.example`（或等价的配置模板）列出全部键与占位说明；真实的 `.env` 入 gitignore。CI 校验"代码里读取的键"⊆"模板声明的键"。
+- **禁止环境特判代码**：代码里出现 `if (env === 'prod')` 改变业务逻辑是反模式；环境差异应体现为**配置值**，不是**代码分支**。可观测性、日志级别等运行差异也走配置。
+
+## 5. 密钥的生命周期
+
+密钥是配置里风险最高的一类，单列治理：
+
+- **绝不进仓库/镜像/日志**：密钥不提交版本库、不打进镜像层、不打印到日志与错误信息、不进前端可见的产物。提交前用 secret 扫描挡住（见 `security/01-standards/supply-chain-security`、`security/secrets-management`）。
+- **运行时注入**：密钥在运行时从密钥管理服务注入（环境变量 / 挂载 / SDK 拉取），应用只持有引用不持有明文落盘。
+- **可轮换**：密钥支持**无停机轮换**——应用能感知新密钥并平滑切换，轮换不需要改代码、不需要长停机。设定轮换周期与到期告警。
+- **最小权限**：每个服务只拿它需要的密钥；不同环境用**不同**密钥，绝不 dev 与 prod 共用一把。
+- **泄露应急**：密钥一旦疑似泄露，流程是**立即吊销 + 轮换**，而不是"先观察"。
+
+## 6. 配置变更管理（配置即代码）
+
+线上配置变更和代码发布一样危险——很多重大故障是"改了一个配置值"引发的。
+
+- **配置走版本控制与评审**：非密钥配置以**配置即代码**方式管理（声明式文件入库 + PR 评审 + diff 可见），不在控制台手改无记录。
+- **变更可审计**：谁、何时、把哪个键从什么改成什么，要有审计记录（见 `compliance/audit-logging-and-evidence`）。
+- **变更可回滚**：配置有版本历史，能一键回滚到上一个已知良好版本；回滚和发布同等重要。
+- **高风险配置灰度**：影响面大的配置（限流、超时、开关）变更要能**灰度 + 监控 + 快速回退**，不要全量瞬时生效。
+- **运行时热更要安全**：支持热更新的配置，变更后要有校验与生效确认；不可在无校验下让一个错值瞬间打到全量。
+
+## 7. 配置漂移与一致性
+
+- **检测漂移**：定期比对"声明的期望配置"与"运行时实际配置"，发现手动改动导致的漂移并告警。运行时实际值应能导出与基线比对。
+- **不可变基础设施优先**：环境通过声明式 IaC 重建而非手动改出来，从根上减少漂移（见 `cloud-native` / `devops/terraform`）。
+- **配置与制品绑定可追溯**：每次部署记录"用了哪个制品版本 + 哪个配置版本"，出事能精确反查组合。
+
+## 8. 反模式（出现即不合格）
+
+1. **硬编码 + 环境特判**：地址/密钥写死在代码里，或用 `if (env==='prod')` 改业务逻辑。
+2. **密钥进仓库/镜像/日志**：token、口令出现在代码、配置仓库、镜像层或日志中。
+3. **缺配置跑到一半才崩**：没有启动校验，错误在第一个用到的请求才暴露在线上。
+4. **环境键集合不一致**：prod 少配/多配了键，本地与线上技术栈不同，"本地好的线上挂"。
+5. **每个环境单独构建**：制品不是环境无关的，切环境要重新打包，破坏可追溯性。
+6. **控制台手改无记录**：线上配置在控制台裸手改，无评审、无审计、无法回滚。
+7. **配置来源含糊**：同一个键多处可能生效，实际取了哪个值靠猜。
+8. **密钥无法轮换**：密钥写死，轮换需要改代码或长停机；dev 与 prod 共用密钥。
+
+## 9. 最低交付 checklist
+
+- [ ] 配置与代码分离、密钥与普通配置分离、制品环境无关（同一产物跑所有环境）。
+- [ ] 配置来源优先级唯一且文档化，能打印脱敏后的生效配置快照。
+- [ ] 启动即校验：必需项缺失/类型错/取值越界立即 fail-fast 并给可读错误。
+- [ ] 各环境配置键集合一致，提供 `.env.example` 模板，CI 校验代码读取的键⊆模板。
+- [ ] 代码中无 `if(env)` 改业务逻辑；环境差异只体现为配置值。
+- [ ] 密钥运行时注入、不入仓库/镜像/日志、可无停机轮换、按环境隔离、有到期告警。
+- [ ] 非密钥配置以配置即代码方式入库评审，变更可审计、可回滚、高风险项可灰度。
+- [ ] 定期检测配置漂移；部署记录制品版本 + 配置版本可追溯。

package/architecture/01-standards/domain-driven-design-complete.md

@@ -0,0 +1,105 @@
+---
+id: domain-driven-design-complete
+title: 领域驱动设计与边界划分规范（商业级必读）
+domain: architecture
+category: 01-standards
+difficulty: advanced
+tags: [ddd, 领域驱动, 限界上下文, bounded-context, 聚合, aggregate, 通用语言, 战略设计, 战术设计, 防腐层, 上下文映射, 服务边界, 商业级]
+quality_score: 95
+last_updated: 2026-06-29
+---
+
+# 领域驱动设计与边界划分规范（商业级必读）
+
+> 服务边界划错，后面所有努力都在还债。商业级系统的复杂度不在技术、在业务——领域驱动设计（DDD）的价值是先用**业务语言**把问题切成内聚、低耦合的块，再让代码结构与团队结构对齐这些块。本规范是框架无关的硬性约束：先做战略划分（限界上下文 + 上下文映射），再做战术建模（聚合 / 实体 / 值对象 / 领域服务），最后才落到分包与接口。**不要按数据库表或技术分层切微服务，要按业务能力切。**
+
+## 1. 何时该用 DDD（先判断，别滥用）
+
+- **适用**：核心业务有真实复杂度（多状态机、复杂规则、多角色协作、长期演进）的系统。这正是 DDD 回本的地方。
+- **不适用 / 轻量化**：纯增删改查后台、一次性脚本、数据搬运、薄展示层——上 DDD 全套是过度设计，用事务脚本（Transaction Script）/ 表模块即可。
+- **判据**：业务规则是否值得用一套"通用语言"反复讨论？是否会演进 3 年以上？是否多团队协作？三个都"否"就别上重型 DDD，只借用"限界上下文"这一条来切边界。
+- 商业级默认：**核心域用 DDD 战术建模，支撑域/通用域用轻量 CRUD**，不要平均用力。
+
+## 2. 通用语言（Ubiquitous Language）——一切的地基
+
+- 业务方、产品、研发、测试**用同一套词**描述同一个概念；这套词必须**直接出现在代码里**（类名、方法名、事件名）。
+- 禁止"翻译层"：业务说"履约单"，代码却叫 `OrderProcess2` / `data` / `info` —— 概念漂移就是 bug 的温床。
+- 同一个词在不同上下文含义不同是**正常的**（"商品"在商品域是 SKU 定义，在订单域是下单快照）——这恰恰是要拆上下文的信号，不要强行做一个"上帝模型"。
+- 落地动作：维护一份**领域术语表（Glossary）**，每个核心概念一句话定义 + 所属上下文；新人 onboarding 和评审都引用它。
+
+## 3. 战略设计：限界上下文（Bounded Context）
+
+限界上下文是 DDD 的**第一性切割**：一个模型在其内部保持一致、边界清晰、有明确的归属团队。
+
+- **一个上下文 = 一套内部一致的模型 + 一种语言 + 一个负责团队**。跨上下文不共享领域模型，只交换契约（DTO/事件）。
+- 上下文边界优先按**业务能力**（下单、支付、库存、履约、风控），不按技术（不是"数据库层""缓存层"）。
+- 上下文 ≠ 微服务，但**微服务边界必须落在上下文边界上**：一个服务可含多个上下文（模块化单体），但绝不允许一个上下文被两个服务撕开。
+- 子域分类，决定投入：
+  - **核心域（Core）**：差异化竞争力所在，投最强的人，做最精的模型。
+  - **支撑域（Supporting）**：业务需要但不差异化，够用就行，可外包/低代码。
+  - **通用域（Generic）**：行业通用（认证、通知、计费），优先买/用现成方案，别自研。
+
+## 4. 战略设计：上下文映射（Context Mapping）
+
+明确上下文之间的**关系与权力结构**——这是治理跨团队耦合的关键。
+
+- **防腐层（Anti-Corruption Layer, ACL）**：下游不让上游/外部的模型污染自己的领域模型，在边界放一层转译。**对接任何外部系统、遗留系统、第三方 API 都必须有 ACL**，否则外部的烂模型会渗透进核心域。
+- **开放主机服务 + 发布语言（OHS/PL）**：被多方依赖的上下文，对外暴露稳定、版本化的契约（如 OpenAPI / 事件 schema），不暴露内部模型。
+- **客户-供应商 / 遵奉者（Conformist）**：上游不为下游改契约时，下游要么做 ACL 适配，要么直接遵奉上游模型（仅当上游模型够好）。
+- **共享内核（Shared Kernel）**：两个上下文共享一小段模型/代码——**慎用**，共享即耦合，必须同一团队或强协作约定，改动需双方同意。
+- 画一张**上下文映射图**作为架构基线产物：节点是上下文，边标注关系类型与依赖方向。评审架构先看这张图。
+
+## 5. 战术设计：聚合 / 实体 / 值对象
+
+在单个上下文内部建模，核心是**聚合（Aggregate）**——一致性与事务的边界。
+
+- **实体（Entity）**：有唯一标识、生命周期内可变（用户、订单）。相等性看 ID，不看属性。
+- **值对象（Value Object）**：无标识、不可变、按值相等（金额、地址、时间区间）。**优先用值对象消灭"裸基本类型"**——`Money{amount, currency}` 远好过两个 `BigDecimal`，类型即约束。
+- **聚合（Aggregate）**：一组实体+值对象的一致性边界，有一个**聚合根（Aggregate Root）**作为唯一入口。规则：
+  1. **外部只能引用聚合根**，不能直接持有聚合内部对象的引用。
+  2. **一个事务只修改一个聚合**（跨聚合一致性用领域事件 + 最终一致，见 §6）。
+  3. **聚合要小**：聚合越大，事务冲突和锁争用越严重。能拆就拆，跨聚合用 ID 软引用而非对象引用。
+  4. 不变量（invariant）在聚合根内强制——业务规则的守门人是聚合，不是 Service、更不是数据库触发器。
+- **领域服务（Domain Service）**：不属于任何单一实体的业务逻辑（如"转账"涉及两个账户），无状态，用领域语言命名。
+- **领域逻辑放领域层**：贫血模型（实体只有 getter/setter，逻辑全在 Service）是反模式——业务规则散落、无法复用、难测试。让聚合/实体承载行为。
+
+## 6. 战术设计：领域事件与跨聚合一致性
+
+- **领域事件（Domain Event）**：领域里有意义的事实，过去式命名（`OrderPlaced` / `PaymentCaptured`）。它是上下文之间、聚合之间解耦的主要手段。
+- 跨聚合 / 跨上下文**不要用分布式事务（2PC）**，用领域事件驱动最终一致性 + 幂等消费（见 `backend/01-standards/idempotency-and-exactly-once.md`）。
+- 事件发布要可靠：业务写库与事件发布同一事务，用**发件箱（Outbox）模式**，避免"库写了事件没发/事件发了库没写"。
+- 跨多个聚合的业务流程（下单→扣库存→支付→履约）用 **Saga / 流程管理器（Process Manager）**编排，每步可补偿、可重试、可观测。
+- 事件是契约：跨上下文的事件 schema 要版本化、向后兼容，纳入契约测试（见 `testing/01-standards/contract-testing-complete.md`）。
+
+## 7. 从模型到代码：分层与分包
+
+- **按上下文分包，再按层分包**（package-by-feature/context 优先于 package-by-layer）：`ordering/`、`inventory/` 在最外层，内部再分 `domain` / `application` / `infrastructure`。
+- 依赖方向**永远指向领域**：`infrastructure → application → domain`，领域层零外部依赖（不 import 框架、不 import ORM 注解时优先用纯对象）。这与整洁/六边形架构一致。
+- **应用层（Application/Use Case）**：编排聚合、管事务、发事件，**不含业务规则**（规则在领域层）。一个用例一个方法，输入输出是 DTO。
+- **仓储（Repository）**：每个聚合根一个仓储，接口定义在领域层，实现放基础设施层。仓储按聚合存取，不暴露查询拼装细节。
+- 读写分离：复杂查询/报表不要硬塞进聚合，用单独的查询模型（CQRS 的读侧），直接投影到 DTO，绕过领域模型。
+
+## 8. 反模式（出现即不合格）
+
+- **按数据库表 / 技术分层切服务**：出现 `user-service` 只是 `user` 表的 CRUD 包装，没有业务边界。
+- **上帝模型 / 大泥球**：一个 `User` / `Order` 类被所有上下文共享，字段几十上百，谁都不敢改。
+- **贫血领域模型**：实体只有数据没有行为，业务逻辑全堆在 `XxxServiceImpl`。
+- **聚合过大**：一个聚合加载几百个子实体，一次保存锁全表。
+- **跨聚合直接对象引用 + 跨聚合一个大事务**：耦合死、扩展难、锁冲突。
+- **无防腐层直连外部模型**：第三方/遗留系统的字段直接渗透进核心领域对象。
+- **共享内核滥用**：多个团队共享一大坨"common"模型，改一处崩一片。
+- **DDD 仪式化**：纯 CRUD 后台硬套聚合/仓储/事件全套，徒增复杂度而无收益。
+- **代码与通用语言脱节**：业务说一套、代码命名另一套，全靠口头翻译。
+
+## 9. Agent Checklist（建模/架构前必过）
+
+- [ ] 是否先判断了"该不该上 DDD"？核心域重点投入、支撑/通用域轻量化？
+- [ ] 是否产出了**上下文映射图**，标注了关系类型与依赖方向？
+- [ ] 服务/模块边界是否落在限界上下文边界上（按业务能力，不按表/技术层）？
+- [ ] 是否维护了**领域术语表**，且代码命名与之一致？
+- [ ] 每个聚合是否足够小、有明确聚合根、外部只引用根、一事务一聚合？
+- [ ] 是否用了值对象消灭裸基本类型，把不变量收进聚合？
+- [ ] 跨聚合/跨上下文是否用领域事件 + 最终一致 + Outbox，而非分布式事务？
+- [ ] 对接外部/遗留系统是否有防腐层（ACL）？
+- [ ] 依赖方向是否指向领域层？领域层是否零框架耦合、承载行为（非贫血）？
+- [ ] 跨上下文契约（API/事件 schema）是否版本化并纳入契约测试？

package/architecture/02-playbooks/migration-playbook.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：系统迁移全流程作战手册
-# 作用：指导团队完成系统迁移的评估、规划、执行、验证与切换
-# 创建时间：2026-03-28
-# 最后修改：2026-03-28
+# 系统迁移作战手册
 
 ## 目标
 

package/architecture/02-playbooks/system-design-playbook.md

@@ -10,11 +10,7 @@ difficulty: intermediate
 quality_score: 70
 ---
 
-# 开发：Excellent（11964948@qq.com）
-# 功能：系统设计全流程作战手册
-# 作用：指导架构师完成从需求分析到详细设计的系统设计全过程
-# 创建时间：2026-03-28
-# 最后修改：2026-03-28
+# 系统设计作战手册
 
 ## 目标
 

package/architecture/adr-template-and-examples.md

@@ -1,16 +1,14 @@
 ---
 id: adr-template-and-examples
-title: adr-template-and-examples
+title: ADR 模板与示例规范
 domain: architecture
-category: adr-template-and-examples.md
+category: 01-standards
 difficulty: intermediate
-tags: [adr, and, architecture, examples, template, 模板与示例规范]
+tags: [adr, 架构决策, decision-record, 模板, 技术选型, architecture]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
-
-## ADR 模板与示例规范
+# ADR 模板与示例规范
 
 ### 目标
 - 对关键架构决策形成可追溯记录，降低后续误解与返工。

package/architecture/api-gateway-deep-dive.md

@@ -2,7 +2,7 @@
 id: api-gateway-deep-dive
 title: API网关深度指南
 domain: architecture
-category: api-gateway-deep-dive.md
+category: 01-standards
 difficulty: intermediate
 tags: [api, architecture, deep, dive, gateway, 主流api网关对比, 安全防护, 性能优化]
 quality_score: 70