# 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. 重启后端

```bash
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 选择"否"即可