module.pub

简体中文

English

简体中文

English

外观

TG-boot AI 编码规范

约 1757 字大约 6 分钟

2026-06-02

TG-boot AI 编码规范（必读）

面向 Cursor / Copilot 等 AI 助手。生成或修改本仓库 Java / Vue 代码前，请先阅读本文；详细背景见 TG-boot 总览，跨模块规则见 跨模块协作规范。

1. 阅读顺序

  1. 本文（硬性约定 + 正反例）
  2. TG-boot 总览（架构、字典/状态机、模块树）
  3. 目标子模块 README.md（如 spring-boot-starter-sms/README.md）
  4. 同域已有 crud/entity、biz/controller 作为模板（优先 Customer、SysUser、DtMatchmaker）

2. 持久层实体（crud/entity）— 最高频错误

2.1 必须继承 BaseEntity

// ✅ 正确
@Data
@EqualsAndHashCode(callSuper = false)
@Schema(description = "客户")
public class Customer extends BaseEntity {
    private String cusCode;  // 业务编码，不是 @TableId
    // 仅写本表业务字段
}

// ❌ 禁止：手写 createTime/updateBy/deleted 且 implements Serializable 不继承 BaseEntity
public class SmsSendLog implements Serializable {
    @TableId(value = "sms_send_log_code", type = IdType.ASSIGN_ID)
    private String smsSendLogCode;
    private String createBy;
    private LocalDateTime createTime;
    // ...
}

BaseEntity（pub.module.common.model.po.BaseEntity）已包含：

字段说明
idMyBatis-Plus 主键（@TableId(type = IdType.ASSIGN_ID)），映射列 id
createBy / createTime / updateBy / updateTime审计字段
orgCode / version / seqNo组织、版本、序号
deleted逻辑删除（@TableLogic）

2.2 双主键模型（技术主键 + 业务主键）

层级字段注解说明
技术主键id在 BaseEntity，不要在子类重复 @TableId表 PRIMARY KEY (id)
业务主键xxxCode（如 userCode、smsTemplateCode）无 @TableId表列 xxx_code，对外关联、展示用语义编码
  • 表 DDL 中同时有 id 与 sms_template_code 时：MP 只认 id 为 PK；sms_template_code 是普通业务列。
  • 禁止把 sms_template_code 标成 @TableId，否则 id 列长期为空、与全库约定不一致。

2.3 Service 层配套（crud/service/impl）

参考 SysUserServiceImpl / DtMatchmakerServiceImpl：

  • getByCode(String code)：按业务编码查询（列名用 StrUtil.toUnderlineCase("xxxCode")）。
  • save：若业务编码允许为空则 IdUtil.getSnowflakeNextIdStr() 自动生成；若用户必填（如 loginSms）则校验唯一。
  • updateById：先 getByCode 取已有行，把 entity.setId(existing.getId()) 再 updateById。
  • 管理端按业务编码删除：提供 removeByBizCodes(Collection<String>)，不要对 xxxCode 调 removeByIds（那是删 id）。

2.4 参考实体（复制前先打开看）

  • pub.module.customer.crud.entity.Customer
  • pub.module.system.crud.entity.SysUser
  • pub.module.dating.crud.entity.DtMatchmaker
  • pub.module.sms.crud.entity.SmsTemplate（短信模块已对齐）

3. 模块与包结构（*-api / *-biz）

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

*-biz/                     # 实现层，仅 runner 聚合
├── biz/
│   ├── controller/{cus|mgt|pub}/
│   ├── service/
│   │   ├── impl/          # Api**Service 实现、SPI 实现
│   │   └── Spi**Service   # 仅模块内多实现（短信渠道、支付等）
├── crud/
│   ├── entity/            # 必须 extends BaseEntity
│   ├── mapper/
│   └── service/impl/      # MyBatis-Plus Service，可含 getByCode
└── Biz*AutoConfiguration.java

3.1 *-api 禁止依赖 *-biz（最高频架构错误）

Maven 与 Java 包两层约束：

层级规则
Maven*-api 的 pom.xml 只能依赖 common 或他域 *-api；禁止依赖同域或他域 *-biz
Java 包*-api 内 禁止 import 任意 crud.entity、crud.mapper、crud.service、biz.service.impl（含本模块 *-biz 包）

Api**Service 接口约定：

  • 入参 / 返回值 必须使用 *-api 内的 *DTO / *VO / *CodeEnum
  • 禁止在 Api**Service 中直接引用 crud.entity.* 作为参数或返回类型
// ❌ 禁止：api 模块 import biz/crud 实体
package pub.module.verification.api.service;
import pub.module.verification.crud.entity.VtAssetCertRecord;

public interface ApiVtAssetCertService {
    VtAssetCertRecord submitApply(...);  // 编译/架构均错误
}

