Skills — 设计器表单自动生成

1. 功能介绍

jeecg-desform 是 Claude Code 的 AI Skill，能够将自然语言的表单需求描述自动转换为 JeecgBoot 设计器表单（desform），完成从需求解析 → JSON 生成 → API 创建的全流程自动化。

核心能力：

用自然语言描述表单需求，AI 自动推导控件类型和配置
自动生成完整的 desformDesignJson（表单设计 JSON）
通过 API 自动创建表单并保存设计
支持 30+ 种控件类型（文本、日期、选择、上传、子表、关联、公式等）
支持系统字典和静态选项两种数据源
支持编辑已有表单

不确定该用哪个 Skill？请查看 AI Skills 技能清单。

2. 前置条件

使用前需要准备两个信息：

信息	获取方式	示例
API 地址	JeecgBoot 后端服务地址	`https://boot3.jeecg.com/jeecgboot`
X-Access-Token	浏览器 F12 → Network → 任意请求的 Request Headers	`eyJhbGciOiJIUzI1NiIs...`

获取 Token 步骤：

登录 JeecgBoot 后台管理系统
按 F12 打开浏览器开发者工具
切换到 Network（网络）面板
点击页面上任意操作触发一个请求
点击该请求，在 Request Headers 中找到 X-Access-Token 的值并复制

3. 使用方式

在 Claude Code 中直接用自然语言描述需求即可。以下是触发关键词：

AI设计表单、AI生成表单、自动创建表单、智能表单、
生成一个表单、帮我设计表单、创建表单、新建表单、做一个表单

4. 实战示例：创建请假申请表

4.1 第一步：描述需求

帮我设计一个请假申请表单，包含：
- 姓名（必填，标题字段）
- 请假类型（下拉选择：事假/病假/年假/调休）
- 开始日期和结束日期
- 请假天数（整数，必填）
- 请假原因（多行文本）
- 附件（文件上传）

4.2 第二步：AI 展示摘要

AI 会根据描述自动推导控件类型，展示摘要等待确认：

## 表单摘要

- 表单名称：请假申请
- 表单编码：qing_jia_shen_qing
- 目标环境：https://boot3.jeecg.com/jeecgboot

### 字段列表

| 序号 | 字段名称  | 控件类型              | 必填 | 说明                      |
|------|----------|----------------------|------|--------------------------|
| 1    | 姓名      | input (单行文本)      | 是   | 标题字段                   |
| 2    | 请假类型  | select (下拉选择)     | 是   | 选项：事假/病假/年假/调休   |
| 3    | 开始日期  | date (日期)           | 是   |                          |
| 4    | 结束日期  | date (日期)           | 是   |                          |
| 5    | 请假天数  | integer (整数)        | 是   |                          |
| 6    | 请假原因  | textarea (多行文本)   | 否   |                          |
| 7    | 附件      | file-upload (文件上传) | 否   |                          |

确认以上信息正确？(y/n)

4.3 第三步：提供 Token 并确认

确认。
API地址：https://boot3.jeecg.com/jeecgboot
x-access-token: eyJhbGciOiJIUzI1NiIs...

4.4 第四步：AI 自动执行

AI 会自动执行三步操作：

POST /desform/add → 创建空表单 ✓
GET /desform/queryByCode → 获取表单 ID 和 updateCount ✓
PUT /desform/edit → 保存表单设计 JSON ✓

技术说明： POST /desform/add 返回的 result 为 null，这是正常行为。AI 会自动通过 queryByCode 查询获取表单 ID。

4.5 第五步：查看结果

## 表单创建成功

- 表单ID：abc123def456
- 表单名称：请假申请
- 表单编码：qing_jia_shen_qing
- 字段数量：7 个
- 目标环境：https://boot3.jeecg.com/jeecgboot

请在表单设计器中查看：
JeecgBoot 后台 → 表单设计器 → 找到该表单

AI 还会输出菜单 SQL（可选执行），将表单加入系统左侧菜单：

INSERT INTO sys_permission(id, parent_id, name, url, component, component_name, ...)
VALUES ('{menuId}', NULL, '请假申请',
  '/online/desform/list/qing_jia_shen_qing',
  'super/online/desform/auto/AutoDesformDataList',
  'AutoDesformDataList', ...);

创建成功后，可以在 JeecgBoot 后台的表单设计器中看到该表单，支持：

拖拽调整字段位置和布局
可视化修改控件属性
预览表单效果
绑定流程作为审批表单

