lan-low-code-cli 2.1.0 → 2.3.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,62 @@ 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` + 显示方式）。
+ *
+ * 骨架逐键对齐**设计器手动创建的真实字段**（物料入库单 `fd_col_9bg1ms`）：
+ * - `refFieldName` 是 `$<字段名>$` 引用（运行时解析为所选记录的显示值）——
+ *   早期版本误写成 `$<表名>.<字段名>$`，运行时解析不到就会把字面量显示出来；
+ * - 不写 `showFields`（设计器不生成该键）；
+ * - `datasource.queryCondition` 是 `{ linkType, query: {} }`——带 `conditionGroup` 的
+ *   完整条件结构会导致运行时**列表加载失败**；
+ * - `isDisplayMode` 必须为 `false`（true 是「仅展示」模式）；
+ * - 不写 `queryCollection` / `sorters` / `querySorters`（设计器未配置时不生成）。
+ */
+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,
+            refFieldName: spec.refFieldName,
+            tableType: 'main',
+            tableName: target.tableName,
+            fdFormType: target.fdFormType ?? 0,
+        },
+        datasource: {
+            queryCondition: { linkType: '$and', query: {} },
+            columns,
+            filters: spec.filters ?? [],
+            tree: {
+                treeLoop: true,
+                querySorters: [],
+                conditionSetting: false,
+                relationCfg: {},
+                relationConditions: [{ operator: { value: '$eq' }, value: { format: 'field' } }],
+                queryCondition: {
+                    linkType: '$and',
+                    query: { type: 'conditionGroup', condition: [] },
+                },
+                navigationMode: 'custom',
+                // 树导航的实体引用（sys-modeling#<表单fdId>），设计器创建的字段必有
+                entityName: `sys-modeling#${target.modelId}`,
+            },
+            isListThrough: true,
+            isDisplayMode: false,
+            viewId: '',
+            conditionSetting: false,
+            isForwardView: true,
+        },
+        ...(spec.outParams ? { outParams: spec.outParams } : {}),
+    };
+}
 /** 全局动作支持的（前端注册的）事件类型 */
 exports.GLOBAL_ACTION_EVENTS = ['onLoad', 'onBeforeSubmit', 'onAfterSubmit'];
 /** 字段级多语言的 prop 集合（沿用旧视图时这些条目由生成器重建，不从旧 lang 携带） */
@@ -68,6 +125,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 +314,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 +345,35 @@ 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,
+        kind: entry.kind ?? 'control',
         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 +387,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 +464,39 @@ 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) {
+        // 业务关联重建时（extraControlProps 提供 relationCfg/datasource），旧字段可能带着
+        // 早期版本写入的空 outParams——设计器创建的字段没有这个键，不沿用
+        const skipStaleOutParams = params.extraControlProps != null && !('outParams' in params.extraControlProps);
+        for (const [propKey, value] of Object.entries(prev)) {
+            if (skipStaleOutParams && propKey === 'outParams')
+                continue;
+            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,
+        // 设计器新建控件的默认属性（逐键取自设计器落库，见 CONTROL_DESIGNER_DEFAULTS）——
+        // 按控件逻辑类型匹配，修正 CLI 与设计器新建控件的默认值差异
+        ...(constants_1.CONTROL_DESIGNER_DEFAULTS[resolved.logicalType] ?? {}),
+        ...carried,
         ...params.fontExtend,
+        ...(params.extraControlProps ?? {}),
         // 保留已有选项：本函数会重建 controlProps，不显式带回会丢失用户配置的 options
         ...(params.options && params.options.length ? { options: params.options } : {}),
         ...(params.placeholderKey ? { placeholder: params.placeholderKey } : {}),
@@ -328,7 +527,7 @@ function buildFieldAttribute(params) {
     const config = {
         key,
         type: logicalType,
-        kind: 'control',
+        kind: resolved.kind,
         label: langKey,
         controlProps,
         labelProps,
@@ -374,10 +573,9 @@ function enrichField(field, model, resolved) {
                     passValue: false,
                     trace: false,
                     encrypt: false,
-                    // 初始值模式：config.json 默认 'null'（无初始值）。不能写 'formula'——
-                    // 公式模式下 defaultValueFormulaVO 必填，设计器提交会被拦截
-                    defaultValueType: 'null',
                     encryptDefinition: {},
+                    // 注意：不写 defaultValueType——由 CONTROL_DESIGNER_DEFAULTS 提供各控件
+                    // 的设计器默认值（formula/fixed/defalut…），并在构建后回同步到此处
                 });
     }
     if (!field.fdIsSystem && (field.fdOrder === undefined || field.fdOrder === null)) {
@@ -386,6 +584,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 +608,65 @@ 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),
-            };
+    // 门控：config.json 声明了 placeholder 的控件 + 面板由设计器拼装（config.json 未声明
+    // 但设计器新建时同样写提示文字）的控件。两者都不满足的（radio/checkbox/button 等）
+    // 设计器也不写提示文字——不能仅凭资源探测，否则会多写（已与设计器新建表单核对）
+    if (registry &&
+        ((0, widgets_1.hasConfigItem)(resolved.meta, 'placeholder') || constants_1.PLACEHOLDER_PANEL_PKGS[resolved.desktopPkg])) {
+        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;
+            }
+            // 拼装面板控件（config.json 未声明 placeholder）：控件资源探测不到时使用
+            // 设计器的通用默认文案（选择类=请选择、输入类=请输入，见 PLACEHOLDER_PANEL_PKGS）
+            if (!placeholderKey) {
+                const fallbackText = constants_1.PLACEHOLDER_PANEL_PKGS[resolved.desktopPkg];
+                if (fallbackText) {
+                    placeholderKey = (0, random_1.generateMessageKey)();
+                    lang[placeholderKey] = {
+                        prop: 'placeholder',
+                        name: field.fdName,
+                        type: 'input',
+                        content: buildLangContent(locales, fallbackText, undefined, options.messages),
+                    };
+                }
+            }
         }
     }
     // 新建选项（--option）：写入 fdFontExtendData.options，作为选项的唯一来源
