lan-low-code-cli 2.1.0 → 2.3.0

package/README.md

@@ -25,6 +25,11 @@ 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`。
+>
+> **打包分发**：`pnpm run pack`（`scripts/pack.js`，注意与 `rebuild` 一样要用 `run`，`pnpm pack` 是 pnpm 内置命令）把 CLI 与 skill 打成压缩包，输出到 `release/`（`dist/` 只放构建产物），
+> 文件名拼接版本号：`lan-low-code-cli-<version>.tgz`、`lan-low-code-cli-skill-<version>.tgz`，
+> 外加 `--with-deps` 的解压即用包（`-standalone`）。默认 tgz（npm 可直接 `npm i -g ./xxx.tgz`），
+> `--format zip|both` 可切换；`--target cli|skill` 只打其一，`--list` 预览文件清单，`--no-build` 跳过构建。
 
 ## 二、鉴权与服务端地址
 
@@ -101,6 +106,7 @@ llc form create --name <名称> [选项]
 | `--auth-file <path>` | 精细字段权限（JSON），见「字段权限」章节 |
 | `--action <spec>` | 控件动作：`"字段名:事件:函数源码或@js文件"`，可重复；全局动作用 `$global`，见「控件动作」章节 |
 | `--action-file <path>` | 控件动作定义文件（JSON），见「控件动作」章节 |
+| `--relation <spec>` | 业务关联：`"字段名=目标表单[:显示值=字段][:显示项=字段1,字段2]"`，可重复，见「关联类控件」章节 |
 | `--no-config` | 仅创建空表单，不生成字段配置 |
 | `--publish` | 创建后立即发布 |
 | `--dry-run` | 只打印将提交的数据，不发起请求 |
@@ -188,14 +194,14 @@ llc field gen-key --name <名称>      # 生成字段编码
 
 **先查环境再选控件**：
 
-`ash
+```bash
 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）。
+control list 的数据源是 `{origin}/web/sys/artifact/elements/index.json` + 各控件 `config.json`（首次运行会逐个拉取并落盘缓存，之后秒回）。`备注` 含义：`已登记` = 可直接用于 `--add-field`；`支持选项` = 可用 `--option`（`dictType=optionDict`）；`容器类` = 明细/分页等需专用参数；`已废弃` = 平台标记废弃（如 `relation`）；`需设计器配置` = 关键属性是环境对象选择，CLI 只建骨架。
 
 `--add-field` 的第三个 token 既可写**数据项类型**（`varchar`/`number`/…），
 也可直接写**控件类型**（`moneytext`/`select`/…），第四 token 为控件类型：
@@ -218,10 +224,146 @@ control list 的数据源是 {origin}/web/sys/artifact/elements/index.json + 各
 | 数值 | `numbertext`、`moneytext`、`rate`、`slider`、`timepicker`、`daterange` |
 | 选择 | `select`、`radio`、`checkbox`（均支持 `--option` 配选项） |
 | 日期 | `timestamp`、`timeZone` |
-| 组织/地址 | `address` |
+| 组织人员 | `address`（**地址本**，选人/选组织，非地址文本，见下） |
 | 附件/媒体 | `attachment`、`image`、`video` |
 | 编码/码图 | `barcode`、`qrcode` |
 | 其它 | `switch`、`hidden`、`dividing`、`subject`、`relation`、`relationQuery` |
+| 高级·元素类 | `desc`（说明文字）、`interval`（分割线）、`button`、`html`、`iframe`、`review`（审批意见）、`timeAxis`（时间轴）、`associatedFields`（关联字段）、`serial-number`（明细表序号） |
+| 高级·编号类 | `mechnumber`（机制编号）、`manualNumber`（手工编号）、`reserveNumber`（预留编号） |
+| 高级·数据类 | `association`（关联选择）、`refTemplate`（关联模板）、`foreignKey`（外键）、`cfg`（配置项）、`mdm`（主数据）、`dynamic`（动态控件）、`component`、`agency`、`area`、`tags`、`location`、`calculate`、`fileEdit`、`invoice`、`ocr`、`auditNote`、`template`、`ikm-author`、`ikm-category`、`ikm-content`、`ikm-player` |
+
+高级控件（环境中 67 个 `kind=control` 控件已登记 64 个，其余 3 个是容器类）使用注意：
+
+- **元素类**（`desc`/`html`/`interval`/`button`/`iframe`/`review`/`timeAxis`/`associatedFields`/`serial-number`）
+  `fdIsStored=false`：仍写入 `dataModel`，但不建物理列（与设计器一致）；
+- **容器类**（`detail` 明细表、`bigDetail` 大数据明细表、`paged` 分页容器）**不是数据项**，
+  不能用 `--add-field` 创建——明细表用 `--detail`；`bigDetail`/`paged` 暂不支持（环境 1628 个表单中无使用样例）；
+- **需设计器补充配置**的控件（关联范围 / 主数据 / 配置项 / 编号规则 / 识别类型 …）：CLI 只创建骨架，
+  生成时会打印提示；缺必填属性时发布校验会拦截（见「控件必填属性校验」）。
+
+```bash
+# 高级控件用法与普通控件一致（第三个 token 写控件类型）
+llc form autofill --id <fdId> --apply --add-field "fd_note:说明文字:desc" --add-field "fd_code:平台编码:mechnumber"
+```
+
+#### `address`：地址本（组织 / 人员选择器）
+
+⚠️ **`address` 不是「地址（文本）」控件**，而是平台的**地址本**——用来选人、选部门/组织/岗位/用户组。
+凡涉及组织架构与人员的字段（责任人、经办人、所属部门、归属单位…）都用这个类型。
+
+落库特征（与真实表单核对）：`fdDataType=address`、`fdDictType=orgElementDict`（组织人员字典，
+环境内唯一的 `orgElementDict` 控件）、`fdIsStored=true`。
+
+| 属性 | 含义 |
+|---|---|
+| `range` | 选择范围：`all`（全部组织，默认）/ `custom`（自定义——此时才出现预选相关属性） |
+| `org.orgTypeArr` | 可选类型，**位掩码数组**：`1`=组织、`2`=部门、`4`=岗位、`8`=人员、`16`=用户组；组合值如 `3`=组织或部门、`12`=岗位或人员、`31`=全部。CLI 默认 `['8']`（仅人员） |
+| `multi` | 是否多选（默认 `false`，单选） |
+| `preSelectType` / `preSelectValue` / `nextDept` | 仅 `range='custom'` 生效（预选类型 / 预选值 / 越过部门） |
+| `relation` | 联动传值（`relationKey`/`relationValue`/`relationEnum`/`relationTableName`） |
+| `orgAvailable` / `showAvatar` / `showType` | 是否可选组织、显示头像、显示类型 |
+
+平台把上述属性**同时**存两份：控件属性 `controlProps` 与数据项 `fdFontExtendData`
+（前端 `syncApi.frontExtendData2Config` 反向同步；公式/接口 Schema 的 `$ref` 依赖它——
+如 `orgTypeArr:['8']` → `ORG_PERSON`、缺省则为 `ORG_ALL`）。CLI 两者都会写入并保持一致。
+
+```bash
+# 选人字段（默认：全部范围 / 仅人员 / 单选）
+llc form autofill --id <fdId> --apply --add-field "fd_owner:责任人:address"
+```
+
+> 需要「多选 / 自定义范围 / 可选部门」等配置时，用设计器改（CLI 会把这些配置**原样保留**，
+> 不会因为重新生成而丢失）；平台预置的 `fd_creator`/`fd_owner`/`fd_alter` 等也是 `address` 类型，
+> 但只靠 `fdFontExtendData.orgTypeArr` 表达类型（`fd_creator`=人员、`fd_creator_dept`=部门）。
+
+#### 关联类控件（`relation` / `relationQuery` / `association` / …）
+
+| 控件 | 含义 | CLI 状态 |
+|---|---|---|
+| `relation` | **业务关联**（关联其它表单的业务数据） | ⚠️ 控件包被平台标记**废弃**（`xform.group=deprecated`，但存量表单大量在用：环境内 1371 个字段）。控件包 `config.json` 里**没有任何必填属性**，但属性面板由设计器拼装、有强制要求——CLI 已按设计器规则做**语义校验**（见下），裸字段会被拦截。新表单建议改用 `association` |
+| `relationQuery` | 关联查询 | 需设计器配置查询页签（`tabs` 必填 → 校验拦截） |
+| `association` | 关联选择 | 需设计器配置关联范围与列表列（`xlistColumn` 必填 → 校验拦截） |
+| `foreignKey` | 外键关联 | 需设计器配置映射类型与目标模型（`mappedType` 必填 → 校验拦截） |
+| `refTemplate` | 关联模板 | 需设计器选择关联模板（校验拦截） |
+| `associatedFields` | 关联字段（展示关联表单的字段） | 无必填属性，但未配置关联源时**后端发布会 500**（生成时告警） |
+
+业务关联的真实落库结构（已用《科技成果登记》等真实表单核对）：`fdDataType=relation`、
+`fdDictType=querySourceDict`、`fdLength=200`，核心配置在 `controlProps` 与 `fdFontExtendData`：
+
+```
+controlProps.relationCfg  = { appCode, xformName, modelId, tableName, refFieldName, fdFormType }
+// refFieldName 是 `$<字段名>$` 引用（如 `$fd_material_name$`），运行时解析为所选记录的显示值；
+// 不能写成 `$<表名>.<字段名>$`（解析不到会把字面量显示出来），relationCfg 也没有 showFields 键
+controlProps.datasource   = { columns:[{name,label}], queryCondition, tree, relationConditions }
+controlProps.outParams    = { params:[{ sourceField:{fdName,tableName,tableType}, targetField:{…} }] }（可选）
+controlProps.mappedType / multi / renderMode / direction / rowCount / isForwardView / modelId / modelName
+```
+
+这些是「选业务对象」的结果，CLI 无法推断、也不伪造——需在设计器里选好（选好后
+`autofill` 会原样保留这些属性，见「设计器配置的控件属性会被保留」）。
+
+**业务关联的必填项（CLI 已按设计器规则校验，见「控件语义校验」）**：
+
+| 必填项 | controlProps | 规则来源 |
+|---|---|---|
+| 关联表单（业务对象）+ 显示值 | `relationCfg.appCode` / `relationCfg.refFieldName` | IDE `controlConfig.tsx` 的 `relationForm` 校验器「关联表单不能为空」 |
+| 数据源显示项 | `datasource.columns` 非空 | IDE `dataSource` 校验器 + `dataSource/formDetails.tsx` 显示项 `required: true`（适用显示方式 `singlelist`/`mullist`/`treeList`/`multiTreeList`） |
+| 卡片设置（卡片类显示方式） | `datasource.card.displayName` / `displayImage` + `columns` | 「卡片设置为必填项」 |
+| 导航设置（树+卡片/列表类） | `datasource.tree.conditionsFromTree` / `relationConditions` / `relationCfg` | 「导航设置为必填项」（分类导航除外） |
+| 树层级设置（`panel`/`tree` 类） | `datasource.tree.relationConditions` | 「树层级设置为必填项」 |
+
+CLI 生成业务关联字段时会写入设计器的默认属性（依据环境 1371 个真实字段的分布）：
+`renderMode: 'singlelist'`（95%）、`direction: 'column'`、`rowCount: 3`、`isForwardView: 'no'`
+（`mappedType` 仅 5% 字段使用，属按需配置，不做默认）。
+
+```bash
+llc form autofill --id <fdId> --apply --add-field "fd_r:业务关联:relation"
+# → ✖ 字段 fd_r（@elem/xform-relation）：关联表单不能为空：需在设计器中选择业务对象并设置显示值…
+# → ✖ 字段 fd_r（@elem/xform-relation）：列表设置为必填项：需在数据源配置中选择显示项（datasource.columns）
+# 退出码 1（--force 可跳过，但该控件仍需到设计器补配置）
+```
+
+#### 用 `--relation` 配置业务关联（含业务对象与显示项）
+
+`--relation` 把「字段 = 目标表单」解析成完整的业务关联配置（`form create` / `form autofill` 均支持）：
+
+```bash
+# 最简：目标按表单名（同名多份时优先当前表单所属应用）或 fdId
+llc form autofill --id <fdId> --apply --detail "出库明细=fd_dtl_out_name:物料名称:relation" \
+  --relation "fd_dtl_out_name=物料信息"
+
+# 指定显示值（选人看到的文案）与显示项（列表列）
+llc form autofill --id <fdId> --apply \
+  --relation "fd_customer=客户信息:显示值=fd_cust_name:显示项=fd_cust_name,fd_cust_code,fd_level"
+```
+
+| 部分 | 说明 | 缺省 |
+|---|---|---|
+| `字段名` | 目标字段物理名（主表或明细表字段，命中后自动改写为 `relation` 控件） | — |
+| `目标表单` | 表单名或 fdId；按名匹配到多份时优先当前表单所属应用，仍歧义则报错列出候选 | — |
+| `显示值=字段` | 存入 `relationCfg.refFieldName`（写 `$字段名$`，多项用逗号拼接） | 目标表首个文本类业务字段 |
+| `显示项=字段1,字段2` | 存入 `datasource.columns`（设计器强制必填） | 目标表**全部**业务字段 |
+
+解析后会写入：`relationCfg`（业务对象）、`datasource`（数据源骨架 + 显示项 + 筛选项 + 树设置）、
+`renderMode: 'singlelist'`、`modelName`，并把这些键同步到 `fdFontExtendData`（控件源码 JSDoc 的
+`@frontExtendData` 声明）；`datasource` 骨架结构取自真实表单，保证设计器打开该控件时结构完整。
+
+**实测案例**（物料管理应用）：把《物料出库单》明细表的「物料名称」由单行文本改为关联《物料信息》：
+
+```bash
+llc form autofill --id 1k4ihs42swdw2vebw38dpgr036rj6uqi0tw0 --apply --publish \
+  --detail "出库明细=fd_dtl_out_name:物料名称:relation" \
+  --relation "fd_dtl_out_name=物料信息"
+# → 业务关联：fd_dtl_out_name → 物料信息（显示值 物料名称，显示项 11 项：物料名称/规格型号/…/默认供应商）
+# → 落库：fdType=relation、fdDictType=querySourceDict、renderMode=singlelist、fdStatus=official
+```
+
+> 注意：切换为业务关联后，该字段**历史数据**（原文本值）不会自动解析成关联记录——设计器切换
+> 关联表单时也有同样提示。另外「选中物料后自动带出其它列」（传出参数 `outParams`，如把
+> 物料编码/参考单价写回明细行）尚未提供 CLI 参数，需要的话可以再加。
+
+> 平台标记废弃的控件共 3 个：`relation`（业务关联）、`associatedFields`（关联字段）、`timeAxis`（时间轴）。
+> `llc control list` 会以 `已废弃` 备注并汇总列出。
 
 `--option` 为选择类控件建选项，写入 `controlProps.options` 与 `fdFontExtendData.options`，
 并生成 `prop:'option'` 的多语言条目：
@@ -275,6 +417,9 @@ llc form autofill --id <fdId> --apply --publish \
 
 要点（均为真实表单核对结论）：
 
+- **栅格始终是满格的**：`GridItem` 总数 = `columns × rows`，最后一行的空位也会保留
+  （`children: []`、`controlProps: { id, column, row }`）——与设计器一致（真实样本如
+  《业务审批管理》`columns=3` 但只有 2 个字段，第 3 格仍存在）。旧版本会删掉末行多余格子，已修复。
 - **栅格布局控件不进 `controlMappings`**；**多页签控件必须进**（`tab-appearance` / `tabs` / `tabpane` 三件套）。
 - 多页签的 key 约定：外观 key 形如 `@elem/xform-tab-appearance~xxxxxx`，
   tabs 节点 key 为 `<外观key>-tabItem`，面板为 `<外观key>-tabN`，
@@ -486,7 +631,10 @@ CLI 在 `form create` / `form autofill` 保存前会校验**控件必填属性
 
 - 校验对象：控件 `config.json` 属性面板中满足
   `required && !disabled && !protected && !slotScope` 的**叶子属性项**；
-- 值为空（`undefined/null/''/空数组`）即报错，格式 `请输入<label>（key）`；
+- 值为空（`undefined/null/''`）即报错，格式 `请输入<label>（key）`；
+  **空数组不算空**——设计器规则是 `{required:true}`（不带 `type`），async-validator 仅在
+  `type === 'array'` 时才把 `[]` 判为空，因此 `preSelectValue: []`（地址本自定义范围的真实结构）
+  是合法的，CLI 必须一致，否则会对合法表单误报并中止保存；
 - 与设计器一致地跳过：带 `enableWhen`/`hidden` 的条件渲染项（未渲染不校验）、
   分组容器（baseGroup/styleGroup 等）、`inputLocale` 类标题项（取 `title` 值）；
 - 校验失败默认**中止保存/发布**（预览模式仅提示）；加 `--force` 可跳过。
@@ -503,12 +651,46 @@ CLI 按 `src/constants.ts#REQUIRED_PROP_DEFAULTS` 自动补齐，
 | 控件 | 属性 | 默认值 |
 |---|---|---|
 | textarea | height | `"3"`（3 行，设计器实测） |
