adspecs 0.1.12

package/.adspecs/templates/03-/347/263/273/347/273/237/350/256/276/350/256/241/346/250/241/346/235/277.md

@@ -0,0 +1,1878 @@
+# 系统设计统一模板（OOA + OOD）
+
+> **所属模块**：{{一级模块名称}}
+> **服务名称**：{{微服务名称，来自于02-crm_system_architecture.md 二、技术架构章节}}  |**端口**:3103
+> **版本**: v1.1
+> **创建日期**: 2026-06-12
+> **修订日期**: 2026-06-13（§5.2 重构：Controller 代码骨架精简为方法路由 + Service 调用表；§5.3 新增 5 个标准端点的成功/错误响应 JSON 示例；§5.4 权限矩阵调整）
+> **适用人员**: 需求分析师、系统设计师、AI助手
+> **目的**: 基于 PRD / 原始需求，一次性完成需求分析（OOA）和系统设计（OOD），输出可直接编码的设计文档。本文件包含完整的项目约定、模板结构、填写示例和追溯关系。
+
+### 修订记录
+
+| 版本号 | 修订日期   | 修订人 | 修订内容                                                                                                                                                                                          |
+| ------ | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| v1.0   | 2026-06-12 | AI     | 初始版本：合并项目约定 + 两阶段导航 + 追溯关系，引用 04/05 外部文件                                                                                                                               |
+| v1.1   | 2026-06-13 | AI     | **单阶段重构**：统一流程模板。按业务关注点组织（实体→数据→行为→接口→异常…），每个部分从分析自然过渡到设计，消除实体字段/接口/异常在 OOA 和 OOD 中的重复定义。合并前 21 个部分，合并后 13 个部分。 |
+
+---
+
+## 使用说明
+
+本模板将需求分析（OOA："做什么"）和系统设计（OOD："怎么做"）合并为**单阶段一体化流程**——按业务关注点组织，每个部分从"分析"出发、直接落地到"设计"，一次完成一个完整关注点。
+
+**使用方式**：
+
+1. 读取 PRD 文件（`docs/20-prd/`）
+2. 按本文结构，依次完成 §1~§13（全部必填，无对应需求时填写"无"并说明原因）
+3. 输出文件：`{模块编号}-{模块名}_system-design.md` + `{模块编号}-{模块名}_schema.sql`，保存到 `docs/30-system-design/{crm|mom}/`
+
+**设计原则**：
+- 每个部分从分析直接落地到设计，不再分两个阶段来回切换
+- 每个设计条目标注 `**来源需求**:` 引用 PRD ID，支撑全链路追溯
+- 避免重复：同一实体字段只在 §2 定义一次，§3 直接引用；同一接口只在 §5 定义一次
+
+---
+
+## 项目约定
+
+> 以下约定基于 `docs/40-project_conventions/end-integration/` 全部 11 份规范 + `gushen-demo/` 实际代码 + `CLAUDE.md`。
+> **本文所有设计内容均遵循本节约定。**
+
+### 架构概览
+
+本项目采用 **ECP 端集成平台** Spring Cloud 微服务架构，每个业务模块由 `{port}-{service}-api` + `{port}-{service}-model` + `{port}-{service}-application` 三个子模块组成：
+
+```
+{port}-{service}/                       # 如 2051-demo/
+├── {port}-{service}-api/               # Feign 接口 + DTO（契约层）
+│   └── src/main/java/com/sie/gushen/{service}/api/
+│       ├── client/                         # @FeignClient 接口
+│       └── dto/                            # DTO（继承 ReqeustCommonDataBean，注意平台拼写）
+├── {port}-{service}-model/             # Entity + DAO + Mapper XML + Ro（数据层）
+│   └── src/main/java/com/sie/gushen/{service}/model/
+│       ├── entity/                         # Entity（继承 BaseEntity<Entity>）
+│       │   └── readonly/                   # Ro 只读视图对象（implements Serializable）
+│       └── dao/                            # DAO 接口 + MyBatis XML Mapper（同包路径）
+└── {port}-{service}-application/       # Service + Controller + Config（实现层）
+    └── src/main/java/com/sie/gushen/{service}/
+        ├── {Service}Application.java       # 启动类（继承 CommonApplication）
+        ├── api/controller/                 # Controller（继承 CommonAbstractService）
+        ├── model/service/                  # Service 接口（II{Entity}, 双I前缀）
+        │   └── impl/                       # Service 实现（继承 BaseCommonServer）
+        ├── app/consume/                    # Kafka Consumer
+        └── infra/
+            ├── config/                     # DataSource/MybatisPlus/SpringDoc 配置
+            ├── constant/                   # 常量
+            ├── enumeration/                # 枚举
+            ├── interceptor/                # 拦截器
+            └── utils/                      # 工具类
+```
+
+### 工程结构与分层
+
+| 约定项   | 规则                                                                                             | 来源                |
+| -------- | ------------------------------------------------------------------------------------------------ | ------------------- |
+| 工程结构 | 三模块 Maven：`{port}-{service}-api` + `{port}-{service}-model` + `{port}-{service}-application` | 后端分层规范 §1     |
+| 包根路径 | `com.sie.{产品线}.{服务名}`                                                                      | 后端分层规范 §1     |
+| 父 POM   | `com.sie.irradiator:sie-irradiator:3.0.2`                                                        | gushen-demo/pom.xml |
+
+### 对象与命名
+
+| 约定项     | 规则                                                                                                                                                                                                                             | 来源            |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| **Entity** | 继承 `BaseEntity<T>`，实现 `Serializable`。`@TableName` 用反引号，每字段 `@TableField` + `@Schema`。主键 `Long`，策略 `IdType.ASSIGN_ID`。**BaseEntity 已含审计字段（creationDate/createdBy 等），Entity 中禁止重复声明**        | 后端分层规范 §2 |
+| **DTO**    | 继承 `ReqeustCommonDataBean`（注意平台拼写 Reqeust）。Date 字段 `@JSONField(format = "yyyy-MM-dd HH:mm:ss")`。校验分组定义为 DTO 内部接口 `save{Entity}` / `update{Entity}`。校验 message 格式 `{port}_{table_snake}_{三位序号}` | 后端分层规范 §3 |
+| **Ro**     | 简单 POJO，`implements Serializable` + `serialVersionUID`。手动声明所有字段（不继承 BaseEntity）。日期用 `@DateTimeFormat` + `@JsonFormat`。位于 `model/entity/readonly/`                                                        | 后端分层规范 §4 |
+
+### 数据访问
+
+| 约定项          | 规则                                                                                     | 来源               |
+| --------------- | ---------------------------------------------------------------------------------------- | ------------------ |
+| **DAO**         | 接口继承 `BaseCommonDAO_HI<Entity>`，注解 `@Component("{camel}DAO")`。XML 与接口同包同名 | 后端分层规范 §5    |
+| **MyBatis XML** | **所有数据库操作必须使用 MyBatis XML，禁止使用 QueryWrapper / LambdaQueryWrapper**       | 后端分层规范 §5    |
+| **软删除**      | 所有 SELECT 必须包含 `WHERE delete_flag = 0`。删除调用 `this.deleteById(id, true)`       | 后端分层规范 §5/§7 |
+| **resultMap**   | 必须显式映射所有字段（含审计字段）                                                       | 后端分层规范 §5    |
+| **名称字段**    | LIKE 查询（`CONCAT('%', #{params.xxx}, '%')`）                                           | 后端分层规范 §5    |
+| **编码字段**    | 精确匹配（`= #{params.xxx}`）                                                            | 后端分层规范 §5    |
+| **时间范围**    | 固定模板，直接复制                                                                       | 后端分层规范 §5    |
+
+### 业务逻辑
+
+| 约定项           | 规则                                                                                                                        | 来源            |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| **Service 接口** | 命名 `II{Entity}`（双 I 前缀），继承 `IBaseCommon<Entity>`                                                                  | 后端分层规范 §6 |
+| **Service 实现** | 注解 `@Component("{camel}Service")`，继承 `BaseCommonServer<Entity>`                                                        | 后端分层规范 §7 |
+| **Save 转换**    | **使用 FastJSON 转换**：`JSONObject.parseObject(JSONObject.toJSONString(dto), Entity.class)`                                | 后端分层规范 §7 |
+| **Update 合并**  | **使用 Spring BeanUtils**：`BeanUtils.copyProperties(dto, entity, "createdBy", "creationDate", "versionNum")`，排除审计字段 | 后端分层规范 §7 |
+| **分页排序**     | 默认 `creation_date DESC`（orderByBean 为 null 时自动设置）                                                                 | 后端分层规范 §7 |
+| **DTO→Map**      | `BeanUtil.beanToMap(paramBean, new LinkedHashMap<>(), false, false)`                                                        | 后端分层规范 §7 |
+| **注入方式**     | `@Autowired`（Spring），配合 `@Component("{camel}Name")` 显式命名                                                           | gushen-demo     |
+
+### 主子表级联
+
+| 约定项           | 规则                                                                                             | 来源            |
+| ---------------- | ------------------------------------------------------------------------------------------------ | --------------- |
+| **Save**         | 先保存主表拿到 ID，遍历子表设父 ID、清空子表主键、逐条 save                                      | 后端分层规范 §7 |
+| **Update**       | 子表采用"先删后增"：先 `deleteBy{父}Id(id)` 删旧数据，再 `saveListBy{父}Id(id, list)` 保存新数据 | 后端分层规范 §7 |
+| **Delete**       | 主表软删除 + 子表级联软删除（先查子表列表，再逐个 `deleteById(subId, true)`）                    | 后端分层规范 §7 |
+| **子表 Service** | 额外声明 `findListBy{父}Id` / `saveListBy{父}Id` / `updateListBy{父}Id` / `deleteBy{父}Id`       | 后端分层规范 §6 |
+
+### Controller
+
+| 约定项        | 规则                                                                                     | 来源            |
+| ------------- | ---------------------------------------------------------------------------------------- | --------------- |
+| **基类**      | 继承 `CommonAbstractService`，重写 `getBaseCommonServer()`                               | 后端分层规范 §8 |
+| **认证**      | 所有端点加 `@CheckToken`                                                                 | 后端分层规范 §8 |
+| **请求包装**  | 普通：`RequestData<Dto>`，分页：`PaginationRequestData<Dto>`                             | 后端分层规范 §8 |
+| **响应包装**  | `ResponseData.data(...)` / `ResponseData.fail(...)` / `ResponseData.success()`           | 后端分层规范 §8 |
+| **参数获取**  | Controller 取参用 `requestData.getParams()`（不是 `getData()`）                          | 后端分层规范 §8 |
+| **空参数**    | Controller 返回 `ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode)`              | 后端分层规范 §8 |
+| **标准端点**  | `/get-id`(GET), `/find-pagination`(POST), `/save`(POST), `/update`(POST), `/delete`(GET) | 后端分层规范 §8 |
+| **SpringDoc** | `@Tag(name = "{Entity}Controller控制器")` + `@Operation(summary = "xxx")`                | gushen-demo     |
+
+### 异常处理
+
+| 约定项         | 规则                                                                                                   | 来源                    |
+| -------------- | ------------------------------------------------------------------------------------------------------ | ----------------------- |
+| **异常位置**   | **Service 层抛出**，Controller 仅做参数空校验                                                          | 多语言与异常处理规范 §1 |
+| **异常类**     | 使用 `GushenRuntimeException`、`RecordNotExistsException`、`ParameterNotValidException` 等平台异常类   | 多语言与异常处理规范 §1 |
+| **消息码**     | 使用 `ResponseMsgCode` 枚举的 `.msgCode`，格式 `{port}_{table_snake}_{三位序号}`，**禁止硬编码字符串** | 多语言与异常处理规范 §1 |
+| **服务层函数** | `RecordNotExistsException`：`throw new RecordNotExistsException(msgCode, List.of(id))`                 | 多语言与异常处理规范    |
+
+### 国际化 i18n
+
+| 约定项       | 规则                                                                                                                     | 来源                    |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
+| **文件数量** | 每个模块 **7 个** `.properties` 文件                                                                                     | 多语言与异常处理规范 §2 |
+| **文件命名** | `{port}-{module}-application.properties` (默认Unicode) + `_zh_CN` / `_zh_TW` / `_en_US` / `_vi_VN` / `_th_TH` / `_hu_HU` | 多语言与异常处理规范 §2 |
+| **内容要求** | 每个语言文件必须包含**该语言的实际翻译内容**，禁止不同语言文件混放同一语言内容                                           | 多语言与异常处理规范 §2 |
+
+### 其他平台基础设施
+
+| 约定项        | 规则                                                                                         | 来源             |
+| ------------- | -------------------------------------------------------------------------------------------- | ---------------- |
+| **Redis**     | 使用 `DawnRedis`，键格式 `{module}:{business}:{identifier}`，通过 `ICacheKey` 枚举统一管理   | Redis使用规范    |
+| **EasyTrans** | 数据翻译使用 easy-trans（VO 自动将 ID 翻译为名称）                                           | 通用工具类规范   |
+| **分布式锁**  | 使用 `@Klock` 注解，`keys` 必须包含业务标识（SpEL 表达式），禁止空 keys                      | 分布式锁规范     |
+| **ES**        | 使用 `Es.chainLambdaQuery(Entity.class)`，深度分页(>5000)用 `EsPaginationUtil`               | ES使用规范       |
+| **文件中心**  | 使用 `IotBaseAttachmentClient`，业务类型命名 `{module}_{entity}_{type}`                      | 文件中心规范     |
+| **BPM 流程**  | 使用 `BpmHelper.startProcess(procDefKey, businessKey)`，回调通过 `BpmFlowConsumer` 消费      | 流程中心规范     |
+| **编码生成**  | 统一使用 `AutoCodeRuleService.generate(prefix, length)`，禁止自编编码                        | 编码自动生成规范 |
+| **IdToName**  | `@IdToName(alias="nameField", type=IdToNameType.USER)` + `@EnableIdToName`，仅注解 Long 字段 | IdToName使用规范 |
+| **Liquibase** | 所有数据库变更通过 Liquibase 管理（DDL/DML 幂等），禁止直接执行 SQL                          | Liquibase规范    |
+| **工具类**    | Hutool 优先（StrUtil/CollUtil/BeanUtil/ObjectUtil），JSON 用 FastJSON，日志用 SLF4J          | 通用工具类规范   |
+| **加密**      | `EncryUtil.encrypt(plainText)` / `decrypt(cipherText)`，自动兼容 RSA 和 DES                  | 通用工具类规范   |
+| **配置**      | `ServerConfigConmonUtil.get(key, tenantId, redisTemplate, defaultValue)`                     | 通用工具类规范   |
+
+---
+
+## 部分清单
+
+| 部分 | 标题                     | 必填/选填 | 关注点                                                                                                            |
+| ---- | ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| §1   | 需求 ID 映射与模块上下文 | **必填**  | 分析：从 PRD 提取 ID 映射，明确模块边界                                                                           |
+| §2   | 业务实体与领域对象       | **必填**  | 分析→设计：实体清单 → Entity/DTO/Ro 字段表                                                                        |
+| §3   | 数据模型                 | **必填**  | 设计：UML 类图 → DDL 字段表 → MyBatis XML 结构                                                                    |
+| §4   | 业务行为与 Service 设计  | **必填**  | 分析→设计：行为清单 → Service 接口/实现 + 事务标注                                                                |
+| §5   | 接口与 Controller 设计   | **必填**  | 设计：端点清单 → Controller 完整代码骨架 → 权限矩阵 + 响应示例                                                    |
+| §6   | 枚举与数据字典           | **必填**  | 分析→设计：枚举值定义 → Java 枚举类 → 数据校验规则                                                                |
+| §7   | 异常处理                 | **必填**  | 分析→设计：异常清单 → 消息码 → 抛出方式 → 流程图                                                                  |
+| §8   | 缓存与性能               | **必填**  | 设计：DawnRedis 键管理 + 索引优化 + 并发控制。如无缓存需求，填写"无"。                                            |
+| §9   | 领域事件                 | **必填**  | 分析→设计：发布事件 + 消费事件 + Payload 结构 + 事件流程图。如无事件，填写"无"。                                  |
+| §10  | 跨模块依赖               | **必填**  | 分析→设计：被依赖清单（本模块对外提供）+ 依赖清单（本模块调用外部）+ 依赖关系图。如无依赖，填写"无"。             |
+| §11  | 非功能性需求             | **必填**  | 分析：性能/安全/兼容性/数据一致性/审计日志/可扩展性等非功能维度。如无特殊要求，至少保留数据一致性和审计日志两项。 |
+| §12  | 测试场景                 | **必填**  | 分析：正常/异常/边界场景。如无复杂场景，至少列出基础 CRUD 的 2 条场景。                                           |
+| §13  | 总结                     | **必填**  | 总结：成果汇总 + 后续工作 + 注意事项                                                                              |
+
+---
+
+## §1 需求 ID 映射与模块上下文（必填）
+
+> **关注点**：分析。从 PRD 提取 ID 映射关系，建立全链路追溯起点。明确模块的上下文边界和核心职责。
+
+```markdown
+## 1. 需求 ID 映射与模块上下文
+
+### 1.1 需求 ID 映射
+
+> 本表记录了 PRD 中每个可测试条目与需求 ID 的对应关系。
+> ID 由 AI 在生成设计文档时自动赋予，PRD 本身不包含 ID。
+
+#### 1.1.1 用户故事映射
+
+| 需求 ID | PRD 位置 | 故事简述   |
+| ------- | -------- | ---------- |
+| US-01   | §2.1.1   | {故事标题} |
+| US-02   | §2.1.2   | {故事标题} |
+
+#### 1.1.2 验收场景映射
+
+| 需求 ID   | PRD 位置         | 故事 ID | 场景简述   |
+| --------- | ---------------- | ------- | ---------- |
+| US-01-AC1 | §2.1.1 验收场景1 | US-01   | {场景描述} |
+| US-01-AC2 | §2.1.1 验收场景2 | US-01   | {场景描述} |
+
+#### 1.1.3 业务规则映射
+
+| 需求 ID | PRD 位置 | 规则简述   |
+| ------- | -------- | ---------- |
+| BR-01   | §3.2.1   | {规则标题} |
+| BR-02   | §3.2.2   | {规则标题} |
+
+#### 1.1.4 功能条目映射
+
+| 需求 ID | PRD 位置（功能编号）                           | 功能简述   |
+| ------- | ---------------------------------------------- | ---------- |
+| FUNC-01 | §4.3.x P{模块}-{子模块}-{序号}（如 P05-01-01） | {功能简述} |
+| FUNC-02 | §4.3.x P{模块}-{子模块}-{序号}（如 P05-01-02） | {功能简述} |
+
+#### 1.1.5 权限映射
+
+| 需求 ID | PRD 位置 | 权限标识    | 角色   |
+| ------- | -------- | ----------- | ------ |
+| PERM-01 | §5.1     | @CheckToken | {角色} |
+| PERM-02 | §5.1     | @CheckToken | {角色} |
+
+### 1.2 模块定位
+- **模块名称**: [模块名称，如 2051-demo]
+- **模块描述**: [模块承载什么业务职责]
+- **所属分层**: [业务核心层 / 平台支撑层 / 智能中枢层]
+- **模块结构**: -api（Feign接口+DTO） + -model（Entity+DAO+XML+Ro） + -application（Service+Controller+Config）
+
+### 1.3 上下文边界
+- **上游依赖**: [本模块依赖哪些外部模块/系统]
+- **下游调用**: [哪些模块会调用本模块的能力]
+- **外部集成**: [是否对接外部系统，如 SAP、第三方 API 等]
+
+### 1.4 核心职责
+- [职责1]: [简要说明]
+- [职责2]: [简要说明]
+- [职责3]: [简要说明]
+```
+
+---
+
+## §2 领域对象（必填）
+
+> **关注点**：分析 → 设计。先从 PRD 中提取业务实体及其属性（分析），然后直接落地为 Entity / DTO / Ro 三类领域对象的完整字段表（设计）。**同一字段不再在 §3 重复定义。**
+
+```markdown
+## 2. 业务实体与领域对象
+
+### 2.1 对象类型说明
+
+| 对象       | 父类/接口                                            | 所在模块                | 用途                                                                            |
+| ---------- | ---------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
+| **Entity** | `extends BaseEntity<Entity> implements Serializable` | -model                  | 与数据库表一一映射。**审计字段继承自 BaseEntity，禁止重复声明**                 |
+| **DTO**    | `extends ReqeustCommonDataBean`                      | -api                    | 接口入参传输，包含 Bean Validation 校验分组                                     |
+| **Ro**     | `implements Serializable`                            | -model/entity/readonly/ | 只读视图对象，组合多表查询结果返回前端。**手动声明所有字段，不继承 BaseEntity** |
+
+### 2.2 实体清单
+
+#### 2.2.1 实体1: {Entity}Entity
+
+- **来源需求**: [引用 PRD ID，如 US-01, FUNC-01]
+- **实体描述**: [这个实体是什么，用来做什么]
+- **表名**: \`{table_name}\`（反引号包裹）
+- **所属域**: [所属业务域]
+
+**完整字段**：
+
+| 字段名      | Java类型                  | DB类型   | 长度   | 必填  | 默认值   | 注解                              | 说明           |
+| ----------- | ------------------------- | -------- | ------ | ----- | -------- | --------------------------------- | -------------- |
+| {pkField}   | Long                      | BIGINT   | 20     | Y     |          | @TableId(type=ASSIGN_ID), @Schema | 主键（雪花ID） |
+| [业务字段1] | [String/Long/Integer/...] | [DB类型] | [长度] | [Y/N] | [默认值] | @TableField("{col}"), @Schema     | [说明]         |
+| [业务字段2] | [类型]                    | [DB类型] | [长度] | [Y/N] | [默认值] | @TableField("{col}"), @Schema     | [说明]         |
+
+> **审计字段**（tenant_id, creation_date, created_by, last_update_date, last_updated_by, last_update_login, delete_flag, version_num）继承自 BaseEntity，由 ModelMetaObjectHandler 自动填充。**Entity 中禁止重复声明，但在 DDL（§3）和 Ro 中需按需列出。**
+
+- **主键**: {pkField} (Long, ASSIGN_ID 雪花算法)
+- **索引**: uk_xxx (UNIQUE) / idx_xxx (NORMAL) — [说明]
+- **关联关系**: [{Entity} 1:N {SubEntity}（主从表）] 或 [无]
+
+#### 2.2.2 实体2: {SubEntity}Entity（子表，如有）
+
+- **来源需求**: [引用 PRD ID]
+- **实体描述**: [描述]
+- **表名**: \`{sub_table_name}\`
+- **完整字段**: [同上格式，含关联主表的外键字段]
+- **主键**: {subPkField} (Long, ASSIGN_ID)
+- **索引**: idx_{fk_col} (NORMAL) — 按主表ID查询子表
+- **关联关系**: {SubEntity} N:1 {Entity}
+
+### 2.3 DTO 清单
+
+> DTO 继承 `ReqeustCommonDataBean`（注意平台拼写），位于 `-api` 模块。
+
+#### 2.3.1 DTO1: {Entity}Dto
+
+- **来源需求**: [引用 PRD ID]
+- **使用场景**: [如：新增/更新/分页查询的入参]
+
+| 字段名          | Java类型         | 必填            | 校验规则                                                                                   | 说明                       |
+| --------------- | ---------------- | --------------- | ------------------------------------------------------------------------------------------ | -------------------------- |
+| {pkField}       | Long             | 更新时必填      | @NotNull(message="{port}_{table}_001", groups={update{Entity}.class})                      | 主键（仅更新组）           |
+| [业务字段1]     | [类型]           | 新增/更新时必填 | @NotEmpty(message="{port}_{table}_002", groups={save{Entity}.class, update{Entity}.class}) | [说明]                     |
+| [业务字段2]     | [类型]           | 否              | 无校验                                                                                     | [说明]                     |
+| creationDates   | List\<Date\>     | 否              | @JSONField(format="yyyy-MM-dd HH:mm:ss")                                                   | 创建时间范围（分页查询用） |
+| lastUpdateDates | List\<Date\>     | 否              | @JSONField(format="yyyy-MM-dd HH:mm:ss")                                                   | 更新时间范围（分页查询用） |
+| [{sub}List]     | List\<{Sub}Dto\> | 否              | @Valid                                                                                     | 级联子表数据               |
+
+> 日期字段标注 `@JSONField(format = "yyyy-MM-dd HH:mm:ss")`；校验 message 格式 `{port}_{table_snake}_{三位序号}`。
+
+- **验证分组**（DTO 内部接口）:
+  - `save{Entity}` 接口：新增时的校验组（主键不参与校验）
+  - `update{Entity}` 接口：更新时的校验组（主键仅属于此组）
+- **来源实体**: {Entity}Entity [ + {SubEntity}Entity]
+
+### 2.4 Ro 清单
+
+> Ro 实现 `Serializable` + `serialVersionUID`，手动声明所有字段（不继承 BaseEntity），位于 `model/entity/readonly/`。
+
+#### 2.4.1 Ro1: {Entity}EntityRo
+
+- **来源需求**: [引用 PRD ID]
+- **使用场景**: [如：get-id 详情查询返回]
+
+| 字段名         | Java类型            | 注解                                                                                                        | 说明         |
+| -------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- | ------------ |
+| {pkField}      | Long                | @Schema(description = "主键")                                                                               | 主键         |
+| [业务字段1]    | [类型]              | @Schema                                                                                                     | [说明]       |
+| creationDate   | Date                | @DateTimeFormat(pattern="yyyy-MM-dd HH:mm:ss") @JsonFormat(pattern="yyyy-MM-dd HH:mm:ss", timezone="GMT+8") | 创建日期     |
+| createdBy      | Long                | @Schema                                                                                                     | 创建人       |
+| lastUpdateDate | Date                | @DateTimeFormat @JsonFormat                                                                                 | 最后更新日期 |
+| deleteFlag     | Integer             | @Schema                                                                                                     | 删除标识     |
+| versionNum     | Integer             | @Schema                                                                                                     | 版本号       |
+| [{sub}List]    | List\<{Sub}Entity\> | @Schema                                                                                                     | 关联子表列表 |
+
+> 日期字段标注 `@DateTimeFormat` + `@JsonFormat`；Ro 需手动列出需要返回的审计字段。
+```
+
+---
+
+## §3 数据模型（必填）
+
+> **关注点**：设计。基于 §2 的实体定义，绘制 UML 类图，设计完整的 DDL 和 MyBatis XML 结构。
+
+```markdown
+## 3. 数据模型
+
+### 3.1 UML 类图
+
+```mermaid
+classDiagram
+    class {Entity}Entity {
+        +Long {pkField}
+        +[类型] [业务字段1]
+        +[类型] [业务字段2]
+        #Long tenantId
+        #Date creationDate
+        #Long createdBy
+        #Date lastUpdateDate
+        #Long lastUpdatedBy
+        #Integer deleteFlag
+        #Integer versionNum
+    }
+    class {SubEntity}Entity {
+        +Long {subPkField}
+        +Long {fkField}
+        +[类型] [子表字段]
+    }
+
+    {Entity}Entity "1" --> "N" {SubEntity}Entity : 包含
+```
+
+### 3.2 数据库表设计
+
+> 主键使用雪花 ID（Long, IdType.ASSIGN_ID），不使用自增。不使用数据库外键，关联关系在代码层面维护。字段定义见 §2.2，本节仅列出 DDL 格式。
+
+**表1**: \`{table_name}\`
+- **表描述**: [表用途说明]
+
+| 字段名            | 类型     | 长度   | 是否必填 | 默认值   | 说明                           |
+| ----------------- | -------- | ------ | -------- | -------- | ------------------------------ |
+| {pk_col}          | BIGINT   | 20     | Y        |          | 主键（雪花ID, ASSIGN_ID）      |
+| [字段1]           | [类型]   | [长度] | [Y/N]    | [默认值] | [说明]                         |
+| tenant_id         | BIGINT   | 20     | Y        |          | 租户ID（审计字段）             |
+| creation_date     | DATETIME |        | Y        |          | 创建日期                       |
+| created_by        | BIGINT   | 20     | Y        |          | 创建人                         |
+| last_update_date  | DATETIME |        | Y        |          | 最后更新日期                   |
+| last_updated_by   | BIGINT   | 20     | Y        |          | 最后更新人                     |
+| last_update_login | BIGINT   | 20     | N        |          | 最后登录ID                     |
+| delete_flag       | INT      | 11     | Y        | 0        | 删除标识（0=未删除，1=已删除） |
+| version_num       | INT      | 11     | Y        | 0        | 版本号（乐观锁）               |
+
+- **主键**: {pk_col} (BIGINT, ASSIGN_ID)
+- **索引**:
+  | 索引名  | 索引类型        | 字段   | 说明   |
+  | ------- | --------------- | ------ | ------ |
+  | [索引1] | [UNIQUE/NORMAL] | [字段] | [说明] |
+
+**表2**: \`{sub_table_name}\`（子表，如有）
+- **表描述**: [用途说明]
+- **字段列表**: [同上格式]，额外包含 `{fk_col} BIGINT 20 Y — 关联主表主键`
+- **主键**: {sub_pk_col} (BIGINT, ASSIGN_ID)
+- **索引**: idx_{fk_col} NORMAL ({fk_col}) — 按主表ID查询子表
+
+### 3.3 MyBatis 映射
+
+> **所有 SQL 通过 MyBatis XML 实现，禁止 QueryWrapper / LambdaQueryWrapper。**
+> XML 文件与 DAO 接口同包路径：`src/main/resources/com/sie/gushen/{service}/model/dao/{Entity}DAO.xml`
+
+#### 3.3.1 DAO 接口
+
+- **类路径**: `com.sie.gushen.{service}.model.dao.{Entity}DAO`
+- **继承**: `BaseCommonDAO_HI<{Entity}Entity>`
+- **注解**: `@Component("{camel}DAO")`
+- **自定义方法**:
+  - `Page<{Entity}Entity> findPagination(@Param("page") Page<{Entity}Entity> page, @Param("params") Map<String, Object> params)` — 分页查询
+  - `List<{SubEntity}Entity> findListBy{父}Id(@Param("{父}Id") Long {父}Id)` — 按主表ID查子表（有子表时）
+
+#### 3.3.2 Mapper XML 结构
+
+```xml
+<mapper namespace="com.sie.gushen.{service}.model.dao.{Entity}DAO">
+
+    <resultMap id="BaseResultMap" type="com.sie.gushen.{service}.model.entity.{Entity}Entity">
+        <id column="{pk_col}" property="{pkField}"/>
+        <!-- 所有业务字段映射 -->
+        <!-- 所有审计字段映射（完整列出，禁止省略） -->
+    </resultMap>
+
+    <sql id="Base_Column_List">
+        {pk_col}, {col1}, {col2}, ..., tenant_id, creation_date, created_by,
+        last_update_date, last_updated_by, last_update_login, delete_flag, version_num
+    </sql>
+
+    <sql id="BASE_QUERY_CONDITION">
+        <!-- 动态条件：编码精确匹配、名称 LIKE、日期范围、状态等 -->
+        <if test="params.{col} != null and params.{col} != ''">
+            AND {col} = #{params.{col}}
+        </if>
+    </sql>
+
+    <select id="findPagination" resultMap="BaseResultMap">
+        SELECT <include refid="Base_Column_List"/>
+        FROM `{table_name}`
+        WHERE delete_flag = 0
+        <include refid="BASE_QUERY_CONDITION"/>
+    </select>
+
+    <!-- 如有子表：按主表ID查询 -->
+    <select id="findListBy{父}Id" resultMap="BaseResultMap">
+        SELECT <include refid="Base_Column_List"/>
+        FROM `{sub_table_name}`
+        WHERE delete_flag = 0 AND {父}_id = #{{父}Id}
+    </select>
+
+</mapper>
+```
+
+**关键约定**:
+- 所有 SELECT 必须 `WHERE delete_flag = 0`
+- 日期范围使用 `params.creationDates[0]` 配合 `jdbcType=TIMESTAMP`
+- 模糊查询使用 `<bind>` 标签（`<bind name="name" value="'%' + params.name + '%'"/>`）
+- 表名使用反引号
+```
+
+---
+
+## §4 业务行为与 Service 设计（必填）
+
+> **关注点**：分析 → 设计。从 PRD 业务场景中提取核心行为（分析），然后直接设计 Service 接口方法签名、实现逻辑和事务边界（设计）。
+
+```markdown
+## 4. 业务行为与 Service 设计
+
+### 4.1 业务行为清单
+
+#### 4.1.1 行为1: [行为名称，如"新增{实体}"]
+
+- **来源需求**: [引用 PRD ID，如 BR-01, BR-02, FUNC-01]
+- **行为描述**: [这个行为做什么，达到什么目的]
+- **触发方**: [谁/什么触发这个行为]
+- **业务规则**:
+  - [规则1]: [规则描述]
+  - [规则2]: [规则描述]
+- **前置条件**: [执行前需满足的条件]
+- **后置条件**: [执行后应达到的状态]
+- **涉及实体**: [涉及哪些实体]
+
+#### 4.1.2 行为2: [行为名称]
+
+[同上格式]
+
+### 4.2 业务流程图
+
+```mermaid
+flowchart TD
+    A[开始] --> B[步骤1]
+    B --> C{判断条件}
+    C -->|条件1| D[步骤2]
+    C -->|条件2| E[步骤3]
+    D --> F[步骤4]
+    E --> F
+    F --> G[结束]
+```
+
+### 4.3 状态机图（如有状态流转）
+
+```mermaid
+stateDiagram-v2
+    [*] --> [状态1]
+    [状态1] --> [状态2]: [触发条件]
+    [状态2] --> [状态3]: [触发条件]
+    [状态3] --> [*]
+```
+
+### 4.4 Service 接口设计
+
+#### 4.4.1 II{Entity}（主表 Service 接口）
+
+- **类路径**: `com.sie.gushen.{service}.model.service.II{Entity}`
+- **继承**: `IBaseCommon<{Entity}Entity>`
+
+| 方法签名                                                                                        | 入参           | 出参                         | 事务           | 说明                                               |
+| ----------------------------------------------------------------------------------------------- | -------------- | ---------------------------- | -------------- | -------------------------------------------------- |
+| `findById(Serializable id)`                                                                     | Long id        | {Entity}Entity               | 无             | 覆写，调用 this.getById(id)                        |
+| `findPagination({Entity}Dto dto, Integer pageIndex, Integer pageRows, OrderByBean orderByBean)` | DTO + 分页参数 | Pagination\<{Entity}Entity\> | 无             | 默认排序 creation_date DESC                        |
+| `save{Entity}({Entity}Dto dto)`                                                                 | DTO            | {Entity}Entity               | @Transactional | FastJSON 转换 + 主子表级联保存                     |
+| `update{Entity}({Entity}Dto dto)`                                                               | DTO            | {Entity}Entity               | @Transactional | Spring BeanUtils 合并(排除审计字段) + 子表先删后增 |
+| `delete{Entity}(Long id)`                                                                       | Long id        | void                         | @Transactional | 主表软删除 + 子表级联软删除                        |
+
+#### 4.4.2 II{SubEntity}（子表 Service 接口，如有）
+
+| 方法签名                                                | 说明                                                |
+| ------------------------------------------------------- | --------------------------------------------------- |
+| `findListBy{父}Id(Long {父}Id)`                         | 按主表ID查询子表列表                                |
+| `saveListBy{父}Id(Long {父}Id, List<{Sub}Entity> list)` | 批量保存（遍历设父ID + 清空主键）                   |
+| `deleteBy{父}Id(Long {父}Id)`                           | 级联软删除（查列表 → 逐个 deleteById(subId, true)） |
+
+### 4.5 Service 实现逻辑
+
+#### 4.5.1 {Entity}Service
+
+- **类路径**: `com.sie.gushen.{service}.model.service.impl.{Entity}Service`
+- **继承**: `BaseCommonServer<{Entity}Entity>`
+- **注解**: `@Component("{camel}Service")`
+- **注入**: `@Autowired private {Entity}DAO {camel}DAO;` [+ `@Autowired private II{SubEntity} {sub}Service;`]
+
+**关键方法逻辑**:
+
+```
+save{Entity}(dto):
+  1. FastJSON: JSONObject.parseObject(JSONObject.toJSONString(dto), {Entity}Entity.class)
+  2. this.save(entity)                                  // 保存主表
+  3. Long id = entity.get{Entity}Id()
+  4. if 子表列表非空:
+      遍历设 {父}Id = id, 清空子表主键 = null
+      {sub}Service.saveListBy{父}Id(id, list)           // 批量保存子表
+  5. return entity
+  事务: @Transactional(rollbackFor = Exception.class)
+
+update{Entity}(dto):
+  1. entity = this.getById(dto.get{Entity}Id())
+  2. if entity == null: throw RecordNotExistsException(UPDATE_DATA_NOT_EXIST)
+  3. Spring BeanUtils: BeanUtils.copyProperties(dto, entity,
+       "createdBy", "creationDate", "versionNum")        // 排除审计字段
+  4. this.update(entity)                                 // 更新主表
+  5. {sub}Service.deleteBy{父}Id(id)                     // 软删除旧子表
+  6. if 子表列表非空:
+      {sub}Service.saveListBy{父}Id(id, list)            // 保存新子表
+  7. return entity
+  事务: @Transactional(rollbackFor = Exception.class)
+
+delete{Entity}(id):
+  1. this.deleteById(id, true)                           // 主表软删除
+  2. {sub}Service.deleteBy{父}Id(id)                     // 子表级联软删除
+  事务: @Transactional(rollbackFor = Exception.class)
+
+findPagination(dto, pageIndex, pageRows, orderByBean):
+  1. if orderByBean == null: 设置默认排序 creation_date DESC
+  2. BeanUtil.beanToMap(dto, new LinkedHashMap<>(), false, false) → params
+  3. Condition.getPage(pageIndex, pageRows, orderByBean) → page
+  4. {camel}DAO.findPagination(page, params)             // MyBatis XML 查询
+  5. PaginationUtil.toPagination(page) → return
+  事务: 无（只读查询）
+```
+
+### 4.6 事务边界汇总
+
+| 方法                      | @Transactional                | 原因                               |
+| ------------------------- | ----------------------------- | ---------------------------------- |
+| save{Entity}              | rollbackFor = Exception.class | 主表 INSERT + 子表批量 INSERT      |
+| update{Entity}            | rollbackFor = Exception.class | 主表 UPDATE + 子表 DELETE + INSERT |
+| delete{Entity}            | rollbackFor = Exception.class | 主表软删除 + 子表级联软删除        |
+| saveListBy{父}Id          | rollbackFor = Exception.class | 子表批量保存                       |
+| findById / findPagination | **无**                        | 只读查询                           |
+```
+
+---
+
+## §5 接口与 Controller 设计（必填）
+
+> **关注点**：设计。基于 §4 的业务行为，设计 REST 端点和 Controller 代码骨架。
+
+```markdown
+## 5. 接口与 Controller 设计
+
+### 5.1 端点清单
+
+| #   | HTTP | 路径                        | 说明                 | 请求包装                             | 响应包装                   | 校验分组       |
+| --- | ---- | --------------------------- | -------------------- | ------------------------------------ | -------------------------- | -------------- |
+| 1   | GET  | `/{entity}/get-id`          | 按ID查询详情(含子表) | @RequestParam Long id                | ResponseData\<{Entity}Ro\> | —              |
+| 2   | POST | `/{entity}/find-pagination` | 分页查询             | PaginationRequestData\<{Entity}Dto\> | ResponseData\<Pagination\> | —              |
+| 3   | POST | `/{entity}/save`            | 新增                 | RequestData\<{Entity}Dto\>           | ResponseData\<{Entity}\>   | save{Entity}   |
+| 4   | POST | `/{entity}/update`          | 更新                 | RequestData\<{Entity}Dto\>           | ResponseData\<{Entity}\>   | update{Entity} |
+| 5   | GET  | `/{entity}/delete`          | 软删除               | @RequestParam Long id                | ResponseData.success()     | —              |
+
+> [如有自定义端点，在此追加]
+
+### 5.2 Controller 代码骨架
+
+```java
+@Tag(name = "{Entity}Controller控制器", description = "{Entity}Controller控制器")
+@RestController
+@RequestMapping("/{entity}")
+public class {Entity}Controller extends CommonAbstractService {
+    private static final Logger LOGGER = LoggerFactory.getLogger({Entity}Controller.class);
+
+    @Autowired
+    private II{Entity} {camel}Service;
+
+    @Override
+    public IBaseCommon getBaseCommonServer() {
+        return this.{camel}Service;
+    }
+
+    @Operation(summary = "根据Id查询数据")
+    @GetMapping(value = "/get-id")
+    @CheckToken
+    public ResponseData<{Entity}EntityRo> findById(@RequestParam Long id) {
+        return ResponseData.data({camel}Service.findById(id));
+    }
+
+    @Operation(summary = "分页查询")
+    @PostMapping(value = "/find-pagination")
+    @CheckToken
+    public ResponseData<Pagination<{Entity}Entity>> findByPage(
+            @RequestBody PaginationRequestData<{Entity}Dto> paginationRequestData) {
+        Integer pageIndex = paginationRequestData.getPageIndex();
+        Integer pageRows = paginationRequestData.getPageRows();
+        {Entity}Dto dto = paginationRequestData == null ? null : paginationRequestData.getParams();
+        Pagination<{Entity}Entity> pagination = {camel}Service.findPagination(
+            dto, pageIndex, pageRows,
+            paginationRequestData != null ? paginationRequestData.getOrderByBean() : null);
+        return ResponseData.data(pagination);
+    }
+
+    @Operation(summary = "保存接口")
+    @PostMapping(value = "/save")
+    @CheckToken
+    public ResponseData<{Entity}Entity> save(
+            @Validated({Entity}Dto.save{Entity}.class)
+            @RequestBody RequestData<{Entity}Dto> requestData) {
+        {Entity}Dto dto = requestData == null ? null : requestData.getParams();
+        if (dto == null) {
+            return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode);
+        }
+        return ResponseData.data({camel}Service.save{Entity}(dto));
+    }
+
+    @Operation(summary = "根据ID更新数据")
+    @PostMapping(value = "/update")
+    @CheckToken
+    public ResponseData<{Entity}Entity> update(
+            @Validated({Entity}Dto.update{Entity}.class)
+            @RequestBody RequestData<{Entity}Dto> requestData) {
+        {Entity}Dto dto = requestData == null ? null : requestData.getParams();
+        if (dto == null) {
+            return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode);
+        }
+        return ResponseData.data({camel}Service.update{Entity}(dto));
+    }
+
+    @Operation(summary = "根据id删除")
+    @GetMapping(value = "/delete")
+    @CheckToken
+    public ResponseData deleteById(@RequestParam Long id) {
+        {camel}Service.delete{Entity}(id);
+        return ResponseData.success();
+    }
+}
+```
+
+### 5.3 响应示例
+
+> 以下为每个接口的典型成功响应和错误响应示例，使用 JSON 格式。
+
+#### 5.3.1 按ID查询 — GET `/{entity}/get-id`
+
+**成功响应**（HTTP 200）：
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": {
+    "{pkField}": 1234567890,
+    "{字段1}": "{示例值}",
+    "creationDate": "2026-06-13 10:00:00",
+    "createdBy": 1001,
+    "deleteFlag": 0,
+    "versionNum": 1
+  }
+}
+```
+
+**错误响应**（HTTP 200，业务错误码）：
+
+```json
+{
+  "code": "{port}_{table}_005",
+  "msg": "{实体}数据不存在",
+  "data": null
+}
+```
+
+#### 5.3.2 分页查询 — POST `/{entity}/find-pagination`
+
+**成功响应**（HTTP 200）：
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": {
+    "total": 50,
+    "records": [
+      {
+        "{pkField}": 1234567890,
+        "{字段1}": "{示例值}",
+        "creationDate": "2026-06-13 10:00:00"
+      }
+    ],
+    "pageIndex": 1,
+    "pageRows": 20
+  }
+}
+```
+
+**错误响应**（HTTP 200，空参数）：
+
+```json
+{
+  "code": "{port}_common_001",
+  "msg": "参数不能为空",
+  "data": null
+}
+```
+
+#### 5.3.3 新增 — POST `/{entity}/save`
+
+**成功响应**（HTTP 200）：
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": {
+    "{pkField}": 1234567890,
+    "{字段1}": "{示例值}",
+    "creationDate": "2026-06-13 10:00:00",
+    "createdBy": 1001,
+    "deleteFlag": 0,
+    "versionNum": 0
+  }
+}
+```
+
+**错误响应 — 参数为空**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_common_001",
+  "msg": "参数不能为空",
+  "data": null
+}
+```
+
+**错误响应 — 字段校验失败**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_{table}_002",
+  "msg": "{字段1}不能为空",
+  "data": null
+}
+```
+
+**错误响应 — 业务规则校验失败**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_{table}_006",
+  "msg": "{业务规则描述，如同系统下角色编码已存在}",
+  "data": null
+}
+```
+
+#### 5.3.4 更新 — POST `/{entity}/update`
+
+**成功响应**（HTTP 200）：
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": {
+    "{pkField}": 1234567890,
+    "{字段1}": "{更新后的值}",
+    "lastUpdateDate": "2026-06-13 11:00:00",
+    "lastUpdatedBy": 1001,
+    "versionNum": 2
+  }
+}
+```
+
+**错误响应 — 数据不存在**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_{table}_005",
+  "msg": "待更新数据不存在",
+  "data": null
+}
+```
+
+**错误响应 — 参数为空**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_common_001",
+  "msg": "参数不能为空",
+  "data": null
+}
+```
+
+**错误响应 — 乐观锁冲突**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_{table}_007",
+  "msg": "数据已被他人修改，请刷新后重试",
+  "data": null
+}
+```
+
+#### 5.3.5 删除 — GET `/{entity}/delete`
+
+**成功响应**（HTTP 200）：
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": null
+}
+```
+
+**错误响应 — 数据不存在**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_{table}_005",
+  "msg": "{实体}数据不存在",
+  "data": null
+}
+```
+
+**错误响应 — 存在关联数据无法删除**（HTTP 200）：
+
+```json
+{
+  "code": "{port}_{table}_008",
+  "msg": "存在关联{子实体}数据，请先删除关联数据",
+  "data": null
+}
+```
+
+> **说明**：
+> - ECP 平台所有响应 HTTP 状态码统一为 200，业务错误通过 `code` 字段区分（`200` 表示成功，其他为错误码）
+> - `code` 值为 `ResponseMsgCode` 枚举中的 `.msgCode`，格式 `{port}_{table_snake}_{三位序号}`
+> - `{port}_common_001` 为平台通用"参数不能为空"消息码（即 `ResponseMsgCode.NOT_NULL_PARAM.msgCode`）
+> - 成功响应 `data` 字段为接口定义的出参类型；错误响应 `data` 统一为 `null`
+> - 分页成功响应 `data` 包含 `total`、`records`、`pageIndex`、`pageRows` 四个标准字段
+> - 删除成功响应 `data` 为 `null`（`ResponseData.success()` 不携带数据体）
+
+### 5.4 权限矩阵
+
+| 接口     | 方式 | 路径                        | 权限要求    | Sentinel |
+| -------- | ---- | --------------------------- | ----------- | -------- |
+| 按ID查询 | GET  | `/{entity}/get-id`          | @CheckToken | 可选     |
+| 分页查询 | POST | `/{entity}/find-pagination` | @CheckToken | —        |
+| 新增     | POST | `/{entity}/save`            | @CheckToken | 可选     |
+| 更新     | POST | `/{entity}/update`          | @CheckToken | —        |
+| 删除     | GET  | `/{entity}/delete`          | @CheckToken | —        |
+```
+
+---
+
+## §6 枚举与数据字典（必填）
+
+> **关注点**：分析 → 设计。从 PRD 状态定义和字段校验规则中提取枚举值，直接给出 Java 枚举类定义。
+
+```markdown
+## 6. 枚举与数据字典
+
+### 6.1 枚举值定义
+
+> ECP 平台中枚举定义为普通 Java 枚举类或常量类，存放在 `infra/enumeration/` 或 `infra/constant/` 目录下。
+
+#### 6.1.1 枚举1: [枚举名称]（如 {Entity}StatusEnum）
+
+- **来源需求**: [引用 PRD ID]
+- **枚举描述**: [表示什么含义]
+- **存储值**: [Integer/TINYINT 或 String/VARCHAR]
+- **类路径**: `com.sie.gushen.{service}.infra.enumeration.{Entity}StatusEnum`
+
+| 枚举值 | 编码    | 显示名称 | 说明   | 使用场景 |
+| ------ | ------- | -------- | ------ | -------- |
+| [值1]  | [编码1] | [名称1]  | [说明] | [场景]   |
+| [值2]  | [编码2] | [名称2]  | [说明] | [场景]   |
+
+#### 6.1.2 枚举2: [枚举名称]
+
+[同上格式]
+
+### 6.2 数据校验规则
+
+| 数据项    | Java类型          | 必填     | 取值范围 | 校验注解                  | 消息码             |
+| --------- | ----------------- | -------- | -------- | ------------------------- | ------------------ |
+| {pkField} | Long              | 更新必填 | >0       | @NotNull(update组)        | {port}_{table}_001 |
+| [字段1]   | [String/Long/...] | [Y/N]    | [范围]   | @NotEmpty / @NotNull / 无 | {port}_{table}_002 |
+| [字段2]   | [类型]            | [Y/N]    | [范围]   | [校验]                    | {port}_{table}_003 |
+
+> 消息码格式: `{port}_{table_snake}_{三位序号}`，001-004 用于字段校验，005+ 用于业务异常。
+```
+
+---
+
+## §7 异常处理（必填）
+
+> **关注点**：分析 → 设计。从 PRD 验收场景和业务规则中提取异常场景，直接定义消息码、抛出位置和抛出方式。
+
+```markdown
+## 7. 异常处理
+
+> **原则**：异常在 Service 层抛出，Controller 仅做参数空校验返回 `ResponseData.fail()`。
+> 平台异常类：`RecordNotExistsException`、`GushenRuntimeException`、`ParameterNotValidException`。
+
+### 7.1 业务异常清单
+
+| #   | 异常名称       | 来源需求  | 消息码                | 触发条件                           | 抛出方式                                                                            | 抛出位置                                  |
+| --- | -------------- | --------- | --------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- |
+| 1   | 数据不存在     | US-01-AC1 | `{port}_{table}_005`  | get-id/update 时记录不存在或已删除 | `throw new RecordNotExistsException("{port}_{table}_005", List.of(id))`             | Service.findById / Service.update{Entity} |
+| 2   | 更新数据不存在 | US-01-AC2 | UPDATE_DATA_NOT_EXIST | update 时 getById 返回 null        | `throw new RecordNotExistsException(ResponseMsgCode.UPDATE_DATA_NOT_EXIST.msgCode)` | Service.update{Entity}                    |
+| 3   | [业务异常]     | [BR-xx]   | `{port}_{table}_006`  | [触发条件]                         | `throw new GushenRuntimeException("{port}_{table}_006")`                            | Service.xxx                               |
+| 4   | 参数为空       | 通用      | NOT_NULL_PARAM        | Controller 收到 null dto           | `return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode)`                  | Controller（所有端点）                    |
+
+### 7.2 异常处理流程
+
+```mermaid
+flowchart TD
+    A[Controller接收请求] --> B{dto == null?}
+    B -->|是| C[返回 ResponseData.fail NOT_NULL_PARAM]
+    B -->|否| D[调用 Service 层]
+    D --> E{业务校验}
+    E -->|记录不存在| F[Service抛出 RecordNotExistsException]
+    E -->|业务规则违反| G[Service抛出 GushenRuntimeException]
+    E -->|校验通过| H[返回 ResponseData.data]
+    F --> I[全局异常处理器捕获 → 返回错误响应]
+    G --> I
+    C --> J[前端展示错误信息]
+    I --> J
+```
+
+### 7.3 消息码汇总
+
+```properties
+# config/{port}-{module}-application_zh_CN.properties
+# 字段校验 001-004
+{port}_{table}_001 = 主键ID不能为空
+{port}_{table}_002 = {字段1}不能为空
+{port}_{table}_003 = {字段2}不能为空
+# 业务异常 005+
+{port}_{table}_005 = {实体}数据不存在
+{port}_{table}_006 = {业务异常描述}
+```
+
+> 每个模块维护 7 个 i18n properties 文件（default/zh_CN/zh_TW/en_US/vi_VN/th_TH/hu_HU），每个文件必须包含该语言的实际翻译内容。
+```
+
+---
+
+## §8 缓存与性能（必填）
+
+> **关注点**：设计。仅当有明确缓存需求或性能要求时填写。
+
+```markdown
+## 8. 缓存与性能
+
+### 8.1 缓存策略
+
+> 使用 DawnRedis，键格式 `{module}:{business}:{identifier}`，通过 ICacheKey 枚举统一管理。
+
+| 缓存数据 | 缓存原因 | 键格式                   | 过期时间 |
+| -------- | -------- | ------------------------ | -------- |
+| [数据1]  | [原因]   | {module}:{business}:{id} | [TTL]    |
+
+```java
+@Autowired
+private DawnRedis dawnRedis;
+
+// Key 通过 ICacheKey 枚举管理
+// 仅 Pipeline/Lua/Stream/PubSub 场景通过 dawnRedis.getRedisTemplate() 获取原生 RedisTemplate
+```
+
+### 8.2 数据库优化
+
+**索引优化**: [补充索引说明]
+
+**SQL 优化**:
+- 使用 `<include refid="Base_Column_List"/>` 避免 `SELECT *`
+- 模糊查询使用 `<bind>` 标签防止 SQL 注入
+- 分页查询使用 MyBatis Plus 分页插件
+
+### 8.3 并发控制
+
+| 策略     | 实现                                                           | 适用场景                   |
+| -------- | -------------------------------------------------------------- | -------------------------- |
+| 乐观锁   | version_num + OptimisticLockerInnerInterceptor                 | 更新操作（平台自动处理）   |
+| 分布式锁 | @Klock(keys = {"#id"}), fair=true, waitTime=60s, leaseTime=60s | 编码唯一性校验等写冲突场景 |
+
+> `@Klock` 禁止空 keys（会导致全局锁）。
+```
+
+---
+
+## §9 领域事件（必填）
+
+> **关注点**：分析 → 设计。梳理本模块的事件发布（本模块触发 → 下游消费）和事件消费（上游触发 → 本模块响应）。ECP 平台中事件通过 Kafka `StreamBridge` 发送，消费者通过 `BpmFlowConsumer` / 自定义 `Consumer<…>` Bean 接收。**如本模块无领域事件，填写"无"并说明原因（如采用拉模式、同步调用等）。**
+
+```markdown
+## 9. 领域事件
+
+### 9.1 发布事件
+
+> 本模块产生的业务事件，通过 Kafka 发送至消息系统，驱动下游模块或通知服务。
+
+| #   | 事件名称 | 触发条件                    | Payload 关键字段  | 消费者              | 通知机制                |
+| --- | -------- | --------------------------- | ----------------- | ------------------- | ----------------------- |
+| 1   | [事件名] | [触发该事件的 Service 方法] | [字段1, 字段2, …] | [下游模块/消息服务] | [站内消息/飞书/邮件/无] |
+
+#### 9.1.1 事件1: [事件名]
+
+- **来源需求**: [引用 PRD ID，如 N01，BR-01]
+- **触发条件**: [详细触发描述，标注触发该事件的 Service 方法]
+- **发送方式**: `StreamBridge.send("topic", payload)` / `BpmHelper.startProcess(procDefKey, businessKey)`
+- **Payload 结构**:
+
+| 字段名  | 类型   | 说明   |
+| ------- | ------ | ------ |
+| [字段1] | [类型] | [说明] |
+| [字段2] | [类型] | [说明] |
+
+- **消费者**: [消费者模块/服务名称]
+- **消费者处理逻辑**: [收到事件后的处理步骤]
+
+### 9.2 消费事件
+
+> 本模块消费的外部事件，通过 Kafka Consumer 接收，驱动本模块内部状态变更。
+
+| #   | 事件名称 | 来源                | Payload 关键字段  | 处理逻辑       |
+| --- | -------- | ------------------- | ----------------- | -------------- |
+| 1   | [事件名] | [来源模块/外部系统] | [字段1, 字段2, …] | [简要处理描述] |
+
+#### 9.2.1 事件1: [事件名]
+
+- **来源需求**: [引用 PRD ID]
+- **来源**: [来源模块名称 + 接口/事件名称]
+- **消费方式**: [Kafka Consumer, BpmFlowConsumer, Feign 回调, 定时轮询]
+- **Consumer 类**: `[包路径].[Consumer类名]` — Bean name 必须与 `function.definition` 一致
+- **Payload 结构**:
+
+| 字段名  | 类型   | 说明   |
+| ------- | ------ | ------ |
+| [字段1] | [类型] | [说明] |
+
+- **处理逻辑**: [收到事件后的完整处理步骤，标注调用的 Service 方法]
+
+### 9.3 事件流向图
+
+```mermaid
+flowchart LR
+    subgraph 本模块
+        A[业务操作]
+        B[事件 Consumer]
+    end
+    A -->|发布事件1| C[(Kafka Topic A)]
+    C --> D[消费者模块A]
+    C --> E[通知服务]
+    F[(Kafka Topic B)] -->|事件2| B
+    B --> G[本模块状态变更]
+```
+```
+
+---
+
+## §10 跨模块依赖（必填）
+
+> **关注点**：分析 → 设计。梳理本模块与外部模块/系统的依赖关系——"谁依赖我"（被依赖 / 上游调用方）和"我依赖谁"（依赖 / 下游被调用方）。用于明确模块边界、Feign Client SDK 接口契约和集成测试范围。**如本模块为独立模块无外部依赖，填写"无"并说明原因。**
+
+```markdown
+## 10. 跨模块依赖
+
+### 10.1 被依赖（本模块对外提供的服务）
+
+> 哪些模块/系统会调用本模块的能力？本模块需要对外暴露什么 Feign Client / SDK / REST 接口？
+
+| #   | 调用方     | 依赖方式                                      | 说明             | 对应接口                              |
+| --- | ---------- | --------------------------------------------- | ---------------- | ------------------------------------- |
+| 1   | [模块名称] | [Feign Client / SDK / REST 回调 / Kafka 消费] | [调用的业务目的] | [本模块暴露的接口路径 / Feign 方法名] |
+
+#### 10.1.1 调用方1: [模块名称]
+
+- **来源需求**: [引用 PRD ID]
+- **依赖方式**: [说明通信协议与方式]
+- **调用场景**: [调用方在什么业务场景下调用本模块]
+- **本模块对外暴露的契约**:
+
+| 接口            | 说明       | 请求关键字段      | 响应关键字段      |
+| --------------- | ---------- | ----------------- | ----------------- |
+| [方法签名/路径] | [功能说明] | [字段1, 字段2, …] | [字段1, 字段2, …] |
+
+### 10.2 依赖（本模块调用的外部服务）
+
+> 本模块需要调用哪些外部模块/系统的能力？
+
+| #   | 目标                | 依赖方式                            | 说明             | 调用时机                    |
+| --- | ------------------- | ----------------------------------- | ---------------- | --------------------------- |
+| 1   | [模块名称/外部系统] | [Feign Client / SDK / REST / Kafka] | [调用的业务目的] | [在哪个 Service 方法中调用] |
+
+#### 10.2.1 依赖1: [模块名称]
+
+- **来源需求**: [引用 PRD ID]
+- **依赖方式**: [说明通信协议与方式，如 Feign Client、Client SDK、REST 回调]
+- **Feign Client 接口**: `[包路径].[Client 接口名].[方法名]`（如为 Feign 调用）
+- **调用时机**: [在哪个 Service 方法的哪个步骤中调用]
+- **外部接口契约**:
+
+| 接口        | 说明       | 请求关键字段      | 响应关键字段      |
+| ----------- | ---------- | ----------------- | ----------------- |
+| [路径/方法] | [功能说明] | [字段1, 字段2, …] | [字段1, 字段2, …] |
+
+- **异常处理**: [外部调用失败时的处理策略：重试/降级/抛异常/返回默认值]
+
+### 10.3 依赖关系图
+
+```mermaid
+flowchart LR
+    subgraph 本模块["本模块: {模块名}"]
+        A[Controller]
+        B[Service]
+    end
+
+    subgraph 上游["上游调用方"]
+        C[调用方1]
+        D[调用方2]
+    end
+
+    subgraph 下游["下游依赖"]
+        E[外部模块A]
+        F[外部系统B]
+        G[平台基础设施]
+    end
+
+    C -->|Feign/REST| A
+    D -->|Feign/REST| A
+    B -->|Feign Client| E
+    B -->|REST API| F
+    B -->|SDK| G
+```
+```
+
+---
+
+## §11 非功能性需求（必填）
+
+> **关注点**：分析。从 PRD 验收标准中提取非功能性要求，结合 ECP 平台基础设施能力，明确性能指标、安全约束、数据一致性和审计要求。**如 PRD 未明确非功能需求，至少保留数据一致性（乐观锁 version_num）和审计日志两项。**
+
+```markdown
+## 11. 非功能性需求
+
+| 维度           | 要求                                        | 说明                           |
+| -------------- | ------------------------------------------- | ------------------------------ |
+| **性能**       | [如：列表查询 ≤3s，详情查询 ≤1s]            | [具体指标 + 实现方式]          |
+| **安全**       | [如：@CheckToken + 角色权限 + 数据隔离]     | [认证/授权/数据范围]           |
+| **兼容性**     | [如：Chrome / Edge 最新两个版本]            | [浏览器/终端兼容范围]          |
+| **数据一致性** | [如：变更联动原子操作 + 乐观锁 version_num] | [并发控制策略]                 |
+| **审计日志**   | [如：关键操作记录操作人/时间/前后值]        | [哪些操作需要记录]             |
+| **可用性**     | [如：99.9% 可用]                            | [SLA 要求，如无明确要求可不填] |
+| **可扩展性**   | [如：预留批量操作接口，当前版本不支持]      | [对未来扩展的预留设计]         |
+```
+
+---
+
+## §12 测试场景（必填）
+
+> **关注点**：分析。至少覆盖正常/异常/边界各 2 条场景。**如业务逻辑极为简单（纯单表 CRUD），最少列出 2 条核心正常场景。**
+
+```markdown
+## 9. 测试场景
+
+### 9.1 正常场景
+
+| #   | 场景名称 | 前置条件 | 操作步骤            | 预期结果 | 测试数据 |
+| --- | -------- | -------- | ------------------- | -------- | -------- |
+| 1   | [场景]   | [条件]   | 1. [步骤] 2. [步骤] | [预期]   | [数据]   |
+
+### 9.2 异常场景
+
+| #   | 场景名称 | 前置条件 | 操作步骤            | 预期结果 | 关联异常 |
+| --- | -------- | -------- | ------------------- | -------- | -------- |
+| 1   | [场景]   | [条件]   | 1. [步骤] 2. [步骤] | [预期]   | [消息码] |
+
+### 9.3 边界场景
+
+| #   | 场景名称 | 前置条件 | 操作步骤            | 预期结果 |
+| --- | -------- | -------- | ------------------- | -------- |
+| 1   | [场景]   | [条件]   | 1. [步骤] 2. [步骤] | [预期]   |
+```
+
+---
+
+## §13 总结（必填）
+
+```markdown
+## 13. 总结
+
+### 10.1 设计成果
+
+| 成果项            | 数量/内容                                   |
+| ----------------- | ------------------------------------------- |
+| 业务实体          | N 个（{Entity}Entity[, {SubEntity}Entity]） |
+| DTO               | N 个（{Entity}Dto[, {SubEntity}Dto]）       |
+| Ro                | N 个（{Entity}EntityRo）                    |
+| Service 接口/实现 | N 对                                        |
+| DAO + XML         | N 组                                        |
+| Controller        | N 个                                        |
+| REST 端点         | N 个                                        |
+| 业务异常          | N 个                                        |
+| 枚举类            | N 个                                        |
+
+### 10.2 关键设计决策
+
+| 决策    | 说明   |
+| ------- | ------ |
+| [决策1] | [说明] |
+| [决策2] | [说明] |
+
+### 10.3 后续工作
+
+- 编码实现：按本文 §2~§7 的设计生成 Entity/DTO/Ro/DAO+XML/Service/Controller
+- 编写 i18n：7 个 .properties 文件，确保每个语言文件包含该语言的实际翻译
+- Liquibase：按 §3.2 表结构创建 changelog
+- 单元测试：按 §9 测试场景编写
+- 集成测试：Controller 端点集成测试
+
+### 10.4 关键注意事项
+
+- DTO 必须继承 `ReqeustCommonDataBean`（注意拼写，非 "Request"）
+- Entity 中**禁止重复声明** BaseEntity 已有的审计字段
+- **所有 DB 操作通过 MyBatis XML 实现，禁止 QueryWrapper / LambdaQueryWrapper**
+- **所有 SELECT 必须含 WHERE delete_flag = 0**
+- Save 用 **FastJSON**：`JSONObject.parseObject(JSONObject.toJSONString(dto), Entity.class)`
+- Update 用 **Spring BeanUtils**：`BeanUtils.copyProperties(dto, entity, "createdBy", "creationDate", "versionNum")`
+- **异常在 Service 层抛出**，Controller 仅做参数空校验
+- 消息码格式 `{port}_{table_snake}_{三位序号}`，**禁止硬编码字符串**
+```
+
+---
+
+## 填写示例
+
+以下以 **gushen-demo 角色管理（含主从表）** 为例，演示按本模板完成设计。
+
+### §1 需求 ID 映射与模块上下文
+
+#### 1.1 模块定位
+- **模块名称**: 2051-demo
+- **模块描述**: ECP 平台基础服务演示模块，承载角色管理、系统管理、用户角色关联等基础功能
+- **所属分层**: 平台支撑层
+- **模块结构**: 2051-demo-api + 2051-demo-model + 2051-demo-application
+
+#### 1.2 上下文边界
+- **上游依赖**: sieiot-common-application、2021-sieiot-oauth-api
+- **下游调用**: 其他业务模块通过 Feign 调用角色查询能力
+- **外部集成**: Nacos、Redis（DawnRedis）、Kafka、Sentinel
+
+#### 1.3 核心职责
+- 角色管理：角色的增删改查、角色类型、启用状态、入口类型
+- 系统管理：子系统的注册管理、系统编码、请求配置
+- 用户角色关联：维护用户与角色的 N:N 关系
+
+### §2 业务实体与领域对象
+
+#### 2.1 实体1: IotBaseRoleEntity
+
+- **来源需求**: US-01, FUNC-01
+- **实体描述**: 定义系统中的角色，用于权限分配
+- **表名**: \`iot_base_role\`
+
+| 字段名       | Java类型 | DB类型  | 长度 | 必填 | 说明                   |
+| ------------ | -------- | ------- | ---- | ---- | ---------------------- |
+| roleId       | Long     | BIGINT  | 20   | Y    | 主键（雪花ID）         |
+| roleCode     | String   | VARCHAR | 64   | Y    | 角色编码               |
+| roleName     | String   | VARCHAR | 128  | Y    | 角色名称               |
+| systemCode   | String   | VARCHAR | 64   | Y    | 系统编码               |
+| remark       | String   | VARCHAR | 512  | N    | 备注                   |
+| tenantId     | Long     | BIGINT  | 20   | Y    | 租户ID                 |
+| tenantName   | String   | VARCHAR | 128  | N    | 租户名称               |
+| roleType     | Integer  | TINYINT | 4    | N    | 10=默认 null=非默认    |
+| orderNo      | Integer  | INT     | 11   | N    | 顺序号                 |
+| enterType    | String   | VARCHAR | 32   | N    | 入口类型 PC/WAP/APP/SR |
+| useStatus    | Integer  | TINYINT | 4    | N    | 0=禁用 1=启用          |
+| tpsRoleCode  | String   | VARCHAR | 64   | N    | 第三方角色编码         |
+| roleCategory | String   | VARCHAR | 64   | N    | 角色类别               |
+| expand       | String   | VARCHAR | 1024 | N    | 扩展字段（JSON）       |
+
+- **主键**: roleId (Long, ASSIGN_ID)
+- **索引**: uk_role_code_system (UNIQUE role_code, system_code), idx_tenant_id (NORMAL tenant_id)
+- **关联**: IotBaseRoleEntity 1:N IotBaseUserRoleEntity
+
+#### 2.2 实体2: IotBaseUserRoleEntity
+
+- **表名**: \`iot_base_user_role\`
+
+| 字段名   | Java类型 | DB类型 | 长度 | 必填 | 说明               |
+| -------- | -------- | ------ | ---- | ---- | ------------------ |
+| urId     | Long     | BIGINT | 20   | Y    | 主键（雪花ID）     |
+| tenantId | Long     | BIGINT | 20   | Y    | 租户ID             |
+| userId   | Long     | BIGINT | 20   | Y    | 用户ID             |
+| roleId   | Long     | BIGINT | 20   | Y    | 角色ID（关联主表） |
+
+- **主键**: urId (Long, ASSIGN_ID)
+- **索引**: idx_role_id (NORMAL), idx_user_id (NORMAL)
+
+#### 2.3 DTO: IotBaseRoleDto
+
+| 字段名              | Java类型                   | 必填          | 校验规则                                                             | 说明         |
+| ------------------- | -------------------------- | ------------- | -------------------------------------------------------------------- | ------------ |
+| roleId              | Long                       | 更新必填      | @NotNull(message="2051_iot_base_role_001", groups=updateIotBaseRole) | 主键         |
+| roleCode            | String                     | 新增/更新必填 | @NotEmpty(message="2051_iot_base_role_002", groups={save,update})    | 角色编码     |
+| roleName            | String                     | 新增/更新必填 | @NotEmpty(message="2051_iot_base_role_003", groups={save,update})    | 角色名称     |
+| systemCode          | String                     | 新增/更新必填 | @NotEmpty(message="2051_iot_base_role_004", groups={save,update})    | 系统编码     |
+| creationDates       | List\<Date\>               | 否            | @JSONField(format="yyyy-MM-dd HH:mm:ss")                             | 创建时间范围 |
+| iotBaseUserRoleList | List\<IotBaseUserRoleDto\> | 否            | @Valid                                                               | 级联子表     |
+
+- **验证分组**: `saveIotBaseRole` / `updateIotBaseRole`
+
+#### 2.4 Ro: IotBaseRoleEntityRo
+
+| 字段名              | Java类型                      | 说明                          |
+| ------------------- | ----------------------------- | ----------------------------- |
+| roleId              | Long                          | 主键                          |
+| roleCode            | String                        | 角色编码                      |
+| roleName            | String                        | 角色名称                      |
+| systemCode          | String                        | 系统编码                      |
+| creationDate        | Date                          | @DateTimeFormat + @JsonFormat |
+| createdBy           | Long                          | 创建人                        |
+| lastUpdateDate      | Date                          | @DateTimeFormat + @JsonFormat |
+| deleteFlag          | Integer                       | 删除标识                      |
+| versionNum          | Integer                       | 版本号                        |
+| iotBaseUserRoleList | List\<IotBaseUserRoleEntity\> | 关联用户角色列表              |
+
+### §3 数据模型
+
+#### 3.1 UML 类图
+
+```mermaid
+classDiagram
+    class IotBaseRoleEntity {
+        +Long roleId
+        +String roleCode
+        +String roleName
+        +String systemCode
+    }
+    class IotBaseUserRoleEntity {
+        +Long urId
+        +Long userId
+        +Long roleId
+    }
+    IotBaseRoleEntity "1" --> "N" IotBaseUserRoleEntity : 包含
+```
+
+#### 3.2 数据库表
+
+**表1**: \`iot_base_role\`
+
+| 字段名            | 类型     | 长度 | 必填 | 默认值 | 说明           |
+| ----------------- | -------- | ---- | ---- | ------ | -------------- |
+| role_id           | BIGINT   | 20   | Y    |        | 主键（雪花ID） |
+| role_code         | VARCHAR  | 64   | Y    |        | 角色编码       |
+| role_name         | VARCHAR  | 128  | Y    |        | 角色名称       |
+| system_code       | VARCHAR  | 64   | Y    |        | 系统编码       |
+| remark            | VARCHAR  | 512  | N    |        | 备注           |
+| tenant_id         | BIGINT   | 20   | Y    |        | 租户ID         |
+| tenant_name       | VARCHAR  | 128  | N    |        | 租户名称       |
+| role_type         | TINYINT  | 4    | N    |        | 10=默认        |
+| order_no          | INT      | 11   | N    |        | 顺序号         |
+| enter_type        | VARCHAR  | 32   | N    |        | 入口类型       |
+| use_status        | TINYINT  | 4    | N    |        | 0=禁用 1=启用  |
+| tps_role_code     | VARCHAR  | 64   | N    |        | 第三方编码     |
+| role_category     | VARCHAR  | 64   | N    |        | 角色类别       |
+| expand            | VARCHAR  | 1024 | N    |        | 扩展字段       |
+| creation_date     | DATETIME |      | Y    |        | 创建日期       |
+| created_by        | BIGINT   | 20   | Y    |        | 创建人         |
+| last_update_date  | DATETIME |      | Y    |        | 最后更新日期   |
+| last_updated_by   | BIGINT   | 20   | Y    |        | 最后更新人     |
+| last_update_login | BIGINT   | 20   | N    |        | 最后登录ID     |
+| delete_flag       | INT      | 11   | Y    | 0      | 删除标识       |
+| version_num       | INT      | 11   | Y    | 0      | 版本号         |
+
+- **主键**: role_id (BIGINT, ASSIGN_ID)
+- **索引**: uk_role_code_system UNIQUE(role_code, system_code), idx_tenant_id NORMAL(tenant_id)
+
+**表2**: \`iot_base_user_role\`（同格式，含审计字段，ur_id 主键，索引 idx_role_id + idx_user_id）
+
+#### 3.3 MyBatis XML 结构
+
+IotBaseRoleDAO.xml 包含 BaseResultMap（22列全字段映射）、Base_Column_List、BASE_QUERY_CONDITION、findPagination（含 WHERE delete_flag = 0）。
+
+### §4 业务行为与 Service 设计
+
+#### 4.1 行为清单
+
+| 行为     | 描述                  | 关键规则                                                                      |
+| -------- | --------------------- | ----------------------------------------------------------------------------- |
+| 新增角色 | 创建角色+级联保存子表 | FastJSON转换 → 主表save → 遍历子表设roleId → 逐条save                         |
+| 更新角色 | 更新角色+子表先删后增 | getById校验 → BeanUtils合并(排除审计字段) → deleteByRoleId → saveListByRoleId |
+| 删除角色 | 主表+子表级联软删除   | deleteById(id,true) + 子表逐个deleteById                                      |
+| 分页查询 | 按条件分页            | 默认creation_date DESC → DTO→Map → MyBatis XML                                |
+
+#### 4.2 Service 接口
+
+**IIotBaseRole** extends IBaseCommon\<IotBaseRoleEntity\>: findById / findPagination / saveIotBaseRole / updateIotBaseRole / deleteIotBaseRole
+
+**IIotBaseUserRole**: findListByIotBaseRoleId / saveListByIotBaseRoleId / deleteByIotBaseRoleId
+
+#### 4.3 Service 实现
+
+**IotBaseRoleService** `@Component("iotBaseRoleService")`:
+- saveIotBaseRole: FastJSON DTO→Entity → this.save(entity) → 遍历子表设roleId + urId=null → iotBaseUserRoleService.saveListByIotBaseRoleId
+- updateIotBaseRole: getById → BeanUtils.copyProperties(排除createdBy,creationDate,versionNum) → this.update → deleteByIotBaseRoleId + saveListByIotBaseRoleId
+- deleteIotBaseRole: deleteById(id,true) + deleteByIotBaseRoleId(id)
+
+#### 4.4 事务边界
+
+| 方法                      | @Transactional                |
+| ------------------------- | ----------------------------- |
+| saveIotBaseRole           | rollbackFor = Exception.class |
+| updateIotBaseRole         | rollbackFor = Exception.class |
+| deleteIotBaseRole         | rollbackFor = Exception.class |
+| findById / findPagination | 无                            |
+
+### §5 接口与 Controller 设计
+
+#### 5.1 端点清单
+
+| #   | HTTP | 路径                           | 说明                     |
+| --- | ---- | ------------------------------ | ------------------------ |
+| 1   | GET  | `/iotBaseRole/get-id`          | 按ID查询角色详情(含子表) |
+| 2   | POST | `/iotBaseRole/find-pagination` | 分页查询                 |
+| 3   | POST | `/iotBaseRole/save`            | 新增角色                 |
+| 4   | POST | `/iotBaseRole/update`          | 更新角色                 |
+| 5   | GET  | `/iotBaseRole/delete`          | 软删除                   |
+
+#### 5.2 Controller
+
+```java
+@Tag(name = "IotBaseRoleController控制器")
+@RestController
+@RequestMapping("/iotBaseRole")
+public class IotBaseRoleController extends CommonAbstractService {
+
+    @Autowired private IIotBaseRole iotBaseRoleService;
+
+    @Override public IBaseCommon getBaseCommonServer() { return this.iotBaseRoleService; }
+
+    @GetMapping("/get-id") @CheckToken
+    public ResponseData<IotBaseRoleEntityRo> findById(Long id) {
+        return ResponseData.data(iotBaseRoleService.findById(id));
+    }
+
+    @PostMapping("/find-pagination") @CheckToken
+    public ResponseData<Pagination<IotBaseRoleEntity>> findByPage(
+            @RequestBody PaginationRequestData<IotBaseRoleDto> req) {
+        return ResponseData.data(iotBaseRoleService.findPagination(
+            req.getParams(), req.getPageIndex(), req.getPageRows(), req.getOrderByBean()));
+    }
+
+    @PostMapping("/save") @CheckToken
+    public ResponseData<IotBaseRoleEntity> save(
+            @Validated(IotBaseRoleDto.saveIotBaseRole.class) @RequestBody RequestData<IotBaseRoleDto> req) {
+        IotBaseRoleDto dto = req == null ? null : req.getParams();
+        if (dto == null) return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode);
+        return ResponseData.data(iotBaseRoleService.saveIotBaseRole(dto));
+    }
+
+    @PostMapping("/update") @CheckToken
+    public ResponseData<IotBaseRoleEntity> update(
+            @Validated(IotBaseRoleDto.updateIotBaseRole.class) @RequestBody RequestData<IotBaseRoleDto> req) {
+        IotBaseRoleDto dto = req == null ? null : req.getParams();
+        if (dto == null) return ResponseData.fail(ResponseMsgCode.NOT_NULL_PARAM.msgCode);
+        return ResponseData.data(iotBaseRoleService.updateIotBaseRole(dto));
+    }
+
+    @GetMapping("/delete") @CheckToken
+    public ResponseData deleteById(@RequestParam Long id) {
+        iotBaseRoleService.deleteIotBaseRole(id);
+        return ResponseData.success();
+    }
+}
+```
+
+### §6 枚举与数据字典
+
+| 枚举      | 存储值             | 值                   |
+| --------- | ------------------ | -------------------- |
+| useStatus | Integer/TINYINT    | 0=禁用, 1=启用       |
+| enterType | String/VARCHAR(32) | PC, WAP, APP, SR     |
+| roleType  | Integer/TINYINT    | 10=默认, null=非默认 |
+
+数据校验规则：roleId(2051_iot_base_role_001), roleCode(002), roleName(003), systemCode(004)。
+
+### §7 异常处理
+
+| #   | 消息码                 | 触发条件                       | 抛出位置   |
+| --- | ---------------------- | ------------------------------ | ---------- |
+| 1   | 2051_iot_base_role_005 | get-id/update 时 roleId 无匹配 | Service    |
+| 2   | UPDATE_DATA_NOT_EXIST  | update 时 getById 返回 null    | Service    |
+| 3   | NOT_NULL_PARAM         | Controller 收到 null dto       | Controller |
+
+### §8 缓存与性能（示例 — 角色缓存策略）
+
+> 角色数据变更频率低、读取频率高，适合缓存加速分页查询和 get-id 查询。
+
+#### 8.1 缓存策略
+
+| 缓存数据           | 缓存原因                       | 键格式                        | 过期时间 |
+| ------------------ | ------------------------------ | ----------------------------- | -------- |
+| 角色详情           | get-id 高频读取，变更低频      | `demo:role:{roleId}`          | 30 min   |
+| 角色列表（按系统） | 分页查询按 systemCode 筛选频繁 | `demo:role:list:{systemCode}` | 10 min   |
+
+```java
+@Autowired
+private DawnRedis dawnRedis;
+
+// 角色详情缓存：get-id 命中返回，未命中查 DB 后写入
+// 角色更新/删除时清除对应缓存键
+```
+
+#### 8.2 并发控制
+
+| 策略     | 实现                                                                                  | 适用场景                     |
+| -------- | ------------------------------------------------------------------------------------- | ---------------------------- |
+| 乐观锁   | version_num + OptimisticLockerInnerInterceptor                                        | 角色更新（平台自动处理）     |
+| 分布式锁 | `@Klock(keys = {"#dto.roleCode + ':' + #dto.systemCode"}, waitTime=60, leaseTime=60)` | 同一系统下角色编码唯一性校验 |
+
+### §9 领域事件（示例 — 角色变更通知）
+
+> 角色管理为平台基础模块，当前未定义领域事件。以下为占位示例，展示事件发布/消费的标准格式。
+
+#### 9.1 发布事件
+
+| #   | 事件名称 | 触发条件 | Payload 关键字段 | 消费者 | 通知机制 |
+| --- | -------- | -------- | ---------------- | ------ | -------- |
+| —   | 暂无     | —        | —                | —      | —        |
+
+#### 9.2 消费事件
+
+| #   | 事件名称 | 来源 | Payload 关键字段 | 处理逻辑 |
+| --- | -------- | ---- | ---------------- | -------- |
+| —   | 暂无     | —    | —                | —        |
+
+### §10 跨模块依赖（示例 — 角色管理依赖关系）
+
+> 角色管理模块为平台支撑层基础模块，对外暴露 Feign Client 供其他业务模块查询角色信息，内部依赖 Nacos / Redis / Kafka 等平台基础设施。
+
+#### 10.1 被依赖（对外提供）
+
+| #   | 调用方                       | 依赖方式         | 说明                                     | 对应接口                                   |
+| --- | ---------------------------- | ---------------- | ---------------------------------------- | ------------------------------------------ |
+| 1   | 其他业务模块（用户权限校验） | Feign Client SDK | 查询用户的角色列表、校验用户是否有某角色 | `IIotBaseRole.findById` / `findPagination` |
+
+#### 10.2 依赖（调用外部）
+
+| #   | 目标                      | 依赖方式   | 说明                                           | 调用时机                       |
+| --- | ------------------------- | ---------- | ---------------------------------------------- | ------------------------------ |
+| 1   | Nacos                     | 服务发现   | 服务注册与配置中心                             | 应用启动时                     |
+| 2   | Redis (DawnRedis)         | 平台 SDK   | 角色数据缓存                                   | get-id / findPagination 查询时 |
+| 3   | sieiot-common-application | Maven 依赖 | 平台公共基类（BaseEntity/BaseCommonServer 等） | 编译/运行时                    |
+
+### §11 非功能性需求（示例 — 角色管理）
+
+| 维度           | 要求                           | 说明                         |
+| -------------- | ------------------------------ | ---------------------------- |
+| **性能**       | get-id ≤500ms，分页查询 ≤1s    | 角色数据量小，无复杂关联查询 |
+| **安全**       | @CheckToken + RBAC 角色权限    | 管理员可编辑，普通用户只读   |
+| **数据一致性** | 乐观锁 version_num             | 平台自动处理更新冲突         |
+| **审计日志**   | 角色创建/更新/删除记录操作日志 | ECP 平台日志审计基础设施     |
+
+### §12 测试场景（示例）
+
+#### 9.1 正常场景
+
+| #   | 场景名称               | 前置条件                                 | 操作步骤                                                                                                           | 预期结果                          | 测试数据                             |
+| --- | ---------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------ |
+| 1   | 正常新增角色（含子表） | 管理员已登录，roleCode+systemCode 不重复 | 1. POST /save 传入 roleCode="TEST", roleName="测试角色", systemCode="SIE-CRM", iotBaseUserRoleList=[{userId:2001}] | 返回 entity，含 roleId 和子表数据 | roleCode="TEST", roleName="测试角色" |
+| 2   | 正常分页查询           | 数据库存在角色记录                       | 1. POST /find-pagination pageIndex=1, pageRows=10                                                                  | 返回分页数据，total 为总记录数    | pageIndex=1, pageRows=10             |
+
+#### 9.2 异常场景
+
+| #   | 场景名称         | 前置条件             | 操作步骤                      | 预期结果                    | 关联异常                 |
+| --- | ---------------- | -------------------- | ----------------------------- | --------------------------- | ------------------------ |
+| 1   | 查询不存在的角色 | roleId=999999 不存在 | 1. GET /get-id?id=999999      | 返回 2051_iot_base_role_005 | RecordNotExistsException |
+| 2   | 更新不存在的角色 | roleId=999999 不存在 | 1. POST /update roleId=999999 | 返回 UPDATE_DATA_NOT_EXIST  | RecordNotExistsException |
+
+#### 9.3 边界场景
+
+| #   | 场景名称                       | 前置条件              | 操作步骤                               | 预期结果                             |
+| --- | ------------------------------ | --------------------- | -------------------------------------- | ------------------------------------ |
+| 1   | 子表为空的新增                 | 管理员已登录          | 1. POST /save iotBaseUserRoleList=[]   | 正常返回 entity，子表为空            |
+| 2   | 子表为空的更新（清空关联用户） | 角色原有 2 个关联用户 | 1. POST /update iotBaseUserRoleList=[] | 角色更新成功，所有旧关联用户被软删除 |
+
+### §13 总结（示例）
+
+#### 13.1 设计成果
+
+| 成果项            | 数量/内容                                          |
+| ----------------- | -------------------------------------------------- |
+| 业务实体          | 2 个（IotBaseRoleEntity, IotBaseUserRoleEntity）   |
+| DTO               | 2 个（IotBaseRoleDto, IotBaseUserRoleDto）         |
+| Ro                | 1 个（IotBaseRoleEntityRo）                        |
+| Service 接口/实现 | 2 对（IIotBaseRole + IIotBaseUserRole）            |
+| DAO + XML         | 2 组（IotBaseRoleDAO.xml, IotBaseUserRoleDAO.xml） |
+| Controller        | 1 个（IotBaseRoleController）                      |
+| REST 端点         | 5 个（标准 5 端点）                                |
+| 业务异常          | 3 个                                               |
+| 枚举类            | 3 个（useStatus, enterType, roleType）             |
+
+#### 13.2 关键设计决策
+
+| 决策                      | 说明                                                                     |
+| ------------------------- | ------------------------------------------------------------------------ |
+| 子表更新采用"先删后增"    | 简化代码实现，事务保护原子性；子表数据量小（单角色关联用户数通常 < 100） |
+| 乐观锁 + 分布式锁双重保护 | version_num 处理普通并发更新；@Klock 处理编码唯一性校验的高并发写冲突    |
+| 角色缓存 30min TTL        | 角色变更后主动清除缓存，确保数据一致性                                   |
+
+#### 13.3 后续工作
+
+- 编码实现：按 §2~§7 的设计生成 Entity/DTO/Ro/DAO+XML/Service/Controller
+- 编写 i18n：7 个 .properties 文件（default/zh_CN/zh_TW/en_US/vi_VN/th_TH/hu_HU）
+- Liquibase：按 §3.2 表结构创建 changelog
+- 单元测试：按 §9 测试场景编写
+- 集成测试：Controller 端点集成测试
+
+#### 13.4 关键注意事项
+
+- DTO 继承 `ReqeustCommonDataBean`（注意平台拼写，非 "Request"）
+- Entity 中**禁止重复声明** BaseEntity 已有的审计字段
+- **所有 DB 操作通过 MyBatis XML 实现，禁止 QueryWrapper**
+- **所有 SELECT 必须含 WHERE delete_flag = 0**
+- Save 用 **FastJSON**：`JSONObject.parseObject(JSONObject.toJSONString(dto), Entity.class)`
+- Update 用 **Spring BeanUtils**：`BeanUtils.copyProperties(dto, entity, "createdBy", "creationDate", "versionNum")`
+
+---
+
+## 两阶段追溯关系（参考）
+
+> 本文已合并为单阶段。以下仅展示历史追溯关系，供理解 OOA→OOD 映射逻辑。
+
+```
+PRD（用户故事/业务规则/功能）
+  │
+  ▼  本文（单阶段一体化设计）
+需求 ID 映射（§1: US-xx / BR-xx / FUNC-xx / PERM-xx）
+  │
+  ├─→ 业务实体与领域对象（§2: Entity/DTO/Ro 字段表）
+  ├─→ 数据模型（§3: UML 类图 → DDL → MyBatis XML）
+  ├─→ 业务行为与 Service 设计（§4: 行为清单 → 接口/实现 → 事务边界）
+  ├─→ 接口与 Controller 设计（§5: 端点 → Controller 代码骨架 → 权限矩阵）
+  ├─→ 枚举与数据字典（§6: 枚举值定义 → 校验规则）
+  └─→ 异常处理（§7: 异常清单 → 消息码 → 抛出方式 → 流程图）
+                          │
+                          ▼
+                     编码实现（OOP）
+```
+
+---
+
+## 填写建议
+
+1. **严格遵循 ECP 平台约定** — 所有包路径、注解、命名规范以本文「项目约定」章节为准
+2. **禁止 QueryWrapper / LambdaQueryWrapper** — 所有 DB 操作走 MyBatis XML
+3. **禁止硬编码错误消息字符串** — 使用 `ResponseMsgCode` 枚举
+4. **禁止在 Entity 中重复声明审计字段** — BaseEntity 已提供
+5. **Save 用 FastJSON，Update 用 Spring BeanUtils**（排除 `"createdBy", "creationDate", "versionNum"`）
+6. **消息码格式** `{port}_{table_snake}_{三位序号}`，每个模块维护 7 个 i18n properties 文件
+7. **使用 Mermaid 可视化** — 实体关系用 classDiagram，业务流程用 flowchart，状态流转用 stateDiagram
+8. **按顺序填写** — 从 §1 到 §13 逐步完成，后续部分引用前面定义的内容，避免重复
+9. **每个设计条目标注** `**来源需求**:` 引用 PRD ID
+10. **禁止过度设计** — 简单 CRUD 不套用策略/工厂模式，选填部分仅在确需时填写
+11. **禁止虚构需求** — 分析内容必须来自 PRD，不做无依据的假设设计
+
+---
+
+## 附录：最终代码结构
+
+> 以下为按本模板完成设计后应生成的完整工程目录树。工程结构遵循 ECP 三模块 Maven 约定（`{port}-{service}-api` + `{port}-{service}-model` + `{port}-{service}-application`）。
+> 各模块的文件数按实际设计内容确定（如有子表则多 1 组 DAO+XML+Service，如有自定义端点则多若干 Controller 方法）。
+
+```
+{port}-{service}/                                      # 顶层 Maven 父工程
+├── pom.xml                                            #   父 POM（parent: sie-irradiator:3.0.2）
+├── {port}-{service}-api/                              # ========== 契约层 ==========
+│   ├── pom.xml
+│   └── src/main/java/com/sie/{product}/{service}/api/
+│       ├── client/                                    #   @FeignClient 接口定义
+│       │   ├── {ExternalA}Client.java                 #     外部模块A的 Feign 调用契约
+│       │   ├── {ExternalB}Client.java                 #     外部模块B的 Feign 调用契约
+│       │   └── ...                                   #     （按 §10 跨模块依赖定义）
+│       └── dto/                                       #   DTO（extends ReqeustCommonDataBean）
+│           ├── {Entity}Dto.java                       #     主表入参（含 save/update 校验分组）
+│           ├── {SubEntity}Dto.java                    #     子表入参（如有子表）
+│           ├── {Custom}Dto.java                       #     自定义操作入参（如批量审批、查询条件等）
+│           └── ...                                   #     （按 §2.3 DTO 清单生成）
+│
+├── {port}-{service}-model/                            # ========== 数据层 ==========
+│   ├── pom.xml
+│   └── src/main/
+│       ├── java/com/sie/{product}/{service}/model/
+│       │   ├── entity/                                #   Entity（extends BaseEntity<T>）
+│       │   │   ├── {Entity}Entity.java                #     主表实体（@TableName 反引号，每字段 @TableField + @Schema）
+│       │   │   ├── {SubEntity}Entity.java             #     子表实体（含外键关联主表主键）
+│       │   │   └── readonly/                          #   Ro 只读视图对象（implements Serializable）
+│       │   │       └── {Entity}EntityRo.java          #     详情视图（手动声明字段，含关联子表 List）
+│       │   └── dao/                                   #   DAO 接口 + MyBatis Mapper XML（同包路径）
+│       │       ├── {Entity}DAO.java                   #     主表 DAO（extends BaseCommonDAO_HI）
+│       │       ├── {Entity}DAO.xml                    #     主表 XML（BaseResultMap → Base_Column_List → BASE_QUERY_CONDITION → findPagination）
+│       │       ├── {SubEntity}DAO.java                #     子表 DAO（如有）
+│       │       └── {SubEntity}DAO.xml                 #     子表 XML（findListBy{父}Id 等）
+│       └── resources/
+│           └── liquibase/mysql/{module_name}/         #   Liquibase 数据库变更管理
+│               ├── master.xml                         #     入口 changelog：引用版本 XML
+│               ├── v1.0.xml                           #     版本变更日志
+│               └── ddl/
+│                   └── DDL_1.0_{date}.sql             #     建表 DDL（{table_name} + {sub_table_name}）
+│
+└── {port}-{service}-application/                      # ========== 实现层 ==========
+    ├── pom.xml
+    └── src/main/
+        ├── java/com/sie/{product}/{service}/
+        │   ├── {Service}Application.java              #   启动类（extends CommonApplication）
+        │   ├── api/controller/                        #   Controller（extends CommonAbstractService）
+        │   │   ├── {Entity}Controller.java            #     主表 REST 控制器（5 标准端点 + N 自定义端点）
+        │   │   └── {SubEntity}Controller.java         #     子表控制器（如有独立端点需求）
+        │   ├── model/service/                         #   Service 接口（II{Entity} 双I前缀 + extends IBaseCommon）
+        │   │   ├── II{Entity}.java                    #     主表 Service 接口
+        │   │   ├── II{SubEntity}.java                 #     子表 Service 接口（如有）
+        │   │   └── impl/                              #   Service 实现（extends BaseCommonServer）
+        │   │       ├── {Entity}Service.java           #     主表业务逻辑（CRUD + 级联 + 自定义方法 + 事务）
+        │   │       └── {SubEntity}Service.java        #     子表业务逻辑（findListBy{父}Id + saveListBy{父}Id + deleteBy{父}Id）
+        │   ├── app/consume/                           #   Kafka Consumer（如有领域事件消费）
+        │   │   └── {Event}Consumer.java               #     事件消费者（@Configuration + Consumer<String> Bean）
+        │   └── infra/
+        │       ├── config/                            #   配置类
+        │       │   ├── DataSourceConfig.java           #     数据源配置
+        │       │   ├── MybatisPlusConfig.java          #     MyBatis Plus 分页插件 + 乐观锁插件
+        │       │   └── SpringDocConfig.java            #     SpringDoc API 文档配置
+        │       ├── constant/                          #   常量
+        │       │   └── ResponseMsgCode.java            #     消息码枚举（字段校验 + 业务异常 + 通用消息码）
+        │       ├── enumeration/                       #   枚举类（按 §6.1 枚举值定义生成）
+        │       │   ├── {Entity}StatusEnum.java         #     主实体状态枚举
+        │       │   ├── {Type}Enum.java                 #     业务类型枚举
+        │       │   └── ...                           #     （按 §6.1 逐一生成）
+        │       ├── interceptor/                       #   拦截器
+        │       │   └── TokenInterceptor.java           #     @CheckToken 令牌校验拦截器
+        │       └── utils/                             #   工具类
+        │           └── {Module}Utils.java              #     模块专用工具（如日期计算、编码校验等）
+        └── resources/
+            └── config/                                #   i18n 多语言配置（7 个文件）
+                ├── {port}-{service}-application.properties          # 默认（Unicode 转义）
+                ├── {port}-{service}-application_zh_CN.properties    # 简体中文
+                ├── {port}-{service}-application_zh_TW.properties    # 繁体中文
+                ├── {port}-{service}-application_en_US.properties    # 英文
+                ├── {port}-{service}-application_vi_VN.properties    # 越南语
+                ├── {port}-{service}-application_th_TH.properties    # 泰语
+                └── {port}-{service}-application_hu_HU.properties    # 匈牙利语
+```
+
+**目录树统计**：
+
+| 层级                  | 文件数                                                                                                   | 说明                                                             |
+| --------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| -api (契约层)         | N Feign Client + N DTO                                                                                   | 对外接口契约与入参定义（按 §10 依赖数 + §2.3 DTO 数）            |
+| -model (数据层)       | N Entity + N Ro + N DAO + N XML                                                                          | 数据实体、只读视图与 MyBatis 映射（按 §2.2 实体数 + §2.4 Ro 数） |
+| -application (实现层) | N Controller + N Service接口 + N Service实现 + N Consumer + 3 Config + 1 常量 + N 枚举 + N 工具 + 7 i18n | 业务逻辑、REST接口、基础配置与国际化                             |
+| Liquibase             | 1 master + 1 version + 1 DDL                                                                             | 数据库版本管理                                                   |
+| **合计**              | **约 30~50 个文件**                                                                                      | 覆盖完整的 3 模块工程结构                                        |
+
+> **使用说明**：生成系统设计文档时，将上述 `{placeholders}` 替换为实际值：
+> - `{port}` = 端口号（如 3103）
+> - `{service}` = 服务名（如 crm-contract / sales-forecast）
+> - `{product}` = 产品线（gushen）
+> - `{Entity}` = 实体类名（PascalCase，如 ForecastOrder）
+> - `{SubEntity}` = 子表实体类名（如有）
+> - `{entity}` = URL 路径前缀（kebab-case，如 forecast-order）
+> - `{table_name}` = 数据库表名（snake_case）
+> - `{module_name}` = 模块业务名（如 sales_forecast）
+
+---
+
+## 模板优势
+
+1. **单阶段一体化** — OOA 和 OOD 合并为一份模板，按业务关注点组织，一次完成"分析→设计"全过程
+2. **消除重复** — 同一实体字段只在 §2 定义一次，同一接口只在 §5 定义一次，不再在 OOA/OOD 中重复
+3. **全链路追溯** — 需求 ID 从 PRD → 设计文档 → 代码 贯穿始终
+4. **贴合 ECP 实际** — 所有包路径、注解、命名规范均以 `gushen-demo/` 实际代码和 11 份 ECP 规范为准
+5. **三模块架构** — 包含 -api（契约）、-model（数据+DAO+XML）、-application（实现）完整分层
+6. **覆盖全面** — 从需求 ID 映射到事务/缓存设计，13 个部分覆盖完整设计生命周期
+7. **主从表示例** — 以 gushen-demo 角色管理为例，完整展示 ECP 平台主从表级联操作模式
+8. **AI 友好** — 结构化格式便于 AI 理解和生成 ECP 工程代码
+
+---
+
+## 使用流程
+
+```
+1. 读取 PRD 文件（docs/20-prd/）
+       │
+2. 按本模板 §1~§13 完成设计文档 + 建表 SQL
+   → 保存到 docs/30-system-design/{crm|mom}/
+   → 文件命名：{模块编号}-{模块名}_system-design.md
+       │
+3. 编码实现（OOP）
+   → 根据设计文档，严格按照 CLAUDE.md ECP 编码规范生成代码
+       │
+4. 测试
+   → 单元测试 → 集成测试 → 性能测试
+```
+
+---
+
+**文档结束**
+
+*本文件 v6.0 将原两阶段 OOA/OOD 21 个部分合并为单阶段 13 个部分。合并策略：按业务关注点组织（实体→数据→行为→接口→异常…），每部分从"分析"直接过渡到"设计"，消除跨阶段重复定义。原 04-需求分析模板.md 和 05-系统设计模板.md 的内容已完全内嵌于本文。*