jeecg-onlform

JeecgBoot Online フォーム AI 自動生成ツール

自然言語によるフォーム要件の説明を Online フォーム設定 JSON に変換し、API を通じて JeecgBoot システムでフォームを自動作成・編集します。

重要：このスキルは「Online フォーム」（メタデータ駆動、実行時 CRUD）を扱います。「デザイナーフォーム」（desform）は対象外です。両者は完全に独立したフォーム体系です。

⚠️ 対象の判定（2026-09-03 実測に基づく再発防止）：文字列 ≠ URL。 ユーザーの発言に「テナント＋アプリ＋フォーム／ワークシート」と「新規追加時に非表示／タイトルを非表示」などのパネル属性を表す語が含まれる場合、対象は敲敲云（lowApp）のワークシートです。jeecg-lowcode-lowapp を使用してください。同じリクエストに Online／jmreport の URL が貼られていても同様です。jmreport の generateTemplateByOnline?onlineId=… にある onlineId は、印刷テンプレートが設定されたことを示す Online テーブルの headId です。URL 内の token= は jmreport のセッショントークンであり、API トークンとして使用すると 401 になります。この URL が貼られているからといって、ユーザーがその Online テーブルの操作を望んでいるとは限りません。文字列から対象を判断し、URL を根拠に誤ってこのスキルを使うことは禁止です。

適切なスキルの選択

ユーザーの要望	使用するスキル
メタデータ駆動のテーブル／フォーム設定（フィールド定義、コントロール種別、データベースのテーブル作成）	本スキル (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 が案内して確認します）。

1. API アドレス：JeecgBoot バックエンドのアドレス（例：https://boot3.jeecg.com/jeecgboot）
2. X-Access-Token：JWT ログイントークン（ブラウザーの F12 から取得）

実行効率のルール（無駄な待ち時間を減らす）

すべての HTTP 呼び出しは、以下のルールに従う必要があります。従わないと、ユーザーは応答が明らかに遅くなったと感じます。本節は必須要件です。違反すると、ユーザーから「遅すぎる」と直接苦情を受けます。

0. Windows 環境では必ず PowerShell tool で python を実行する（最も陥りやすい落とし穴）

現象：Windows の Bash tool は python／python -c／スキルスクリプトを長いコマンドとして扱い、自動的に run_in_background で実行します。tool は background ID をすぐに返しますが、実際の実行結果はシステム通知が届くまで返りません。これによりミリ秒単位の呼び出しが数秒に引き延ばされ、ユーザーはすぐに「遅い」と感じます。

ルール：

• Windows（platform=win32） → すべての python 呼び出し（スキルスクリプトと 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 ...                    ← 同上

過去の教訓：このスキルの初期バージョンでは、「Python はすべてのシェルで同期的に返る」と誤って説明していました。実測では、Windows Bash tool でも python がバックグラウンド実行されます。このため、ユーザーから「実行が遅すぎる」と何度も苦情を受けました。

0.1. 🔴 Bash は $ 文字を食い尽くす（フィールドのデフォルト値／fieldHref の落とし穴）

現象：fieldDefaultValue（例：${order_num_rule}、#{sysUserId}）と fieldHref（例：?name=${name_required}）には $ が含まれます。Bash で python -c "..." を実行すると、シェルが ${xxx} を変数として展開します。xxx がシェル変数でなければ空文字列になり、値が欠落します（例：?name= となり、変数名が失われます）。

根本原因：Bash は二重引用符で囲まれた文字列を解析する際、Python の文字列リテラル内であっても ${...} を優先的に展開します。

ルール：

• フィールド設定に $ が含まれる場合、python -c "..." によるインライン実行は禁止です（Bash でも PowerShell でも安全ではありません。PowerShell は ${} を展開しませんが、特定の状況では ${} が原因で問題が発生する場合があります）。
• 正しい方法：必ず Write tool で一時的な .py ファイルを書き込み、その後 Bash／PowerShell で .py ファイルを実行します。ファイルの内容はシェルによる解析を受けないため、$ は安全です。
• 履歴に残る過去の誤り：
  • ${order_num_rule} → bash が order_num_rule_param: onl_watch=text_pure: command not found を報告
  • ${name_required} → バックエンドに届いた値が ?name= に変わる（変数が消失）

正しい例（Write → Execute）：

Write: C:\Users\zhang\AppData\Local\Temp\onl_create_xxx.py   ← 含 $ 的配置写进 .py
Bash:  python "C:\Users\zhang\AppData\Local\Temp\onl_create_xxx.py"

過去の教訓：${name_required} が bash によって ?name= に切り詰められ、ユーザーからスキルに欠陥があるのではないかと指摘されました。実際にはシェルの動作によるもので、Python やバックエンドの問題ではありません。それ以降、$ を含むフィールド設定はすべてファイル経由で実行しています。

Windows の中国語エンコーディングルール（python -c には -X utf8 が必須）： PowerShell のデフォルトエンコーディングは UTF-16 LE です。python -c "..." のインラインコードに中国語のリテラルが含まれている場合、シェルから引数を渡す過程で文字化けし、SyntaxError: unterminated string literal が発生します。

• 対処法：python -c "..." ではなく、必ず python -X utf8 -c "..." を使用します。
• 中国語を含む複雑なロジック：一時的な .py ファイルに書き込んでから実行し、インラインでの中国語使用を完全に避けます。
• 中国語を含む結果を print する場合：インラインスクリプトの先頭に import sys; sys.stdout.reconfigure(encoding='utf-8') を追加します。

1. reference ファイルは並列で読み込み、順番に読み込まない

複数の reference ファイルが必要な場合は、同じメッセージ内ですべての Read 呼び出しを並行して行ってください。1 つずつ読み込まないでください。

// ✅ 正确：一条消息同时 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）. スキル付属の Python スクリプトを優先し、独自に HTTP ラッパーを作らない

スキルには onlform_creator.py／onlform_jimureport.py などのスクリプトが用意されており、認証、リトライ、head の解析、親子テーブルの関連付けなどの詳細が処理されています。python -c を使うのは、HTTP の確認を一度だけ行う場合にしてください。

3（原2）. 跳过非必要前置检查，直接跑脚本

• 表名查重：仅在"用户暗示要复用已有表 / 表名看上去像已有资源"时才查。普通新建场景直接跑 onlform_creator.py——遇重名接口会返回明确错误，预查反而增加一次往返。onlform_creator.py 已内置自动加 _1/_2 后缀重试，主表冲突无需手动干预。

• 字典存在性：以下系统内置字典直接使用，禁止发 API 查询，值已固化：

  字典编码	值 → 含义	控件类型
  yn	1=是 / 0=否	list / radio / switch
  sex	1=男 / 2=女	list / radio
  valid_status	1=有效 / 0=无效	list / radio
  priority	L=低 / M=中 / H=高	list / radio
  bpm_status	1=待提交 / 2=审批中 / 3=审批通过 / 4=审批拒绝	list

  仅在字典编码明显是业务自定义且不确定是否创建过时才发 sys/dict/list 查询。

• ❌ 严禁拼造 /sys/dict/queryDictItemsByCode/{code} 这种 RESTful 风格的字典查询路径：后端根本没有这个端点，会返回 "路径不存在，请检查路径是否正确"。

  • 「按 dictCode 直接拿字典项」的前端接口是 GET /sys/dict/getDictItems/{dictCode}，但需要 X-Sign 签名；不想处理签名就用下面的两步法。
  • ⚠️ /sys/api/queryDictItemsByCode 是微服务内部接口，2026-10-14 起单体模式下不存在，不要再用。
  • 但对上表中的内置字典，仍然不要调用任何接口——直接用固化值。
  • 业务自定义字典优先走 sys/dict/list?dictCode=xxx + sys/dictItem/list?dictId={id} 两步法（见 references/onlform-data-crud.md）。

• 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} —— 路径 + 风格全错，后端没有这个端点
• ❌ /sys/api/queryDictItemsByCode?code={code} —— 微服务内部接口，单体下不存在（2026-10-14 起）
• ✅ 正确：sys/dict/list?dictCode=xxx + sys/dictItem/list?dictId={id} 两步法；或带签名调 GET /sys/dict/getDictItems/{dictCode}