5. 支持的控件类型

5.1 基础控件

用户描述关键词	控件类型	说明
名称/标题/姓名/文本	`input`	单行文本输入
描述/备注/原因/多行	`textarea`	多行文本输入
数量/数字/金额(无单位)	`number`	数字输入
整数/个数/天数	`integer`	整数输入
金额/费用/价格	`money`	金额（带元单位）
手机/电话/手机号	`phone`	手机号输入
邮箱/Email	`email`	邮箱输入

5.2 选择控件

用户描述关键词	控件类型	说明
单选/性别/是否/状态	`radio`	单选框组
多选/标签/兴趣	`checkbox`	多选框组
下拉/选择/类型/类别	`select`	下拉选择框
开关/启用/是否激活	`switch`	开关切换
评分/星级/打分	`rate`	评分组件
颜色	`color`	颜色选择器
滑块/进度/百分比	`slider`	滑块组件

5.3 日期时间控件

用户描述关键词	控件类型	说明
日期/生日/入职日期	`date`	日期选择器
时间/几点	`time`	时间选择器

5.4 上传控件

用户描述关键词	控件类型	说明
图片/照片/头像	`imgupload`	图片上传
附件/文件/上传	`file-upload`	文件上传

5.5 高级控件

用户描述关键词	控件类型	说明
富文本/HTML内容	`editor`	富文本编辑器
Markdown	`markdown`	Markdown 编辑器
省市/地区/地址选择	`area-linkage`	省市级联动
地图/位置	`map`	地图组件
定位/GPS	`location`	定位组件
条码/二维码	`barcode`	条码组件
自动编号/流水号	`auto-number`	自动编号
手写签名/签字	`hand-sign`	手写签名
大写金额/中文大写	`capital-money`	金额转大写

5.6 组织架构控件

用户描述关键词	控件类型	说明
选人/审批人/负责人	`select-user`	用户选择组件
部门/选部门	`select-depart`	部门选择组件
岗位/选岗位	`select-depart-post`	岗位选择组件
分类树/树选择	`select-tree`	下拉树组件

5.7 关联和计算控件

用户描述关键词	控件类型	说明
表字典/弹窗选择	`table-dict`	表字典（popup 或模糊查询）
关联记录/引用	`link-record`	关联其他表单的记录
他表字段/自动填充	`link-field`	显示关联记录的字段值
公式/自动计算	`formula`	公式计算（求和/均值/自定义）
文本组合	`text-compose`	多字段值拼接显示

5.8 布局和子表

用户描述关键词	控件类型	说明
分隔符/分区	`divider`	表单区域分隔线
子表/明细/清单	`sub-table-design`	子表（行内可编辑明细表）

6. 字典数据源

对于 radio、select、checkbox 控件，支持两种数据源方式：

6.1 静态选项（默认）

用户直接描述选项值：

请假类型（下拉选择：事假/病假/年假/调休）

AI 自动生成静态选项配置。

6.2 系统字典

用户提到字典编码：

性别（单选，使用字典 sex）
优先级（下拉，字典 priority）

AI 自动配置字典数据源，运行时从系统字典表动态加载选项。

常用 JeecgBoot 系统字典：

字典编码	说明	典型值
`sex`	性别	1=男, 2=女
`priority`	优先级	L=低, M=中, H=高
`valid_status`	有效状态	0=无效, 1=有效
`yn`	是否	Y=是, N=否

7. 更多使用场景

7.1 带子表的表单

创建一个采购申请表单：
- 申请人（选人控件）
- 申请日期（日期）
- 采购明细子表：
  - 物料名称
  - 规格
  - 数量（整数）
  - 单价（金额）
  - 小计（公式：数量×单价）

AI 会自动创建 sub-table-design 子表控件，子表内嵌入各字段控件。

7.2 带关联记录的表单

创建一个报销表单：
- 关联采购申请（关联记录，引用采购申请表单）
- 采购金额（他表字段，自动填充关联记录的总金额）
- 报销金额（金额，必填）
- 报销说明（多行文本）

AI 会自动配置 link-record 关联控件和 link-field 他表字段控件。

7.3 带分区布局的表单

创建员工信息表单：
--- 基本信息 ---
- 姓名、性别、手机号
--- 工作信息 ---
- 部门（选部门）、岗位、入职日期
--- 其他 ---
- 备注、附件

AI 会使用 divider 分隔线控件划分表单区域。

7.4 编辑已有表单