-| address | org / multi | `{"orgTypeArr":["8"],…}` / `false`（设计器实测） |
+| address（地址本） | org / multi | `{"orgTypeArr":["8"],"defaultValueType":"null"}` / `false`（设计器实测；`8`=人员） |
 | rate | max | `5` |
 | slider | min / max | `0` / `100` |
 | rich-text | height | `300`（config.json min 200） |
 | bar-code | height | `80` |
 | hyperlinks | largestSet | `"infinit"`（选项首项） |
+| description | defaultTextValue | `$title`（字段标题的多语言 key，见下方占位符） |
+| tag | tabsRange / multi | `{categorys:[],targs:[],rangeType:'all'}` / `true` |
+| location | allowed / mapContent / searchNearBy | `false` / `{address:'formattedAddress'}` / `{…}`（实测） |
+| area | defaultValueType / precisionRegion / showHierarchy | `'null'` / `'county'` / `'all'` |
+| html | source | `{html:'',css:'',javascript:''}` |
+| iframe | heigth / expressionFormulaVO | `150` / `{}` |
+| file-edit | height / allowImport / accept | `600` / `true` / `{docx,[.doc,.docx]}`（实测） |
+| association | mode / processStatus | `'multiple'` / `['30']`（实测） |
+| mdm | renderMode / direction / rowCount | `'singlelist'` / `'column'` / `3` |
+| cfg | renderMode / cascader / showLevel / selectLevel | `'select'` / `true` / `'lastLevel'` / `'allLevel'` |
+| calculate | statisticMode / defaultValueType | `'SUM'` / `'empty'` |
+| interval / button / agency / associated-fields / time-axis / review / attach-demo / dynamic | 样式与开关类 | 设计器实测值 |
+
+`REQUIRED_PROP_DEFAULTS` 支持两个**字段级占位符**（生成时解析）：
+`$title` → 字段多语言 key（`langKey`）、`$name` → 字段物理名（`fdName`）。
+
+**设计器默认属性**（`src/constants.ts#CONTROL_DEFAULT_PROPS`）：控件包 `config.json` **未声明**、
+但设计器新建字段时一定会写入的项。这类值不属于「必填」，缺失时运行时兜底不可靠：
+
+| 控件 | 属性 | 默认值 | 依据 |
+|---|---|---|---|
+| relation（业务关联） | renderMode / direction / rowCount / isForwardView | `'singlelist'` / `'column'` / `3` / `'no'` | 环境 1371 个关联字段分布 95%/99%/99%/98% |
+| moneytext（金额） | precision / symbol | `2` / `''` | 环境 115 个金额字段 `precision` 出现率 **100%**（88% 为 2）；平台数据迁移代码缺省时按 0 位小数落库，故显式写 2 位。`symbol`（币种）属业务选择（69% CNY、28% 空），取中立空值 |
+
+已有字段的该项值若已由设计器配置，**原值优先**（`carried` 覆盖默认值），`autofill` 不会改写。
+
+**需要「环境对象选择」的属性 CLI 不伪造**（选了才有意义）：关联范围 `xlistColumn`、
+主数据 `mdm`、配置项 `cfg`、接口 `renderMode`(dynamic)、编号规则 `fdSysNumber`、
+映射类型 `mappedType`、识别类型 `discernType`、审批显示字段 `defaultFields`、
+默认附件/图片 `defaultValue` 等。生成时会给出「需在设计器中配置」提示，
+保存时被发布前校验拦截（`--force` 可跳过，但生成的控件需要人工补配置才能真正可用）。
+
+特例：`associatedFields`（关联字段）**没有必填属性**，但未配置关联源时后端发布会直接
+失败（HTTP 500，已实测）——CLI 会在生成时提示，需到设计器指定关联源字段。
 
 例外：`upcasing.relationControl`（联动控件）是语义性选择，CLI 不兜底；
 未指定时校验会拦截，需显式给出（存于 `fdFontExtendData.relationControl = {fdName, fdLabel}`）。
