lan-low-code-cli 2.0.0 → 2.2.0

package/dist/generator/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GLOBAL_ACTION_EVENTS = exports.ACTION_GLOBAL_TARGET = void 0;
+exports.buildRelationProps = buildRelationProps;
 exports.resolveLocales = resolveLocales;
 exports.completeOptionsI18n = completeOptionsI18n;
 exports.buildViewModel = buildViewModel;
@@ -15,6 +16,57 @@ const random_1 = require("../utils/random");
 const widgets_1 = require("../widgets");
 /** `$global`：动作目标为表单全局（onLoad / onBeforeSubmit / onAfterSubmit） */
 exports.ACTION_GLOBAL_TARGET = '$global';
+/** 建模表单的数据模型类名（业务关联的 `modelName`，取自真实表单） */
+const MODELING_MODEL_NAME = 'com.landray.sys.xform.core.entity.design.SysXFormDesign';
+/**
+ * 构建业务关联的 `controlProps` 片段（`relationCfg` + `datasource` + 显示方式）。
+ *
+ * `datasource` 的骨架键取自真实表单（queryCondition/tree/filters/isListThrough…），
+ * 这些是设计器「列表设置」弹窗的固有字段，缺失会导致设计器打开该控件时结构不完整。
+ */
+function buildRelationProps(spec) {
+    const { target } = spec;
+    const columns = spec.columns;
+    return {
+        renderMode: 'singlelist',
+        modelName: MODELING_MODEL_NAME,
+        relationCfg: {
+            appCode: target.appCode,
+            xformName: target.xformName,
+            modelId: target.modelId,
+            showFields: spec.showFields,
+            refFieldName: spec.refFieldName,
+            tableType: 'main',
+            tableName: target.tableName,
+            fdFormType: target.fdFormType ?? 0,
+        },
+        datasource: {
+            queryCondition: { linkType: '$and', query: {} },
+            columns,
+            filters: spec.filters ?? columns,
+            tree: {
+                treeLoop: true,
+                querySorters: [],
+                conditionSetting: false,
+                relationCfg: {},
+                relationConditions: [{ operator: { value: '$eq' }, value: { format: 'field' } }],
+                queryCondition: {
+                    linkType: '$and',
+                    query: { type: 'conditionGroup', orAndOperator: 'type', condition: [] },
+                },
+                navigationMode: 'custom',
+            },
+            isListThrough: true,
+            isDisplayMode: true,
+            viewId: '',
+            conditionSetting: false,
+            isForwardView: true,
+            queryCollection: {},
+            sorters: [],
+        },
+        ...(spec.outParams ? { outParams: spec.outParams } : {}),
+    };
+}
 /** 全局动作支持的（前端注册的）事件类型 */
 exports.GLOBAL_ACTION_EVENTS = ['onLoad', 'onBeforeSubmit', 'onAfterSubmit'];
 /** 字段级多语言的 prop 集合（沿用旧视图时这些条目由生成器重建，不从旧 lang 携带） */
@@ -68,6 +120,28 @@ function collectUnreferencedFields(referencedKeys, built, details) {
     }
     return missing;
 }
