qhmes/.trae/skills/jeecg-codegen/docs/skill-usage-guide.md

jeecg-codegen Skills 使用指南

通过 Claude Code 以自然语言描述业务需求，自动生成 JeecgBoot 全套 CRUD 代码（后端 Java + 前端 Vue3 + 建表 SQL + 菜单 SQL）。 无需预建表结构，AI 根据语义自动推导表结构、字段类型与前端控件；也支持基于已有表或多表关联生成代码。覆盖单表、树表、一对多等模型，可一次性生成整个业务模块。主键策略自适应，字典字段自动匹配系统已有编码——不只是模板填充，而是从业务需求到可运行代码的端到端生成。

与传统代码生成器的区别

• 无需预建表结构：只需用自然语言描述业务需求，AI 即可自动推导出表结构与字段属性，省去手动建表的前置工作
• 表结构驱动同样支持：也可以直接基于已有的数据库表或多表关联关系生成代码，兼容传统代码生成器的使用习惯
• 模块级批量生成：支持一次性生成整个业务模块的全部代码文件（涵盖多张表、多个功能点），而非逐表逐模型地单独生成
• 主键策略自适应：AI 会参照项目中已有表的主键定义，自动选用合适的 MyBatis-Plus 主键策略，不局限于 String 类型的雪花 ID
• 字典智能匹配：自动读取系统字典表（sys_dict + sys_dict_item），为字段精准匹配已有的字典编码，免去手动查找和指定的繁琐步骤
• 代码自动归位：生成的前后端代码自动落入项目对应目录，建表与菜单 SQL 自动追加至 Flyway 升级脚本，无需手动搬运，生成即就绪

---

触发方式

在 Claude Code 对话中，用自然语言描述你要创建的功能，包含以下任意关键词即可自动触发：

代码生成 / 生成代码 / 创建模块 / 新增功能 / 建表 / 加字段 / 增加字段 / 新增字段 / 修改字段 / 删除字段

示例用法

1. 一句话描述（最简方式）

帮我生成一个商品管理模块，包含商品名称、价格、库存、状态、图片、描述

AI 会自动推导：表名 biz_goods、字段类型（价格→BigDecimal、库存→Integer、图片→JImageUpload 等）。

2. 指定表名和字典

创建一个订单管理功能：
- 表名 biz_order
- 字段：订单编号、客户名称、下单日期、金额、状态（待付款/已付款/已发货/已完成）、备注
- 状态用字典 order_status

3. 树表（带层级关系）

建一个部门分类的树表，包含分类名称和分类编码

提到"分类/层级/树/上下级"等关键词，AI 自动识别为树表模式。

4. 一对多（主子表）

生成一个采购单模块，主表是采购单（单号、供应商、日期、总金额），
子表是采购明细（商品名、数量、单价、小计）

提到"主子表/明细/一对多"等关键词，AI 自动识别为一对多模式。

5. 指定后端模块

在 jeecg-module-demo 模块下生成一个公告管理，包含标题、内容（富文本）、发布时间、状态

6. 已有表反向生成（给表名即可）

生成 tmp_tables 这个表的代码

AI 会自动连接数据库查询 DDL，解析主键类型、全部字段、系统字段，然后生成匹配的代码。无需手动描述字段。

7. 增量修改（给已有模块加/改/删字段）

给表信息管理加一个备注字段

给 tmp_tables 增加两个字段：排序号和状态（启用/停用）

把商品管理的价格字段从 int 改成 decimal

删除商品管理的描述字段

AI 会自动定位已生成的全部代码文件（Entity、data.ts、Form.vue 等），精确修改每个文件，并生成 ALTER TABLE 的 Flyway SQL，无需重新生成整个模块。

交互流程

全量生成流程

Step 0  判断操作类型：全量生成 or 增量修改？
        ↓
Step 1  解析需求，判断场景：
        · 场景A — 已有表 → 查数据库获取 DDL，自动解析字段
        · 场景B — 新建表 → 从自然语言推导表结构
        ↓
Step 2  询问 4 个选项（都有默认值，说"确认"即可）：
        ① 后端模块 — 默认 jeecg-module-system/jeecg-system-biz
        ② 前端风格 — vue3（封装风格）或 vue3Native（原生风格）
        ③ 前端目录 — 默认按 entityPackage 值
        ④ 是否读取系统字典 — 默认是，自动匹配已有字典编码
        ↓
Step 3  展示表结构摘要（含匹配到的字典），等待确认
        ↓
Step 4  确认后，自动生成全部文件写入项目目录
        ↓
Step 5  输出生成文件清单 + 后续操作说明

增量修改流程

Step 0  识别增量修改关键词（加字段/删字段/修改字段/给XX加...）
        ↓
Step 1  定位目标模块，扫描并读取已有代码文件
        （Entity.java / *.data.ts / *List.vue / *Modal.vue / *Form.vue）
        ↓
Step 2  解析已有字段，推导新字段属性
        ↓
Step 3  展示修改摘要（每个文件的具体变更内容），等待确认
        ↓