@@ -517,6 +699,15 @@ CLI 按 `src/constants.ts#REQUIRED_PROP_DEFAULTS` 自动补齐，
 （如 datetime 的 `defaultValueType='formula'` 时公式配置 `defaultValueFormulaVO` 必填）；
 条件不成立或为复杂表达式时跳过，与设计器一致。
 
+**控件语义校验（`src/constants.ts#CONTROL_SEMANTIC_RULES`）**：有些控件的属性面板由**设计器拼装**
+（控件包 `config.json` 的 `config` 为空），必填项不在 `config.json` 里，通用必填校验覆盖不到。
+CLI 按设计器源码中的校验器补了一层「语义校验」，每条规则可声明 `renderModes`（仅特定显示方式生效）。
+
+目前覆盖 `relation`（业务关联）：`relationCfg`（关联表单）+ `datasource.columns`（显示项）
++ 卡片/导航/树层级设置，文案与设计器一致（关联表单不能为空 / 列表设置为必填项 / 卡片设置为必填项 /
+导航设置为必填项 / 树层级设置为必填项）。存量影响面已实测：环境 1371 个业务关联字段中
+仅 34 个（2.5%，涉及 26 个表单）不合规，这些历史表单 `autofill` 时报错，需 `--force` 或到设计器补齐。
+
 **初始值模式**：新建字段 `defaultValueType` 默认为 `null`（无初始值），与控件 `config.json` 默认一致；
 不要写 `formula`——公式模式下 `defaultValueFormulaVO` 必填，设计器提交会被拦截。
 若需要公式初始值，按以下结构写入 `fdFontExtendData`（迁移自前端 `dataMigration.ts`）：