排查顺序：先按 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。 🔴 2026-08-05 用户反馈：自动加 业务名_YYYYMMDD 日期后缀（如 leave_apply_20260805）表名冗长难记，明确禁止。

强制规则： 直接用纯业务名（不加日期后缀），遇到 数据库表[xxx]已存在 错误时，用短序号后缀 xxx_1 → xxx_2 递增重试，禁止加 _YYYYMMDD 日期后缀。

# ✅ 首选（不加后缀）
dept_info                ← 主表
dept_archive             ← 一对一子表
dept_employee            ← 一对多子表

# ⚠️ 冲突时（仅当 addAll 报已存在）
dept_info_1              ← 短序号后缀
dept_employee_1

• 业务名优先简洁可读，禁止为"保证唯一"而堆砌日期/时间戳
• onlform_creator.py 已内置 _1/_2 自动重试并同步子表 mainTable 引用，无需手动干预
• 子表与主表后缀保持一致
• 完成后在汇总中告知用户实际表名

7.5 字段排序规则：系统字段放业务字段下方（🔴 强制）

历史教训：2026-08-05 用户反馈：通过 skills 创建的 Online 表单，数据库属性页里 create_by/create_time/update_by/update_time/sys_org_code 等系统字段排在业务字段上方，查看和编辑时很不方便。

强制规则： onlform_creator.py 创建表单时，字段顺序必须按以下规则排列：

1. 主键 id 始终排在第一位
2. 业务字段紧跟 id（按用户给出的字段顺序）
3. 系统字段放到业务字段后面：create_by / create_time / update_by / update_time / sys_org_code
4. 树表 has_child 始终放在业务字段最后
5. 子表外键字段（{mainTable}_id）作为隐藏字段，排在业务字段后面

效果示例：

# ✅ 正确顺序
1  id
2  applicant          ← 业务字段
3  apply_date
4  expense_type
5  total_amount
6  create_by          ← 系统字段
7  create_time
8  update_by
9  update_time
10 sys_org_code

