@umacloud/knowledge 1.0.15 → 1.0.16

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

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

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

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

@@ -8,7 +8,7 @@ tags: [adr, and, architecture, examples, template, 模板与示例规范]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# adr-template-and-examples
 
 ## ADR 模板与示例规范