@@ -696,7 +887,19 @@ CLI 会按需拉取并缓存到 `~/.llc/widgets-cache.json`。从中获取：
 - `env`：运行环境（`["xform"]`）
 - `config[].default`：控件默认属性（`aiFill/showText/passValue/encrypt/maskFormatType/encryptMonth/failureRule` 等）
 
-`placeholder` 通过 `POST {baseUrl}/sys-lang/getFrontResource`（key 约定 `{pkg}###langs###placeholder`）获取并写入 `lang`。
+`placeholder`（提示文字）通过 `POST {baseUrl}/sys-lang/getFrontResource` 获取并写入 `lang`。**资源键名因控件而异**
+（来源：控件源码 `defaultProps.placeholder`，见 `src/constants.ts#CONTROL_PLACEHOLDER_LANG_KEYS`）：
+
+| 资源键 | 控件 | 环境文案（zh-cn） |
+|---|---|---|
+| `pleaseEnter` | `@elem/xform-datetime`、`@elem/xform-timepicker`（含移动端 timepicker） | 请选择日期 / 请选择时间 |
+| `enter` | `@elem/xform-m-datetime` | 请选择日期 |
+| `pleaseSelect` | `@elem/xform-area` 系列 | 请选择 |
+| `placeholder` | 其余控件（input/select/money/number/textarea/phone-number/rich-text…） | 请输入 / 请选择 |
+
+> 此前 CLI 一律查 `###langs###placeholder`，导致日期控件取不到文案、**提示文字缺失**；现已按控件取键，
+> 并保留未命中时的兜底探测（`placeholder → pleaseEnter → enter → pleaseSelect`）。
+> **已有提示文字优先沿用**（设计器里的自定义文案不会被覆盖，如「请选择月份」）。
 
 内置的 `fdDataType → 控件包` 入口映射（见 `src/constants.ts`），可通过项目级 `lcode.config.json` 覆盖：
 
