TG-BOOT springboot 功能集散开发框架（AI 协作友好）

本文档面向 AI 助手与开发者，是 tg-boot 文档站入口：说明最新模块分层、协作边界，以及生成代码前的硬性约定，以下文档需要down项目查阅，后面有GIT地址。

优先级	文档	说明
必读	AI 编码规范	实体 `BaseEntity`、双主键、`*-api` 边界、检查清单
必读	跨模块协作规范	MQ 与同步 `Api**Service` 选用、依赖禁止项
部署	运维说明	Actuator 禁止公网暴露、MQ 生产配置
门禁	架构测试	ArchUnit 模块边界守护
理念	树-图架构	树形定边界、图形定关系

功能演示

定位

TG 基于 Spring Boot 3.5.x ，以 Maven 多模块划分 common / components / business / runner ；默认将多个 *-biz 打进同一个 spring-boot-starter-runner 进程（模块化单体）。

模块之间 ：只通过 *-api 中的 Api**Service 与 MQ 消息契约协作。
模块内部 ：在 *-biz/service 用 SPI 表达多实现（支付渠道、短信、存储等），由注册表路由。
v3.6.0 起 ：移除低代码生成器与通用字典模块，改由 AI + 仓库约定 驱动开发（见版本变更）。

模块架构（与 `pom.xml` 同步）

