JeecgBoot 代码生成器（Freemarker 驱动）

把用户的自然语言需求转成 Freemarker 上下文 JSON，交给 scripts/codegen.py 调用模板生成全套 CRUD（后端 Java + 前端 Vue3 + 菜单 SQL）。

核心原则

AI 不再从零写代码。 基础代码全部由 jeecg 官方 Freemarker 模板生成，AI 只做三件事：

1. 拼参数 — 把用户需求映射成 ctx.json
2. 调脚本 — 跑 scripts/codegen.py 让 Freemarker 出基础代码
3. 改产物 — 用户提了模板不覆盖的特殊需求时，用 Edit 改已生成的代码

⛔ 禁止修改 templates/ 目录下任何模板文件。模板由 jeecg 官方维护，改了就脱离了升级路径。 ⛔ 禁止绕开脚本直接手写 Entity / Controller / data.ts 等基础文件。

主数据复用

涉及字典、角色、用户、部门时遵循"先查后建"，使用 jeecg-system skill。详见 ../jeecg-system/SKILL.md。

接口禁止猜测

所有接口路径/参数必须来自用户提供、jeecg-system skill 文档、或经查询确认。猜测命中也算违规。

模板覆盖范围

不是所有"表类型 × 前端风格"的组合都有模板。先选表类型 → 决定可选的前端风格：

不支持的组合： 一对多 + 默认布局（即旧 SKILL 中的"原始布局"）目前没有 vue3 模板，jeecg 官方枚举 CgformEnum.MANY 仅支持 vue2。 如果用户要"默认/原始布局"的 vue3 一对多，改推荐 tab 或 inner-table，并向用户说明原因。

交互流程

Step 0 — 判断操作类型

• 关键词 "加字段 / 删字段 / 改字段 / 给XX加" → 增量修改（跳到本文末"增量修改"章节）
• 其他 → 全量生成

Step 1 — 收集参数（一次性问完）

⛔ **铁律：**Step 2 摘要被用户明确确认前，禁止调脚本、禁止落地任何文件、禁止执行任何 SQL。 "需求很清楚了""都用默认值""先生成再改" 都是合理化跳过确认的借口，全部无效。

向用户一次问全所有缺失项（已知项可填默认值并标注"如无异议保留"）：

Step 2 — 展示摘要

把构造好的 ctx.json 用表格展示给用户：

• 表头：表名、实体名、风格、前端风格、字段数
• 字段表：fieldName / fieldDbName / 注释 / fieldDbType / classType / 字典 / 必填 / 列表显示 / 表单显示 / 查询
• 不要 dump 整个 JSON，太冗长

明确询问 "是否生成？" — 收到 "确认 / ok / 可以 / 没问题" 等表述后才进入 Step 3。

Step 3 — 调用脚本

调用前先把构造好的 JSON 写到临时目录（路径规则见下方"临时配置文件规则"），然后用绝对路径调脚本。

SKILL 路径定位： 脚本永远在 <SKILL_ROOT>/scripts/codegen.py。<SKILL_ROOT> 就是包含 SKILL.md 的那个目录，比如 C:\Users\moe\.claude\skills\jeecg-codegen-new 或 E:\Projects\BJGJ\jeecg-skills\jeecg-codegen-new——你能加载 SKILL.md 就能得出这个路径，不要再去 Read codegen.py 来确认任何东西，下面的 CLI 参考就是脚本的完整契约。

完整 CLI 参考

python <SKILL_ROOT>/scripts/codegen.py [OPTIONS]

🟡 = 在没有 --out 的"正常模式"下，至少要传 --backend-root 或 --frontend-root 或 --flyway-dir 之一（任何没传的目录类型对应的产物都被跳过）；正常代码生成场景三个都该传。

✅ = 任何模式都必填。

退出码 & 输出

• 退出码 0 = 成功；其他都失败（参数非法、Java 编译失败、Freemarker 渲染异常）
• 标准输出每行一个事件：[codegen] WROTE <绝对路径>、[codegen] WOULD WRITE ...（dry-run 时）、[codegen] running FtlRunner … 等
• 失败时 stderr 含完整 Java 栈或 [codegen] xxx 错误信息

典型调用（复制后改 4 个值即可）

python E:/Projects/BJGJ/jeecg-skills/jeecg-codegen-new/scripts/codegen.py \
  --style default/one \
  --ctx /c/Users/moe/AppData/Local/Temp/jeecg-codegen-new/biz_goods_ctx.json \
  --backend-root D:/jeecgboot/jeecg-module-system/jeecg-system-biz \
  --frontend-root D:/jeecgboot-vue3 \
  --frontend-style vue3 \
  --flyway-dir D:/jeecgboot/jeecg-module-system/jeecg-system-start/src/main/resources/flyway/sql/mysql

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

所有传给脚本的 --ctx <xxx.json> 必须写到 {系统临时目录}/jeecg-codegen-new/ 下，由操作系统自动清理；skill 与脚本均不主动删除该目录或文件。