@@ -729,6 +932,44 @@ CLI 会按需拉取并缓存到 `~/.llc/widgets-cache.json`。从中获取：
 | clob | `@elem/xform-textarea` | `@elem/xform-m-textarea` | textarea |
 | relation | `@elem/xform-relation` | `@elem/xform-m-relation` | relation |
 
+### 高级控件映射与「未登记控件」保护
+
+`CONTROL_TYPE_MAP`（`src/constants.ts`）覆盖环境中的 64/67 个 `kind=control` 控件。
+高级控件条目逐项按真实环境核对，除控件包外还携带落库元信息：
+
+| 字段 | 写入 | 说明 |
+|---|---|---|
+| `dataType` | `fdDataType` | 控件包 `config.json` 未声明时以映射表兜底（`desc`/`serial-number`/`bigDetail` 等） |
+| `dictType` | `fdDictType` | 如 `serialNumberDict`、`manyToManyDict`、`mapDict`、`attachmentDict` |
+| `defaultLength` | `fdLength` | 如 `tags=2000`、`component=100` |
+| `isStored` | `fdIsStored` | 元素类控件为 `false`（不建物理列） |
+
+对**未登记**的控件（平台新增或定制控件包），`autofill` **不再降级为输入框**：
+`resolveControl` 会从字段已有 `fdAttribute.config.controlProps.desktop.type` 还原控件包，
+并原样保留 `fdType`，避免把环境里的高级控件改写成普通文本框（可安全地对存量表单做
+`autofill`）。`llc control list` 会同时打印未登记控件与容器类控件清单。
+
+### 设计器配置的控件属性会被保留
+
+生成 `controlProps` 时，**同控件包**（`controlProps.desktop.type` 未变）的已有属性会被沿用，
+仅身份信息（`id`/`name`/`uuid`/`title`/`desktop`/`mobile`/`span`/`$$tableType`/`$$tableName`）、
+`options`、`maxLength` 由生成器统一重建。换控件类型时不沿用（避免残留旧属性）。
+
+`placeholder`（提示文字）是「**已有则沿用、缺失则补默认**」：设计器里的自定义文案（如
+「请选择月份」）连同其 `lang` 条目一起保留；没有时才按控件资源键补上默认文案（如
+日期控件→「请选择日期」、时间→「请选择时间」、文本类→「请输入」、下拉→「请选择」）。
+
+因此设计器里配置过的属性不会因为重新生成而丢失，例如：
+
+| 控件 | 保留下来的属性 |
+|---|---|
+| `address`（地址本） | `range`、`multi`、`org.orgTypeArr`、`preSelectType`/`preSelectValue`、`nextDept` … |
+| `moneytext` | `precision`、`symbol`、`showCount` … |
+| 任意控件 | `placeholder`（自定义提示文字 + 对应多语言） |
+
+同时这些「前端扩展属性」（`config.json` 中声明 `frontExtendData` 的项）会同步写入
+`fdFontExtendData`，与平台两处并存的约定一致。
+
 > 输出约定：除 `--json` 的结果外，所有日志/表格输出到 **stderr**，便于 `llc ... --json > out.json`。
 
 ## 七、目录结构