Step 4  确认后，用 Edit 精确修改每个文件 + 生成 ALTER TABLE SQL
        ↓
Step 5  输出修改文件清单 + 后续操作说明

生成产物

单表模式（11 个文件）

类别	文件	说明
后端	Entity.java	实体类，含 MyBatis-Plus / AutoPoi / Dict 注解
	Controller.java	REST 控制器，继承 JeecgController，含权限注解
	IService.java	Service 接口
	ServiceImpl.java	Service 实现
	Mapper.java	MyBatis Mapper 接口
	Mapper.xml	MyBatis XML 映射
前端	*.api.ts	API 接口定义（list/save/edit/delete/export/import）
	*.data.ts	列定义 + 查询表单 + 编辑表单 Schema
	*List.vue	列表页面（表格 + 查询 + 操作按钮）
	*Modal.vue	编辑弹窗
	*Form.vue	表单组件（仅 vue3Native 风格）
SQL	V*__.sql	Flyway 迁移：建表DDL + 菜单 + 7个按钮权限 + 角色授权

树表模式

在单表基础上增加：

• Entity 额外字段：pid（父节点）、has_child（是否有子节点）
• Controller 额外接口：rootList、childList、getChildListBatch
• Service 额外方法：树节点的增删改逻辑
• 前端额外接口：树数据加载、子节点查询

一对多模式

在单表基础上增加：

• 子表完整的 Entity / Mapper / Service 各一套
• 主表 Service 包含联合保存/更新/删除
• Page VO 用于 Excel 主子表导入导出
• 前端 Tab 页展示子表数据

两种前端风格

	vue3 封装风格	vue3Native 原生风格
表单	BasicForm + FormSchema 配置驱动	a-form + a-form-item 模板直接写控件
弹窗	BasicModal + useModal Hook	JModal + ref + defineExpose
表格	BasicTable + useTable + formConfig 内置查询	BasicTable + 手写查询表单区域
数据文件	columns + searchFormSchema + formSchema	columns + superQuerySchema（表单在模板中）
优点	代码量少，配置化，统一风格	灵活度高，可深度定制交互
适合	标准 CRUD 页面	需要复杂交互或自定义布局的场景

智能字段推导

AI 根据字段语义自动推导类型和控件：

语义关键词	数据库类型	Java 类型	前端控件
名称/标题/编码	varchar(100)	String	Input / a-input
金额/价格/费用	decimal(10,2)	BigDecimal	InputNumber / a-input-number
数量/个数	int	Integer	InputNumber / a-input-number
状态/类型/级别	varchar(10)	String	JDictSelectTag
是否/开关	varchar(2)	String	Switch / a-switch
日期/生日	date	Date	DatePicker / a-date-picker
时间/日期时间	datetime	Date	DatePicker(showTime)
备注/描述/说明	text	String	InputTextArea / a-textarea
内容/富文本	text	String	JEditor
图片/头像/照片	varchar(1000)	String	JImageUpload
文件/附件	varchar(1000)	String	JUpload
用户/负责人	varchar(32)	String	JSelectUserByDept
部门/组织	varchar(32)	String	JSelectDept
排序/序号	int	Integer	InputNumber / a-input-number

当然，你也可以在描述中明确指定字段类型，AI 会优先使用你的指定。

已有表的 DB 类型→控件自动映射

对于已有表场景，如果字段没有注释，AI 根据数据库列类型自动推导前端控件：

DB 列类型	Java 类型	默认前端控件
varchar(n) n<=200	String	Input
varchar(n) n>200	String	InputTextArea
text / longtext	String	InputTextArea
int / tinyint	Integer	InputNumber
bigint	Long	InputNumber
decimal / double / float	BigDecimal	InputNumber
date	Date	DatePicker
datetime / timestamp	Date	DatePicker(showTime)

字典智能匹配

生成代码时，AI 可选择读取系统字典表（sys_dict + sys_dict_item），自动为字段匹配已有的字典编码。

匹配优先级：

1. 用户明确指定 — "状态用字典 order_status"，直接使用
2. 字段名精确匹配 — 字段名 status 与字典编码 status 一致
3. 语义关键词匹配 — 字段注释含"状态"，搜索字典名称含"状态"的字典
4. 不匹配 — 找不到合适字典时，不使用字典注解，按普通 Input 处理

效果示例：

假设系统中已有字典 order_status（待付款=0, 已付款=1, 已完成=2），当你描述字段"订单状态"时：

位置	自动生成内容
Entity.java	@Dict(dicCode = "order_status")
columns	dataIndex: 'orderStatus_dictText'
formSchema	component: 'JDictSelectTag', componentProps: { dictCode: 'order_status' }
searchFormSchema	component: 'JDictSelectTag', componentProps: { dictCode: 'order_status' }

在 Step 3 表结构摘要中会展示匹配结果，确认前可以修改或取消字典关联。

已有表反向生成

给定表名时，AI 会自动连接数据库获取精确表结构：