修改表单 qing_jia_shen_qing，加一个"审批意见"多行文本字段

AI 会查询已有表单设计 JSON，在现有字段基础上追加新字段，然后调用 PUT /desform/edit 保存。

8. 涉及的 API 接口

接口	方法	路径	说明
创建表单	POST	`/desform/add`	创建空表单（返回 result 为 null）
查询表单	GET	`/desform/queryByCode?desformCode={code}`	按编码查询表单详情
保存设计	PUT	`/desform/edit`	保存表单设计 JSON（需传 updateCount）

API 调用注意事项：

POST /desform/add 返回的 result 为 null，需要再调用 queryByCode 获取表单 ID
PUT /desform/edit 的 updateCount 必须传当前数据库中的值（不要 +1），后端会自动递增
Windows 环境下必须使用 Python 调用 API（不要用 curl），避免中文编码问题

9. 菜单 SQL 模板

将设计器表单配置为系统菜单，使用户可以在左侧菜单中直接访问表单的数据列表页。

INSERT INTO sys_permission(
    id, parent_id, name, url, component, component_name, redirect,
    menu_type, perms, perms_type, sort_no, always_show, icon,
    is_route, is_leaf, keep_alive, hidden, hide_tab,
    description, status, del_flag, rule_flag,
    create_by, create_time, update_by, update_time, internal_or_external
) VALUES (
    '{menuId}',          -- 菜单ID
    NULL,                -- 父菜单ID（NULL=一级菜单）
    '{desformName}',     -- 菜单名称（表单名称）
    '/online/desform/list/{desformCode}',  -- 路由URL（固定格式，用表单编码）
    'super/online/desform/auto/AutoDesformDataList',  -- 组件路径（固定值）
    'AutoDesformDataList',  -- 组件名（固定值）
    NULL, 0, NULL, '1', 0.00, 0, NULL,
    0, 1, 0, 0, 0, NULL, '1', 0, 0,
    'admin', now(), NULL, NULL, 0
);

与 Online 表单菜单 SQL 的区别：

字段	设计器表单 (desform)	Online 表单
url	`/online/desform/list/{desformCode}`	`/online/cgformList/{headId}`
component	`super/online/desform/auto/AutoDesformDataList`	`1`
component_name	`AutoDesformDataList`	`OnlineAutoList`
路由标识	使用表单编码（desformCode）	使用配置ID（headId）

10. 常见问题

「该 code 已存在」怎么办？

表单编码重复。AI 会自动先查询是否已存在，如果存在则直接更新设计。

「当前版本已过时，请刷新重试」怎么办？

updateCount 传值错误。必须传 queryByCode 查到的当前值，不要手动 +1。

表单创建成功但看不到字段？

检查 desformDesignJson 是否正确保存到 edit 接口。add 只创建空表单，设计 JSON 需要通过 edit 单独保存。

设计器表单和 Online 表单有什么区别？

特性	设计器表单 (desform)	Online 表单
存储方式	JSON 配置	数据库元数据
渲染方式	前端 JSON 渲染引擎	后端自动生成 CRUD 页面
适用场景	数据采集、审批表单、复杂布局	管理后台标准 CRUD
是否建表	自动建表（desform_data 存储）	需要同步数据库建表
流程集成	天然支持绑定工作流	需要额外配置
控件丰富度	30+ 种（含签名、公式、关联等）	20+ 种（侧重数据展示）

1. 功能介绍​

2. 前置条件​

3. 使用方式​

4. 实战示例：创建请假申请表​

4.1 第一步：描述需求​

4.2 第二步：AI 展示摘要​

4.3 第三步：提供 Token 并确认​

4.4 第四步：AI 自动执行​

4.5 第五步：查看结果​

5. 支持的控件类型​

5.1 基础控件​

5.2 选择控件​

5.3 日期时间控件​

5.4 上传控件​

5.5 高级控件​

5.6 组织架构控件​

5.7 关联和计算控件​

5.8 布局和子表​

6. 字典数据源​

6.1 静态选项（默认）​

6.2 系统字典​

7. 更多使用场景​

7.1 带子表的表单​

7.2 带关联记录的表单​

7.3 带分区布局的表单​

7.4 编辑已有表单​

8. 涉及的 API 接口​

9. 菜单 SQL 模板​

10. 常见问题​

「该 code 已存在」怎么办？​

「当前版本已过时，请刷新重试」怎么办？​

表单创建成功但看不到字段？​

设计器表单和 Online 表单有什么区别？​