package/dist/api/formDefine.js

@@ -100,6 +100,18 @@ exports.modelingXFormApi = {
         conditions: { 'fdApp.fdId': request.fdAppId },
         columns: ['fdId', 'fdName', 'fdStatus', 'fdTableName'],
     }),
+    /**
+     * 按条件查询表单（业务对象解析等场景）。
+     *
+     * 注意：`list` 接口**必须带 conditions**（无条件调用会触发后端空指针 500）；
+     * 返回含 `fdApp`（应用）与 `fdType`（表单定义类型），供 `--relation` 解析业务对象。
+     */
+    query: (client, request = {}) => client.post(`${MODELING_XFORM_BASE}/list`, {
+        pageNo: 1,
+        pageSize: 50,
+        columns: ['fdId', 'fdName', 'fdTableName', 'fdApp', 'fdType'],
+        ...request,
+    }),
     /** 生成建模业务表单数据库表名（mk_model_yyyyMMdd + 随机5位） */
     generateTableName: (client) => client.post(`${MODELING_XFORM_BASE}/generateTableName`),
     /** 检查表名是否可用（true=可用） */

package/dist/commands/control.js

@@ -66,16 +66,22 @@ function registerListCommand(control) {
             const short = pkg.name.replace(/^@elem\/xform-/, '');
             const mobileCandidate = `@elem/xform-m-${short}`;
             const type = String(xform.type ?? '');
+            const container = constants_1.CONTAINER_CONTROL_TYPES[type];
             rows.push({
                 type,
-                dataType: String(xform.dataType ?? ''),
-                dictType: String(xform.dictType ?? ''),
+                dataType: String(xform.dataType ?? constants_1.CONTROL_TYPE_MAP[type]?.dataType ?? ''),
+                dictType: String(xform.dictType ?? constants_1.CONTROL_TYPE_MAP[type]?.dictType ?? ''),
                 for: String(xform.for ?? ''),
                 kind: String(xform.kind ?? ''),
                 desktop: pkg.name,
                 mobile: mobileNames.has(mobileCandidate) ? mobileCandidate : pkg.name,
                 registered: Boolean(constants_1.CONTROL_TYPE_MAP[type]),
                 options: xform.dictType === constants_1.OPTION_DICT_TYPE,
+                container: Boolean(container),
+                hint: container?.hint ?? '',
+                // 平台标记为废弃的控件包（xform.group='deprecated'，如 relation 业务关联）
+                deprecated: String(xform.group ?? '') === 'deprecated',
+                needsDesigner: Boolean(constants_1.CONTROL_DESIGNER_NOTES[type]),
             });
         }
         const kind = opts.all ? undefined : String(opts.kind ?? 'control');
@@ -91,10 +97,35 @@ function registerListCommand(control) {
             适用: r.for,
             桌面端: r.desktop,
             移动端: r.mobile === r.desktop ? '同桌面端' : r.mobile,
-            备注: [r.registered ? '已登记' : '', r.options ? '支持选项' : ''].filter(Boolean).join('/'),
+            备注: [
+                r.registered ? '已登记' : r.container ? '容器类' : '未登记',
+                r.options ? '支持选项' : '',
+                r.deprecated ? '已废弃' : '',
+                r.needsDesigner ? '需设计器配置' : '',
+            ]
+                .filter(Boolean)
+                .join('/'),
         })));
         const registered = filtered.filter((r) => r.registered).length;
+        const containers = filtered.filter((r) => r.container);
         logger_1.logger.info(logger_1.color.gray(`共 ${filtered.length} 个（kind=${kind ?? '全部'}）；其中 ${registered} 个已登记到 CONTROL_TYPE_MAP，可直接用于 --add-field`));
