lan-low-code-cli 0.0.0-stage → 2.1.0

package/README.md

@@ -1,3 +1,814 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# low-code-cli（`llc`）
+
+低代码表单引擎命令行工具。在 Node 端**独立实现**，不依赖任何前端包（`@ekp-infra/*`、`@ekp-runtime/*`、`@lui/*`），
+直接组装数据并调用后台接口，支持：
+
+- **创建表单**：覆盖 6 种表单类型（普通 / 审批意见 / 全局配置项 / 弹窗 / 通用 / 引用者）
+- **自动获取可用字段**：表单数据模型字段、外部映射表字段、字段库
+- **自动完善表单字段**：依据数据模型自动生成完整表单配置（`fdConfig`：字段控件 + 场景 viewModel + 权限 + 多语言 + 全局规则）并保存
+
+## 一、安装与构建
+
+本项目**使用 pnpm 管理依赖**（`package.json` 已声明 `packageManager: pnpm@10.26.2`）。
+
+```bash
+cd D:\project\aiWork\low-code-cli
+
+# 若本机未安装 pnpm：node -v >= 16 时可直接启用 corepack
+corepack enable
+
+pnpm install          # 安装依赖（会自动执行 prepare -> build）
+pnpm build            # 构建
+pnpm link --global    # 可选：全局注册 llc 命令
+```
+
+> 请勿混用 npm/yarn，以免生成多余的 `package-lock.json` / `yarn.lock`。
+> 常用脚本：`pnpm build`、`pnpm typecheck`、`pnpm start`、`pnpm run rebuild`（clean + build，注意 `pnpm rebuild` 是 pnpm 内置命令，脚本需用 `pnpm run rebuild`）。
+> 非交互式 CI 可使用 `pnpm install --frozen-lockfile`。
+
+## 二、鉴权与服务端地址
+
+请求头统一携带 `X-AUTH-TOKEN`，服务端基址由用户提供。三种配置方式，优先级从高到低：
+
+| 方式 | 示例 |
+|---|---|
+| 命令行参数 | `--base-url <url> --token <token>` |
+| 环境变量 | `LLC_BASE_URL` / `LLC_TOKEN` |
+| 配置文件 | `llc config set`（写入 `~/.lcode/config.json`）或项目根目录 `lcode.config.json` |
+
+```bash
+llc config set --base-url http://mkdev01.ywork.me/data --token <X-AUTH-TOKEN>
+llc config show
+```
+
+> `baseUrl` 需包含 `/data` 前缀。完整请求地址 = `${baseUrl}/sys-xform/<module>/<method>`。
+
+## 三、命令一览
+
+### 创建表单
+
+```bash
+llc form create --name <名称> [选项]
+```
+
+**所属应用**（低代码应用）决定表单挂在哪个应用下，是 `modeling` 接口族的核心参数：
+
+| 选项 | 说明 |
+|---|---|
+| `--app-id <appId>` | **表单所属应用 id**（应用主键 `fdId`）。给出后默认走 `modeling` 接口族，写入 `fdAppId` |
+| `--group-id <fdGroupId>` | 表单所属分组 id（`modeling` 族） |
+| `--edit-draft` / `--no-edit-draft` | 草稿状态是否允许编辑（`modeling` 族，默认允许） |
+| `--reader-flag` | 阅读者为空时所有人可阅读（`modeling` 族） |
+| `--data-source-id <id>` | 外部数据源 id（`modeling` 族） |
+| `--outer-mapping` | 是否映射外部表（`modeling` 族） |
+| `--fd-entity-id <id>` | 业务建模对应 appId / 应用模块对应 templateId（默认取 `--app-id`） |
+| `--fd-entity-name <name>` | 所属实体 model 名称（`modeling` 族由服务端固定写入，通常无需传） |
+| `--fd-entity-key <key>` | 实体扩展键（预留） |
+| `--fd-run-entity-name <name>` | 表单运行时实体名称 |
+| `--table-name <name>` | 主表名（不传则调用对应接口自动生成） |
+
+其余选项：
+
+| 选项 | 说明 |
+|---|---|
+| `--name <name>` | 表单名称（必填） |
+| `--code <code>` | 业务编码，默认 `template_xxxxxx` |
+| `--type <type>` | 表单类型：`common` \| `general`（默认）\| `config` \| `modal` \| `template` \| `refer`，也可用 1-6 |
+| `--api <family>` | 接口族：`auto`（默认）\| `modeling` \| `general` \| `design`，见下节 |
+| `--source-form-id <fdId>` | 引用源表单 id（`type=refer` 必填） |
+| `--category <fdId>` | 表单分类 id（`general` 族） |
+| `--icon <icon>` | 页面图标（图标名或图标 JSON）。**必填语义**：不给则使用内置默认图标 |
+| `--readers <ids>` / `--editors <ids>` | 可阅读者 / 可编辑者，逗号分隔（`general` 族） |
+| `--mechanism-entity-name <name>` | 机制实体名（决定可用控件库），默认按接口族推导 |
+| `--mechanism-entity-code <code>` | 机制编码，默认按接口族推导 |
+| `--from-model <fdId>` | 从指定数据模型拷贝字段（默认用新表单自身数据模型） |
+| `--fields <names>` | 仅生成指定字段，逗号分隔 |
+| `--add-field <spec>` | **新增/调整字段**，格式 `name:label[:dataType\|controlType[:controlType]]`，可重复；见「控件类型」章节 |
+| `--option <spec>` | 为下拉/单选/多选**新建选项**：`"字段名=选项1,选项2:值2"`，可重复 |
+| `--detail <spec>` | **新建/调整明细表**：`"明细表标题=字段1:标题1[:控件类型],..."`，可重复，见「明细表」章节 |
+| `--include-system` | 同时把系统字段渲染到表单上（默认只渲染业务字段） |
+| `--per-row <n>` | 每行控件数，默认 2 |
+| `--span <n>` | 控件栅格宽度，默认 12 |
+| `--locale <locales>` | 多语言，逗号分隔，**第一个为主语言**（默认 `Cn`）；`all` = `Cn,Us,Tw` |
+| `--lang-file <path>` | 多语言文案文件（JSON），见「多语言」章节 |
+| `--layout <mode>` | 渲染布局：`rows`（默认）\| `grid` 栅格 \| `tabs` 多页签，见「布局」章节 |
+| `--grid-columns <n>` | 栅格列数（`--layout grid`，默认取 `--per-row`） |
+| `--tabs <spec>` | 多页签定义：`"标题:字段1,字段2\|标题2:字段3"`（`--layout tabs`） |
+| `--tab-layout <mode>` | 页签内层布局：`rows`（默认）\| `grid` 栅格，可组合出「页签 + 栅格」的嵌套结构 |
+| `--required <fields>` | 必填字段（逗号分隔，作用于 `add`/`edit`） |
+| `--readonly <fields>` | 只读字段（逗号分隔，`editable=false`，作用于 `add`/`edit`） |
+| `--hidden <fields>` | 隐藏字段（逗号分隔，`visible=false`，作用于 `add`/`edit`/`view`） |
+| `--auth-file <path>` | 精细字段权限（JSON），见「字段权限」章节 |
+| `--action <spec>` | 控件动作：`"字段名:事件:函数源码或@js文件"`，可重复；全局动作用 `$global`，见「控件动作」章节 |
+| `--action-file <path>` | 控件动作定义文件（JSON），见「控件动作」章节 |
+| `--no-config` | 仅创建空表单，不生成字段配置 |
+| `--publish` | 创建后立即发布 |
+| `--dry-run` | 只打印将提交的数据，不发起请求 |
+
+### 接口族与表单类型的对应关系（重要）
+
+后端 `SysGeneralFormDefineService` 对类型有强校验：
+
+```java
+case add:
+case update:
+    if (!Objects.equals(formDefinedVO.getFdFormDefineType(), FormDefineType.General)) {
+        throw new ParamsNotValidException();
+    }
+```
+
+即 `generalFormDefine/*` **只能建审批意见表单**。CLI 提供三种接口族：
+
+| 接口族 | 适用场景 | 接口链路 |
+|---|---|---|
+| `modeling` | **低代码应用下建表单（推荐）** | `sysModelingXForm/generateTableName` → `create` → `saveDesign`（或 `saveDesignAndPublish`） |
+| `general` | 审批意见表单（后台"表单管理"） | `generalFormDefine/init` → `add` → `save` → `publish` |
+| `design` | 表单引擎原始接口，任意类型 | `sysXFormDesign/create` → `save` → `publish` |
+
+`--api auto`（默认）的选择规则：
+
+1. 给了 `--app-id` → `modeling`（应用下建表单）
+2. 否则 `--type general` → `general`
+3. 其余 → `design`
+
+显式指定与类型冲突的组合会被直接拦截（如 `--type common --api general`）。
+
+### 各接口族的关键差异
+
+| | `modeling` | `general` | `design` |
+|---|---|---|---|
+| 表单归属 | `fdAppId`（`modeling_xform.fd_app_id` 外键） | 独立定义表 | 表单设计表 |
+| `fdEntityName` | 服务端写死 `sys-modeling` | `init` 返回 `...SysGeneralFormDefine` | 需自行指定 |
+| `fdRunEntityName` | 服务端写死 `sys-modeling` | `init` 返回 | 需自行指定 |
+| `fdEntityId` | 服务端写死 = 表单 id | `init` 返回 = 表单 id | 需自行指定 |
+| 表名规则 | `mk_model_yyyyMMdd` + 随机 5 位 | 服务端生成 | `sysXFormDataModel/generateTableName` |
+| 发布 | `saveDesignAndPublish`（含发布校验与默认视图） | `publish` | `publish`（`XFormDesignPushVO`） |
+
+机制默认值：`general` 族 → `sys-xform` / `...SysGeneralFormDefine`；`modeling` 与 `design` 族 → `sys-modeling` / `...SysModelingMainEntity`（可用 `--mechanism-entity-*` 覆盖）。
+
+### 应用（创建 / 查询 / 修改 / 删除）
+
+```bash
+llc app list                  # 列出应用，返回的 fdId 即 --app-id
+llc app list --keyword 请假    # 按名称搜索
+llc app list --no-auth        # 使用不做权限校验的接口（sysModelingApplication/listNotAuth）
+llc app get --id <appId>      # 查看详情（含可访问者/可维护者）
+
+# 新建应用（后端会同时创建默认首页）
+llc app create --name 客户管理 --code crm --desc 客户全生命周期 --icon iconCommon_line_16_file
+
+# 修改应用（只传需要改的项；不会丢失可访问者/可维护者）
+llc app update --id <appId> --name 客户管理2.0 --desc 新描述
+
+# 删除应用（连带其下表单，需 --yes 确认）
+llc app delete --id <appId> --yes
+llc app delete-data --id <appId> --yes   # 只清业务数据，保留应用
+```
+
+> 应用编码 `--code` 只允许**字母/数字/连字符**（平台校验 `^[a-zA-Z-0-9]*$`），不能使用下划线；CLI 会本地预校验。
+
+### 删除表单
+
+```bash
+llc form delete --id <fdId> --yes        # 删除表单（连同数据模型，需 --yes）
+llc form delete-data --id <fdId> --yes   # 只删运行时业务数据，保留表单定义
+```
+
+### 获取可用字段
+
+```bash
+llc field list --form-id <fdId>     # 表单已有字段（数据模型）
+llc field list --model-id <fdId>    # 指定数据模型字段
+llc field list --table <tableName>  # 外部映射表字段
+llc field library [--keyword <kw>]  # 字段库
+llc field gen-key --name <名称>      # 生成字段编码
+```
+
+### 控件类型
+
+**先查环境再选控件**：
+
+`ash
+llc control list                      # 列出环境全部可用控件（含桌面/移动端包、数据项类型、是否登记、是否支持选项）
+llc control list --all                # 含布局/外观类
+llc control show --type moneytext     # 查看某控件的属性面板配置项与默认值
+llc control show --element @elem/xform-select --json
+`
+
+control list 的数据源是 {origin}/web/sys/artifact/elements/index.json + 各控件 config.json（首次运行会逐个拉取并落盘缓存，之后秒回）；已登记 表示可直接用于 --add-field，支持选项 表示可用 --option（dictType=optionDict）。
+
+`--add-field` 的第三个 token 既可写**数据项类型**（`varchar`/`number`/…），
+也可直接写**控件类型**（`moneytext`/`select`/…），第四 token 为控件类型：
+
+```bash
+--add-field "fd_a:项目名称"                 # 默认单行文本
+--add-field "fd_b:预算金额:moneytext"       # 按控件类型
+--add-field "fd_c:评分:number:rate"         # 数据项类型 + 控件类型
+```
+
+**若字段名已存在，则视为「调整该字段」**：覆盖其标题与控件类型，保留 `fdId`、`fdOrder` 等，
+因此可以对既有表单做控件替换（`llc form autofill --add-field "fd_amt:预算金额:moneytext" --apply`）。
+
+支持的全部控件（`src/constants.ts#CONTROL_TYPE_MAP`，均经真实环境 `config.json` 的
+`xform.type` 成对校验；无移动端包的控件回落为桌面端包，与平台 `platform=all` 行为一致）：
+
+| 分类 | 控件类型 |
+|---|---|
+| 文本 | `text`、`textarea`、`rich-text`、`upcasing`、`phoneNumber`、`hyperlinks` |
+| 数值 | `numbertext`、`moneytext`、`rate`、`slider`、`timepicker`、`daterange` |
+| 选择 | `select`、`radio`、`checkbox`（均支持 `--option` 配选项） |
+| 日期 | `timestamp`、`timeZone` |
+| 组织/地址 | `address` |
+| 附件/媒体 | `attachment`、`image`、`video` |
+| 编码/码图 | `barcode`、`qrcode` |
+| 其它 | `switch`、`hidden`、`dividing`、`subject`、`relation`、`relationQuery` |
+
+`--option` 为选择类控件建选项，写入 `controlProps.options` 与 `fdFontExtendData.options`，
+并生成 `prop:'option'` 的多语言条目：
+
+```bash
+--option "fd_col_level=高:high,中:mid,低:low"
+--option "fd_col_type=研发:rd,实施:impl,运维:ops"     # 省略值则按 1..n
+```
+
+### 明细表
+
+```bash
+llc form autofill --id <fdId> --apply --publish \
+  --detail "设备清单=fd_sname:设备名称,fd_scount:设备数量:numbertext,fd_sstatus:设备状态:select" \
+  --detail "人员明细=fd_pname:姓名,fd_pwork:是否在职:switch" \
+  --option "fd_sstatus=在用,报废,维修中" \
+  --required "fd_sname,fd_pname"
+```
+
+明细表会生成**一整个子数据模型**（`fdType:'detail'`），落库位置：
+
+| 位置 | 内容 |
+|---|---|
+| `dataModel` | 新增一个 detail 模型：`fdId` 来自 `sysXFormDataModel/getSystemDefaultModel`，表名来自 `generateTableName({fdType:'detail'})`，系统字段 `fd_id`/`fd_main_id`/`fd_order`，`fdAttribute` 为明细表控件配置 |
+| `view.render.desktop` | `main` 末尾追加独立行（span 24）：`row → { key:<明细表名>, children:[明细字段引用] }` |
+| `view.render.mobile` | 平铺追加明细表节点与字段引用 |
+| `view.controlMappings` | 追加 `@elem/xform-detail-table` / `@elem/xform-m-detail-table`（**明细表控件需要进 mappings**） |
+| `view.controlStyle` | 明细表自身条目（desktop + mobile）；**明细字段不需要** |
+| `auth` | 按表名新增条目：`add/edit` 带 `canAddRow/canDeleteRow/canImport` 与行操作，`view` 带 `canExport` |
+| `lang` | 明细表标题（`prop:'label'`，含 `default`）与明细字段标题/占位/选项 |
+
+要点：
+
+- **再次执行 `--detail` 同名标题会复用已有明细表**（保留 `fdId`、系统字段与已有列），可继续调整字段；
+  不传 `--detail` 时已有明细表原样保留。
+- 明细字段的控件类型、选项、权限与主表字段完全一致（`--option`/`--required`/`--readonly`/`--hidden`
+  对明细字段同样生效，按字段名匹配）。
+- 明细表控件的默认属性（`mode`/`defaultRowNumber`/`showNumber`/`showRowSelection` 等）
+  **不在** `config.json` 里，而由前端写死；CLI 按 `src/constants.ts#DETAIL_CONTROL_DEFAULTS` 复刻。
+
+### 布局
+
+`--layout` 决定 `viewModel.view.render.desktop` 的结构。**移动端始终是平铺的字段引用**
+（实测真实表单的 `render.mobile` 不含任何布局容器），因此布局只影响桌面端。
+
+| `--layout` | 桌面端结构 | 真实样本依据 |
+|---|---|---|
+| `rows`（默认） | `main` → 若干 `@elem/xform-row` → 字段引用 | ✔ |
+| `grid` | `main` → `layout` → `@elem/layout-grid` → 若干 `@elem/layout-grid.GridItem` → 字段引用 | ✔ |
+| `tabs` | `main` → `@elem/xform-tabs` → 若干 `@elem/xform-tabpane` → `@elem/xform-row` → 字段引用 | ✔ |
+
+要点（均为真实表单核对结论）：
+
+- **栅格布局控件不进 `controlMappings`**；**多页签控件必须进**（`tab-appearance` / `tabs` / `tabpane` 三件套）。
+- 多页签的 key 约定：外观 key 形如 `@elem/xform-tab-appearance~xxxxxx`，
+  tabs 节点 key 为 `<外观key>-tabItem`，面板为 `<外观key>-tabN`，
+  且 `controlProps.parent = { name: '@elem/xform-tab-appearance', type: 'appearance' }`。
+  渲染树中**没有**独立的 `tab-appearance` 节点。
+- 页签标题走多语言：`controlProps.tabMessageKey`，
+  对应 `lang[..] = { prop:'tabs', name:<字段名>, type:'input', content:{ Cn, Us, Tw, default } }`。
+- `--tabs` 未列出的字段会**自动归入末尾的「其它」页**；未提供 `--tabs` 时全部字段进单个「其它」页。
+
+```bash
+llc form create --name 复杂表单 --app-id <appId> --layout tabs \
+  --tabs "基本信息:fd_col_a,fd_col_b|金额信息:fd_col_c,fd_col_d" \
+  --add-field "fd_col_a:姓名" --add-field "fd_col_b:部门" \
+  --add-field "fd_col_c:金额:number" --add-field "fd_col_d:日期:timestamp" \
+  --publish
+```
+
+### 字段权限（必填 / 可见 / 只读）
+
+对应控件属性面板的「字段权限」（各控件 `config.json` 的
+`controlGroup > fieldPermission > { required, editable, visible }`），
+落库位置是 `auth[0].{add|edit|view}[表名].fields[字段名]`：
+
+```json
+{ "visible": true, "editable": true, "required": false, "hide": false }
+```
+
+快捷参数：
+
+| 参数 | 写入 |
+|---|---|
+| `--required <fields>` | `add` / `edit` 的 `required: true` |
+| `--readonly <fields>` | `add` / `edit` 的 `editable: false` |
+| `--hidden <fields>` | `add` / `edit` / `view` 的 `visible: false` |
+
+精细控制用 `--auth-file`：
+
+```json
+{
+  "add":  { "fd_col_a": { "required": true } },
+  "edit": { "fd_col_b": { "visible": false }, "fd_col_c": { "editable": false } },
+  "view": { "fd_col_d": { "visible": false } }
+}
+```
+
+> 注意：`--required` 写入的是**权限**（`auth`），不是数据项本身。
+> 数据项的「是否显示」是 `fdDisplay`，本 CLI 默认只把业务字段渲染成控件，不写 `fdDisplay`。
+
+### 多语言
+
+表单标题、控件提示等文案统一存放在 `fdConfig.lang` 中，key 形如 `!{mv0dg6b08kjn1fost7o}`。
+
+#### 1. messageKey 格式（重要）
+
+前端识别多语言标记的正则是 `/\!\{([\w\.]*)\}/gi`，`\w` = `[A-Za-z0-9_]`，**不含连字符**。
+key 主体必须与前端 `sys-xform/src/util/runtimeUtil.ts#uuid` 一致：
+
+```ts
+Date.now().toString(36) + Math.random().toString(36).slice(2)   // 纯 base36
+```
+
+CLI 已按此实现（`src/utils/random.ts#generateMessageKey`），并对历史非法 key 自动重建。
+
+#### 2. 语言解析顺序
+
+`sys-xform/src/components/runtime/utils.ts` 的规则是 `content[当前语言] → content['Cn']`。
+因此只写 `Cn` 时任何语言的用户都能看到中文兜底；要展示真实翻译需显式开启多语言。
+
+#### 3. 用法
+
+```bash
+# 只写中文（默认）
+llc form create --name 请假单 --type general
+
+# 同时写入 简体/英文/繁体（两者等价）
+llc form create --name 请假单 --type general --locale Cn,Us,Tw
+llc form create --name 请假单 --type general --locale all
+
+# 提供真实翻译
+llc form create --name 请假单 --type general --locale Cn,Us --lang-file ./lang.json
+```
+
+`lang.json` 结构：
+
+```json
+{
+  "Us": { "姓名": "Name", "金额": "Amount", "请输入": "Please enter" },
+  "Tw": { "金额": "金額" }
+}
+```
+
+非主语言的取值优先级：
+
+| 顺序 | 来源 | 说明 |
+|---|---|---|
+| 1 | `--lang-file` | 用户翻译，按「字段标题」再按「字段物理名」匹配 |
+| 2 | 控件自带译文 | 从控件多语言资源接口取（如英文 placeholder `Please enter`） |
+| 3 | 主语言文案 | 兜底，与前端 `ide-model/business/input/inputLocale.tsx` 行为一致 |
+
+第 3 条保证不会出现空白标题；语言码大小写自动归一（`us` / `US` → `Us`）。
+`--locale` / `--lang-file` 同样适用于 `llc form autofill`。
+
+#### 4. 覆盖范围
+
+| `lang[].prop` | 对应文案 | 是否由 CLI 生成 |
+|---|---|---|
+| `label` | 字段标题 | 是 |
+| `placeholder` | 控件输入提示 | 是 |
+| `option` | 下拉 / 单选 / 多选的**选项文案** | 是（已有选项时完善） |
+
+选项多语言的落库结构（与真实环境数据一致）：
+
+```
+lang["!{xxx}"]                        = { prop:'option', name:<fdName>, type:'input', content:{ Cn:'选项1' } }
+fdAttribute…controlProps.options[]    = { label:'!{xxx}', value:'1' }
+fdFontExtendData.options[]            = { messageKey:'!{xxx}', label:'选项1', value:'1', … }
+```
+
+要点：
+
+- **选项必须先存在**。CLI 不会凭空创建选项；选项由数据项管理 / 设计器 / Excel 导入向导配置，
+  CLI 负责把它们的文案补成多语言（并保留 `colorSwitch`、`type`、`value` 等原有字段）。
+- **数据字典选项会被跳过**。`messageKey` 形如 `${sys-xform:enum.X}` / `sys-xform:enum.X`
+  的选项走平台静态多语言资源，写入 `lang` 反而会污染，因此原样保留。
+- 选项的 `--lang-file` 匹配支持两种 key：**选项文案**（如 `选项1`）与
+  **`字段名#选项值`**（如 `fd_col_x#2`，用于多个选项文案重复时的精确匹配）。
+
+### 控件动作（onChange / onLoad 等）
+
+许多控件支持配置动作。动作存放于 `fdConfig.attribute.formAttr.controlAction`（真实表单结构已核对）：
+
+```
+controlAction.control['<表名>.<控件uuid>'][<事件>] = [{ name, id, function }]
+controlAction.global[<事件>]                      = [{ name, id, function }]
+controlAction.javascript                          = 所有函数源码拼接（设计器 JS 面板按此展示）
+```
+
+`function` 是**函数源码字符串**，运行时经
+`new Function('MKXFORM', 'return (' + source + ')')` 求值后挂到控件的
+`controlProps.controlActions[事件]`（`sys-xform/src/components/runtime/business/action.ts`）。
+
+#### 1. 两种写法
+
+```bash
+# 内联源码（可重复）
+llc form autofill --id <fdId> --apply --publish \
+  --action "fd_col_a:onChange:function onChange(value){ MKXFORM.setValue('fd_col_b', value) }"
+
+# 复杂函数建议放 js 文件（@开头）
+llc form autofill --id <fdId> --apply --publish --action "fd_col_a:onChange:@./on-change.js"
+```
+
+或用 JSON 文件（适合多条 / 全局动作）：
+
+```bash
+llc form autofill --id <fdId> --apply --publish --action-file ./actions.json
+```
+
+`actions.json`：
+
+```json
+{
+  "fd_col_a": { "onChange": "function onChange(value){ … }" },
+  "$global":  { "onLoad": "function onLoad(){ … }" }
+}
+```
+
+也支持数组形式：`[{ "target": "fd_col_a", "event": "onChange", "source": "…", "name": "可选函数名" }]`。
+
+#### 2. 规则与边界
+
+| 项 | 说明 |
+|---|---|
+| 目标 | 字段物理名（`fd_col_a`）；`$global` 为全局动作，仅支持 `onLoad` / `onBeforeSubmit` / `onAfterSubmit` |
+| 控件级事件 | 任意标识符（`onChange` / `onFocus` / `onBlur`…），运行时按控件实际支持的事件触发 |
+| 函数签名 | 控件级 `function onChange(value, rowNum)`（value 当前值，rowNum 明细行号）；运行时闭包内可用 `MKXFORM`（如 `MKXFORM.setValue('表名.字段名', v)`） |
+| key | `表名.控件uuid`（与运行时 `addActionToControlProps` 的查找规则一致）；明细表字段同样适用 |
+| 函数重名 | 自动追加随机后缀（与前端 `mergeControlAction` 行为一致） |
+| 函数命名 | 控件级动作禁止裸事件名（`onChange` 等）——CLI 自动规范为 `onChange_<控件id>` 并同步重写函数源码声明；`$global` 全局动作保持裸事件名（如 `onLoad`） |
+| 目标字段不存在 | 跳过并告警，不阻断 |
+| 已有动作 | **保留**。`autofill` 会加载已有 `formAttr` 合并写入，不会清掉设计器里配置的动作/表单规则 |
+
+`form create` 同样支持 `--action` / `--action-file`。
+
+### 查询环境语言
+
+```bash
+llc locale list
+llc locale list --element @elem/xform-select --json
+```
+
+数据源是控件多语言资源接口 `POST {baseUrl}/sys-lang/getFrontResource`
+（`path=sys/artifact/elements/i18n`），其响应的 `data[0].data` 按**原始语言码**（`zh-cn`）分组：
+
+```
+环境为「@elem/xform-input」提供的语言（共 1 个）
+  zh-cn      -> Cn     请输入
+可直接用于 --locale 的取值
+  Cn
+```
+
+用途是回答「**哪些语言有现成译文**」——这些语言在 `--locale` 里能自动填上真实译文（如英文 placeholder）。
+环境**配置的**语言全集（前端 `mk.getUserConfig('allLocales')`）未暴露后端接口，如需其它语言请直接 `--locale` 指定。
+
+### 控件必填属性校验（发布前）
+
+CLI 在 `form create` / `form autofill` 保存前会校验**控件必填属性值**，规则对齐设计器
+（`formBuilderHelper` 必填规则 + 发布时 `validates.validating()` 阻断）：
+
+- 校验对象：控件 `config.json` 属性面板中满足
+  `required && !disabled && !protected && !slotScope` 的**叶子属性项**；
+- 值为空（`undefined/null/''/空数组`）即报错，格式 `请输入<label>（key）`；
+- 与设计器一致地跳过：带 `enableWhen`/`hidden` 的条件渲染项（未渲染不校验）、
+  分组容器（baseGroup/styleGroup 等）、`inputLocale` 类标题项（取 `title` 值）；
+- 校验失败默认**中止保存/发布**（预览模式仅提示）；加 `--force` 可跳过。
+
+```bash
+llc form autofill --id <fdId> --apply --publish            # 校验失败会中止
+llc form autofill --id <fdId> --apply --publish --force    # 跳过校验
+```
+
+**必填属性兜底默认值**：部分控件声明了必填属性但无默认值（设计器中靠用户填写），
+CLI 按 `src/constants.ts#REQUIRED_PROP_DEFAULTS` 自动补齐，
+取值来自设计器创建表单的实测值或控件约定：
+
+| 控件 | 属性 | 默认值 |
+|---|---|---|
+| textarea | height | `"3"`（3 行，设计器实测） |
+| address | org / multi | `{"orgTypeArr":["8"],…}` / `false`（设计器实测） |
+| rate | max | `5` |
+| slider | min / max | `0` / `100` |
+| rich-text | height | `300`（config.json min 200） |
+| bar-code | height | `80` |
+| hyperlinks | largestSet | `"infinit"`（选项首项） |
+
+例外：`upcasing.relationControl`（联动控件）是语义性选择，CLI 不兜底；
+未指定时校验会拦截，需显式给出（存于 `fdFontExtendData.relationControl = {fdName, fdLabel}`）。
+
+**条件必填**：带 `enableWhen` 的属性项按条件判定——条件为「键 = 简单值」且在 `controlProps` 中成立时才校验
+（如 datetime 的 `defaultValueType='formula'` 时公式配置 `defaultValueFormulaVO` 必填）；
+条件不成立或为复杂表达式时跳过，与设计器一致。
+
+**初始值模式**：新建字段 `defaultValueType` 默认为 `null`（无初始值），与控件 `config.json` 默认一致；
+不要写 `formula`——公式模式下 `defaultValueFormulaVO` 必填，设计器提交会被拦截。
+若需要公式初始值，按以下结构写入 `fdFontExtendData`（迁移自前端 `dataMigration.ts`）：
+
+```json
+{
+  "defaultValueType": "formula",
+  "defaultValueFormulaVO": { "script": "\"2026-01-01\"", "type": "Eval", "vo": { "mode": "formula", "content": "2026-01-01" } }
+}
+```
+另：`labelProps.layout` 默认写入 `horizontal`（左右布局）、`labelTextAlign: 'left'`；
+如需上下布局可在生成后调整或后续提供选项。
+
+### 自动完善表单字段
+
+> **布局保护**：`autofill` 不带 `--layout` 时会**沿用已有视图**——设计器里的栅格布局、
+> 多页签等布局不会被动过；同时保留已配置的控件动作（`controlAction`）与表单规则。
+> 显式传入 `--layout`（如 `--layout grid --grid-columns 3`）才会按参数重建布局。
+> 通过 `--add-field` 新增的字段不在旧布局中，保存时会告警提示，需显式 `--layout` 才会展示。
+
+```bash
+# 预览（不写入）
+llc form autofill --id <fdId>
+
+# 确认后写入
+llc form autofill --id <fdId> --apply
+```
+
+`autofill` 支持与 `create` 相同的 `--add-field` / `--include-system` / `--icon` / `--fields` / `--per-row` / `--span` 选项，
+同样会重建每个字段的 `fdAttribute.config`、`view.controlMappings` 与多语言（`lang`）。
+
+> `saveDesign` 会把表单置为**草稿态**。修复已发布表单时请加 `--publish`（`modeling` 族会走 `saveDesignAndPublish`）。
+> 不加 `--publish` 且原状态为 `official` 时会给出提示。
+它会先尝试 `sysModelingXForm/loadBase`，命中则按 `modeling` 族处理；否则读取表单的 `fdFormDefineType` 自动在 `general` / `design` 之间选择。
+
+> 若表单是早期版本 CLI 生成的（缺少 `fdAttribute.config` / 渲染节点不是 `{key}` 引用），
+> 执行一次 `llc form autofill --id <fdId> --apply` 即可修复为可加载格式。
+
+### 其他
+
+```bash
+llc app list [--keyword <name>]
+llc form list [--keyword <kw>]
+llc form get --id <fdId> [--with-config]
+llc form publish --id <fdId> [--api modeling|general|design] [--desc <说明>]
+llc form category-list
+llc config show | set | clear
+```
+
+## 四、调用的后台接口
+
+| 功能 | 接口 |
+|---|---|
+| 控件多语言资源（语言探测） | `POST sys-lang/getFrontResource` |
+| 应用新建（含默认首页） | `POST sys-modeling/sysModelingApplication/add` |
+| 应用编辑页数据 | `POST sys-modeling/sysModelingApplication/edit` |
+| 应用修改 | `POST sys-modeling/sysModelingApplication/update` |
+| 应用删除 | `POST sys-modeling/sysModelingApplication/delete` |
+| 应用业务数据删除 | `POST sys-modeling/sysModelingApplication/deleteData` |
+| 表单删除 | `POST sys-modeling/sysModelingXForm/delete` |
+| 表单业务数据删除 | `POST sys-modeling/sysModelingXForm/deleteData` |
+| 【modeling 族】生成主表名 | `POST sys-modeling/sysModelingXForm/generateTableName` |
+| 【modeling 族】检查表名 | `POST sys-modeling/sysModelingXForm/checkTableNameExist` |
+| 【modeling 族】检查表单名 | `POST sys-modeling/sysModelingXForm/checkXFormNameExist` |
+| 【modeling 族】表单新建 | `POST sys-modeling/sysModelingXForm/create` |
+| 【modeling 族】保存设计 | `POST sys-modeling/sysModelingXForm/saveDesign` |
+| 【modeling 族】保存并发布 | `POST sys-modeling/sysModelingXForm/saveDesignAndPublish` |
+| 【modeling 族】发布 | `POST sys-modeling/sysModelingXForm/publish` |
+| 【modeling 族】加载设计 | `POST sys-modeling/sysModelingXForm/loadDesign` |
+| 【modeling 族】加载基本信息 | `POST sys-modeling/sysModelingXForm/loadBase` |
+| 【modeling 族】应用列表 | `POST sys-modeling/sysModelingApplication/list` |
+| 【modeling 族】应用列表（免权限） | `POST sys-modeling/sysModelingApplication/listNotAuth` |
+| 【general 族】表单初始化 | `POST sys-xform/generalFormDefine/init` |
+| 【general 族】表单新建 | `POST sys-xform/generalFormDefine/add` |
+| 【general 族】表单加载 | `POST sys-xform/generalFormDefine/get` |
+| 【general 族】表单保存 | `POST sys-xform/generalFormDefine/save` |
+| 【general 族】表单发布 | `POST sys-xform/generalFormDefine/publish` |
+| 【general 族】表单列表 | `POST sys-xform/generalFormDefine/list` |
+| 【design 族】表单新建 | `POST sys-xform/sysXFormDesign/create` |
+| 【design 族】表单加载 | `POST sys-xform/sysXFormDesign/load` |
+| 【design 族】表单保存 | `POST sys-xform/sysXFormDesign/save` |
+| 【design 族】表单发布 | `POST sys-xform/sysXFormDesign/publish` |
+| 表单分类列表 | `POST sys-xform/generalFormCategory/list` |
+| 表单数据模型（字段） | `POST sys-xform/sysXFormDataModel/loadByFormId` |
+| 数据模型字段 | `POST sys-xform/sysXFormDataModel/getModelFields` |
+| 数据模型（按 id） | `POST sys-xform/sysXFormDataModel/load` |
+| 主表名生成 | `POST sys-xform/sysXFormDataModel/generateTableName` |
+| 外部表字段 | `POST sys-xform/sysXFormDataModelField/loadFieldMeta` |
+| 字段库 | `POST sys-xform/sysXFormWordsField/list` |
+| 字段编码生成 | `POST sys-xform/sysXFormWordsField/generateFdKey` |
+
+## 五、生成的表单配置结构（`fdConfig`，**持久化格式**）
+
+> ⚠️ 表单引擎有**两套格式**：IDE 内存中的 form-builder 树 ≠ 落库格式。
+> CLI 必须生成后者，否则前端加载时控件无法还原。
+
+**落库格式的关键点**（由 `sys-xform/components/ide/store/viewModel/view/pureUtils.ts#getRenderLayout` 决定）：
+
+1. `view.render.*` 中，**控件节点被折叠为 `{ key: <uuid> }`**（容器节点保留 `key/type/kind/controlProps/children`）。
+2. 控件的真实定义放在 **`view.controlMappings`**（平台 → 控件包元数据）与**字段的 `fdAttribute.config`** 中。
+3. 前端加载时 `cacheConfig[attr.uuid] = attr.config`，再按 `{ key }` 回填 —— **`fdAttribute` 缺失或结构不符，控件就会丢失**。
+
+```jsonc
+{
+  "dataModel": [
+    {
+      "fdTableName": "mk_model_xxx",
+      "fdType": "main",
+      "fdFields": [
+        {
+          "fdName": "fd_col_text01",
+          "fdLabel": "单行文本",
+          "fdLabelLangKey": "!{...}",
+          "fdType": "text",
+          "fdDataType": "varchar",
+          "fdDictType": "textDict",
+          "fdLength": 200,
+          "fdIsSystem": false,
+          "fdDisplay": true,
+          "fdState": "effective",
+          "fdFontExtendData": "{\"passValue\":false,\"trace\":false,\"encrypt\":false,\"defaultValueType\":\"formula\",\"encryptDefinition\":{}}",
+          // ↓ 关键：控件配置唯一来源
+          "fdAttribute": "{\"uuid\":\"fd_col_text01\",\"env\":[\"xform\"],\"config\":{\"key\":\"@elem/xform-input~xxxxxx\",\"type\":\"text\",\"kind\":\"control\",\"label\":\"!{...}\",\"controlProps\":{\"aiFill\":false,\"showText\":false,\"passValue\":false,\"trace\":false,\"encrypt\":false,\"defaultValueType\":\"formula\",\"placeholder\":\"!{...}\",\"maskFormatType\":\"********\",\"encryptMonth\":9999,\"failureRule\":\"ANONYMIZE\",\"id\":\"@elem/xform-input~xxxxxx\",\"desktop\":{\"type\":\"@elem/xform-input\"},\"mobile\":{\"type\":\"@elem/xform-m-input\"},\"name\":\"fd_col_text01\",\"uuid\":\"fd_col_text01\",\"title\":\"!{...}\",\"span\":12,\"$$tableType\":\"main\",\"$$tableName\":\"mk_model_xxx\",\"maxLength\":200},\"labelProps\":{\"desktop\":{},\"mobile\":{},\"title\":\"!{...}\",\"showText\":false,\"trace\":false}}}"
+        }
+      ]
+    }
+  ],
+  "auth": [ /* 新增/编辑/查看 权限（按表按字段） */ ],
+  "attribute": { "formAttr": "{\"subjectRule\":{\"type\":\"Eval\",\"script\":\"${data.biz.fd_doc_subject}\",\"vo\":{\"mode\":\"formula\",\"content\":\"$<模型名>.<标题>$\"}},\"formRule\":{\"pattern\":{}},\"dataUnique\":{},\"controlAction\":{},\"currentTableName\":\"<主表名>\"}" },
+  "error": "{}",
+  "lang": "{ \"!{labelKey}\": {\"prop\":\"label\",\"name\":\"fd_col_text01\",\"type\":\"input\",\"content\":{\"Cn\":\"单行文本\"}}, \"!{phKey}\": {\"prop\":\"placeholder\",...} }",
+  "authFilter": { "detailAuthDefine": {} },
+  "extendMap": {},
+  "sign": { "formula": {} },
+  "viewModel": [
+    {
+      "fdCode": "SCENE_DEFAULT",
+      "fdName": "默认",
+      "fdStatus": "draft",
+      "fdLockMode": "none",
+      "fdOrder": 0,
+      "dynamicProps": {},
+      "needDelete": false,
+      // ↑ 同样是 JSON 字符串
+      "fdConfig": "{\"view\":{\"render\":{\"desktop\":[{\"key\":\"@elem/xform-appearance\",\"type\":\"@elem/xform-appearance\",\"kind\":\"container\",\"controlProps\":{\"$$tableName\":\"mk_model_xxx\"},\"children\":[{\"key\":\"main\",\"type\":\"main\",\"kind\":\"container\",\"children\":[{\"key\":\"@elem/xform-row~xxxxxx\",\"type\":\"@elem/xform-row\",\"kind\":\"container\",\"controlProps\":{\"id\":\"@elem/xform-row~xxxxxx\",\"spans\":[12]},\"children\":[{\"key\":\"fd_col_text01\"}]}]}]}],\"mobile\":[...]},\"controlMappings\":{\"desktop\":[{\"name\":\"@elem/xform-input\",\"platform\":\"desktop\",\"xform\":{\"type\":\"text\",\"dataType\":\"varchar\",\"dictType\":\"textDict\",\"span\":12,\"env\":[\"xform\"],...}}],\"mobile\":[{\"name\":\"@elem/xform-m-input\",...}]}},\"theme\":{\"desktop\":{\"name\":\"default\",\"status\":\"done\",\"viewAttr\":{...}},\"mobile\":{...}},\"controlStyle\":{\"fd_col_text01\":{\"desktop\":{...}}}}"
+    }
+  ]
+}
+```
+
+要点：
+- 外层 `fdConfig`、内层 `viewModel[].fdConfig`、`lang`、`error` 都是 JSON **字符串**。
+- 渲染树为 `@elem/xform-appearance` → `main` → `@elem/xform-row` → `{ key: <uuid> }`。
+- 系统字段（`fdIsSystem: true`）默认**不渲染**到表单上，可用 `--include-system` 打开。
+- `id/name/tableName/entityName/entityCode` 会被后端 `DesginConfigVO` 丢弃，前端加载 IDE 时从 VO 回填（正常行为）。
+
+### 新增字段
+
+```bash
+llc form create --name 请假单 --app-id <appId> --add-field "fd_col_text01:单行文本" --publish
+```
+
+`--add-field` 格式：`name:label[:dataType[:controlType]]`，可重复。只给 label 时自动生成 `fd_col_xxxxxx`。
+字段会写入 `dataModel[].fdFields`，发布时由后端创建真实数据库列。
+
+## 六、控件元数据与类型映射
+
+控件类型/字典类型/默认长度/默认属性等**不来自静态映射表**，而是运行时读取控件包的 `config.json`：
+
+```
+{origin}/web/sys/artifact/elements/{pkg}/config.json
+  例：http://host/web/sys/artifact/elements/xform-input/config.json
+```
+
+CLI 会按需拉取并缓存到 `~/.llc/widgets-cache.json`。从中获取：
+- `xform`：`type/dataType/dictType/defaultLength/span/order/kind/for/isStored/...`
+- `env`：运行环境（`["xform"]`）
+- `config[].default`：控件默认属性（`aiFill/showText/passValue/encrypt/maskFormatType/encryptMonth/failureRule` 等）
+
+`placeholder` 通过 `POST {baseUrl}/sys-lang/getFrontResource`（key 约定 `{pkg}###langs###placeholder`）获取并写入 `lang`。
+
+内置的 `fdDataType → 控件包` 入口映射（见 `src/constants.ts`），可通过项目级 `lcode.config.json` 覆盖：
+
+```json
+{
+  "baseUrl": "http://mkdev01.ywork.me/data",
+  "controlMap": {
+    "clob": {
+      "desktop": "@elem/xform-rich-text",
+      "mobile": "@elem/xform-m-rich-text",
+      "logicalType": "rich-text"
+    },
+    "myType": {
+      "desktop": "@elem/xform-custom",
+      "mobile": "@elem/xform-m-custom",
+      "logicalType": "custom"
+    }
+  }
+}
+```
+
+| fdDataType | desktop 控件 | mobile 控件 | logicalType |
+|---|---|---|---|
+| varchar | `@elem/xform-input` | `@elem/xform-m-input` | text |
+| number | `@elem/xform-number` | `@elem/xform-m-number` | numbertext |
+| boolean | `@elem/xform-switch` | `@elem/xform-m-switch` | switch |
+| timestamp | `@elem/xform-datetime` | `@elem/xform-m-datetime` | timestamp |
+| address | `@elem/xform-address` | `@elem/xform-m-address` | address |
+| attach | `@elem/xform-attachment` | `@elem/xform-m-attachment` | attachment |
+| clob | `@elem/xform-textarea` | `@elem/xform-m-textarea` | textarea |
+| relation | `@elem/xform-relation` | `@elem/xform-m-relation` | relation |
+
+> 输出约定：除 `--json` 的结果外，所有日志/表格输出到 **stderr**，便于 `llc ... --json > out.json`。
+
+## 七、目录结构
+
+```
+low-code-cli/
+├── bin/llc.js               # 可执行入口
+├── src/
+│   ├── index.ts               # commander 入口与命令注册
+│   ├── client.ts              # HTTP 客户端（fetch + X-AUTH-TOKEN）
+│   ├── config.ts              # 配置解析与持久化
+│   ├── constants.ts           # 表单类型 / 控件映射常量
+│   ├── types.ts               # 类型定义（对齐后端 DTO）
+│   ├── widgets.ts             # 控件元数据注册表（拉取 config.json + 控件多语言，落盘缓存）
+│   ├── api/formDefine.ts      # 后台接口封装（modeling / general / design 三族）
+│   ├── generator/index.ts     # 表单配置生成器（自动完善字段核心）
+│   ├── commands/              # config / app / form / field 子命令
+│   └── utils/                 # 日志与工具函数
+└── package.json
+```
+
+## 八、常见问题（前端报错）
+
+### 进入表单编辑器报 `SyntaxError: "undefined" is not valid JSON`
+
+**原因**：`sys-modeling` 表单编辑页存在如下写法（`manage/pages/sysModelingForm/edit/content.tsx`）：
+
+```ts
+fdIcon: JSON.parse(`${fdIcon}` || '{}')
+```
+
+当 `fdIcon` 为 `undefined` 时，`` `${fdIcon}` `` 会得到**真值字符串 `"undefined"`**，`|| '{}'` 兜底失效 →
+`JSON.parse("undefined")` 抛错；而 `init()` 是 async 且未被 await/catch → `Uncaught (in promise)`。
+
+**修复**：
+
+- 新建：CLI 已默认写入图标，无需处理；
+- 已有表单：执行一次 `llc form autofill --id <fdId> --apply`（会自动补默认图标），
+  或 `llc form autofill --id <fdId> --icon <图标名> --apply` 指定图标。
+
+> 图标必须写入 `modeling_xform` 镜像表，所以走 `sysModelingXForm/saveBase`（`saveDesign` 只写表单引擎表，不生效）。
+
+### 界面上标题/提示显示成 `!{46573e93-82ef-4def-b184-33f74b2681e6}` 这类原文
+
+**原因**：多语言 messageKey 的格式不合法。
+
+前端识别多语言标记统一使用正则 `/\!\{([\w\.]*)\}/gi`
+（`sys-xform/src/components/ide/store/i18n/syncApi.ts#isCustomI18n`、`components/runtime/utils.ts`），
+`\w` = `[A-Za-z0-9_]`，**不包含连字符 `-`**。
+若用 RFC4122 UUID（带 `-`）作 key，`isCustomI18n()` 判定为 false，前端就不会做替换，直接原样显示。
+
+正确的 key 由前端 `sys-xform/src/util/runtimeUtil.ts#uuid` 生成：
+
+```ts
+Date.now().toString(36) + Math.random().toString(36).slice(2)   // 纯 base36，形如 mv0dg6b08kjn1fost7o
+```
+
+**修复**：CLI 已按上式生成 key（`src/utils/random.ts#generateMessageKey`），
+并会对「不符合 `[\w.]` 的历史 key」自动重建。
+
+- 新建：无需处理；
+- 已有表单：`llc form autofill --id <fdId> --apply --publish`。
+
+### 表单能打开但控件不显示 / 报“找不到默认视图”
+
+一般是 `fdConfig` 结构不对（用了 IDE 内存格式而非落库格式），
+执行 `llc form autofill --id <fdId> --apply` 重新生成即可（见第五章）。
+
+## 九、参考源码
+
+接口契约依据以下后端源码整理（非本仓库，仅供核对）：
+
+**`mk-sys-xform`（表单引擎）**
+- `SysGeneralFormDefineService#beforeExecute`：`generalFormDefine` 仅接受 `fdFormDefineType=General`
+- `SysXFormBaseDefineService#init`：生成 `fdId/fdEntityId/fdEntityName/fdRunEntityName/fdTableName`
+- `SysXFormDesignController` / `SysXFormDesignService#voCreate`：表单引擎原始创建接口
+- `FormDefineType`：表单类型枚举（1-6）
+
+**`mk-sys-modeling`（业务建模/低代码应用）**
+- `SysModelingXFormController#create/saveDesign/saveDesignAndPublish/publish/generateTableName`
+- `SysModelingXFormService#create`：写死 `fdEntityId=表单id`、`fdEntityName=fdRunEntityName='sys-modeling'`，并按 `fdAppId` 归属应用
+- `SysModelingApplication`（表 `modeling_application`）：应用实体，`fdAppCode` 为 URL 段标识
+- `SysModelingDataModelService#buildMainTableName`：`mk_model_yyyyMMdd` + 随机 5 位