cdspec 0.1.1 → 0.1.3

package/templates/{standards-backend → backend-standard}/references/DDD/346/236/266/346/236/204/347/272/246/346/235/237.md

@@ -1,103 +1,103 @@
-# DDD 架构约束（项目实战总结版）
-
-## 1. 目标与适用边界
-1. 本规范用于业务规则复杂、状态流转明确、需要长期演进的模块。
-2. 以“领域规则内聚、技术细节外置、跨服务编排上收”为核心目标。
-3. 纯 CRUD 且规则稳定场景优先使用传统三层，不强行 DDD 化。
-
-## 2. 分层模型与职责
-### 2.1 Performance（接口层）
-1. 只负责请求接收、参数校验、响应组装。
-2. 禁止在 Controller 写领域规则和状态流转。
-3. 对外 DTO 只表达接口语义，不泄露领域内部对象结构。
-
-### 2.2 Application（应用层）
-1. 负责用例编排、事务边界、流程顺序控制。
-2. 负责“加载聚合 -> 调用领域行为 -> 持久化 -> 后置动作”的主线流程。
-3. 可做跨聚合协调，但禁止承载可复用的核心业务规则。
-
-### 2.3 Domain（领域层）
-1. 聚合根维护一致性边界内的业务不变量。
-2. 领域实体/值对象暴露业务行为（如提交、确认、状态刷新、数量回写）。
-3. 领域服务承载跨实体规则，保持无基础设施依赖。
-4. 对外依赖通过领域接口抽象（如 `*DomainService`、`*Policy`、`*Repository`）。
-
-### 2.4 Infrastructure（基础设施层）
-1. 实现仓储、策略实现、事件发布器、外部系统客户端。
-2. 承担实体映射与持久化细节，不写业务编排。
-3. 将技术框架能力适配为领域可用接口实现。
-
-## 3. 依赖方向与边界约束
-1. 依赖方向必须稳定：Performance -> Application -> Domain <- Infrastructure。
-2. Domain 禁止依赖 Spring 配置对象、三方 SDK、数据库/消息中间件 API。
-3. Application 禁止绕过领域接口直接依赖底层持久化细节。
-4. Infrastructure 不得反向调用 Application 形成环依赖。
-
-## 4. 聚合设计经验
-1. 聚合根只维护本聚合状态，不跨聚合直接改写对方对象。
-2. 聚合行为命名必须体现业务语义（如 `submit`、`confirm`、`ensureCanEdit`），避免 `doXxx`。
-3. 聚合内校验前置：关键写操作前统一执行可编辑性、状态合法性和明细合法性校验。
-4. 状态流转规则优先封装到枚举/值对象，避免散落的状态码判断。
-5. 聚合字段保持业务最小集，查询条件对象与聚合对象分离。
-
-## 5. 应用服务编排经验
-1. 应用层方法先做轻量参数保护，再加载聚合，最后调用领域行为。
-2. 提交、确认、删除等写操作必须加事务，防止主子表或多仓储更新不一致。
-3. 应用层日志至少记录：业务主键、关键状态、明细数量、执行结果。
-4. 批量操作采用“逐条复用单条逻辑”优先，保证规则一致性。
-
-## 6. 仓储与聚合持久化经验
-1. 仓储接口定义在 Domain，实现在 Infrastructure。
-2. 主表与明细作为聚合整体持久化，提供 `saveAggregate/updateAggregate` 语义接口。
-3. 仓储实现负责“主表落库 + 明细绑定主键 + 明细落库”，应用层不拼装 SQL。
-4. 查询场景按职责拆分：`findById`、`findByNumber`、`findByIdOrNo` 等语义化接口。
-5. Converter 统一负责领域对象与持久化对象转换，禁止在应用层手写大量字段搬运。
-
-## 7. 策略与工厂落地经验
-1. 多租户/多工厂差异规则统一抽象为 `Policy/Strategy` 接口。
-2. 应用层使用工厂解析策略，先匹配显式配置，再匹配租户能力，最后默认兜底。
-3. 默认策略必须存在，且行为可预期。
-4. 策略实现只关注规则差异，不复制主流程。
-
-## 8. 适配器与防腐层经验
-1. 领域接口与已有应用服务模型不一致时，使用应用层 Adapter 进行桥接转换。
-2. 适配器职责只做转换与转调，不承载业务决策。
-3. 外部返回结果判断必须绑定业务语义，禁止笼统“成功/失败兜底”。
-
-## 9. 跨服务编排约束（项目级）
-1. 原子服务（DDD 主栈）只处理本域逻辑，不直接编排外部微服务调用。
-2. 跨服务联动统一放聚合层编排（Facade 层）处理。
-3. 原子服务只负责状态回写、领域规则执行和本域数据一致性。
-
-## 10. 领域事件与一致性经验
-1. 领域事件接口定义在 Domain，发布实现放 Infrastructure。
-2. 应用层在聚合状态稳定后触发事件发布，避免中间态事件外泄。
-3. 事件发布失败策略需明确：重试、补偿或降级日志，不能静默吞掉。
-
-## 11. 校验、异常与日志规范
-1. 参数校验保持最小必要原则，避免重复校验链。
-2. 业务异常信息必须可读并包含关键上下文。
-3. 关键分支、状态变更、异常场景必须有中文日志。
-4. 禁止在通用兜底里吞异常后继续成功返回。
-
-## 12. 测试与回归要求
-1. 领域层：聚合行为与状态流转必须有单元测试。
-2. 基础设施层：仓储聚合保存、更新、删除要有集成测试。
-3. 接口层：关键 API 场景要有集成测试覆盖。
-4. 每次重构至少保证“新增/编辑/提交/删除”主链路可回归。
-
-## 13. 反模式清单（必须规避）
-1. 在 Controller 或 Mapper 层写核心业务规则。
-2. 领域对象直接依赖 Spring 或外部服务 SDK。
-3. 应用层出现大量状态码分支，领域对象退化为贫血模型。
-4. 仓储只存主表不处理聚合明细，导致一致性缺口。
-5. 没有默认策略实现，新增租户时直接运行失败。
-6. 跨服务调用下沉到原子服务，破坏边界与可测试性。
-
-## 14. 交付前 DDD 自检清单
-1. 本次规则是否真正沉淀在 Domain。
-2. 是否存在跨层越权调用。
-3. 聚合保存是否覆盖主表与明细一致性。
-4. 策略扩展是否满足“新增实现类即可扩展”。
-5. 是否补齐关键测试与中文日志。
-6. 是否将跨服务编排留在聚合层处理。
+# DDD 架构约束（项目实战总结版）
+
+## 1. 目标与适用边界
+1. 本规范用于业务规则复杂、状态流转明确、需要长期演进的模块。
+2. 以“领域规则内聚、技术细节外置、跨服务编排上收”为核心目标。
+3. 纯 CRUD 且规则稳定场景优先使用传统三层，不强行 DDD 化。
+
+## 2. 分层模型与职责
+### 2.1 Performance（接口层）
+1. 只负责请求接收、参数校验、响应组装。
+2. 禁止在 Controller 写领域规则和状态流转。
+3. 对外 DTO 只表达接口语义，不泄露领域内部对象结构。
+
+### 2.2 Application（应用层）
+1. 负责用例编排、事务边界、流程顺序控制。
+2. 负责“加载聚合 -> 调用领域行为 -> 持久化 -> 后置动作”的主线流程。
+3. 可做跨聚合协调，但禁止承载可复用的核心业务规则。
+
+### 2.3 Domain（领域层）
+1. 聚合根维护一致性边界内的业务不变量。
+2. 领域实体/值对象暴露业务行为（如提交、确认、状态刷新、数量回写）。
+3. 领域服务承载跨实体规则，保持无基础设施依赖。
+4. 对外依赖通过领域接口抽象（如 `*DomainService`、`*Policy`、`*Repository`）。
+
+### 2.4 Infrastructure（基础设施层）
+1. 实现仓储、策略实现、事件发布器、外部系统客户端。
+2. 承担实体映射与持久化细节，不写业务编排。
+3. 将技术框架能力适配为领域可用接口实现。
+
+## 3. 依赖方向与边界约束
+1. 依赖方向必须稳定：Performance -> Application -> Domain <- Infrastructure。
+2. Domain 禁止依赖 Spring 配置对象、三方 SDK、数据库/消息中间件 API。
+3. Application 禁止绕过领域接口直接依赖底层持久化细节。
+4. Infrastructure 不得反向调用 Application 形成环依赖。
+
+## 4. 聚合设计经验
+1. 聚合根只维护本聚合状态，不跨聚合直接改写对方对象。
+2. 聚合行为命名必须体现业务语义（如 `submit`、`confirm`、`ensureCanEdit`），避免 `doXxx`。
+3. 聚合内校验前置：关键写操作前统一执行可编辑性、状态合法性和明细合法性校验。
+4. 状态流转规则优先封装到枚举/值对象，避免散落的状态码判断。
+5. 聚合字段保持业务最小集，查询条件对象与聚合对象分离。
+
+## 5. 应用服务编排经验
+1. 应用层方法先做轻量参数保护，再加载聚合，最后调用领域行为。
+2. 提交、确认、删除等写操作必须加事务，防止主子表或多仓储更新不一致。
+3. 应用层日志至少记录：业务主键、关键状态、明细数量、执行结果。
+4. 批量操作采用“逐条复用单条逻辑”优先，保证规则一致性。
+
+## 6. 仓储与聚合持久化经验
+1. 仓储接口定义在 Domain，实现在 Infrastructure。
+2. 主表与明细作为聚合整体持久化，提供 `saveAggregate/updateAggregate` 语义接口。
+3. 仓储实现负责“主表落库 + 明细绑定主键 + 明细落库”，应用层不拼装 SQL。
+4. 查询场景按职责拆分：`findById`、`findByNumber`、`findByIdOrNo` 等语义化接口。
+5. Converter 统一负责领域对象与持久化对象转换，禁止在应用层手写大量字段搬运。
+
+## 7. 策略与工厂落地经验
+1. 多租户/多工厂差异规则统一抽象为 `Policy/Strategy` 接口。
+2. 应用层使用工厂解析策略，先匹配显式配置，再匹配租户能力，最后默认兜底。
+3. 默认策略必须存在，且行为可预期。
+4. 策略实现只关注规则差异，不复制主流程。
+
+## 8. 适配器与防腐层经验
+1. 领域接口与已有应用服务模型不一致时，使用应用层 Adapter 进行桥接转换。
+2. 适配器职责只做转换与转调，不承载业务决策。
+3. 外部返回结果判断必须绑定业务语义，禁止笼统“成功/失败兜底”。
+
+## 9. 跨服务编排约束（项目级）
+1. 原子服务（DDD 主栈）只处理本域逻辑，不直接编排外部微服务调用。
+2. 跨服务联动统一放聚合层编排（Facade 层）处理。
+3. 原子服务只负责状态回写、领域规则执行和本域数据一致性。
+
+## 10. 领域事件与一致性经验
+1. 领域事件接口定义在 Domain，发布实现放 Infrastructure。
+2. 应用层在聚合状态稳定后触发事件发布，避免中间态事件外泄。
+3. 事件发布失败策略需明确：重试、补偿或降级日志，不能静默吞掉。
+
+## 11. 校验、异常与日志规范
+1. 参数校验保持最小必要原则，避免重复校验链。
+2. 业务异常信息必须可读并包含关键上下文。
+3. 关键分支、状态变更、异常场景必须有中文日志。
+4. 禁止在通用兜底里吞异常后继续成功返回。
+
+## 12. 测试与回归要求
+1. 领域层：聚合行为与状态流转必须有单元测试。
+2. 基础设施层：仓储聚合保存、更新、删除要有集成测试。
+3. 接口层：关键 API 场景要有集成测试覆盖。
+4. 每次重构至少保证“新增/编辑/提交/删除”主链路可回归。
+
+## 13. 反模式清单（必须规避）
+1. 在 Controller 或 Mapper 层写核心业务规则。
+2. 领域对象直接依赖 Spring 或外部服务 SDK。
+3. 应用层出现大量状态码分支，领域对象退化为贫血模型。
+4. 仓储只存主表不处理聚合明细，导致一致性缺口。
+5. 没有默认策略实现，新增租户时直接运行失败。
+6. 跨服务调用下沉到原子服务，破坏边界与可测试性。
+
+## 14. 交付前 DDD 自检清单
+1. 本次规则是否真正沉淀在 Domain。
+2. 是否存在跨层越权调用。
+3. 聚合保存是否覆盖主表与明细一致性。
+4. 策略扩展是否满足“新增实现类即可扩展”。
+5. 是否补齐关键测试与中文日志。
+6. 是否将跨服务编排留在聚合层处理。