+        if (containers.length) {
+            logger_1.logger.info(logger_1.color.gray(`另有 ${containers.length} 个容器类控件（需专用参数创建）：` +
+                containers.map((r) => `${r.type} —— ${r.hint}`).join('；')));
+        }
+        const unregistered = filtered.filter((r) => !r.registered && !r.container);
+        if (unregistered.length) {
+            logger_1.logger.info(logger_1.color.gray(`未登记控件 ${unregistered.length} 个（autofill 会按字段已有属性原样保留，不会降级）：` +
+                unregistered.map((r) => r.type).join('、')));
+        }
+        const deprecated = filtered.filter((r) => r.deprecated);
+        if (deprecated.length) {
+            logger_1.logger.info(logger_1.color.gray(`平台已标记废弃 ${deprecated.length} 个（不建议新表单使用）：` + deprecated.map((r) => r.type).join('、')));
+        }
+        const needsDesigner = filtered.filter((r) => r.needsDesigner);
+        if (needsDesigner.length) {
+            logger_1.logger.info(logger_1.color.gray(`需到设计器补配置 ${needsDesigner.length} 个：` + needsDesigner.map((r) => r.type).join('、')));
+        }
     });
 }
 /* PART3 */

package/dist/commands/form.js

@@ -8,6 +8,7 @@ const client_1 = require("../client");
 const config_1 = require("../config");
 const constants_1 = require("../constants");
 const generator_1 = require("../generator");
+const relation_1 = require("../relation");
 const types_1 = require("../types");
 const logger_1 = require("../utils/logger");
 const icon_1 = require("../utils/icon");
@@ -203,22 +204,34 @@ function parseActionFile(file) {
     }
     return result;
 }
+/** 打印业务关联解析结果（字段 → 业务对象、显示值、显示项数量） */
+function logRelations(specs) {
+    for (const spec of specs) {
+        logger_1.logger.info(`  业务关联：${spec.fieldName} → ${spec.target.xformName}（显示值 ${spec.refFieldName.replace(/\$/g, '')}，` +
+            `显示项 ${spec.columns.length} 项：${spec.columns.map((c) => c.label).join('/')}）`);
+    }
+}
 /** 汇总 `--action` + `--action-file` */
 function resolveActions(opts) {
     const specs = parseActionSpecs(opts.action ?? []);
     const fromFile = parseActionFile(opts.actionFile);
     return [...specs, ...fromFile];
 }