import tempfile, os, json

SKILL_NAME = "jeecg-codegen-new"
skill_dir = os.path.join(tempfile.gettempdir(), SKILL_NAME)
os.makedirs(skill_dir, exist_ok=True)          # 确保目录存在，不主动检查

config_path = os.path.join(skill_dir, 'biz_goods_ctx.json')   # 示例文件名：<表名>_ctx.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）。 文件名建议使用 <表名>_<步骤>.json（如 biz_goods_ctx.json / biz_goods_alter.json），无需重复技能前缀，因路径已包含技能名称，便于排错。

❌ 禁止：

• 写到 <skill>/tmp/ 或当前工作目录（污染 skill / 用户项目）
• 硬编码 /tmp、C:\Temp 或任何固定路径（不跨平台）
• 每步完成后主动 rm / Remove-Item（操作系统会清理，属多余 tool call）
• 主动 os.path.exists() 检查（其本身即为一次 tool call） （使用 os.makedirs(…, exist_ok=True) 满足需求，不算主动检查）

临时文件可能被操作系统异步清理，但仍遵循 乐观调用 + 报错补救：仅当脚本返回 FileNotFoundError 或 配置文件不存在 时，使用相同内容、在相同的 {系统临时目录}/jeecg-codegen-new/ 路径下重写（重写前仍需 os.makedirs(skill_dir, exist_ok=True) 确保目录存在），切勿更换路径或回退至 skill 目录。

Step 4 — 处理特殊需求（模板没覆盖的部分）

用户的需求经常超出模板能力（比如"商品名要带前缀生成""价格变更后自动算总价""列表行加复制按钮"），这时：

1. 先跑脚本生成基础代码
2. 再用 Read 读出对应文件、用 Edit 做精细修改
3. 不要改 templates/，永远改产物

常见的特殊需求与改动位置参考 references/post-edit-recipes.md。

Step 5 — 后续操作

• Flyway SQL：脚本已落到 <flyway-dir>/V<date>_1__menu_insert_<entity>.sql，重启后端时 Flyway 自动执行；如果用户要求立即生效，按"本地自动执行 SQL"流程做（见下方）。
• 重启后端：提示用户 mvn spring-boot:run -pl jeecg-module-system/jeecg-system-start
• 前端热更新：pnpm dev 自动热更，无需重启
• 菜单可见：默认授权 admin，登录系统直接可见

字段语义推导

新建表时，AI 需要把用户描述的字段（如"价格"、"备注"）映射到合适的 classType / fieldDbType / fieldType。映射表见 references/field-mapping.md。

已有表场景下，从 DDL 直接读类型，不依赖语义推导。

已有表反向生成

用户给了表名 → 必须先查数据库取 DDL 再构造 ctx：

# 询问用户目标数据库名后，一条命令拿全部信息
mysql --no-defaults --default-character-set=utf8mb4 -h127.0.0.1 -P3306 -uroot -proot {dbname} \
  -e "SHOW CREATE TABLE 表名\G" \
  -e "SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_COMMENT, COLUMN_KEY, EXTRA FROM information_schema.COLUMNS WHERE TABLE_SCHEMA='{dbname}' AND TABLE_NAME='表名' ORDER BY ORDINAL_POSITION"

⛔ 执行任何 SQL 前必须先询问用户目标数据库名，不要从 application-dev.yml 自动取——用户本机可能多库并存。

字典自动匹配

用户开启后，先查全部字典：

mysql ... -e "
SELECT d.dict_code, d.dict_name,
       GROUP_CONCAT(i.item_text, '=', i.item_value ORDER BY i.sort_order SEPARATOR ', ') AS items
FROM sys_dict d LEFT JOIN sys_dict_item i ON d.id = i.dict_id AND i.status = 1
WHERE d.del_flag = 0 GROUP BY d.dict_code, d.dict_name ORDER BY d.dict_code"

匹配优先级：用户明确指定 > 字段名等于 dict_code > 注释关键词命中 dict_name > 不匹配。

匹配后在 ctx 的 column 上设置 classType: "list" + dictField: "<dict_code>"，模板会自动展开成 @Dict + JDictSelectTag + dataIndex: "fieldName_dictText" 等完整代码。

更详细见 references/dict-matching.md。

本地自动执行菜单 SQL（仅 127.0.0.1 / localhost）

用户确认目标数据库后：

# 1. 检查主菜单是否已存在（避免重复插入）
mysql ... -e "SELECT id FROM sys_permission WHERE name='<描述>' AND parent_id IS NULL"
# 2. 不存在则执行
mysql ... < <flyway_sql_file_path>

执行失败时只提示，不中断流程——Flyway 文件已落地，下次重启会自动执行。

增量修改（加 / 删 / 改字段）

所有"模板已生成的代码 + 用户后续小调整"都走 Edit，不重新跑脚本。

Step A — 定位文件

# Entity
find <b