JeecgBoot Online 表单 AI 自动生成器
将自然语言的表单需求描述转换为 Online 表单配置 JSON，并通过 API 在 JeecgBoot 系统中自动创建/编辑表单。
重要：本 skill 处理「Online 表单」（元数据驱动，运行时 CRUD），不涉及「设计器表单」（desform）。两者是完全独立的表单体系。
选择正确的技能
| 用户需求 | 应使用的技能 |
|---|---|
| 元数据驱动的表/表单配置（字段定义、控件类型、数据库建表） | 本技能 (jeecg-onlform) |
| 拖拽式可视化表单设计（自由布局、表单设计器） | jeecg-desform |
| SQL查询结果以列表展示 | jeecg-onlreport |
| SQL查询结果以图形展示（柱状图/饼图/折线图） | jeecg-onlchart |
| 复杂Excel样式报表（打印、分组、循环） | jimureport |
目录结构
scripts/
├── onlform_creator.py # 表单创建/编辑（单表/主子表/树表）
├── onlform_jimureport.py # 积木报表集成（创建/删除报表并关联）
├── onlform_enhance.py # JS/Java/SQL增强 + 自定义按钮
├── onlform_auth.py # 权限配置（字段/按钮/数据权限）
├── onlform_data.py # 数据 CRUD（增删改查/树数据/导出CSV）
└── onlform_menu.py # 菜单挂载 + 路由缓存 + 角色授权
templates/ # ⚡ 可直接复用的 JSON 模板（优先读取，不要现场设计）
└── all_controls_master_sub.json # 全控件主子表（26种控件，主表+一对多+一对一）
# ⚠️ 模板内的表名仅为占位符，创建时必须按业务语义自定义表名，不能原样照用
references/
├── onlform-field-types.md # 字段类型/控件/字典/校验/默认值/扩展配置
├── onlform-widget-types.md # 控件速查表（fieldShowType 完整清单）
├── onlform-head-field-types.md # head 级字段说明（tableType/themeTemplate 等）
├── onlform-full-widget-template.md # 26种控件配置速查（dictTable/dictField/fieldExtendJson）
├── onlform-enhance-js.md # JS增强参考（onlChange/loaded/列表拦截/API，~310行）
├── onlform-enhance-java.md # Java增强参考 + 实战案例（~140行）
├── onlform-enhance-misc.md # SQL增强/自定义按钮/fieldHref/实战（~130行）
├── onlform-auth.md # 权限配置（字段/按钮/数据权限 API）
├── onlform-data-crud.md # 数据 CRUD API + 存储格式
├── onlform-jimureport.md # 积木报表集成 8 步流程
├── onlform-misc.md # 杂项：表类型/布局/BPM/视图/错误处理
├── onlform-api-reference.md # 完整 JSON 数据结构和字段枚举
└── onlform-route-cache.md # 路由缓存配置（动态/静态路由、组件名称映射）
前置条件
用户必须提供以下信息（或由 AI 引导确认）：
- API 地址：JeecgBoot 后端地址（如
https://boot3.jeecg.com/jeecgboot） - X-Access-Token：JWT 登录令牌（从浏览器 F12 获取）
执行效率规则（减少无谓等待）
所有 HTTP 调用必须遵循，否则用户会感到响应明显变慢。本节为强制要求，违反会直接被用户吐槽"太慢了"。
0. Windows 环境下必须用 PowerShell tool 跑 python（最容易踩的坑）
现象：Windows 的 Bash tool 会把 python / python -c / skill 脚本当作长命令自动 run_in_background，tool 立即返回一个 background ID，真正的执行输出要等系统通知才到——把毫秒级调用放大到数秒，用户会立即感到"卡"。
规则：
- Windows（platform=win32） → 所有 python 调用（skill 脚本 +
python -c探测）都用 PowerShell tool，不要用 Bash tool。 - Linux / macOS（platform=linux/darwin） → 用 Bash tool 即可，python 不会被后台化。
curl在任何平台都不用——跨平台不一致，且 Windows Bash 下同样被后台化。
Windows 正确示例：
PowerShell: python C:/path/to/onlform_creator.py --api-base http://localhost:8080 --token xxx --config config.json
PowerShell: python -X utf8 -c "import urllib.request as u, json; r=u.urlopen(...); print(r.read().decode())"
Windows 错误示例（会被后台化）：
Bash: python onlform_creator.py ... ← 会返回 "Command running in background"
Bash: python -c "..." ← 同上
Bash: curl -X POST ... ← 同上
历史教训：本 skill 早期版本错误地声称"Python 在所有 shell 下都同步返回"——实测 Windows Bash tool 对 python 也会后台化。曾因此被用户连续吐槽"执行太慢了"。
Windows 中文编码规则（
python -c必须加-X utf8）： PowerShell 默认编码为 UTF-16 LE，python -c "..."inline 代码中含中文字面量时，shell 传参过程会乱码，导致SyntaxError: unterminated string literal。
- 解法：始终用
python -X utf8 -c "..."而不是python -c "..."- 含中文的复杂逻辑：写入临时
.py文件再执行，彻底避免 inline 中文- 结果含中文的 print：在 inline 脚本开头加
import sys; sys.stdout.reconfigure(encoding='utf-8')
1. 并行读取 reference 文件，不要串行
需要多个 reference 文件时，在同一条消息中并发发出所有 Read 调用，不要一个读完再读下一个。
// ✅ 正确：一条消息同时 Read 多个文件（并发）
Read(onlform-field-types.md) + Read(onlform-master-detail-checklist.md) + Read(onlform-enhance-js.md)
// ❌ 错误：串行读取
Read(field-types) → 等结果 → Read(checklist) → 等结果 → Read(enhance)
常用并发组合：建表 → 同时读
field-types.md+master-detail-checklist.md；JS增强 → 同时读enhance.md（若已在建表时读过则跳过）。
2（原1）. 优先用 skill 自带的 Python 脚本，不要自己另起 HTTP 封装
skill 已提供 onlform_creator.py / onlform_jimureport.py 等脚本，它们封装了鉴权、重试、head 解析、主子表关联等细节。需要一次性 HTTP 探测再用 python -c。
3（原2）. 跳过非必要前置检查，直接跑脚本
-
表名查重：仅在"用户暗示要复用已有表 / 表名看上去像已有资源"时才查。普通新建场景直接跑
onlform_creator.py——遇重名接口会返回明确错误，预查反而增加一次往返。onlform_creator.py已内置自动加_1/_2后缀重试，主表冲突无需手动干预。 -
字典存在性：以下系统内置字典直接使用，禁止发 API 查询，值已固化：
字典编码 值 → 含义 控件类型 yn1=是 /0=否list / radio / switch sex1=男 /2=女list / radio valid_status1=有效 /0=无效list / radio priorityL=低 /M=中 /H=高list / radio bpm_status1=待提交 /2=审批中 /3=审批通过 /4=审批拒绝list 仅在字典编码明显是业务自定义且不确定是否创建过时才发
sys/dict/list查询。 -
❌ 严禁拼造
/sys/dict/queryDictItemsByCode/{code}这种 RESTful 风格的字典查询路径：后端根本没有这个端点，会返回"路径不存在，请检查路径是否正确"。- 正确的「按 dictCode 直接拿字典项」接口是
GET /sys/api/queryDictItemsByCode?code={dictCode}（code走 query 串，不是 path variable）。 - 但对上表中的内置字典，仍然不要调用任何接口——直接用固化值。
- 业务自定义字典优先走
sys/dict/list?dictCode=xxx+sys/dictItem/list?dictId={id}两步法（见references/onlform-data-crud.md）。
- 正确的「按 dictCode 直接拿字典项」接口是
-
link_table 引用表存在性：这项仍然必须查（见
references/onlform-field-types.md），引用不存在的表会让创建成功但运行时报错，排查成本高。
4（原3）. 并行多个 GET 检查时，一个 Python 调用里顺序打完，不要拆成多条 shell
一次 tool call 拿到所有结果；拆成多条 shell 既有进程启动开销，在 Windows 下还会被后台化。
# 用 shell tool 跑（Windows: PowerShell，Linux/macOS: Bash）
python -c "
import urllib.request as u, json
h = {'X-Access-Token':'<token>'}; base = 'http://host'
def g(p): return json.loads(u.urlopen(u.Request(base+p, headers=h), timeout=10).read())
dup = g('/sys/duplicate/check?tableName=onl_cgform_head&fieldName=table_name&fieldVal=xxx')
dct = g('/sys/dict/list?dictCode=xxx')
print('dup=', dup.get('result'), '; dict.total=', dct.get('result', {}).get('total'))
"
5（原4）. API base 确认（避免"路径不存在"返工）
JeecgBoot 后端的 context path 因部署而异：
- 较老版本 / 标准部署：
http://host:port/jeecg-boot - 较新版本 / 根路径部署：
http://host:port（无/jeecg-boot后缀）
首次不确定时：直接按用户给的原样用。如果 onlform_creator.py 返回 "路径不存在，请检查路径是否正确"，去掉 /jeecg-boot 重试一次（或反之）——这个错误是确定性的，不要改别的参数。
「路径不存在」也可能是接口路径本身写错了（context path 没问题，但端点本身后端没有）。常见反例：
- ❌
/sys/dict/queryDictItemsByCode/{code}—— 路径 + 风格全错，后端没有这个端点 - ✅ 正确：
GET /sys/api/queryDictItemsByCode?code={code}（注意是/sys/api，参数走 query）
排查顺序：先按 context path 加/去 /jeecg-boot 重试；仍然 404 时，回到 SKILL 文档/references 里复核接口路径——不要凭印象拼 RESTful 风格的 URL。
6. 编辑前查字段顺序：直接用 listByHeadId，禁止其他接口
历史教训：曾因依次试错
field/list（返回跨表乱序垃圾）→ 读脚本源码 →getByHead（返回空）→ 才到listByHeadId，浪费了 4 次往返，被用户吐槽"不应该 30s 就搞定吗"。
强制规则（新增/删除/修改字段前获取现有字段时必须遵守）：
- ✅ 唯一正确接口：
GET /online/cgform/field/listByHeadId?headId={headId} - ❌ 禁止用
field/list——不带cgformHeadId过滤时会返回所有表的混合数据 - ❌ 禁止用
getByHead——实测返回空 fields - ❌ 禁止为了查接口用法去读
onlform_creator.py源码——直接用上面的接口即可
多表并行查询（一次 shell tool 调用，不要串行；Windows: PowerShell，Linux/macOS: Bash）：
for tbl, hid in [('t1','id1'), ('t2','id2')]:
req = u.Request(base + '/online/cgform/field/listByHeadId?headId=' + hid, headers=h)
fields = json.loads(u.urlopen(req, timeout=10).read()).get('result', [])
# 按 orderNum 排序后直接使用
fields.sort(key=lambda f: f.get('orderNum', 999))
7. 建表时必须加日期后缀，避免冲突重试链
历史教训：
dept_info冲突 → 改名 dept_info_1 → 子表再次冲突 → 再改名 → 额外更新 subTableStr，三步重试链浪费 ~50s。
强制规则： 从用户描述推导业务表名后，立即拼上当日日期后缀再写入 config JSON，无需查重，直接创建。
# 格式：业务名_YYYYMMDD
dept_info_20260509 ← 主表
dept_archive_20260509 ← 一对一子表
dept_employee_20260509 ← 一对多子表
- 日期后缀保证全局唯一，彻底跳过自动重试逻辑
- 子表同步加后缀，保持命名一致性
- 完成后在汇总中告知用户实际表名
8. 所有临时 JSON 配置在一个 Python 脚本里批量写入
历史教训：3 个 JSON 文件拆成 3 次 Write tool call，每次有固定开销，合计浪费 ~12s。
强制规则： 多个临时 JSON 配置必须在同一个 Python 脚本里批量写入，禁止逐个调用 Write tool。用 Python 的 json.dump 写文件——跨平台一致，无 BOM 风险。
# 正确：在同一个 Python 脚本里批量写入多个 JSON（跨平台）
import tempfile, json, os, subprocess
tmp = tempfile.gettempdir() # 自动适配 Windows %TEMP% / Linux /tmp / macOS /var/folders/.../T
CREATOR = r'<skill目录>/scripts/onlform_creator.py'
configs = {
'onl_main.json': {"action": "create", "tables": [{"tableName": "...", ...}]},
'onl_sub1.json': {"action