@@ -437,7 +686,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 ?? [])
@@ -450,6 +698,21 @@ async function buildField(field, model, options, lang, locales) {
             label: item?.label,
             value: item?.value,
         }));
+    // 选项类控件缺省选项：对齐设计器新建时的默认选项（选项1/2/3，值 1/2/3，含多语言）。
+    // CLI 此前不写默认选项，下拉/单选/多选运行时是空选项（真实缺陷，已与设计器新建表单核对）
+    const defaultOptions = !prevOptions.length && !specified?.length &&
+        ['radio', 'checkbox', 'select', 'select~multi'].includes(String(field.fdType))
+        ? ['1', '2', '3'].map((value, i) => {
+            const key = (0, random_1.generateMessageKey)();
+            lang[key] = {
+                prop: 'option',
+                name: field.fdName,
+                type: 'input',
+                content: buildLangContent(locales, `选项${i + 1}`, undefined, options.messages),
+            };
+            return { label: key, value };
+        })
+        : undefined;
     const { attribute, config } = buildFieldAttribute({
         fieldUuid: field.uuid,
         langKey,
@@ -461,14 +724,49 @@ async function buildField(field, model, options, lang, locales) {
         resolved,
         placeholderKey,
         fontExtend: fontExtendOf(field),
-        options: prevOptions.length ? prevOptions : undefined,
+        options: prevOptions.length ? prevOptions : defaultOptions,
+        prevControlProps: prevAttr?.config?.controlProps,
+        extraControlProps: relationSpec ? buildRelationProps(relationSpec) : undefined,
     });
     field.fdAttribute = attribute;
+    // 前端扩展数据同步（如 address 的 orgTypeArr/multi/range）
+    syncFontExtendData(field, resolved.meta, (config.controlProps ?? {}));
+    // fdFontExtendData.defaultValueType 与 controlProps 保持一致（设计器行为：
+    // 新建控件的默认初始值模式为 formula/fixed/defalut 等，见 CONTROL_DESIGNER_DEFAULTS）
+    {
+        const feObj = (0, random_1.safeJsonParse)(field.fdFontExtendData, {});
+        const cpObj = (config.controlProps ?? {});
+        if (cpObj.defaultValueType !== undefined && feObj.defaultValueType !== cpObj.defaultValueType) {
+            feObj.defaultValueType = cpObj.defaultValueType;
+            field.fdFontExtendData = JSON.stringify(feObj);
+        }
+    }
+    // 业务关联的前端扩展数据（控件源码 JSDoc 声明的 @frontExtendData 路径）：
+    // modelId/refFieldName/tableType/tableName、datasource 各键、renderMode、outParams
+    if (relationSpec) {
+        const fontExtend = field.fdFontExtendData
+            ? (0, random_1.safeJsonParse)(field.fdFontExtendData, {})
+            : {};
+        // 早期版本生成、现在不再写的键：清掉，避免运行时拿到过期结构
+        for (const stale of ['queryCollection', 'querySorters', 'sorters'])
+            delete fontExtend[stale];
+        if (!relationSpec.outParams)
+            delete fontExtend.outParams;
+        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 +787,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 +795,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 +805,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 +823,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,
@@ -676,6 +993,9 @@ function wrapAppearance(tableName, children) {
                 key: constants_1.MAIN,
                 type: constants_1.MAIN,
                 kind: 'container',
+                // 设计器保存时经 setMainCmpt 写入（ide/editor/runtime/business/feature.ts），
+                // 值为空也必须带键：CLI 曾缺失该属性，与设计器发布的视图不一致
+                controlProps: { importBtn: null, onDesktopImport: null },
                 children,
             },
         ],
@@ -687,7 +1007,7 @@ function wrapAppearance(tableName, children) {
  * 注意：栅格布局（`layout` / `@elem/layout-grid` / `GridItem`）**不写入**此处，
  * 而多页签（`tab-appearance` / `tabs` / `tabpane`）**需要写入** —— 均为真实表单核对结论。
  */
-function buildControlMappings(built, options = {}) {
+function buildControlMappings(built, options = {}, details = []) {
     /** 布局控件的兜底元数据（控件包无 xform 时用，与真实表单的 xform.type 一致） */
     const layoutDefaults = {
         [constants_1.TAB_APPEARANCE]: 'tabAppearance',
@@ -697,11 +1017,13 @@ function buildControlMappings(built, options = {}) {
     const build = (platform) => {
         const seen = new Set();
         const list = [];
-        built.forEach((item) => {
+        // **主表 + 明细字段**的控件都要进映射：运行时按 controlMappings 解析控件，
+        // 明细字段的控件缺失时明细表渲染不完整（如顶部操作栏不出现）——真实缺陷已核对
+        for (const item of [...built, ...details.flatMap((d) => d.fields)]) {
             const pkg = platform === 'desktop' ? item.resolved.desktopPkg : item.resolved.mobilePkg;
             const meta = platform === 'desktop' ? item.resolved.meta : item.resolved.metaMobile;
             if (!pkg || seen.has(pkg))
-                return;
+                continue;
             seen.add(pkg);
             const xform = { ...(meta?.xform ?? {}), type: item.resolved.logicalType };
             // 前端 handleFindXFormWidgets 会把包级 env 同步进 xform.env
@@ -710,7 +1032,7 @@ function buildControlMappings(built, options = {}) {
                 xform.env = meta.env;
             }
             list.push({ name: pkg, platform, xform });
-        });
+        }
         if (options.layout === 'tabs') {
             const pkgs = platform === 'desktop'
                 ? [constants_1.TAB_APPEARANCE, constants_1.TABS, constants_1.TAB_PANE]
@@ -745,7 +1067,7 @@ function buildViewModel(built, mainTableName, options = {}, lang = {}, locales =
     });
     // 页签多语言只生成一次，供桌面端渲染树复用
     const panes = options.layout === 'tabs' ? resolveTabs(built, options, lang, locales) : [];
-    const mappings = buildControlMappings(built, options);
+    const mappings = buildControlMappings(built, options, details);
     if (detailMappings?.desktop.length)
         mappings.desktop.push(...detailMappings.desktop);
     if (detailMappings?.mobile.length)
@@ -820,7 +1142,7 @@ function buildAuth(models, options = {}) {
                     hide: false,
                     ...perm.edit?.[field.fdName],
                 };
-                viewFields[field.fdName] = { visible: true, ...perm.view?.[field.fdName] };
+                viewFields[field.fdName] = { visible: true, hide: false, ...perm.view?.[field.fdName] };
             });
             add[model.fdTableName] = {
                 ...constants_1.DETAIL_ROW_FLAGS.add,
@@ -857,7 +1179,28 @@ function buildAuth(models, options = {}) {
                 hide: false,
                 ...perm.edit?.[field.fdName],
             };
-            viewFields[field.fdName] = { visible: true, ...perm.view?.[field.fdName] };
+            viewFields[field.fdName] = { visible: true, hide: false, ...perm.view?.[field.fdName] };
+        });
+        // 明细表在主表 auth 中以「字段条目」出现，携带行操作（添加行/删除行/导入/导出）。
+        // 缺失时运行时明细表顶部操作栏不渲染（真实缺陷，设计器保存的结构已核对）
+        models
+            .filter((m) => m.fdType === 'detail')
+            .forEach((detail) => {
+            addFields[detail.fdTableName] = {
+                ...constants_1.DETAIL_MAIN_FIELD_BASE.add,
+                ...perm.add?.[detail.fdTableName],
+                operations: constants_1.DETAIL_MAIN_FIELD_OPERATIONS.add,
+            };
+            editFields[detail.fdTableName] = {
+                ...constants_1.DETAIL_MAIN_FIELD_BASE.add,
+                ...perm.edit?.[detail.fdTableName],
+                operations: constants_1.DETAIL_MAIN_FIELD_OPERATIONS.add,
+            };
+            viewFields[detail.fdTableName] = {
+                ...constants_1.DETAIL_MAIN_FIELD_BASE.view,
+                ...perm.view?.[detail.fdTableName],
+                operations: constants_1.DETAIL_MAIN_FIELD_OPERATIONS.view,
+            };
         });
         add[model.fdTableName] = { fields: addFields };
         edit[model.fdTableName] = { fields: editFields };
@@ -1119,6 +1462,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');
@@ -1144,6 +1490,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 +1563,54 @@ async function buildFdConfig(models, options = {}, stats) {
                 ];
             }
         }
+        // 沿用视图时同样补齐 `<main>` 节点的 controlProps（设计器保存时经 setMainCmpt 写入，
+        // CLI 早期版本重建的视图缺失；详见 wrapAppearance 注释），并把 controlMappings
+        // 与重建的映射做并集——旧视图的映射可能缺明细字段的控件（真实缺陷）
+        const rebuiltMappings = buildControlMappings(built, options, details);
+        for (const vm of viewModel) {
+            const viewConfig = (0, random_1.safeJsonParse)(vm.fdConfig, {});
+            const render = viewConfig?.view?.render;
+            if (!render)
+                continue;
+            let patched = false;
+            const patchMain = (nodes) => {
+                for (const node of nodes) {
+                    if (!node || typeof node !== 'object')
+                        continue;
+                    if (node.type === constants_1.MAIN) {
+                        node.controlProps = {
+                            importBtn: null,
+                            onDesktopImport: null,
+                            ...(node.controlProps ?? {}),
+                        };
+                        patched = true;
+                        return true;
+                    }
+                    if (Array.isArray(node.children) && patchMain(node.children))
+                        return true;
+                }
+                return false;
+            };
+            for (const platform of Object.keys(render)) {
+                if (Array.isArray(render[platform]))
+                    patchMain(render[platform]);
+            }
+            // controlMappings 并集：旧条目保留（如页签控件），重建条目按 name 覆盖（元数据最新）
+            const cm = viewConfig.view?.controlMappings;
+            if (cm) {
+                for (const platform of ['desktop', 'mobile']) {
+                    const byName = new Map((Array.isArray(cm[platform]) ? cm[platform] : []).map((e) => [e.name, e]));
+                    for (const entry of rebuiltMappings[platform] ?? [])
+                        byName.set(entry.name, entry);
+                    for (const entry of detailMappings?.[platform] ?? [])
+                        byName.set(entry.name, entry);
+                    cm[platform] = [...byName.values()];
+                    patched = true;
+                }
+            }
+            if (patched)
+                vm.fdConfig = JSON.stringify(viewConfig);
+        }
     }
     else {
         viewModel = buildViewModel(built, mainTableName, options, lang, locales, details, detailMappings);
@@ -1227,7 +1624,28 @@ 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];
     }
+    // attribute：formAttr 重建，其余顶层键（dataUnique / subjectRule 等）从已有设计整体保留
+    let prevAttributeObj = {};
+    if (options.prevAttribute)
+        prevAttributeObj = (0, random_1.safeJsonParse)(options.prevAttribute, {});
+    delete prevAttributeObj.formAttr;
     return {
         id: options.formId ?? '',
         name: options.formName ?? '',
@@ -1236,7 +1654,7 @@ async function buildFdConfig(models, options = {}, stats) {
         entityCode: options.entityCode ?? constants_1.ENTITY_CODE,
         dataModel: models,
         auth: buildAuth(models, options),
-        attribute: { formAttr: JSON.stringify(formAttr) },
+        attribute: { ...prevAttributeObj, formAttr: JSON.stringify(formAttr) },
         error: JSON.stringify({}),
         lang: JSON.stringify(lang),
         authFilter: { detailAuthDefine: {} },
@@ -1259,6 +1677,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];
@@ -1278,16 +1704,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',
     };
 }