该规则已写入 scripts/onlform_creator.py 的 build_fields_from_config()，所有通过本 skill 新建的 Online 表单自动遵守。

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": "create", "tables": [{"tableName": "...", ...}]},
}
paths = {}
for fname, cfg in configs.items():
    path = os.path.join(tmp, fname)
    with open(path, 'w', encoding='utf-8') as f:
        json.dump(cfg, f, ensure_ascii=False)
    paths[fname] = path

# 依次调用 onlform_creator.py
for path in paths.values():
    subprocess.run(['python', CREATOR, '--api-base', BASE, '--token', TOKEN, '--config', path], check=True)

9. 字段编辑"查询 + 生成配置 + 执行"合并为 1 个 Python 脚本

历史教训：查 orderNum → Write tool 写 JSON → 再调用 creator，拆成 3 步 tool call 浪费 ~10s。

强制规则： 编辑字段时，把 listByHeadId 查询、edit config 生成、写临时文件、调用 creator 全部写进一个 Python 脚本，在单次 shell tool call（Windows: PowerShell，Linux/macOS: Bash）里跑完。

# 模板：查询 → 生成 config → 写文件 → 调用 creator（一个脚本搞定）
import subprocess, json, os, tempfile
import urllib.request as u

# 1. 查询现有字段
fields = query_fields(head_id)

# 2. 在内存中构建 edit config（无需 Write tool）
cfg = {"action": "edit", "tableName": tname, "addFields": [...], "modifyFields": [...]}
path = os.path.join(tempfile.gettempdir(), f'onl_edit_{tname}.json')
with open(path, 'w', encoding='utf-8') as f:
    json.dump(cfg, f, ensure_ascii=False)

# 3. 直接调用 creator
subprocess.run(['python', '-X', 'utf8', CREATOR, '--api-base', BASE, '--token', TOKEN, '--config', path], check=True)

10. 多表编辑必须用 tables: [] 并行 + 单表 add/modify 一次提交（节省 ~20s）

历史教训：曾分两轮编辑 3 张表 = 6 次串行 subprocess.run(creator)。每次 creator 启动 ~1s + addAll/syncDb HTTP 各 ~1s ≈ 共 18-25s。三个症状叠加：

1. 同一张表的 addFields（新增）和 modifyFields（重排）拆成两轮调用 → HTTP/syncDb 翻倍
2. 多张表的 edit 串行 spawn 子进程 → 表数 × Python 冷启动
3. 每次都重新 import 模块 → Windows 上每次 ~800ms 启动开销

强制规则（多表/复合编辑必须遵守）：

1. 同一张表的所有变更合并为一次 editAll：addFields + modifyFields + deleteFields 写在同一个 config，creator 内部一次提交即完成。

   ⚠️ addFields 的 orderNum 不被后端采纳——新字段始终追加到末尾（实测）。 同一次 editAll 里 modifyFields 只对已存在字段生效，对同批 addFields 新建的字段无效。 教训来源：2026-05-09 给员工子表插入 sex 字段，指定 orderNum=9 并在 modifyFields 里后移 id_card/phone，结果 sex 仍追加到末尾（orderNum=11），需第二次单独 modifyFields 才修正。

   插入到中间位置的正确两步法：

   • 第一步：addFields 创建字段（orderNum 随便填，后端忽略，字段追加到末尾）；modifyFields 里只后移已有字段
   • 第二步：单独再跑一次 modifyFields，把新建字段的 orderNum 设到目标位置

   # 第一步：创建字段 + 后移已有字段（新字段 orderNum 会被忽略，先追加到末尾）
   cfg1 = {"action":"edit","tableName":"t","addFields":[{"dbFieldName":"sex",...}],
           "modifyFields":[{"dbFieldName":"id_card","orderNum":10},{"dbFieldName":"phone","orderNum":11}]}
   # 第二步：修正新字段的 orderNum（必须在第一步完成后执行）
   cfg2 = {"action":"edit","tableName":"t","modifyFields":[{"dbFieldName":"sex","orderNum":9}]}
   

2. 多表编辑用顶层 tables: []：onlform_creator.py 的 action: "edit" 现在支持 tables 数组，会用线程池并发执行 N 张表的编辑。表数 ≥ 2 时必须用此格式，不要写 N 个单表 config 串行 spawn。

# ✅ 正确：一次 creator 调用，N 张表并行
cfg = {"action": "edit", "tables": [
    {"tableName": "t1", "addFields": [...], "modifyFields": [...]},
    {"tableName": "t2", "addFields": [...]},
    {"tableName": "t3", "modifyFields": [...]}
]}
subprocess.run(['python', '-X', 'utf8', CREATOR, '--api-base', BASE, '--token', TOKEN, '--config', path], check=True)

# ❌ 错误：串行 spawn 3 次 creator
for cfg in [cfg1, cfg2, cfg3]:
    subprocess.run([..., '--config', path], check=True)  # 每次 ~3-5s

# ❌ 错误：同一张表 add 一轮、reorder 一轮
subprocess.run([..., '--config', add_only_config])    # 第一轮：add
subprocess.run([..., '--config', reorder_only_config]) # 第二轮：reorder（多余的 syncDb）

收益：3 张表的「add + reorder」从 6 次 creator 调用（~25s）降到 1 次（~5s）。

11. 自定义字典用 batchAddDictWithItems 一次搞定

