adspecs 0.1.12

package/.adspecs/templates/16-/347/263/273/347/273/237/346/236/266/346/236/204/350/256/276/350/256/241/346/250/241/346/235/277.md

@@ -0,0 +1,608 @@
+# {项目名称} — 系统架构设计
+
+> **版本**: v{版本号}
+> **创建日期**: {创建日期}
+> **最后更新**: {更新日期}
+> **基于**: {平台名称} + {业务文档名称} v{版本号}
+
+### 修订记录
+
+| 版本号 | 修订日期 | 修订人 | 修订内容 |
+| ------ | -------- | ------ | -------- |
+| v1.0 | {日期} | {修订人} | 初始版本：{平台}架构 + {项目}设计 |
+
+---
+
+## 一、技术栈总览
+
+### 1.1 核心框架
+
+| 技术领域 | 技术选型 | 版本 | 说明 |
+|---------|---------|------|------|
+| JDK | Java | {版本号} | {说明} |
+| 构建工具 | Maven | {版本号} | {说明} |
+| 核心框架 | Spring Boot | {版本号} | 应用基础框架 |
+| 微服务框架 | Spring Cloud | {版本号} | 服务治理、OpenFeign |
+| 服务注册/配置 | Nacos | {版本号} | 注册中心+配置中心 |
+| Web服务器 | {容器名称} | {版本号} | {说明} |
+<!-- 按项目实际技术栈填写 -->
+
+### 1.2 持久层与数据库
+
+| 技术领域 | 技术选型 | 版本 | 说明 |
+|---------|---------|------|------|
+| ORM框架 | {ORM名称} | {版本号} | {说明} |
+| 连接池 | {连接池名称} | {版本号} | {说明} |
+| 数据库 | {数据库名称} | {版本号} | 主数据库 |
+| 缓存 | {缓存名称} | {版本号} | {说明} |
+| 分布式锁 | {锁组件名称} | {版本号} | {说明} |
+| ID生成 | {ID策略} | {版本号} | {说明} |
+<!-- 按项目实际技术栈填写 -->
+
+### 1.3 微服务通信
+
+| 技术领域 | 技术选型 | 说明 |
+|---------|---------|------|
+| 服务注册/发现 | {注册中心} | 服务注册与健康检查 |
+| RPC调用 | {RPC框架} | 声明式远程调用 |
+| 负载均衡 | {负载均衡} | 客户端负载均衡 |
+
+### 1.4 安全与防护
+
+| 技术领域 | 技术选型 | 说明 |
+|---------|---------|------|
+| 认证 | {认证方案} | Token认证 |
+| 权限 | {权限模型} | {权限说明} |
+| 数据加密 | {加密方案} | {加密说明} |
+
+### 1.5 工具库
+
+| 技术领域 | 技术选型 | 说明 |
+|---------|---------|------|
+| 工具类 | {工具库名称} | {说明} |
+| JSON | {JSON库名称} | JSON序列化 |
+| 简化开发 | Lombok | 代码生成 |
+| 日志 | {日志框架} | 统一日志框架 |
+| 对象转换 | {转换工具} | DTO↔Entity转换 |
+| 参数校验 | {校验框架} | 分组校验 |
+| API文档 | {文档工具} | {说明} |
+
+### 1.6 集成中间件
+
+| 技术领域 | 技术选型 | 说明 |
+|---------|---------|------|
+| 消息队列 | {MQ名称} | {用途说明} |
+| 工作流 | {工作流引擎} | {说明} |
+| 文件存储 | {文件中心} | 统一文件管理 |
+| 搜索引擎 | {搜索引擎} | {用途说明} |
+| 自动编码 | {编码服务} | {说明} |
+<!-- 按项目实际中间件填写 -->
+
+---
+
+## 二、技术架构
+
+### 2.1 微服务架构总览
+
+{项目简称}平台按业务子域拆分为 **{服务数量} 个独立微服务 + {平台底座模块}**，部署在{平台名称}上：
+
+```
+                         ┌──────────────────────────────────────────────┐
+                         │           前端（{前端框架} SPA）               │
+                         │      {前端项目名称}                           │
+                         └──────────────────┬───────────────────────────┘
+                                            │ HTTP
+                                            ▼
+                         ┌──────────────────────────────────────────────┐
+                         │         {网关名称} + {注册中心}                │
+                         │    统一入口、路由转发、Token校验、负载均衡        │
+                         └──────────────────┬───────────────────────────┘
+                                            │
+        ┌──────────┬──────────┬─────────────┼─────────────┬──────────┐
+        ▼          ▼          ▼             ▼             ▼          ▼
+  ┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
+  │{端口}-   ││{端口}-   ││{端口}-   ││{端口}-   ││{端口}-   ││{端口}-   │
+  │{服务名}  ││{服务名}  ││{服务名}  ││{服务名}  ││{服务名}  ││{服务名}  │
+  │ ──────── ││ ──────── ││ ──────── ││ ──────── ││ ──────── ││ ──────── │
+  │{模块列表}││{模块列表}││{模块列表}││{模块列表}││{模块列表}││{模块列表}│
+  │ P{优先级}││ P{优先级}││ P{优先级}││ P{优先级}││ P{优先级}││ P{优先级}│
+  └────┬─────┘└────┬─────┘└────┬─────┘└────┬─────┘└────┬─────┘└────┬─────┘
+       │           │           │           │           │           │
+       └───────────┴───────────┴───────────┼───────────┴───────────┘
+                                           │
+              ┌────────────────────────────┼────────────────────────────┐
+              │                            │                            │
+              ▼                            ▼                            ▼
+    ┌──────────────────┐     ┌──────────────────────┐     ┌──────────────────┐
+    │  {平台底座}       │     │   {关联系统}          │     │   外部系统        │
+    │  {能力列表}       │     │   {模块列表}          │     │  {系统列表}      │
+    └────────┬─────────┘     └──────────┬───────────┘     └────────┬─────────┘
+             │                          │                          │
+             └──────────────────────────┼──────────────────────────┘
+                                        │
+          ┌─────────────────────────────┼─────────────────────────────┐
+          │                             │                             │
+          ▼                             ▼                             ▼
+┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
+│  {数据库}        │     │  {缓存}          │     │  {消息队列}       │
+│  {说明}          │     │  {说明}          │     │  {说明}          │
+└──────────────────┘     └──────────────────┘     └──────────────────┘
+```
+
+### 2.2 模块内部架构（三模块结构 · 每服务独立）
+
+每个微服务遵循标准的三模块结构（`-api` / `-model` / `-application`）。服务间通过 `-api` 模块（Feign Client + DTO）实现编译期依赖，运行时通过{注册中心}发现 + {RPC框架}调用。
+
+```
+{服务目录名}/
+│
+├── {端口}-{服务名}/                              # {服务描述}
+│   ├── {端口}-{服务名}-api/                      #   API：{Client列表}, DTO
+│   ├── {端口}-{服务名}-model/                    #   Model：{Entity列表}, DAO+XML
+│   └── {端口}-{服务名}-application/              #   App：控制器 {路径前缀}/**
+<!-- 为每个服务复制此结构 -->
+```
+
+**单服务内部结构（以 {示例服务名} 为例）：**
+
+```
+{端口}-{服务名}/
+│
+├── {端口}-{服务名}-api/                     # API模块 — 纯Jar，被消费方依赖
+│   └── src/main/java/{包路径}/
+│       ├── client/                          #   Feign接口（被外部服务调用）
+│       │   └── {Client名称}.java
+│       └── dto/                             #   传输DTO（被消费方引用）
+│           └── {DTO目录}/
+│
+├── {端口}-{服务名}-model/                   # Model模块 — 纯Jar，数据层
+│   └── src/main/java/{包路径}/
+│       ├── entity/                          #   实体类
+│       │   └── {Entity名称}.java
+│       ├── entity/readonly/                 #   只读组合对象(Ro)
+│       ├── dao/                             #   DAO接口 + MyBatis XML（同包同名）
+│       │   ├── {DAO名称}.java
+│       │   └── {DAO名称}.xml
+│       └── infra/enumeration/               #   ResponseMsgCode枚举
+│
+└── {端口}-{服务名}-application/             # Application模块 — Spring Boot Jar，独立部署
+    └── src/main/java/{包路径}/
+        ├── {Application}Application.java    #   启动类
+        ├── controller/                      #   REST控制器
+        │   └── {Controller名称}.java
+        ├── service/                         #   Service接口
+        │   └── {Service接口名称}.java
+        ├── service/impl/                    #   Service实现
+        │   └── {Service实现名称}.java
+        ├── infra/config/                    #   配置
+        ├── app/consume/                     #   消息消费
+        └── app/produce/                     #   消息生产
+```
+
+**服务间依赖关系（-api 模块引用）：**
+
+```
+{服务A}-application
+        │  compile dependency
+        ▼
+{服务B}-api（{查询描述}）              {服务C}-api（{查询描述}）
+```
+
+### 2.3 请求处理链路
+
+```
+客户端请求（{前端框架} SPA）
+    │
+    ▼
+{网关名称}
+    │  路由匹配：Path=/{模块路径}/**
+    │  Token校验（@CheckToken）
+    │  负载均衡
+    ▼
+{Controller名称}（extends CommonAbstractService）
+    │  @CheckToken 认证
+    │  RequestData<Dto> / PaginationRequestData<Dto> 请求包装
+    │  @Validated(Group.class) 参数校验
+    ▼
+{Service名称}（extends BaseCommonServer<Entity>）
+    │  业务逻辑处理
+    │  DTO → Entity 转换
+    │  异常抛出（GushenRuntimeException + ResponseMsgCode）
+    │  事务管理
+    ▼
+{DAO名称}（extends BaseCommonDAO_HI<Entity>）
+    │  MyBatis XML → SQL执行
+    │  WHERE delete_flag = 0（逻辑删除）
+    ▼
+{数据库名称}（{Schema名称}）
+```
+
+### 2.4 平台基础能力复用
+
+{项目简称}的 M00 系统管理模块**复用{平台名称}已建成的技术底座**，不需要单独开发：
+
+| M00子模块 | {平台名称}对应能力 | 说明 |
+|-----------|-------------------|------|
+| SYS-01 组织架构 | {对应能力} | {说明} |
+| SYS-02 角色权限 | {对应能力} | {说明} |
+| SYS-03 字段配置 | {对应能力} | {说明} |
+| SYS-04 流程配置 | {对应能力} | {说明} |
+| SYS-05 编码规则 | {对应能力} | {说明} |
+<!-- 按项目实际情况填写 -->
+
+---
+
+## 三、关键设计规范（{平台名称}规范）
+
+### 3.1 分层开发规范
+
+严格遵守{平台名称}的三层架构规范：
+
+| 层级 | 所属模块 | 基类 | 核心职责 |
+|------|---------|------|----------|
+| Entity | model | `BaseEntity<Entity>` | 数据表映射 |
+| Ro | model | `Serializable` | 只读组合对象，不映射表 |
+| DTO | api | `ReqeustCommonDataBean` | 传输对象，含校验分组 |
+| DAO | model | `BaseCommonDAO_HI<Entity>` | 持久化接口，MyBatis XML映射 |
+| Service接口 | application | `IBaseCommon<Entity>` | 业务契约，命名`II{Entity}` |
+| Service实现 | application | `BaseCommonServer<Entity>` | 业务逻辑，异常抛出，事务管理 |
+| Controller | application | `CommonAbstractService` | REST端点，`@CheckToken` |
+
+### 3.2 实体设计规范
+
+```java
+@Getter
+@Setter
+@TableName(value = "`{表名}`", autoResultMap = true)
+public class {Entity名称} extends BaseEntity<{Entity名称}> implements Serializable {
+
+    @TableId(value = "{主键字段名}", type = IdType.ASSIGN_ID)
+    @Schema(description = "{主键描述}")
+    private Long {主键属性名};
+
+    @TableField(value = "{字段名}")
+    @Schema(description = "{字段描述}")
+    private {类型} {属性名};
+
+    // ... 其他字段
+}
+```
+
+**关键要点：**
+- 主键类型：`Long`，策略 `IdType.ASSIGN_ID`（Snowflake）
+- 每个字段必须同时标注 `@TableField` + `@Schema`
+- 审计字段由 `BaseEntity` 提供，**不可重复声明**
+- 表名使用反引号包裹
+
+### 3.3 DTO设计规范
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class {Dto名称} extends ReqeustCommonDataBean {
+
+    @NotNull(groups = {Update{Entity}.class}, message = "{port}_{table}_{seq}")
+    @Null(groups = {Save{Entity}.class}, message = "{port}_{table}_{seq}")
+    private Long {主键属性名};
+
+    @NotBlank(groups = {Save{Entity}.class}, message = "{port}_{table}_{seq}")
+    private String {字段名};
+
+    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
+    private Date {日期字段名};
+
+    // 校验分组
+    public interface Save{Entity} {}
+    public interface Update{Entity} {}
+}
+```
+
+### 3.4 DAO设计规范
+
+**⚠️ 核心约束：所有数据库操作必须使用MyBatis XML，禁止使用QueryWrapper/LambdaQueryWrapper。**
+
+```java
+@Component("{dao名称}")
+public interface {DAO名称} extends BaseCommonDAO_HI<{Entity名称}> {
+
+    List<{Entity名称}> findPagination(
+        @Param("page") Page<{Entity名称}> page,
+        @Param("params") Map<String, Object> params
+    );
+}
+```
+
+```xml
+<mapper namespace="{包路径}.{DAO名称}">
+    <resultMap id="BaseResultMap" type="{Entity全限定名}">
+        <id column="{主键列名}" property="{主键属性名}"/>
+        <!-- 所有字段包括审计字段 -->
+    </resultMap>
+
+    <select id="findPagination" resultMap="BaseResultMap">
+        SELECT * FROM {表名}
+        WHERE delete_flag = 0
+        <if test="params.{字段名} != null and params.{字段名} != ''">
+            AND {列名} LIKE CONCAT('%', #{params.{字段名}}, '%')
+        </if>
+        ORDER BY creation_date DESC
+    </select>
+</mapper>
+```
+
+### 3.5 Service设计规范
+
+```java
+// Service接口
+public interface II{Entity} extends IBaseCommon<{Entity名称}> {
+    // 业务方法声明
+}
+
+// Service实现
+@Component("{entity名称}Service")
+public class {Entity名称}Service extends BaseCommonServer<{Entity名称}>
+        implements II{Entity} {
+
+    @Autowired
+    private {DAO名称} {dao名称};
+
+    // Save：使用FastJSON转换 DTO → Entity
+    // Update：使用Spring BeanUtils，排除审计字段
+    // Delete：调用 this.deleteById(id, true) 实现软删除
+}
+```
+
+### 3.6 Controller设计规范
+
+```java
+@Tag(name = "{模块名称}")
+@RestController
+@RequestMapping("/{路径前缀}")
+public class {Controller名称} extends CommonAbstractService {
+
+    @Autowired
+    private II{Entity} {service名称};
+
+    @Override
+    protected IBaseCommon getBaseCommonServer() {
+        return {service名称};
+    }
+
+    @CheckToken
+    @GetMapping("/get-id")
+    @Operation(summary = "按ID查询")
+    public ResponseData<{Ro名称}> getById(@RequestParam Long id) { ... }
+
+    @CheckToken
+    @PostMapping("/find-pagination")
+    @Operation(summary = "分页查询")
+    public ResponseData<Pagination<{Ro名称}>> findPagination(...) { ... }
+
+    @CheckToken
+    @PostMapping("/save")
+    @Operation(summary = "新增")
+    public ResponseData<Void> save(...) { ... }
+
+    @CheckToken
+    @PostMapping("/update")
+    @Operation(summary = "更新")
+    public ResponseData<Void> update(...) { ... }
+
+    @CheckToken
+    @GetMapping("/delete")
+    @Operation(summary = "删除")
+    public ResponseData<Void> delete(@RequestParam Long id) { ... }
+}
+```
+
+### 3.7 i18n国际化规范
+
+每个模块需维护 **7个properties文件**，路径 `src/main/resources/config/`：
+
+| 文件名 | 语言 |
+|--------|------|
+| `{port}-{service}.properties` | 默认（Unicode转义） |
+| `{port}-{service}_zh_CN.properties` | 简体中文 |
+| `{port}-{service}_zh_TW.properties` | 繁体中文 |
+| `{port}-{service}_en_US.properties` | 英文 |
+| `{port}-{service}_vi_VN.properties` | 越南语 |
+| `{port}-{service}_th_TH.properties` | 泰语 |
+| `{port}-{service}_hu_HU.properties` | 匈牙利语 |
+
+**消息码规范：** `{port}_{service}_{module}_{3-digit}`
+
+### 3.8 编码自动生成规范
+
+所有业务编码通过 `AutoCodeRuleService.generate(prefix, length)` 生成，**禁止自编编码逻辑**：
+
+| 业务对象 | 编码前缀 | 长度 | 示例 | 所属服务 |
+|----------|---------|------|------|----------|
+| {业务对象} | {前缀} | {长度} | {示例} | {服务名} |
+<!-- 按项目实际编码规则填写 -->
+
+### 3.9 BPM审批流接入规范
+
+```java
+// 审批发起
+@Autowired
+private BpmHelper bpmHelper;
+
+public void submit{业务}Approval(Long {参数名}) {
+    bpmHelper.startProcess(
+        ProcessDefinitionConstants.{流程常量名},
+        String.valueOf({参数名})
+    );
+}
+
+// 审批结果消费（Kafka Consumer）
+```
+
+**审批流程类型：**
+
+| 流程类型 | 流程定义Key | 业务场景 |
+|----------|------------|----------|
+| {审批类型} | `{流程key}` | {业务场景} |
+<!-- 按项目实际审批流程填写 -->
+
+### 3.10 文件中心接入规范
+
+```java
+@Autowired
+private IotBaseAttachmentClient iotBaseAttachmentClient;
+
+// 保存时关联文件
+iotBaseAttachmentClient.update(dto.getFileIds(), "{业务类型}", entity.getId());
+
+// 查询时加载文件
+ro.setFiles(iotBaseAttachmentClient.findList("{业务类型}", id));
+```
+
+---
+
+## 四、数据库设计
+
+### 4.1 核心表结构概览
+
+```
+{表名1}             {表描述1}
+{表名2}             {表描述2}
+{表名3}             {表描述3}
+<!-- 按项目实际表结构填写 -->
+```
+
+### 4.2 数据库设计规范
+
+**必须字段（每张表）：**
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| tenant_id | BIGINT | 租户ID（多租户隔离） |
+| creation_date | DATETIME | 创建时间 |
+| created_by | BIGINT | 创建人ID |
+| last_update_date | DATETIME | 最后更新时间 |
+| last_updated_by | BIGINT | 最后更新人ID |
+| last_update_login | BIGINT | 最后更新登录ID |
+| delete_flag | TINYINT | 逻辑删除标记（0=正常，1=已删除） |
+| version_num | INT | 乐观锁版本号 |
+
+**命名规范：**
+- 表名：`{前缀}_{business_name}`，全小写下划线
+- 主键：`{business}_id`，BIGINT
+- 外键：`{related_table}_id`，BIGINT
+- 所有表和字段必须添加 `COMMENT`
+
+### 4.3 预留扩展字段
+
+为支持后续功能，建表时预留以下字段：
+
+| 表 | 预留字段 | 说明 | 目标模块 |
+|----|---------|------|----------|
+| {表名} | {字段名} | {说明} | {目标模块} |
+<!-- 按项目实际预留字段填写 -->
+
+---
+
+## 五、服务调用与事件驱动
+
+### 5.1 同步调用
+
+| 调用方向 | 接口 | 场景 |
+|----------|------|------|
+| {服务A} → {服务B} | {接口描述} | {场景描述} |
+<!-- 按项目实际调用关系填写 -->
+
+### 5.2 异步事件（{MQ名称}）
+
+| 事件 | 发布方 | 订阅方 | 说明 |
+|------|--------|--------|------|
+| {事件名称} | {发布方} | {订阅方} | {说明} |
+<!-- 按项目实际事件填写 -->
+
+---
+
+## 六、分期建设范围与技术债务清单
+
+### 6.1 一期微服务开发范围
+
+| 服务 | 包含模块 | 核心数据表 | 分期 |
+|------|---------|-----------|------|
+| {服务名} | {模块列表} | {表列表} | {分期} |
+<!-- 按项目实际规划填写 -->
+
+### 6.2 技术债务清单
+
+| 编号 | 技术债务 | 影响 | 归属服务 | 建议解决阶段 |
+|------|---------|------|----------|-------------|
+| TD-01 | {技术债务描述} | {影响} | {服务} | {阶段} |
+<!-- 按项目实际情况填写 -->
+
+---
+
+## 七、部署与配置
+
+### 7.1 微服务端口规划
+
+| 端口 | 服务名 | 包含模块 | Maven artifact | 分期 |
+|------|--------|---------|----------------|------|
+| {端口} | {服务名} | {模块} | `{artifact}` | {分期} |
+<!-- 按项目实际端口规划填写 -->
+
+### 7.2 配置文件
+
+```
+{端口}-{服务名}-application/src/main/resources/
+├── application-{配置名}.yml            # 主配置
+├── bootstrap.properties                # {注册中心}配置
+├── logback-spring.xml                  # 日志配置
+├── config/                             # i18n（7 properties）
+└── liquibase/                          # 数据库变更管理
+    └── mysql/{schema}/
+        ├── master.xml
+        └── v1.0.0.xml
+```
+
+### 7.3 Docker构建
+
+```bash
+# 构建示例
+mvn clean -U package -Drevision={版本号} -pl ./{application模块} -am
+
+# Docker镜像构建
+docker build -t {镜像仓库}/{服务名}:{版本号} \
+  -f ./{application模块}/Dockerfile .
+```
+
+---
+
+## 八、代码生成检查清单
+
+生成代码时，按以下清单逐项校验：
+
+1. ☐ 确认模块名、包路径、基类FQN
+2. ☐ Entity: `extends BaseEntity<Entity>`，`@TableName`反引号，所有字段`@TableField`+`@Schema`，`IdType.ASSIGN_ID`
+3. ☐ DTO: `extends ReqeustCommonDataBean`（精确拼写），校验分组内部接口，日期`@JSONField`
+4. ☐ DAO: `extends BaseCommonDAO_HI<Entity>`，`@Component`，XML同包同名，resultMap包含所有审计字段，所有SELECT含`WHERE delete_flag = 0`
+5. ☐ **禁止QueryWrapper/LambdaQueryWrapper** — 全部DB操作通过MyBatis XML
+6. ☐ Service接口: `II{Entity}` extends `IBaseCommon<Entity>`，实现: `@Component`，extends `BaseCommonServer<Entity>`
+7. ☐ Save用FastJSON `BeanUtil`，Update用Spring `BeanUtils.copyProperties`排除审计字段，Delete用`deleteById(id, true)`
+8. ☐ Controller: extends `CommonAbstractService`，`getBaseCommonServer()`，全端点`@CheckToken`，标准REST路径，`ResponseData`/`RequestData`/`PaginationRequestData`包装
+9. ☐ 异常在Service层抛出，使用`ResponseMsgCode`枚举 — **禁止硬编码字符串**
+10. ☐ i18n: 7个properties文件，每个语言文件含正确语言内容
+11. ☐ 编码生成通过`AutoCodeRuleService.generate(prefix, length)` — **禁止自编编码**
+12. ☐ BPM审批通过`BpmHelper.startProcess(procDefKey, businessKey)`
+13. ☐ 文件关联通过`IotBaseAttachmentClient.update(fileIds, businessType, businessId)`
+14. ☐ Liquibase管理所有数据库变更，DDL/DML幂等
+15. ☐ 注入使用`@Autowired`
+
+---
+
+## 九、参考文档
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| {文档名称} | `{路径}` | {说明} |
+<!-- 按项目实际参考文档填写 -->
+
+---
+
+**文档结束**