+/**
+ * 由生成器统一管理的控件属性键：沿用已有 controlProps 时跳过（否则会覆盖新生成的身份信息、
+ * 选项、长度等）。其余键（如 address 的 range/multi/org、money 的 precision/symbol）
+ * 视为设计器配置，同控件包时原样沿用。
+ */
+const CONTROL_PROP_MANAGED_KEYS = new Set([
+    'id',
+    'desktop',
+    'mobile',
+    'name',
+    'uuid',
+    'title',
+    'span',
+    '$$tableType',
+    '$$tableName',
+    '$$lockMode',
+    'options',
+    'placeholder',
+    'maxLength',
+]);
+/** 不写入 fdFontExtendData 的键（options 由选项逻辑单独维护） */
+const FONT_EXTEND_SKIP_KEYS = new Set(['options', 'rules']);
 /** 控件配置面板默认值中，不应写入 controlProps 的键（属于样式/布局，存放在 controlStyle） */
 const DEFAULT_EXCLUDE_KEYS = new Set([
     'layout',
@@ -235,12 +309,25 @@ function completeOptionsI18n(field, lang, locales, messages) {
         field.fdFontExtendData = JSON.stringify(fontExtend);
     return count;
 }
-/** 依据数据项类型/逻辑类型解析控件包与元数据 */
+/**
+ * 依据数据项类型/逻辑类型解析控件包与元数据。
+ *
+ * 匹配顺序（前者优先）：
+ * 1. `CONTROL_TYPE_MAP[fdType]`：按控件逻辑类型精确匹配（避免「金额/评分/下拉」
+ *    被降级成同数据项类型的默认控件，如 number -> 数字）；
+ * 2. `controlMap[fdType]`：用户自定义映射；
+ * 3. **字段已有属性中的控件包**：CLI 未登记的环境控件按原样保留（不被降级破坏）；
+ * 4. `DEFAULT_CONTROL_MAP[fdDataType]`：按数据项类型兜底；
+ * 5. 自定义映射中 logicalType 相同的条目；
+ * 6. `FALLBACK_CONTROL`（输入框）。
+ */
 async function resolveControl(field, options) {
     const map = controlMapOf(options);
-    // 优先按控件逻辑类型（xform.type）匹配，避免把「金额/评分/下拉」等
-    // 错误降级成同数据项类型的默认控件（如 number -> 数字）
     let entry = constants_1.CONTROL_TYPE_MAP[field.fdType] ?? map[field.fdType];
+    // 未登记控件：从字段已有属性还原控件包（并保留原字段类型，不被控件包声明覆盖）
+    const preserved = entry ? undefined : preservedControlOf(field);
+    if (!entry)
+        entry = preserved;
     if (!entry)
         entry = map[field.fdDataType];
     if (!entry)
@@ -253,11 +340,34 @@ async function resolveControl(field, options) {
     return {
         desktopPkg: entry.desktop,
         mobilePkg: entry.mobile,
-        logicalType: meta?.xform?.type || entry.logicalType,
+        logicalType: preserved
+            ? field.fdType || preserved.logicalType
+            : meta?.xform?.type || entry.logicalType,
         meta,
         metaMobile,
     };
 }
+/**
+ * 从字段已有 `fdAttribute` 中还原控件包。
+ *
+ * 用于 **CLI 未登记的环境控件**（平台新增或定制控件包）：此时若直接回落到
+ * `FALLBACK_CONTROL`（输入框），`autofill` 会把表单里的高级控件**降级破坏**。
+ * 只要字段属性里带着控件包名，就原样沿用，控件类型得以保全。
+ */
+function preservedControlOf(field) {
+    if (typeof field.fdAttribute !== 'string')
+        return undefined;
+    const attr = (0, random_1.safeJsonParse)(field.fdAttribute, {});
+    const config = attr?.config;
+    const desktop = config?.controlProps?.desktop?.type;
+    if (!desktop)
+        return undefined;
+    return {
+        desktop,
+        mobile: config?.controlProps?.mobile?.type || desktop,
+        logicalType: config?.type || field.fdType || '',
+    };
+}
 /** 从 fdFontExtendData 提取需要注入 controlProps 的前端扩展属性 */
 function pickFontExtend(data) {
     const picked = {};
@@ -271,6 +381,61 @@ function pickFontExtend(data) {
 function fontExtendOf(field) {
     return pickFontExtend((0, random_1.safeJsonParse)(field.fdFontExtendData, {}));
 }
+/** 按点号路径取值（用于语义校验规则） */
+function getByPath(source, path) {
+    return path.split('.').reduce((acc, key) => {
+        if (!acc || typeof acc !== 'object')
+            return undefined;
+        return acc[key];
+    }, source);
+}
+/**
+ * 控件语义校验：`config.json` 必填属性之外、由控件属性面板/数据源弹窗强制的规则
+ * （`CONTROL_SEMANTIC_RULES`，如业务关联的「关联表单」与「显示项」）。
+ *
+ * @returns 未通过规则的报错文案
+ */
+function validateSemanticProps(logicalType, controlProps) {
+    const rules = constants_1.CONTROL_SEMANTIC_RULES[logicalType];
+    if (!rules?.length)
+        return [];
+    const get = (path) => getByPath(controlProps, path);
+    const renderMode = String(controlProps.renderMode ?? '');
+    const errors = [];
+    for (const rule of rules) {
+        if (rule.renderModes && !rule.renderModes.includes(renderMode))
+            continue;
+        const pass = rule.ok ? rule.ok(get) : Boolean(get(rule.path ?? ''));
+        if (!pass)
+            errors.push(rule.message);
+    }
+    return errors;
+}
+/**
+ * 把 `controlProps` 中「前端扩展数据」同步进 `fdFontExtendData`。
+ *
+ * 平台约定两处并存（前端 `syncApi.frontExtendData2Config` 反向同步、公式/接口 Schema 的
+ * `$ref` 依赖 `fdFontExtendData`）——例如 address（地址本）的 `orgTypeArr` 决定公式里
+ * 该字段是 `ORG_PERSON` 还是 `ORG_ALL`。缺了它，控件渲染仍走 controlProps，但公式取值
+ * 会退化。已有的其它键（如 options）原样保留。
+ */
+function syncFontExtendData(field, meta, controlProps) {
+    const keys = (0, widgets_1.collectFrontExtendKeys)(meta).filter(({ key }) => !FONT_EXTEND_SKIP_KEYS.has(key));
+    if (!keys.length)
+        return;
+    const fontExtend = field.fdFontExtendData
+        ? (0, random_1.safeJsonParse)(field.fdFontExtendData, {})
+        : {};
+    for (const { path, key } of keys) {
+        const [head, child] = path.split('.');
+        const value = child
+            ? controlProps[head]?.[child]
+            : controlProps[head];
+        if (value !== undefined)
+            fontExtend[key] = value;
+    }
+    field.fdFontExtendData = JSON.stringify(fontExtend);
+}
 /**
  * 生成数据项的 fdAttribute。
  *
@@ -293,11 +458,31 @@ function buildFieldAttribute(params) {
             controlDefaults[k] = defaults[k];
     });
     const showText = defaults.showText;
+    // 必填属性兜底默认值：支持 $title / $name 占位符（如「描述文字」默认取字段标题）
+    const requiredDefaults = {};
+    for (const [propKey, value] of Object.entries(constants_1.REQUIRED_PROP_DEFAULTS[resolved.desktopPkg] ?? {})) {
+        requiredDefaults[propKey] =
+            value === '$title' ? langKey : value === '$name' ? fieldName : value;
+    }
+    // 沿用同控件包的已有属性（设计器配置过的值优先于 config.json 默认值）
+    const carried = {};
+    const prev = params.prevControlProps;
+    const prevPkg = prev?.desktop?.type;
+    if (prev && prevPkg === resolved.desktopPkg) {
+        for (const [propKey, value] of Object.entries(prev)) {
+            if (!CONTROL_PROP_MANAGED_KEYS.has(propKey))
+                carried[propKey] = value;
+        }
+    }
     const controlProps = {
         ...controlDefaults,
+        // 设计器默认属性（控件包 config.json 未声明的，如业务关联的 renderMode=单一列表）
+        ...(constants_1.CONTROL_DEFAULT_PROPS[resolved.desktopPkg] ?? {}),
         // 必填属性兜底默认值（config.json 声明 required 但无 default 的项）
-        ...constants_1.REQUIRED_PROP_DEFAULTS[resolved.desktopPkg],
+        ...requiredDefaults,
+        ...carried,
         ...params.fontExtend,
+        ...(params.extraControlProps ?? {}),
         // 保留已有选项：本函数会重建 controlProps，不显式带回会丢失用户配置的 options
         ...(params.options && params.options.length ? { options: params.options } : {}),
         ...(params.placeholderKey ? { placeholder: params.placeholderKey } : {}),
@@ -386,6 +571,16 @@ function enrichField(field, model, resolved) {
 }
 /** 依据数据项生成（或补全）控件配置，并回写 fdAttribute / fdLabelLangKey */
 async function buildField(field, model, options, lang, locales) {
+    // 业务关联配置（--relation）命中该字段：先把数据类型改写为 relation，
+    // 使控件解析走业务关联控件（无论原字段是文本还是下拉）
+    const relationSpec = options.relations?.find((item) => item.fieldName === field.fdName);
+    if (relationSpec) {
+        field.fdType = 'relation';
+        field.fdDataType = 'relation';
+        field.fdDictType = 'querySourceDict';
+        if (!field.fdLength)
+            field.fdLength = 200;
+    }
     const resolved = await resolveControl(field, options);
     const span = options.span ?? constants_1.DEFAULT_SPAN;
     enrichField(field, model, resolved);
@@ -400,24 +595,47 @@ async function buildField(field, model, options, lang, locales) {
         type: 'input',
         content: buildLangContent(locales, field.fdLabel || field.fdName, field.fdName, options.messages),
     };
-    // 控件占位提示多语言（约定 key：{pkg}###langs###placeholder）
+    // 已有控件属性（沿用选项、提示文字等）
+    const prevAttr = (0, random_1.safeJsonParse)(field.fdAttribute, {});
+    // 控件提示文字多语言。
+    // ① 已有提示文字优先沿用（设计器里的自定义文案不能丢，如「请选择交办日期」）；
+    // ② 否则取控件自带译文——资源键**因控件而异**（datetime=pleaseEnter、m-datetime=enter、
+    //    area=pleaseSelect，其余=placeholder），键名不对就取不到文案（日期控件提示文字缺失即此原因）。
     let placeholderKey;
     const registry = options.registry;
     if (registry && (0, widgets_1.hasConfigItem)(resolved.meta, 'placeholder')) {
-        const langs = await registry.getElementLangs((0, widgets_1.elementLangKey)(resolved.desktopPkg, 'placeholder'));
-        // 控件自带的多语言（zh-cn/en-us/...），用于填充非主语言的真实译文
-        const elementLangs = langs ? (0, locale_1.normalizeLangMap)(langs) : undefined;
-        const value = elementLangs?.[locales[0]] ??
-            elementLangs?.[constants_1.DEFAULT_LOCALE] ??
-            (elementLangs ? Object.values(elementLangs)[0] : undefined);
-        if (value) {
-            placeholderKey = (0, random_1.generateMessageKey)();
-            lang[placeholderKey] = {
-                prop: 'placeholder',
-                name: field.fdName,
-                type: 'input',
-                content: buildLangContent(locales, value, undefined, options.messages, elementLangs),
-            };
+        const prevPlaceholder = prevAttr?.config?.controlProps?.placeholder;
+        const prevLangEntry = typeof prevPlaceholder === 'string' ? options.prevLang?.[prevPlaceholder] : undefined;
+        if (typeof prevPlaceholder === 'string' &&
+            prevPlaceholder &&
+            (prevLangEntry || !(0, random_1.isMessageKey)(prevPlaceholder))) {
+            placeholderKey = prevPlaceholder;
+            if (prevLangEntry)
+                lang[prevPlaceholder] = prevLangEntry;
+        }
+        else {
+            const mapped = constants_1.CONTROL_PLACEHOLDER_LANG_KEYS[resolved.desktopPkg];
+            const candidates = [
+                ...new Set([mapped, ...constants_1.PLACEHOLDER_LANG_KEY_CANDIDATES].filter(Boolean)),
+            ];
+            for (const keyName of candidates) {
+                const langs = await registry.getElementLangs((0, widgets_1.elementLangKey)(resolved.desktopPkg, keyName));
+                // 控件自带的多语言（zh-cn/en-us/...），用于填充非主语言的真实译文
+                const elementLangs = langs ? (0, locale_1.normalizeLangMap)(langs) : undefined;
+                const value = elementLangs?.[locales[0]] ??
+                    elementLangs?.[constants_1.DEFAULT_LOCALE] ??
+                    (elementLangs ? Object.values(elementLangs)[0] : undefined);
+                if (!value)
+                    continue;
+                placeholderKey = (0, random_1.generateMessageKey)();
+                lang[placeholderKey] = {
+                    prop: 'placeholder',
+                    name: field.fdName,
+                    type: 'input',
+                    content: buildLangContent(locales, value, undefined, options.messages, elementLangs),
+                };
+                break;
+            }
         }
     }
     // 新建选项（--option）：写入 fdFontExtendData.options，作为选项的唯一来源
@@ -437,7 +655,6 @@ async function buildField(field, model, options, lang, locales) {
         field.fdFontExtendData = JSON.stringify(fontExtend);
     }
     // 保留已有的控件选项（数据项/设计器中配置），否则重建 attribute 会丢
-    const prevAttr = (0, random_1.safeJsonParse)(field.fdAttribute, {});
     const attrOptions = prevAttr?.config?.controlProps?.options;
     const fontOptions = field.fdFontExtendData
         ? ((0, random_1.safeJsonParse)(field.fdFontExtendData, {}).options ?? [])
@@ -462,13 +679,33 @@ async function buildField(field, model, options, lang, locales) {
         placeholderKey,
         fontExtend: fontExtendOf(field),
         options: prevOptions.length ? prevOptions : undefined,
+        prevControlProps: prevAttr?.config?.controlProps,
+        extraControlProps: relationSpec ? buildRelationProps(relationSpec) : undefined,
     });
     field.fdAttribute = attribute;
+    // 前端扩展数据同步（如 address 的 orgTypeArr/multi/range）
+    syncFontExtendData(field, resolved.meta, (config.controlProps ?? {}));
+    // 业务关联的前端扩展数据（控件源码 JSDoc 声明的 @frontExtendData 路径）：
+    // modelId/refFieldName/tableType/tableName、datasource 各键、renderMode、outParams
+    if (relationSpec) {
+        const fontExtend = field.fdFontExtendData
+            ? (0, random_1.safeJsonParse)(field.fdFontExtendData, {})
+            : {};
+        const props = (config.controlProps ?? {});
+        for (const path of constants_1.RELATION_FRONT_EXTEND_PATHS) {
+            const value = getByPath(props, path);
+            if (value !== undefined)
+                fontExtend[path.split('.').pop()] = value;
+        }
+        field.fdFontExtendData = JSON.stringify(fontExtend);
+    }
     // 选项多语言（下拉/单选/多选）
     const optionCount = completeOptionsI18n(field, lang, locales, options.messages);
     // 控件必填属性校验（对齐设计器发布前校验）
     const propErrors = (0, widgets_1.validateRequiredProps)(resolved.meta, config);
-    return { field, model, resolved, langKey, optionCount, propErrors };
+    // 控件语义校验（属性面板/数据源弹窗强制的规则，如业务关联的关联表单与显示项）
+    const semanticErrors = validateSemanticProps(resolved.logicalType, (config.controlProps ?? {}));
+    return { field, model, resolved, langKey, optionCount, propErrors, semanticErrors };
 }
 /** 构建虚拟行：控件节点在持久化格式中**只保留 key 引用** */
 function buildRows(built, options) {
@@ -489,7 +726,7 @@ function buildRows(built, options) {
     return rows;
 }
 /**
- * 栅格布局：`layout` → `@elem/layout-grid` → 若干 `@elem/layout-grid.GridItem`。
+ * 栅格布局：`layout` → `@elem/layout-grid` → `columns × rows` 个 `@elem/layout-grid.GridItem`。
  *
  * 结构依据真实环境表单（`layout~xxxx` / `controlProps:{id}`）：
  * ```
@@ -497,6 +734,9 @@ function buildRows(built, options) {
  *   └ @elem/layout-grid       { controlProps:{ id, columns, rows } }
  *       └ GridItem            { controlProps:{ id, column, row, rowSpan, columnSpan, style:{backgroundColor:''} }, children:[{key:<fieldUuid>}] }
  * ```
+ * **最后一行的空位也要保留**：`GridItem` 总数 = `columns × rows`，未放控件的格子为
+ * `children: []`、`controlProps: { id, column, row }`（与设计器一致，已核对真实表单——
+ * 如《业务审批管理》cols=3 而字段只有 2 个，第 3 个格子为空仍在）。
  * 注意：栅格布局控件**不进** `controlMappings`（已核对真实表单）。
  */
 function buildGrid(built, columns) {
@@ -504,6 +744,7 @@ function buildGrid(built, columns) {
     const rows = Math.max(1, Math.ceil(built.length / cols));
     const layoutKey = (0, random_1.generateCmptKey)(constants_1.LAYOUT);
     const gridKey = (0, random_1.generateCmptKey)(constants_1.LAYOUT_GRID);
+    // 先放控件，再补齐最后一行的空位（总数 = cols × rows；无字段时不生成格子）
     const items = built.map((item, index) => {
         const itemKey = (0, random_1.generateCmptKey)(constants_1.LAYOUT_GRID_ITEM);
         return {
@@ -521,6 +762,21 @@ function buildGrid(built, columns) {
             children: [{ key: item.field.uuid }],
         };
     });
+    for (let index = built.length; index < (built.length ? rows * cols : 0); index++) {
+        const itemKey = (0, random_1.generateCmptKey)(constants_1.LAYOUT_GRID_ITEM);
+        items.push({
+            key: itemKey,
+            type: constants_1.LAYOUT_GRID_ITEM,
+            kind: 'container',
+            // 空位与设计器一致：仅 column/row/id，children 为空
+            controlProps: {
+                column: (index % cols) + 1,
+                row: Math.floor(index / cols) + 1,
+                id: itemKey,
+            },
+            children: [],
+        });
+    }
     return [
         {
             key: layoutKey,
@@ -966,16 +1222,29 @@ function applyControlActions(formAttr, targets, actions) {
     const warnings = [];
     let completed = 0;
     for (const action of actions) {
-        // 函数名：显式指定 > 源码解析 > 自动生成；重名时按前端规则追加后缀
-        const base = action.name ??
+        // 函数名：显式指定 > 源码解析 > 自动生成
+        let rawName = action.name ??
             extractFunctionName(action.source) ??
             `${action.event}_${action.target.replace(/[^\w]/g, '_')}`;
-        const name = usedNames.has(base) ? `${base}_${(0, random_1.uuid)()}` : base;
-        if (name !== base) {
-            warnings.push(`动作函数重名：${base} 已重命名为 ${name}`);
+        let source = action.source;
+        // 命名规范：禁止裸事件名（onChange / onClick / onLoad 等）——无法分辨触发控件。
+        // 统一追加控件 ID：onChange -> onChange_<fdName>（$global 全局动作保持裸事件名，不做后缀）
+        if (action.target !== exports.ACTION_GLOBAL_TARGET && /^on[A-Z][a-zA-Z0-9]*$/.test(rawName)) {
+            const suffix = action.target === exports.ACTION_GLOBAL_TARGET ? 'global' : action.target;
+            const normalized = `${rawName}_${suffix}`;
+            // 同步重写源码中的函数声明，保持 JS 面板展示一致（仅替换声明处，不影响函数体）
+            const decl = `function ${rawName}(`;
+            if (source.includes(decl))
+                source = source.replace(decl, `function ${normalized}(`);
+            warnings.push(`动作函数名 "${rawName}" 无法分辨触发控件，已规范为 "${normalized}"`);
+            rawName = normalized;
+        }
+        const name = usedNames.has(rawName) ? `${rawName}_${(0, random_1.uuid)()}` : rawName;
+        if (name !== rawName) {
+            warnings.push(`动作函数重名：${rawName} 已重命名为 ${name}`);
         }
         usedNames.add(name);
-        const item = { name, id: (0, random_1.uuid)(), function: action.source };
+        const item = { name, id: (0, random_1.uuid)(), function: source };
         if (action.target === exports.ACTION_GLOBAL_TARGET) {
             ;
             (globalMap[_a = action.event] ?? (globalMap[_a] = [])).push(item);
@@ -1106,6 +1375,9 @@ async function buildFdConfig(models, options = {}, stats) {
         for (const error of builtField.propErrors) {
             validationErrors.push(`字段 ${field.fdName}（${builtField.resolved.desktopPkg}）：请输入${error.label}（${error.key}）`);
         }
+        for (const error of builtField.semanticErrors) {
+            validationErrors.push(`字段 ${field.fdName}（${builtField.resolved.desktopPkg}）：${error}`);
+        }
     }
     // ---------- 明细表 ----------
     const detailModels = models.filter((m) => m.fdType === 'detail');
@@ -1131,6 +1403,9 @@ async function buildFdConfig(models, options = {}, stats) {
                 for (const error of builtField.propErrors) {
                     validationErrors.push(`明细字段 ${model.fdTableName}.${field.fdName}（${builtField.resolved.desktopPkg}）：请输入${error.label}（${error.key}）`);
                 }
+                for (const error of builtField.semanticErrors) {
+                    validationErrors.push(`明细字段 ${model.fdTableName}.${field.fdName}（${builtField.resolved.desktopPkg}）：${error}`);
+                }
             }
             // 明细表标题多语言（prop:label，content 额外带 default）
             const langKey = (0, random_1.isMessageKey)(model.fdLabelLangKey)
@@ -1214,6 +1489,22 @@ async function buildFdConfig(models, options = {}, stats) {
             stats.actionWarnings = actionResult.warnings;
         if (validationErrors.length)
             stats.validationErrors = validationErrors;
+        // 需到设计器完成配置的高级控件（关键属性是环境对象选择，CLI 无法替选）。
+        // 仅在该字段确实缺配置（有必填/语义校验错误）时提示——已配置好的字段不该被误导；
+        // associatedFields 无必填属性、问题只在发布时暴露，故无条件提示。
+        const notes = new Set();
+        for (const item of [...built, ...details.flatMap((d) => d.fields)]) {
+            const logicalType = String(item.field.fdType);
+            const note = constants_1.CONTROL_DESIGNER_NOTES[logicalType];
+            if (!note)
+                continue;
+            const hasErrors = item.propErrors.length > 0 || item.semanticErrors.length > 0;
+            if (!hasErrors && !constants_1.CONTROL_NOTE_WITHOUT_ERRORS.has(logicalType))
+                continue;
+            notes.add(`${item.field.fdLabel || item.field.fdName}（${logicalType}）—— ${note}`);
+        }
+        if (notes.size)
+            stats.controlWarnings = [...notes];
     }
     return {
         id: options.formId ?? '',
@@ -1246,6 +1537,14 @@ async function createDataField(spec, options = {}) {
         controlType = dataType;
         dataType = undefined;
     }
+    // 容器类控件不是数据项（明细表/大数据明细/分页），给出明确指引而不是模糊报错。
+    // 第三段既可写数据项类型也可写控件类型（见下方容错），两个位置都要拦。
+    for (const token of [spec.controlType, spec.dataType]) {
+        const container = token ? constants_1.CONTAINER_CONTROL_TYPES[token] : undefined;
+        if (container) {
+            throw new Error(`"${token}" 是容器类控件，不能用 --add-field 创建：${container.hint}`);
+        }
+    }
     let entry;
     if (controlType) {
         entry = alias[controlType];
@@ -1265,16 +1564,22 @@ async function createDataField(spec, options = {}) {
     const registry = options.registry;
     const meta = registry ? await registry.get(entry.desktop) : null;
     const xform = meta?.xform ?? {};
+    // 元数据（控件包 config.json）优先，映射表兜底：高级控件中 desc/serial-number
+    // 等控件包未声明 dataType，必须靠映射表补齐，否则数据项类型为空会导致保存失败
+    const resolvedDataType = xform.dataType || entry.dataType || dataType || 'varchar';
+    const resolvedDictType = xform.dictType || entry.dictType;
+    const resolvedLength = xform.defaultLength ?? entry.defaultLength ?? 0;
+    const resolvedStored = xform.isStored ?? entry.isStored ?? true;
     return {
         fdName: spec.name || `${constants_1.FIELD_NAME_PREFIX}${Math.random().toString(36).slice(-6)}`,
         fdLabel: spec.label,
-        fdDataType: xform.dataType ?? dataType,
+        fdDataType: resolvedDataType,
         fdType: xform.type || entry.logicalType,
-        fdDictType: xform.dictType,
-        fdLength: xform.defaultLength ?? 0,
+        ...(resolvedDictType ? { fdDictType: resolvedDictType } : {}),
+        fdLength: resolvedLength,
         fdIsSystem: false,
         fdDisplay: true,
-        fdIsStored: true,
+        fdIsStored: resolvedStored,
         fdState: 'effective',
     };
 }

package/dist/index.js

@@ -9,7 +9,7 @@ const field_1 = require("./commands/field");
 const form_1 = require("./commands/form");
 const locale_1 = require("./commands/locale");
 const logger_1 = require("./utils/logger");
-const VERSION = '2.0.0';
+const VERSION = '2.2.0';
 const program = new commander_1.Command();
 exports.program = program;
 program
@@ -103,9 +103,18 @@ ${logger_1.color.bold('从零到一')}
 ${logger_1.color.bold('常用查询')}
   llc app list [--keyword 名称] [--no-auth]     应用列表（fdId 即 --app-id）
   llc app forms --id <appId>                    应用下表单列表
+  llc control list                              环境可用控件（含高级控件；明细/分页为容器类）
   llc locale list                               环境提供了哪些语言译文
   llc field library [--keyword 关键词]           字段库
 
+${logger_1.color.gray('高级控件（desc / tags / mdm / association / mechnumber …）与普通控件同样写法：')}
+  llc form autofill --id <fdId> --apply --add-field "字段名:标题:控件类型"
+  ${logger_1.color.gray('（需环境对象选择的控件会在生成时提示，并需到设计器补配置）')}
+
+${logger_1.color.gray('业务关联（relation）用 --relation 配置业务对象与显示项：')}
+  llc form autofill --id <fdId> --apply --publish \\
+    --add-field "fd_r:关联选择:relation" --relation "fd_r=目标表单名"
+
 环境变量：
   LLC_BASE_URL    服务端基址
   LLC_TOKEN       鉴权 Token