历史教训：早期用 dict/add + dictItem/add 逐条写入，遇到 result=null 时还会 TypeError 崩溃触发重跑。实际上 JeecgBoot 有批量接口，1 次 HTTP 完成所有字典+items，且内置"已存在跳过"逻辑。

接口：POST /sys/dict/batchAddDictWithItems

• 请求体：{"dictList": [{...}, {...}]}，每项含 sysDictItemList
• 已存在的字典编码自动跳过（服务端 catch 唯一约束异常），不影响其他字典
• 返回：{"successCount": N, "failureCount": M, "failureList": [...]}

def ensure_dicts_batch(base, token, dicts):
    """
    dicts = [
      {"dictName":"订单类型","dictCode":"order_type","description":"...","items":[("国内","1",1),...]},
      ...
    ]
    """
    payload = {"dictList": [
        {
            "dictName": d["dictName"],
            "dictCode": d["dictCode"],
            "description": d.get("description", ""),
            "sysDictItemList": [
                {"itemText": t, "itemValue": v, "sortOrder": o, "status": 1}
                for t, v, o in d["items"]
            ]
        }
        for d in dicts
    ]}
    H = {'X-Access-Token': token, 'Content-Type': 'application/json'}
    body = json.dumps(payload, ensure_ascii=False).encode('utf-8')
    req = urllib.request.Request(base + '/sys/dict/batchAddDictWithItems', data=body, headers=H, method='POST')
    r = json.loads(urllib.request.urlopen(req, timeout=15).read().decode('utf-8'))
      # ⚠️ 全部已存在时接口返回 success=false + code 500，需判断 failList 区分"真失败"和"已存在跳过"
    result = r.get('result') or {}
    fail_list = result.get('failList') or []
    real_fails = [f for f in fail_list if '已经存在' not in f.get('errorMsg', '')]
    if real_fails:
        raise RuntimeError(f'字典创建失败: {real_fails}')
    skip_count = len([f for f in fail_list if '已经存在' in f.get('errorMsg', '')])
    print(f'  字典批量: 新建={result.get("successCount",0)}, 已存在跳过={skip_count}')
    return r

# 调用示例（N 个字典 1 次 HTTP）
ensure_dicts_batch(BASE, TOKEN, [
    {"dictName":"订单类型",  "dictCode":"order_type",    "description":"国内/国际",    "items":[("国内","1",1),("国际","2",2)]},
    {"dictName":"运输方式",  "dictCode":"transport_mode", "description":"运输方式(全量)","items":[("陆运","land",1),("铁运","rail",2),("空运","air",3),("海运","sea",4)]},
])

⚠️ 接口行为陷阱（实测）：全部字典已存在时，接口返回 success=false + code=500，而不是静默跳过。 判断方式：遍历 result.failList，errorMsg 含"字典编码已经存在"的视为正常跳过，其余才是真失败。

收益：N 个字典 + M 个 items 从 1+N×M 次 HTTP → 1 次 HTTP，无 result=null 防御问题。

5. 建表遇到「数据库表 [xxx] 已存在」时的处理

错误 数据库表[xxx]已存在,请从数据库导入表单 表示：物理 DB 表残留，但 Online 配置不存在（通常是之前创建后被手动删了 Online 头）。

onlform_creator.py 和 onlform_pipeline.py 已内置自动加后缀重试，并自动更新关联子表的 mainTable 引用。主表冲突无需手动干预，脚本会自动完成。执行后在汇总输出中确认实际使用的表名即可。

1. 首选：换表名（在 config 中指定新名称）——最快，避免污染现有物理表。
2. 次选：导入：GET /online/cgform/head/transTables/{tableName} 把物理表导入为 Online 配置，再用 action=edit 调整字段。
3. 慎用：删除物理表（通过 DB 直连 DROP TABLE）——只在确认无数据且用户明确要求时做。

主子表场景特别注意：主表建失败且脚本未自动重试时，子表如果已创建会成为"孤儿"。此时先 DELETE /online/cgform/head/delete?id={孤儿子表headId} 删干净，再整体重建。

主数据复用规则

重要： 配置表单字段的字典、用户选择、部门选择等数据源时，必须遵循"先查后建"原则。 使用 jeecg-system skill 的 system_utils.py 查询和管理主数据。

临时配置文件规则（强制）

所有传给脚本的 --config <xxx.json> 必须写到系统临时目录，由 OS 自动清理；skill 和脚本都不主动 rm。

import tempfile, os, json
config_path = os.path.join(tempfile.gettempdir(), 'onl_<表名>_<步骤>.json')
with open(config_path, 'w', encoding='utf-8') as f:
    json.dump(cfg, f, ensure_ascii=False, indent=2)

tempfile.gettempdir() 自动适配：Windows %TEMP% / Linux /tmp / macOS /var/folders/.../T（注意 macOS 不是 /tmp）。命名建议带表名+步骤前缀（如 onl_sk_audit_create.json）便于排错。

❌ 禁止：

• 写到 <skill>/tmp/ 或当前工作目录（污染 skill / 用户项目）
• 硬编码 /tmp / C:\Temp（不跨平台）
• 每步完成后主动 rm / Remove-Item（OS 会清，多余 tool call）
• 主动 os.path.exists() 检查（自身就是一次 tool call）