1. 查询 DDL：SHOW CREATE TABLE 表名 获取完整建表语句
2. 查询字段详情：从 information_schema.COLUMNS 获取每个字段的类型、注释、是否可空、默认值、主键标识
3. 解析主键策略：根据主键列类型和是否 AUTO_INCREMENT 选择 MyBatis-Plus 注解
4. 识别系统字段：检查 create_by/create_time/update_by/update_time/sys_org_code 是否存在
5. 推导前端控件：优先用字段注释语义匹配，无注释时按 DB 类型映射

数据库连接信息：mysql -h127.0.0.1 -P3306 -uroot -proot jeecgboot3（配置文件：application-dev.yml）

增量修改详解

支持的操作

操作	说明	影响的文件
加字段	在所有文件中追加新字段定义	Entity + data.ts + Form.vue(Native) + ALTER TABLE SQL
删字段	从所有文件中移除指定字段	Entity + data.ts + Form.vue(Native) + DROP COLUMN SQL
改字段	修改字段类型/控件/注释等	Entity + data.ts + Form.vue(Native) + MODIFY COLUMN SQL

修改位置清单

每次增量修改，AI 会精确定位并修改以下位置：

1. Entity.java — 字段声明 + 注解（@Excel、@Dict、@Schema、@JsonFormat 等）+ 必要的 import
2. *.data.ts — columns 列定义 + formSchema 表单项 + searchFormSchema 查询条件（如需） + superQuerySchema（如存在）
3. *Form.vue（仅 vue3Native）— <a-form-item> 控件 + formData 初始值
4. Flyway SQL — ALTER TABLE ADD/DROP/MODIFY COLUMN 语句

Flyway 版本号规则

生成 Flyway SQL 前自动检查已有版本号，递增避免冲突：

• 版本命名：V{YYYYMMDD}_{序号}__{描述}.sql
• 检查当天是否已有文件（如 V20260311_1__xxx.sql）
• 如果有，序号递增（V20260311_2__xxx.sql）
• 如果没有，从 _1 开始
• 菜单 SQL 的 ID 使用 13 位毫秒级真实时间戳（date +%s%3N），确保全局唯一

主键策略自适应

AI 会根据已有表的 DDL 自动选择正确的主键策略：

表DDL中的主键定义	Java类型	MyBatis-Plus 注解
int AUTO_INCREMENT	Integer	@TableId(type = IdType.AUTO)
bigint AUTO_INCREMENT	Long	@TableId(type = IdType.AUTO)
varchar(36) 无自增	String	@TableId(type = IdType.ASSIGN_ID)
bigint 无自增	Long	@TableId(type = IdType.ASSIGN_ID)

新建表时默认使用 JeecgBoot 标准的 varchar(36) + ASSIGN_ID。

注意： 当主键为 Integer/Long 类型时，Controller 中 delete 和 queryById 的参数类型也要对应调整，deleteBatch 需要做类型转换。

系统字段智能判断

对于已有表，AI 会检查表结构，只生成表中实际存在的系统字段：

字段	不存在时
create_by / create_time	不生成对应 Java 属性
update_by / update_time	不生成对应 Java 属性
sys_org_code	不生成对应 Java 属性

对于新建表（自然语言描述需求），默认添加全部系统字段。

树表额外字段：pid、has_child（同样需检查是否实际存在）。

生成后的操作

1. 执行 SQL

生成的 Flyway SQL 文件位于：

jeecg-module-system/jeecg-system-start/src/main/resources/flyway/sql/mysql/

两种方式：

• 自动执行：重启后端时 Flyway 自动执行
• 手动执行：在数据库中手动执行 SQL 文件内容

2. 重启后端

cd jeecg-boot-framework-2026
mvn spring-boot:run -pl jeecg-module-system/jeecg-system-start

3. 刷新前端

开发服务器（pnpm dev）会自动热更新，无需重启。

4. 访问功能

登录系统后，新菜单已自动添加（默认授权给 admin 角色），直接可见可用。

文件路径说明

类别	路径
后端代码	jeecg-boot-framework-2026/{module}/src/main/java/org/jeecg/modules/{package}/
前端代码	jeecgboot-vue3-2026/src/views/{viewDir}/
Flyway SQL	jeecg-boot-framework-2026/jeecg-module-system/jeecg-system-start/src/main/resources/flyway/sql/mysql/

注意事项

1. 每次生成/修改前会展示摘要等你确认，不会直接写文件，放心使用
2. 已有表按实际结构生成，不会盲目添加不存在的字段
3. 权限编码规则：{entityPackage}:{tableName}:add/edit/delete/deleteBatch/exportXls/importExcel
4. 如果后端模块目录不存在，AI 会提示你先创建 Maven 模块结构
5. 生成的代码可以二次修改，和手写代码完全一样，没有任何框架锁定
6. 增量修改只改动必要的文件和位置，不会影响你手动修改过的其他代码
7. 字典匹配可选，不想自动匹配字典时在 Step 2 选择"否"即可