// ✅ 正确：api 模块只用 api/dto
package pub.module.verification.api.service;
import pub.module.verification.api.dto.VtAssetCertRecordDTO;

public interface ApiVtAssetCertService {
    VtAssetCertRecordDTO submitApply(...);
}

*-biz 实现层：

  • Api**ServiceImpl 内部可使用 crud.entity，在边界处 BeanUtil.copyProperties 转为 DTO 再返回
  • biz/controller 管理端列表可直接返回 entity（同模块 HTTP 层）；用户端 / 跨模块调用走 Api**Service + DTO
  • 跨模块：只依赖他域 *-api 的 Api**Service、DTO；禁止 *-biz 依赖其他域 *-biz，禁止 import 他域 crud.*
  • 模块内多实现：Spi**Service + 注册表路由（如 SmsProviderRegistry）

参考：SysUserCancellationApplyDTO + ApiSysUserCancellationService（system-api 不引用 system-biz 实体）。

4. 命名与字典（摘要）

  • 目录式命名：表前缀 + 字段名（如 smsTemplateCode、cusName、distUserCode），避免裸 code。
  • 省略系统层：目录式命名只写到当前表前缀 + 业务字段即可，不要把模块/实体类名（如 SysUser、Sys）再叠进字段名。关联用户时存的是 userCode，字段应命名为 xxxUserCode（如 distUserCode、distPayerUserCode），禁止 xxxSysUserCode。
  • 历史遗留：trade 模块中 tdOdSysUserCode 等为旧写法，新代码勿模仿；以 Customer、SysUser 实体及 distribution 域内 dist*UserCode 为准。
  • 字典/枚举字段：以 Code 结尾；枚举放 *-api/constants，类名 XxxCodeEnum。
  • *StatusCode：仅 0/1（否/是），null 视同否；禁止放「审核中」等流程态。
  • *ProcessCode：多步流程（0 待提交、1 审核中…）；终态通过时同步对应 *StatusCode = 1。
  • 已废弃：通用字典表 / spring-boot-starter-dict；勿新增字典 HTTP 依赖。

5. 管理端 Vue（tg-vue）

  • 列表删除：优先传 row.id（技术主键）；若接口约定按业务编码删，后端用 removeByBizCodes，前端 primaryKey 可为 xxxCode。
  • useCrud 默认 primaryKey: 'id'；与 Customer 模块保持一致。
  • 接口路径：/mgt/{域}/{资源}/list|add|edit|delete。

6. 新增表 / 新模块检查清单

生成代码后自检：

6.1 跨模块 MQ 发布（硬性）

  • 须在事务提交后投递：mqPublisher.publishAfterCommit(consumerClass, payload)。
  • 工具类：pub.module.common.messaging.TransactionAfterCommit（非 MQ 副作用同理）。
  • 禁止在 @Transactional 写库方法内直接 mqPublisher.publish（无事务的只读/回调场景除外）。

7. 为何会出现「未继承 BaseEntity」的代码？

常见原因（短信模块 SmsSendLog / SmsTemplate / SmsTencentConfig 即属此类）：

  1. 未加载规范：会话未引用 README.md / AGENTS.md，模型按通用 MyBatis 样板生成「单 @TableId 实体」。
  2. 子模块 README 过简：spring-boot-starter-sms/README.md 仅描述 SPI，未写明实体必须继承 BaseEntity（已在本次补充引用本文）。
  3. 历史反例干扰：仓库内仍有少量旧代码（如 DistRule、NpConfig）未继承 BaseEntity，AI 可能误学；以 Customer / SysUser 为准。
  4. v3.6 移除代码生成器：README 写明改由 AI 手写，若缺少本文档级检查清单，易漏掉 BaseEntity。

8. 认证与会话（common）

  • 短时 KV：pub.module.common.cache.TgEphemeralCache（单区域 tgEphemeral，业务用 namespace::key，禁止自建 sysVerification 等区域名）。
  • 登录会话：AuthSessionStore（auth:session）；登录写 AuthSessionSnapshot（含权限列表），TgJwtAuthenticationFilter 只读缓存、不查库。
  • 权限变更后需用户重新登录或调用登出踢会话。
  • Security / JWT / Actuator Basic 在 spring-boot-starter-common 的 pub.module.common.security.*。

9. 相关文件路径

用途路径
基础实体spring-boot-starter-common/.../BaseEntity.java
架构与 MQCROSS_MODULE_COLLABORATION.md
架构测试mvn -pl spring-boot-starter-architecture-tests -am test（含 BaseEntity / Api 契约 / 模块边界）
MQ 提交后发布common/.../MqPublisher.publishAfterCommit
CI.github/workflows/backend-ci.yml
运维 / Actuator运维说明（生产禁止公网暴露 /actuator/**）
管理端前端tg-vue/

文档版本随仓库演进；与 README.md 冲突时以实际 pom 与参考实体为准。

welcome to tg.
copyright@module.pub