临时文件可能被 OS 异步清理，但乐观调用 + 报错再补救：仅当脚本返回 FileNotFoundError / 配置文件不存在 时，用相同内容重写后重试，不要换路径或去 skill 目录找。

交互流程

Step 0: 判断操作类型

用户意图关键词	操作类型	使用脚本
创建/新建/做一个/生成	新增表单 → Step 1A	onlform_creator.py
加字段/增加字段/修改字段/删除字段	编辑表单 → Step 1B	onlform_creator.py
集成积木/关联打印/打印报表	积木报表集成 → Step 8	onlform_jimureport.py
JS增强/按钮/增强功能	增强配置 → Step 9	onlform_enhance.py
权限/授权/数据规则	权限配置 → Step 10	onlform_auth.py
造数据/插入/查询/导出	数据操作 → Step 11	onlform_data.py
挂载菜单/加到菜单/预览地址/缓存路由	菜单挂载 → Step 12	onlform_menu.py

Step 0.5: 🔴 区分表单与视图（表名含 $N 后缀 = 视图，不是表单！）

现象：用户说"视图"或表名含 $N（如 all_ctrl_demo_20260703$2），AI 却忽略 $N 后缀直接查原表名（去掉 $N），在原表上操作。

根因：$ 在 shell 中有特殊含义，AI 下意识去掉后缀去查"干净"的表名，但 $N 正是视图的标识。

规则：

• 表名含 $N 后缀（N=1,2,3...）→ 这是视图，不是原表单，必须用精确表名查询
• 视图有独立的 headId，physicId 指向原表
• 视图查询：GET /online/cgform/head/list?copyType=1&physicId={原表headId} 或用精确 tableName 查
• 视图与原表共享数据但权限配置独立——在视图上配权限不影响原表，反之亦然
• 用户说"视图"就操作视图的 headId，说"表单"就操作原表的 headId

正确流程：

1. 用户给的表名含 $N → 直接用精确表名查 head/list?tableName=xxx$N
2. 查不到 → 通过 copyType=1&physicId={原表headId} 列出所有视图
3. 找到视图 headId → 所有后续操作（字段编辑/权限/增强）都用视图的 headId

历史教训：用户说"online表单视图名称为 all_ctrl_demo_20260703$2 授权限"，AI 搜索 all_ctrl_demo_20260703（去掉了 $2）找到原表，在原表上配了权限。用户纠正后才发现 $2 是视图标识，视图 headId 完全不同，需重新在视图上操作。

Step 1A: 新增表单 — 解析需求

从用户描述中提取：

信息	默认值	示例
表名 (tableName)	自动生成 snake_case	leave_application
表描述 (tableTxt)	用户指定	"请假申请"
表类型 (tableType)	1=单表	提到"主子表"→2/3，提到"树形"→1+isTree
字段列表	从描述中解析	姓名(必填)、请假天数(数字)、日期(范围查询)

判断表类型：

• 提到"分类/层级/树/上下级" → 树表 (tableType=1, isTree='Y')
• 提到"主子表/明细/一对多/订单+商品" → 主子表 (主表 tableType=2, 子表 tableType=3)，默认使用 normal 风格（不使用 erp），除非用户明确指定
• 默认 → 单表 (tableType=1)

🔴 多数据源原则：用户不提多数据源 → 不设 dbSource → 不追加 enableMultiDataSource → 默认主库。仅用户明确说"多数据源/数据源编码xxx/指定数据源"时才配置。

使用全控件模板（all_controls_master_sub.json）时： 读取模板作为结构参考，但表名（tableName/tableTxt）必须根据用户的业务描述重新命名，不能使用模板中的占位符表名。

创建前不要查重表名。 addAll 接口本身会校验并返回明确的重复提示，提前查重是多余的网络开销。

遇到重名错误（数据库表[xxx]已存在）时的处理规则：

当前操作	处理方式
新建表单（用户意图是创建一个新表）	自动加后缀重试：xxx → xxx_1 → xxx_2 …，直到成功；执行成功后告知用户实际使用的表名
修改/编辑表单（用户意图是改已有表）	切换到 editAll 流程
导入数据库已有表	调用 transTables/{tableName} 导入

❌ 绝对不能删除已有表（DELETE /online/cgform/head/delete）来"让位"给新建——这会丢失已有数据和配置。删除只能在用户显式要求删除时执行。

字典字段配置易错点（必须注意）：

• 下拉框/多选框/单选框/下拉多选/下拉搜索 这 5 种控件必须配置数据字典或表字典，否则没有选项无法使用。生成字段配置时，遇到这 5 种控件必须同时配置 dictField（数据字典）或 dictTable+dictField+dictText（表字典）。
• 数据字典（系统字典/字典编码）：只填 dictField（字典编码，如 sex、education），dictTable 和 dictText 留空。绝对不能把 dictTable 设为 sys_dict_item。
• 表字典：dictTable 填业务表名（如 sys_user，也可以填 Online 创建的表），dictField 填存储值字段，dictText 填显示文本字段。
• 使用的字典编码不存在时，需先通过 sys/dict/list?dictCode=xxx 查询，不存在则通过 sys/dict/add + sys/dictItem/add 创建（先查后建）。

Step 1B: 编辑表单 — 查询现有配置