以 spring-boot-starter-module 下各聚合 pom.xml 为准；增删 runner 能力一般只改 [spring-boot-starter-runner/pom.xml](https://gitee.com/pub_module/tg-boot/blob/master/spring-boot-starter-module/spring-boot-starter-runner/pom.xml)。

Maven 模块树

text 复制代码

tg-boot
├── spring-boot-starter-module          # Maven 反应堆根
│   ├── spring-boot-starter-common      # 公共内核（Result、BaseEntity、MQ 基础设施、安全）
│   ├── spring-boot-starter-components  # 通用能力组件（12 个子模块）
│   │   ├── spring-boot-starter-system       # 用户/组织/权限（核心）
│   │   ├── spring-boot-starter-trade        # 商品订单、支付
│   │   ├── spring-boot-starter-distribution # 分销分佣、钱包
│   │   ├── spring-boot-starter-verification # 二要素/资产认证
│   │   ├── spring-boot-starter-ai           # AI 对话、智能体、消耗明细
│   │   ├── spring-boot-starter-sms          # 短信（SPI 多厂商）
│   │   ├── spring-boot-starter-wechat       # 微信能力
│   │   ├── spring-boot-starter-file         # 文件上传/存储
│   │   ├── spring-boot-starter-cms          # CMS
│   │   ├── spring-boot-starter-im           # 即时通讯
│   │   ├── spring-boot-starter-excel        # Excel 导入导出
│   │   └── spring-boot-starter-ocr          # OCR
│   ├── spring-boot-starter-business    # 垂直业务域
│   │   └── spring-boot-starter-dating       # 婚恋/约会（含 DtCustomer 等）
│   │       ├── spring-boot-starter-dating-api
│   │       └── spring-boot-starter-dating-biz
│   ├── spring-boot-starter-runner      # 默认可执行单体（按需引入 *-biz）
│   └── spring-boot-starter-architecture-tests  # 构建期架构门禁（非运行时代码）
├── tg-vue                              # 管理端（Vue 3 + Element Plus + Vite）
├── tg-uniapp                           # 多端壳（uni-app / unibest）
└── plugins/                            # 运行时外置插件目录

协作关系图

#mermaid-svg-36pxc0wfhmPrO8BL{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-36pxc0wfhmPrO8BL .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-36pxc0wfhmPrO8BL .error-icon{fill:#552222;}#mermaid-svg-36pxc0wfhmPrO8BL .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-36pxc0wfhmPrO8BL .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-36pxc0wfhmPrO8BL .marker{fill:#333333;stroke:#333333;}#mermaid-svg-36pxc0wfhmPrO8BL .marker.cross{stroke:#333333;}#mermaid-svg-36pxc0wfhmPrO8BL svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-36pxc0wfhmPrO8BL p{margin:0;}#mermaid-svg-36pxc0wfhmPrO8BL .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-36pxc0wfhmPrO8BL .cluster-label text{fill:#333;}#mermaid-svg-36pxc0wfhmPrO8BL .cluster-label span{color:#333;}#mermaid-svg-36pxc0wfhmPrO8BL .cluster-label span p{background-color:transparent;}#mermaid-svg-36pxc0wfhmPrO8BL .label text,#mermaid-svg-36pxc0wfhmPrO8BL span{fill:#333;color:#333;}#mermaid-svg-36pxc0wfhmPrO8BL .node rect,#mermaid-svg-36pxc0wfhmPrO8BL .node circle,#mermaid-svg-36pxc0wfhmPrO8BL .node ellipse,#mermaid-svg-36pxc0wfhmPrO8BL .node polygon,#mermaid-svg-36pxc0wfhmPrO8BL .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-36pxc0wfhmPrO8BL .rough-node .label text,#mermaid-svg-36pxc0wfhmPrO8BL .node .label text,#mermaid-svg-36pxc0wfhmPrO8BL .image-shape .label,#mermaid-svg-36pxc0wfhmPrO8BL .icon-shape .label{text-anchor:middle;}#mermaid-svg-36pxc0wfhmPrO8BL .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-36pxc0wfhmPrO8BL .rough-node .label,#mermaid-svg-36pxc0wfhmPrO8BL .node .label,#mermaid-svg-36pxc0wfhmPrO8BL .image-shape .label,#mermaid-svg-36pxc0wfhmPrO8BL .icon-shape .label{text-align:center;}#mermaid-svg-36pxc0wfhmPrO8BL .node.clickable{cursor:pointer;}#mermaid-svg-36pxc0wfhmPrO8BL .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-36pxc0wfhmPrO8BL .arrowheadPath{fill:#333333;}#mermaid-svg-36pxc0wfhmPrO8BL .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-36pxc0wfhmPrO8BL .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-36pxc0wfhmPrO8BL .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-36pxc0wfhmPrO8BL .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-36pxc0wfhmPrO8BL .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-36pxc0wfhmPrO8BL .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-36pxc0wfhmPrO8BL .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-36pxc0wfhmPrO8BL .cluster text{fill:#333;}#mermaid-svg-36pxc0wfhmPrO8BL .cluster span{color:#333;}#mermaid-svg-36pxc0wfhmPrO8BL div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-36pxc0wfhmPrO8BL .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-36pxc0wfhmPrO8BL rect.text{fill:none;stroke-width:0;}#mermaid-svg-36pxc0wfhmPrO8BL .icon-shape,#mermaid-svg-36pxc0wfhmPrO8BL .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-36pxc0wfhmPrO8BL .icon-shape p,#mermaid-svg-36pxc0wfhmPrO8BL .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-36pxc0wfhmPrO8BL .icon-shape .label rect,#mermaid-svg-36pxc0wfhmPrO8BL .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-36pxc0wfhmPrO8BL .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-36pxc0wfhmPrO8BL .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-36pxc0wfhmPrO8BL :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} spring-boot-starter-runner（单 JVM）
Api**Service 同步
MQ 发布-订阅
Api**Service 同步
business · 垂直业务
dating
common

MQ · 安全 · BaseEntity
components · 通用能力
system
trade
distribution
verification
ai
sms / wechat / file / cms / im / excel / ocr

Runner 装配原则 ：runner/pom.xml 显式列出需要的 *-biz；未引入的 biz 不会注册 HTTP 接口与 MQ 消费者。裁剪能力 = 删依赖，不必改上层模块树。

单个域的源码包结构（`-api` / `-biz`）

text 复制代码

*-api/                              # 对外契约，被其他模块 Maven 依赖
├── api/constants/                  # XxxCodeEnum
├── api/dto/                        # 跨模块 DTO / VO
├── api/service/                    # Api**Service 接口
└── api/messaging/                  # MQ 契约（XxxConsumer）

*-biz/                              # 实现层，由 runner 聚合
├── biz/
│   ├── controller/{cus|mgt|pub}/   # 用户端 / 管理端 / 公开接口
│   ├── service/
│   │   ├── impl/                   # Api**Service 实现、SPI 实现
│   │   └── Spi**Service            # 模块内多实现（仅 biz/service）
│   └── messaging/                  # MQ 消费者 Handler
├── crud/
│   ├── entity/                     # 必须 extends BaseEntity
│   ├── mapper/
│   └── service/impl/               # MyBatis-Plus Service（含 getByCode）
└── Biz*AutoConfiguration.java

三层协作机制对照

层级	机制	定义位置	适用场景
跨模块异步	MQ + `XxxConsumer`	`*-api/messaging`	登录通知、支付成功副作用、资料变更广播
跨模块同步	`ApiService`**	`*-api/service`	同进程强一致编排、需立即返回结果
模块内多实现	`SpiService`**	`*-biz/service`	短信渠道、支付渠道、文件存储等

AI 编码规范（生成代码前必读）

完整版含正反例与路径索引：AI 编码规范。Cursor / Copilot 会话开始时应 @ 该文档或本文。

阅读顺序

AI 编码规范（硬性约定 + 检查清单）
本文（模块树与 MQ 原则）
目标子模块 README（如 sms、dating）
同域已有代码作模板：**SysUser、DtCustomer、DtMatchmaker、SmsTemplate**

持久层：最高频错误

必须继承 BaseEntity （pub.module.common.model.po.BaseEntity），禁止在实体上重复手写 createTime / deleted 等审计字段。

双主键模型：

层级	字段	说明
技术主键	`id`	在 `BaseEntity` 中，`@TableId(type = IdType.ASSIGN_ID)`，子类禁止再标 `@TableId`
业务主键	`xxxCode`	普通列，对外关联用语义编码（如 `userCode`、`dtCusCode`）

Service 配套 （crud/service/impl）：

提供 getByCode(String code) 按业务编码查询
updateById 前先 getByCode 取 id 再更新
管理端按业务编码删除用 removeByBizCodes，不要对 xxxCode 调 removeByIds

`*-api` 边界（最高频架构错误）

层级	规则
Maven	`-api/pom.xml` 只能依赖 `common` 或他域 `-api`；禁止依赖任何 `*-biz`
Java	`*-api` 内禁止 import `crud.entity`、`crud.mapper`、`biz.service.impl`
Api 契约	`Api*Service` 入参/返回值必须是 `-api/dto` 或枚举，禁止出现 `crud.entity.`*

java 复制代码

// ❌ 禁止：api 返回 crud 实体
VtAssetCertRecord submitApply(...);

// ✅ 正确：api 返回 DTO
VtAssetCertRecordDTO submitApply(...);

命名摘要

目录式命名 ：表前缀 + 字段名 （如 distUserCode），省略系统层，禁止 *SysUserCode（trade 历史字段勿模仿）
***Code**：字典/枚举字段；枚举放 *-api/constants，类名 XxxCodeEnum
***StatusCode**：仅 0/1（否/是），null 视同否；禁止放流程中间态
***ProcessCode**：多步审核流程；终态通过时同步 *StatusCode = 1
已废弃 ：通用字典表 / spring-boot-starter-dict

跨模块 MQ 发布（硬性）

写库后投递消息必须在事务提交后：

java 复制代码

mqPublisher.publishAfterCommit(XxxConsumer.class, payload);

禁止在 @Transactional 写库方法内直接 publish（无事务的只读场景除外）。

生成代码后检查清单

crud/entity/* 全部 extends BaseEntity，无重复 @TableId 在 xxxCode 上
Api**Service 契约无 crud.entity 引用；*-api/pom.xml 无 *-biz 依赖
*-biz/pom.xml 跨域只新增 *-api 依赖，不依赖他域 *-biz
ServiceImpl 含 getByCode；按业务编码查询用 getByCode 而非 getById
跨模块写库后发 MQ 使用 publishAfterCommit
新增业务域已在 architecture-tests/pom.xml 补充 *-api 与 *-biz
已执行过的 create_*.sql 勿改；新字段另写 alter_*.sql

本地校验：mvn -pl spring-boot-starter-architecture-tests -am test

MQ 通信与模块依赖原则

完整链路表与演进说明：跨模块协作规范。

两大设计原则

避免耦合 ：模块只依赖 *-api 契约，不依赖他域 *-biz；发布方 不感知、不硬编码 订阅方列表。
保持独立 ：各域可独立演进、按需订阅或退订；新增消费者时，发布方代码通常 零改动。

协作模式选型

text 复制代码

┌─────────────────────────────────────────────────────────────────┐
│  任意模块  ──同步 Api**Service──▶  公共组件 / 其他业务模块       │
│           （需立即结果：查用户、发短信、AI 对话、强一致编排）      │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  公共组件  ──MQ 发布-订阅──▶  0～N 个订阅方（dating / distribution）│
│           （异步副作用：登录、资料变更、支付成功等）               │
└─────────────────────────────────────────────────────────────────┘

场景	选用	契约位置
需立即返回结果	同步 `Api**Service`	`*-api/service`
异步通知、多订阅方广播	MQ 发布-订阅	`*-api/messaging/XxxConsumer.java`
一问一答（少数读查询）	MQ request-reply	`@MqChannel(mode=REQUEST_REPLY)`

Maven 与 Java 依赖禁止项

禁止	正确做法
`-biz` 依赖他域 `-biz`	只依赖他域 `*-api` + `common`
`-api` 依赖 `-biz` 或 import `crud.`*	契约只用 `*-api/dto`
`-api` 定义 `Spi` 接口	SPI 只在 `*-biz/service`
跨模块拼 SQL 关联对方表	同步表、API 组装、MQ 冗余
yml 手写 domain binding	契约在 `XxxConsumer`，common 自动注册
Spring `ApplicationEvent` 跨模块	仅限模块内
事务内直接 `publish`	`MqPublisher.publishAfterCommit`

MQ 契约约定

单文件定义 ：发布方 *-api/messaging/XxxConsumer.java 含 @MqChannel、消息体、嵌套 @MqSubscribe 槽位
消费实现 ：*-biz/messaging/ 下 @Component implements XxxConsumer.{Slot}（勿直接实现根接口）
通用广播 ：根契约在发布方 api；各订阅方在 自身 api 声明槽位，发布方零改动
基础设施 ：common 提供 MqPublisher、MqMessagingAutoConfiguration、嵌入式 Rabbit（dev）、application-messaging-baseline.yml（重试/DLQ）

现有 MQ 链路（代码扫描）

Destination	模式	发布方	消费方 group	说明
`trade.order-goods.paid`	单向	trade-biz	`dating` / `distribution`	支付成功后履约 / 分佣
`system.user.login`	单向	system-biz	`dating`	登录后初始化婚恋客户档案
`system.user-info.updated`	单向	system-biz	`dating`	用户昵称变更同步
`system.user.registered`	单向	system-biz	`distribution`	注册后绑定推荐关系
`verification.phone-two-factor.verified`	单向	verification-biz	`dating`	二要素通过后更新实名
`dating.profile.updated`	单向	dating-biz	`dating`	资料变更域内冗余同步
`wx.pay.notify`	单向	wechat-biz	`trade`	微信支付回调异步处理

契约类路径：pub.module.*.api.messaging.*Consumer；运维基线见 common。

新增 MQ 能力决策树

调用方是否需要 立即返回 ？→ 是：Api**Service；否：继续
是否为 公共组件向依赖方异步通知？→ 是：MQ 发布-订阅
是否 多订阅方广播 ？→ 各订阅方在自身 api 声明 @MqSubscribe 槽位
消费者是否幂等？→ 必须声明幂等键（唯一键 / 状态比对 / 业务编码查重）
*-biz/pom.xml 是否 只新增 -api 依赖？

技术栈

类别	技术
后台	Spring Boot 3.5.5、Spring Security、MyBatis-Plus
前台	Vue 3、Element Plus、Vite（tg-vue）
消息	Spring Cloud Stream + RabbitMQ（dev 嵌入式 Rabbit）
数据库	MySQL、PostgreSQL、Oracle、SQL Server、达梦、人大金仓等

组件清单以 components 子文档为准。

快速启动

内置 JDK / Maven（`tg-boot/.tools`）

组件	路径
JDK 21	`tg-boot/.tools/jdk-21`
Maven	`tg-boot/.tools/apache-maven-*/bin`

启动默认 runner

先确保 MySQL / Redis 等与 application-dev.yml 一致，在 **tg-boot 根目录**：

powershell 复制代码

.\scripts\run-runner.ps1

或在 **spring-boot-starter-module** 目录（须保留 -am）：

bat 复制代码

mvn -pl spring-boot-starter-runner -am spring-boot:run -DskipTests

文档索引

分区	说明
AI 编码规范	实体、命名、跨模块硬性约定
跨模块协作规范	MQ 与 Api 选用规则
运维说明	Actuator 安全、MQ 生产配置
架构测试门禁	ArchUnit 模块边界
树-图架构	树形定边界、图形定关系
starter-module	Maven 聚合根
runner	默认单体启动器
components	通用 Starter（system、trade、ai...）
business	垂直业务域（dating）
plugins	运行时外置插件
tg-manage-vue	管理端前端

开发约定摘要

字典与状态字段

***Code**：存编码不存展示名；枚举在 *-api/constants
***StatusCode**：仅 0/1；***ProcessCode**：多步流程中间态
v3.6.0 起：全面舍弃通用字典模块，常量走枚举、复杂选项走业务表

表设计

系统字段来自 BaseEntity（id、审计、逻辑删除、版本等）
业务字段：表前缀 + 字段名；跨表冗余与来源列保持同一语义

版本变更历史

v3.6.0（2026-05-20）

次版本升级 （3.5.2 → 3.6.0）：以架构收敛与 AI 协作友好为主。

变更	说明
移除低代码 / 代码生成	改由 AI 按仓库约定从表结构 → API → biz 手写
移除通用字典模块	常量用枚举、复杂选项用业务表、国标数据用专属表
客户域收敛	独立 `customer` 模块已合并进 `dating`（`DtCustomer`）；MQ group 由 `customer` 改为 `dating`
新增 AI 组件	`spring-boot-starter-ai`（api + biz）
分销提升为 component	`spring-boot-starter-distribution` 归入 components

对开发者 ：新功能按本文 [AI 编码规范](#AI 编码规范) 与 [MQ 原则](#MQ 原则) 扩展；升级时清理对 dict / generator 的依赖。

版本	说明
3.5.2	上一稳定次版本

链接

Gitee ：https://gitee.com/pub_module/tg-boot.git
文档站点 ：http://docs.module.pub
演示环境 ：http://tg.module.pub

文档与 tg-boot 仓库同步；若与 pom 不一致，以 spring-boot-starter-module 实际模块为准。

TG-BOOT springboot 功能集散开发框架（AI 协作友好）