-/** 加载已有表单的 formAttr / viewModel / lang（autofill 时用于合并保留） */
+/** 加载已有表单的 attribute / formAttr / viewModel / lang（autofill 时用于合并保留） */
 async function loadPrevDesign(client, family, formId) {
     try {
         const vo = family === 'modeling'
             ? await formDefine_1.modelingXFormApi.loadDesign(client, formId)
             : await formDefine_1.formDefineApi.get(client, formId).catch(() => formDefine_1.designApi.load(client, formId));
         const cfg = typeof vo.fdConfig === 'string' ? JSON.parse(vo.fdConfig) : vo.fdConfig;
-        const formAttr = cfg?.attribute?.formAttr;
+        // attribute 除 formAttr 外还有 dataUnique / subjectRule 等顶层键，整体保留
+        const attribute = cfg?.attribute;
+        const formAttr = attribute?.formAttr;
         const lang = cfg?.lang;
         return {
+            prevAttribute: attribute && typeof attribute === 'object'
+                ? JSON.stringify(attribute)
+                : undefined,
             prevFormAttr: typeof formAttr === 'string' ? formAttr : undefined,
             prevViewModel: Array.isArray(cfg?.viewModel) &&
                 cfg.viewModel.length
@@ -574,6 +587,24 @@ async function buildDetailModels(client, formId, formName, specs, controlMap, re
     }
     return result;
 }
+/**
+ * 把（新建或调整后的）明细表模型合并进数据模型列表。
+ *
+ * **必须按下标替换而不是追加**：`--detail` 复用已有明细表时，该表本身已在
+ * `models` 里，直接 `[...models, ...details]` 会在负载中产生两份同名明细模型
+ * （同一 `fdId`/`fdTableName`），保存结果取决于服务端去重策略，不可依赖。
+ */
+function mergeDetailModels(models, details) {
+    const result = [...models];
+    for (const detail of details) {
+        const index = result.findIndex((m) => m.fdType === 'detail' && (m.fdId === detail.fdId || m.fdTableName === detail.fdTableName));
+        if (index >= 0)
+            result[index] = detail;
+        else
+            result.push(detail);
+    }
+    return result;
+}
 /** 公共的生成器选项 */
 function generatorOptions(opts, formType, appId) {
     const family = resolveApiFamily(formType, opts.api, appId);
@@ -660,6 +691,7 @@ function registerFormCommand(program) {
         .option('--auth-file <path>', '精细字段权限（JSON），如 {"add":{"fd_col_a":{"required":true}}}')
         .option('--action <spec>', '控件动作："字段名:事件:函数源码或@js文件"，可重复；全局动作用 $global（onLoad/onBeforeSubmit/onAfterSubmit）', collect, [])
         .option('--action-file <path>', '控件动作定义文件（JSON），见 README「控件动作」章节')
+        .option('--relation <spec>', '业务关联："字段名=目标表单[:显示值=字段][:显示项=字段1,字段2]"，可重复；目标可写表单名或 fdId', collect, [])
         .option('--force', '跳过控件必填属性校验（默认校验失败会中止保存/发布）')
         .option('--no-config', '仅创建空表单，不生成字段配置')
         .option('--publish', '创建后立即发布')
@@ -841,6 +873,9 @@ function registerFormCommand(program) {
             if (actionSpecs.length) {
                 logger_1.logger.info(`  控件动作：${actionSpecs.length} 个`);
             }
+            // 业务关联：解析目标表单（业务对象）与显示项
+            const relationSpecs = await (0, relation_1.resolveRelations)(client, (0, relation_1.parseRelationSpecs)(opts.relation ?? []), appId);
+            logRelations(relationSpecs);
             if (layoutOptions.layout && layoutOptions.layout !== 'rows') {
                 logger_1.logger.info(`  布局：${layoutOptions.layout}`);
             }
@@ -851,7 +886,7 @@ function registerFormCommand(program) {
             let withDetail = withNew;
             if (detailSpecs.length) {
                 const details = await buildDetailModels(client, fdId, base.fdName, detailSpecs, controlMap, registry, withNew);
-                withDetail = [...withNew, ...details];
+                withDetail = mergeDetailModels(withNew, details);
                 logger_1.logger.info(`  明细表：${details.length} 个`);
             }
             if (opts.addField?.length) {
@@ -877,6 +912,7 @@ function registerFormCommand(program) {
                 permissions,
                 options: optionSpecs,
                 actions: actionSpecs,
+                relations: relationSpecs.length ? relationSpecs : undefined,
             });
             if (stats.optionsCompleted) {
                 logger_1.logger.info(`  完善选项多语言：${stats.optionsCompleted} 个`);
@@ -884,7 +920,7 @@ function registerFormCommand(program) {
             if (stats.actionsCompleted) {
                 logger_1.logger.info(`  配置控件动作：${stats.actionsCompleted} 个`);
             }
-            for (const warning of stats.actionWarnings ?? []) {
+            for (const warning of [...(stats.actionWarnings ?? []), ...(stats.controlWarnings ?? [])]) {
                 logger_1.logger.warn(warning);
             }
             assertPropValidation(stats, opts, true);
@@ -1048,6 +1084,7 @@ function registerFormCommand(program) {
         .option('--auth-file <path>', '精细字段权限（JSON），如 {"add":{"fd_col_a":{"required":true}}}')
         .option('--action <spec>', '控件动作："字段名:事件:函数源码或@js文件"，可重复；全局动作用 $global（onLoad/onBeforeSubmit/onAfterSubmit）', collect, [])
         .option('--action-file <path>', '控件动作定义文件（JSON），见 README「控件动作」章节')
+        .option('--relation <spec>', '业务关联："字段名=目标表单[:显示值=字段][:显示项=字段1,字段2]"，可重复；目标可写表单名或 fdId', collect, [])
         .option('--force', '跳过控件必填属性校验（默认校验失败会中止保存/发布）')
         .option('--mechanism-entity-name <name>', '机制实体名（决定控件库）')
         .option('--mechanism-entity-code <code>', '机制编码')
@@ -1107,7 +1144,7 @@ function registerFormCommand(program) {
         let withDetail = withNew;
         if (detailSpecs.length) {
             const details = await buildDetailModels(client, opts.id, vo.fdName, detailSpecs, controlMap, registry, withNew);
-            withDetail = [...withNew, ...details];
+            withDetail = mergeDetailModels(withNew, details);
             logger_1.logger.info(`  明细表：${details.length} 个（新建 ${details.filter((d) => !withNew.some((m) => m.fdId === d.fdId)).length}，复用 ${details.filter((d) => withNew.some((m) => m.fdId === d.fdId)).length}）`);
         }
         const actionSpecs = resolveActions(opts);
@@ -1116,6 +1153,9 @@ function registerFormCommand(program) {
         if (actionSpecs.length) {
             logger_1.logger.info(`  控件动作：${actionSpecs.length} 个`);
         }
+        // 业务关联：解析目标表单（业务对象）与显示项（同名表单优先当前表单所属应用）
+        const relationSpecs = await (0, relation_1.resolveRelations)(client, (0, relation_1.parseRelationSpecs)(opts.relation ?? []), await (0, relation_1.appIdOfForm)(client, opts.id));
+        logRelations(relationSpecs);
         const stats = { optionsCompleted: 0, actionsCompleted: 0 };
         const payload = await (0, generator_1.buildFormDefinePayload)(withDetail, {
             base: {
@@ -1140,7 +1180,9 @@ function registerFormCommand(program) {
             permissions,
             options: optionSpecs,
             actions: actionSpecs,
+            relations: relationSpecs.length ? relationSpecs : undefined,
             prevFormAttr: prev.prevFormAttr,
+            prevAttribute: prev.prevAttribute,
             prevViewModel: prev.prevViewModel,
             prevLang: prev.prevLang,
         });
@@ -1151,7 +1193,11 @@ function registerFormCommand(program) {
         if (stats.actionsCompleted) {
             logger_1.logger.info(`  配置控件动作：${stats.actionsCompleted} 个`);
         }
-        for (const warning of [...(stats.actionWarnings ?? []), ...(stats.layoutWarnings ?? [])]) {
+        for (const warning of [
+            ...(stats.actionWarnings ?? []),
+            ...(stats.layoutWarnings ?? []),
+            ...(stats.controlWarnings ?? []),
+        ]) {
             logger_1.logger.warn(warning);
         }
         assertPropValidation(stats, opts, Boolean(opts.apply));