1. 用户提供表单 ID 或表名
2. 查询表名获取 headId：GET /online/cgform/head/list?tableName={表名}&pageNo=1&pageSize=1
3. 查询现有字段（必须用 listByHeadId，见效率规则第6条）： GET /online/cgform/field/listByHeadId?headId={headId} 返回结果按 orderNum 排序，确认需要插入的前后字段的 orderNum 值
4. 根据用户需求进行增/删/改字段，直接写配置跑脚本

多表编辑 / 增删改一次提交（见效率规则第10条）：涉及多张表时用 tables: [] 一次配置并行执行；同一张表的 addFields + modifyFields 必须放在同一个 config（一次 editAll 内全做完，避免 add 一轮、reorder 一轮的双往返）。

单表编辑 + 重排同时进行的 JSON 示例（一次完成）：

{
  "action": "edit",
  "tableName": "dept_employee",
  "addFields": [
    {"dbFieldName": "sex", "dbFieldTxt": "性别", "fieldShowType": "radio",
     "dbType": "string", "dbLength": 2, "dictField": "sex", "orderNum": 9}
  ],
  "modifyFields": [
    {"dbFieldName": "id_card", "orderNum": 10},
    {"dbFieldName": "phone",   "orderNum": 11}
  ]
}

多表并行编辑 JSON 示例（creator 自动用线程池并发）：

{
  "action": "edit",
  "tables": [
    {"tableName": "dept_info",     "addFields": [...], "modifyFields": [...]},
    {"tableName": "dept_archive",  "addFields": [...]},
    {"tableName": "dept_employee", "addFields": [...], "modifyFields": [...]}
  ]
}

Step 2-4: 智能字段推导

详细字段类型映射、字典配置、校验规则、默认值、扩展配置、特殊控件配置参见： references/onlform-field-types.md

⚠️ link_table（关联记录）前置检查（必须执行）： 配置 link_table 字段时，dictTable 只能引用 Online 管理的业务表，不能是系统表。 必须先调用 GET /online/cgform/head/list?tableName={表名}&pageNo=1&pageSize=1 验证被关联表是否存在。

• 若不存在 → 先创建该 Online 表并同步数据库，再插入至少 3 条示例数据，然后再配置 link_table 字段。
• 若已存在 → 继续执行列名验证（必须）：调用 GET /online/cgform/api/getColumns/{headId} 查出实际列名列表，用真实列名覆盖模板/假设中的 dictText 字段值，不能凭猜测或模板占位符直接使用。

教训：仅检查表存在还不够——模板里的 dictText: "user_code,phone" 与目标表实际列 name/age/sex/birthday 完全不同，导致运行时报 Unknown column 'user_code' in 'field list'。 详细说明见 references/onlform-field-types.md 的 link_table 小节。

核心映射速查：

关键词	fieldShowType	dbType
文本	text	string
备注	textarea	string
日期	date	Date
下拉	list	string
单选	radio	string
多选	checkbox	string
开关	switch	string
图片	image	string
文件	file	string
用户选择	sel_user	string
部门选择	sel_depart	string
省市区	pca	string
富文本	umeditor	Text

ステップ 5：概要を提示して確認

設定の概要を必ず提示し、ユーザーの確認を待ってから実行してください。 このステップは非常に重要です。フィールド設定を作成した後の変更コストは高く（1つずつ編集する必要があります）、事前に確認することで手戻りを防げます。概要には次の内容を含めてください。

• テーブル名、テーブルの説明、テーブルの種類
• 6 つの標準システムフィールド
• すべての業務フィールド（連番、フィールド名、ラベル、コントロールの種類、DB の種類、必須、検索、辞書）
• フィールドの合計数

ステップ 6-7：設定 JSON を生成してスクリプトを呼び出す

scripts/onlform_creator.py を使用する（推奨）：

python <skill目录>/scripts/onlform_creator.py --api-base <URL> --token <TOKEN> --config <config.json>

単一テーブル作成用 JSON の例：

{
  "action": "create",
  "tables": [{
    "tableName": "leave_application",
    "tableTxt": "请假申请表",
    "tableType": 1,
    "dbSource": "",
    "fields": [
      {"dbFieldName": "name", "dbFieldTxt": "姓名", "fieldShowType": "text", "dbType": "string", "dbLength": 100, "fieldMustInput": "1", "isQuery": 1}
    ]
  }]
}

複数データソースの設定：dbSource は onl_cgform_head の直接フィールド（extConfigJson ではありません）で、sys_data_source.code を入力します。dbSource を設定すると、スクリプトが extConfigJson に enableMultiDataSource: 1 を自動設定し、フロントエンドの「複数データソースを有効にする」スイッチが自動的にオンになり、「データソースを選択」ドロップダウンも自動的に選択されます。子テーブルには dbSource を設定する必要はありません。親テーブルの設定が自動的に適用されます。

フォーム編集用 JSON の例：

{
  "action": "edit",
  "tableName": "test_demo",
  "addFields": [{"dbFieldName": "new_field", "dbFieldTxt": "新字段", "fieldShowType": "text", "dbType": "string", "dbLength": 100}],
  "deleteFields": ["old_field"],
  "modifyFields": [{"dbFieldName": "existing_field", "dbFieldTxt": "修改后标签", "dbLength": 200}]
}

親子テーブル、ツリーテーブルの完全な JSON 設定例については、 references/onlform-misc.md を参照してください。

ステップ 8：積木レポートとの統合

scripts/onlform_jimureport.py を使用します。

python <skill目录>/scripts/onlform_jimureport.py --api-base <URL> --token <TOKEN> --config <config.json>

設定 JSON の例：

{
  "action": "create_report",
  "tableName": "customer",
  "reportName": "客户表打印",
  "fields": [
    {"fieldName": "customer_name", "fieldText": "客户名称"},
    {"fieldName": "phone", "fieldText": "联系电话"}
  ]
}

スクリプトは次の 8 つのステップを自動で実行します。レポートの作成 → 空のテンプレートの保存 → フィールドの解析 → コードの確認 → データソースの保存 → テンプレートの取得 → 参照の書き込み → フォームとの関連付け。

画像／日付フィールドの自動処理：スクリプトはコントロールの種類（fieldShowType + fieldExtendJson.picker）に応じてセルを自動処理します。画像コントロール（image）では、値セルに display:"img" を追加して画像として描画します（追加しない場合は URL の文字列のみが表示されます）。通常の日付コントロール（picker のない date）では、値セルにスタイル format:"date" を設定し、時分秒を除いて日付 yyyy/MM/dd のみを表示します。年／月／週／四半期の picker 変種の date コントロールは元の値のままにします（API から 2029、2026-34周 などの表示値がすでに返されており、書式を適用すると 1970/01/01 として描画されます）。datetime／time／file コントロールは元の値のままにします。 ⚠️ 日付に =DATE_STR() 式を使用しないでください：フィールド値が空文字列の場合に式がエラーとなり、テーブル全体が「描画失敗」になります（実際に問題が発生することを確認済みです）。空値を安全に扱えるネイティブのセル書式 format:"date" を必ず使用してください。

前提条件：Online テーブルにレコードが少なくとも 1 件存在しないと、フィールドを解析できません。 積木レポート API の詳細については、 references/onlform-jimureport.md を参照してください。

ステップ 9：拡張設定

scripts/onlform_enhance.py を使用します。

python <skill目录>/scripts/onlform_enhance.py --api-base <URL> --token <TOKEN> --config <config.json>

対応する操作：

• create_buttons — カスタムボタンを作成（button/link/form スタイル）
• save_js — JS 拡張を保存（form/list 種類）
• save_java — Java 拡張を保存（spring-key/java-class/http-api）
• save_sql — SQL 拡張を保存
• query — すべての拡張設定を照会

拡張設定の参考資料（必要に応じて該当するファイルを参照）： JS 拡張 → references/onlform-enhance-js.md；Java 拡張 → references/onlform-enhance-java.md；SQL／ボタン → references/onlform-enhance-misc.md

⚠️ 拡張設定を保存する前に、必ず既存の内容を GET してから統合してください。直接 PUT で上書きすることは禁止です！ 過去の教訓：js_enhance_demo_20260702_1 に list JS 拡張を保存する際、直接 PUT して cgJs フィールド全体を上書きしたため、それまでの JS コードが失われ、復元できなくなりました（API にバージョン履歴がありません）。 正しい手順：GET /online/cgform/head/enhanceJs/{headId}?type=list → result.cgJs を取得 → 新しいコードと連結 → 旧コードと新コードを含む全体を PUT で保存します。Java／SQL 拡張も同様です。

ステップ 10：権限設定

scripts/onlform_auth.py を使用します。

python <skill目录>/scripts/onlform_auth.py --api-base <URL> --token <TOKEN> --config <config.json>

対応する操作：

• setup_field_auth — フィールド権限を設定（一覧での表示／フォームでの表示／フォームでの編集）
• setup_button_auth — ボタン権限を設定
• setup_data_auth — データ権限ルールを設定
• grant_role — ロール／部門／ユーザーに権限を付与
• query — すべての権限設定を照会

権限設定の詳細については、 references/onlform-auth.md および references/onlform-misc.md を参照してください。 🔴 フィールド権限を有効にする前に、非表示フィールドを必ず除外してください！ ユーザーが「すべてのフィールドを有効にして」と言った場合でも、無条件にすべてのフィールドの権限を有効にしてはいけません。まず listByHeadId で各フィールドの isShowList と isShowForm を確認し、一覧またはフォームで実際に表示されるフィールド（isShowList=1 または isShowForm=1）のみ権限を有効にしてください。反対に、両方とも 0 のフィールド（isShowList=0 AND isShowForm=0）は画面にまったく表示されないため、フィールド権限の対象に含めないでください。よく除外するフィールド：id／create_by／create_time／update_by／update_time／sys_org_code／has_child。注意：pid（親ノード）は一覧では非表示（list=0）ですが、フォームでは表示される（form=1）ため、除外してはいけません。判定基準は AND であり、OR ではありません。 過去の教訓：tree_ctrl_demo_20260706_1$1 ビューの「すべてのフィールドを有効にして」と言われた際、無条件に 39 個のフィールドすべてを有効にしました。ユーザーから id などの非表示フィールドは表示すべきでないと指摘された後、今度は pid（form=1）まで誤って無効にし、ユーザーから「画面には親ノードがある」と再度指摘されました。正しい方法：listByHeadId → isShowList=0 AND isShowForm=0 のフィールドのみ除外 → それ以外はすべて有効にします。

🔴 「権限付与」は「作成」ではありません。データ権限を付与する前に、既存のルールを必ず確認してください！ ユーザーが「XX にデータ権限を付与して」と言った場合、意味するのは既存のデータルールをロール／部門／ユーザーに付与することであり、新しいルールを作成することではありません。まず GET /online/cgform/api/authData/{cgformId} で既存のルールを確認 → 対象のルールを見つける → POST roleDataAuth で権限を付与してください。ユーザーが明確に「データ権限ルールを作成して」と指示した場合、または既存のルールでは要件を満たせない場合に限り、新しいルールを作成してください。そうしないとルールが重複し、追加されたルールを見たユーザーに、AI が余計なことをしたと思われます。 過去の教訓：ユーザーが「tree_ctrl_demo_20260706_1 のデータ権限を付与して。jeecgユーザーは単一選択ボックスが男性のデータしか見られない」と指示した際、既存の基礎テーブルに「単一選択ボックスが男性のデータしか見られない」というルールがあったにもかかわらず、直接 POST authData で新しいルールを作成してから権限を付与しました。正しい方法：まず GET authData → 既存のルールを見つける → そのルールに対して直接 POST roleDataAuth を実行します。

ステップ 11：データ操作

scripts/onlform_data.py を使用します。

python <skill目录>/scripts/onlform_data.py --api-base <URL> --token <TOKEN> --config <config.json>

対応する操作：

• insert — データを挿入（単一テーブル／親子テーブル）
• insert_tree — ツリーテーブルのデータを挿入（親から子の順に自動処理）
• query — データ一覧を照会（フィルター付き）
• query_tree — ツリーテーブルのデータを照会
• get — 単一レコードを照会
• update — レコードを更新（全項目を自動的にマージ）
• delete — レコードを削除
• export_csv — CSV をエクスポート

データ CRUD API と保存形式の詳細については、 references/onlform-data-crud.md を参照してください。

---

すべてのスクリプト共通のパラメーター

パラメーター	説明
--api-base	JeecgBoot バックエンドのアドレス（例：http://localhost:8080/jeecg-boot）
--token	X-Access-Token
--config	JSON 設定ファイルのパス — システムの一時ディレクトリに配置する必要があります。上記の「一時設定ファイルのルール」を参照してください。

すべてのスクリプトでは tableName から headId が自動的に解決されるため、手動で照会する必要はありません。

参考文档索引（按需读取）

文档	何时读取
onlform-field-types.md	需要确定控件类型(fieldShowType)、字典配置、校验规则、默认值表达式、扩展配置(fieldExtendJson)时——创建/编辑表单字段必读
onlform-enhance-js.md	JS增强：onlChange联动、loaded初始化、beforeSubmit校验、列表拦截、显隐禁用时
onlform-enhance-java.md	Java增强（spring/class/http）、导入增强时
onlform-enhance-misc.md	SQL增强、自定义按钮、按钮表达式、fieldHref超链接时
onlform-auth.md	用户要求配置字段权限、按钮权限、数据权限、或给角色授权时
onlform-data-crud.md	需要插入/查询/更新/删除表单数据、导出CSV时——确认各控件的值格式必读
onlform-jimureport.md	用户要求关联积木报表或集成打印功能时
onlform-master-detail-checklist.md	创建主子表时必读——subTableStr / mainTable / mainField / 外键字段三项必填清单，缺任何一项关联失效
onlform-misc.md	处理head级配置(extConfigJson)、主子表/树表JSON结构、BPM集成、视图配置、表单布局(formTemplate)时
onlform-api-reference.md	需要查看addAll完整请求体模板、head字段枚举、系统默认字段时
onlform-route-cache.md	用户要求开启Online表单路由缓存(keepAlive)、配置菜单组件名称、或询问动态/静态路由配置时

Step 12: 菜单挂载 + 路由缓存（可选 · 不自动执行）

本步骤非必须。 表单/流程创建完成后不要默认执行菜单挂载。先用一句话询问用户："是否需要挂载到菜单？" 用户明确确认后再执行。 用户可以直接通过预览 URL 访问表单，或自行在系统设置中挂载。演示环境账号通常无菜单创建权限，强行执行会失败。

使用 scripts/onlform_menu.py：

python <skill目录>/scripts/onlform_menu.py --api-base <URL> --token <TOKEN> --config <config.json>

支持的操作：

• mount — 挂载单个 Online 表单到菜单（自动推导预览地址和组件名称，可选开启缓存、授权角色）
• mount_batch — 批量挂载多个表
• enable_cache — 为已有菜单开启路由缓存

挂载菜单 JSON 示例：

{
  "action": "mount",
  "tableName": "test_order_main",
  "menuName": "测试订单主表",
  "keepAlive": false,
  "roleCode": "admin"
}

开启缓存 JSON 示例：

{
  "action": "enable_cache",
  "menuId": "xxx"
}

默认不开启缓存路由。仅当用户明确要求时才设置 keepAlive: true。 路由缓存详细参考参见： references/onlform-route-cache.md