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

package/dist/generator/index.js

@@ -0,0 +1,1304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLOBAL_ACTION_EVENTS = exports.ACTION_GLOBAL_TARGET = void 0;
+exports.resolveLocales = resolveLocales;
+exports.completeOptionsI18n = completeOptionsI18n;
+exports.buildViewModel = buildViewModel;
+exports.applyControlActions = applyControlActions;
+exports.buildFdConfig = buildFdConfig;
+exports.createDataField = createDataField;
+exports.parseFieldSpec = parseFieldSpec;
+exports.buildFormDefinePayload = buildFormDefinePayload;
+const constants_1 = require("../constants");
+const locale_1 = require("../utils/locale");
+const random_1 = require("../utils/random");
+const widgets_1 = require("../widgets");
+/** `$global`：动作目标为表单全局（onLoad / onBeforeSubmit / onAfterSubmit） */
+exports.ACTION_GLOBAL_TARGET = '$global';
+/** 全局动作支持的（前端注册的）事件类型 */
+exports.GLOBAL_ACTION_EVENTS = ['onLoad', 'onBeforeSubmit', 'onAfterSubmit'];
+/** 字段级多语言的 prop 集合（沿用旧视图时这些条目由生成器重建，不从旧 lang 携带） */
+const FIELD_LANG_PROPS = new Set(['label', 'placeholder', 'option']);
+/**
+ * 校验并规范化已有 viewModel。
+ *
+ * 合法性：视图 fdConfig 可解析、含 `view.render.desktop` 渲染树与 `view.controlMappings`，
+ * 且无 type 的节点是「纯 key 引用」形态（老版本 CLI 生成的整节点拷贝会重建而不是沿用）。
+ */
+function normalizePrevViewModel(prevViewModel) {
+    if (!Array.isArray(prevViewModel) || prevViewModel.length === 0)
+        return undefined;
+    const viewConfig = (0, random_1.safeJsonParse)(prevViewModel[0]?.fdConfig, {});
+    const desktop = viewConfig?.view?.render?.desktop;
+    if (!Array.isArray(desktop) || !viewConfig?.view?.controlMappings)
+        return undefined;
+    const referencedKeys = new Set();
+    let valid = true;
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (!node || typeof node !== 'object')
+                continue;
+            if (node.type === undefined) {
+                // 引用节点必须是 { key, children? } 纯引用
+                if (typeof node.key !== 'string' || node.controlProps !== undefined || node.kind !== undefined) {
+                    valid = false;
+                    return;
+                }
+                referencedKeys.add(node.key);
+            }
+            if (Array.isArray(node.children))
+                walk(node.children);
+        }
+    };
+    walk(desktop);
+    if (!valid || referencedKeys.size === 0)
+        return undefined;
+    return { viewModel: prevViewModel, referencedKeys };
+}
+/** 找出未包含在已有布局中的字段（新增字段） */
+function collectUnreferencedFields(referencedKeys, built, details) {
+    const missing = [];
+    for (const item of built) {
+        if (!referencedKeys.has(item.field.uuid))
+            missing.push(item.field.fdName);
+    }
+    for (const detail of details) {
+        if (!referencedKeys.has(detail.model.fdTableName))
+            missing.push(detail.model.fdTableName);
+    }
+    return missing;
+}
+/** 控件配置面板默认值中，不应写入 controlProps 的键（属于样式/布局，存放在 controlStyle） */
+const DEFAULT_EXCLUDE_KEYS = new Set([
+    'layout',
+    'labelStyle',
+    'controlValueStyle',
+    'desktopTitleBgColor',
+    'desktopPaddingMode',
+    'titleStyle',
+    'color',
+    'paddingControl',
+    'controlTitleStyle',
+    'controlText',
+]);
+function controlMapOf(options) {
+    return { ...constants_1.DEFAULT_CONTROL_MAP, ...(options.controlMap ?? {}) };
+}
+/**
+ * 归一化多语言列表：拆逗号、去重、大小写归一到前端 `getLocale` 的产物（`Cn`/`Us`/`Tw`），
+ * 并保证至少有一个主语言（列表首项）。
+ */
+function resolveLocales(locale) {
+    const raw = Array.isArray(locale) ? locale : [String(locale ?? '')];
+    const list = raw
+        .flatMap((item) => String(item).split(','))
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map(locale_1.normalizeLocale);
+    if (list.length === 0)
+        return [constants_1.DEFAULT_LOCALE];
+    const result = [];
+    for (const item of list) {
+        if (!result.includes(item))
+            result.push(item);
+    }
+    return result;
+}
+/**
+ * 组装 `lang[messageKey].content`。
+ *
+ * 主语言取真实文案；其余语言的取值优先级：
+ * 1. `--lang-file` 用户翻译（按标题、再按字段物理名匹配）
+ * 2. 控件自带译文（`elementLangs`，如英文 placeholder「Please enter」）
+ * 3. 与主语言写同一份文案
+ *
+ * 第 3 条是兜底：前端解析不到当前语言时会回落 `Cn`，此处保证不漏项，
+ * 与前端 `ide-model/business/input/inputLocale.tsx` 的 placeholder 兜底行为一致。
+ */
+function buildLangContent(locales, text, alias, messages, elementLangs) {
+    const primary = locales[0];
+    const content = { [primary]: text };
+    for (const locale of locales) {
+        if (locale === primary)
+            continue;
+        const dict = messages?.[locale];
+        content[locale] =
+            dict?.[text] ?? (alias ? dict?.[alias] : undefined) ?? elementLangs?.[locale] ?? text;
+    }
+    return content;
+}
+/** 选项是否为「平台静态多语言」（数据字典等），由静态资源解析，不归 lang 管理 */
+function isStaticOption(option) {
+    const messageKey = option?.messageKey;
+    return typeof messageKey === 'string' && messageKey.length > 0 && !messageKey.startsWith('!{');
+}
+/** 取选项中已有的自定义多语言 key（`!{...}`） */
+function findOptionKey(...options) {
+    for (const option of options) {
+        const item = option;
+        for (const value of [item?.messageKey, item?.label]) {
+            if (typeof value === 'string' && value.startsWith('!{'))
+                return value;
+        }
+    }
+    return undefined;
+}
+/** 取选项的真实文案（排除多语言 key 与静态标记） */
+function findOptionText(...options) {
+    for (const option of options) {
+        const label = option?.label;
+        if (typeof label === 'string' && label && !label.startsWith('!{') && !label.startsWith('${')) {
+            return label;
+        }
+        if (label && typeof label === 'object' && typeof label.default === 'string') {
+            return label.default;
+        }
+    }
+    return undefined;
+}
+/** 从已有 lang 中取某个 key 的主语言文案 */
+function resolveLangText(key, lang, primary) {
+    if (!key)
+        return undefined;
+    const content = lang[key]?.content;
+    if (!content)
+        return undefined;
+    return content[primary] ?? content[constants_1.DEFAULT_LOCALE] ?? Object.values(content)[0];
+}
+/**
+ * 完善下拉 / 单选 / 多选控件的**选项多语言**（`EI18nProp.option`）。
+ *
+ * 对应前端 `genFormByDataModel/lang/index.ts#initOptionsI18n` + `dataModel#setOptionsToDataField`，
+ * 落库结构（已用真实环境数据核对）：
+ *
+ * ```
+ * 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', ... }
+ * ```
+ *
+ * ⚠️ 数据字典选项（`messageKey` 形如 `${sys-xform:enum.X}` / `sys-xform:enum.X`）走平台静态多语言，
+ * **跳过不改**，否则会污染 lang。
+ *
+ * @returns 实际完善的选项数量
+ */
+function completeOptionsI18n(field, lang, locales, messages) {
+    const attr = (0, random_1.safeJsonParse)(field.fdAttribute, {});
+    const controlProps = attr?.config
+        ?.controlProps;
+    const ctrlOptions = Array.isArray(controlProps?.options)
+        ? controlProps.options
+        : undefined;
+    const fontExtend = field.fdFontExtendData
+        ? (0, random_1.safeJsonParse)(field.fdFontExtendData, {})
+        : {};
+    const fontOptions = Array.isArray(fontExtend.options) ? fontExtend.options : undefined;
+    if (!ctrlOptions && !fontOptions)
+        return 0;
+    // 以 fdFontExtendData.options 为准（它保存了真实文案），controlProps 仅同步 key
+    const length = Math.max(ctrlOptions?.length ?? 0, fontOptions?.length ?? 0);
+    const primary = locales[0];
+    let count = 0;
+    for (let index = 0; index < length; index++) {
+        const fontOption = fontOptions?.[index];
+        const ctrlOption = ctrlOptions?.[index];
+        // 数据字典 / 静态多语言选项：不改
+        if (isStaticOption(fontOption) || isStaticOption(ctrlOption))
+            continue;
+        const existingKey = findOptionKey(fontOption, ctrlOption);
+        const value = fontOption?.value ?? ctrlOption?.value;
+        const text = findOptionText(fontOption, ctrlOption) ??
+            resolveLangText(existingKey, lang, primary) ??
+            (value === undefined ? undefined : String(value));
+        if (!text)
+            continue;
+        const key = (0, random_1.isMessageKey)(existingKey) ? existingKey : (0, random_1.generateMessageKey)();
+        // 选项文案允许重复，额外支持 `字段名#选项值` 精确匹配
+        const alias = value === undefined ? undefined : `${field.fdName}#${value}`;
+        lang[key] = {
+            prop: 'option',
+            name: field.fdName,
+            type: 'input',
+            content: buildLangContent(locales, text, alias, messages),
+        };
+        if (ctrlOption)
+            ctrlOption.label = key;
+        if (fontOption) {
+            fontOption.messageKey = key;
+            fontOption.label = text;
+        }
+        count++;
+    }
+    if (ctrlOptions && count)
+        field.fdAttribute = JSON.stringify(attr);
+    if (fontOptions && count)
+        field.fdFontExtendData = JSON.stringify(fontExtend);
+    return count;
+}
+/** 依据数据项类型/逻辑类型解析控件包与元数据 */
+async function resolveControl(field, options) {
+    const map = controlMapOf(options);
+    // 优先按控件逻辑类型（xform.type）匹配，避免把「金额/评分/下拉」等
+    // 错误降级成同数据项类型的默认控件（如 number -> 数字）
+    let entry = constants_1.CONTROL_TYPE_MAP[field.fdType] ?? map[field.fdType];
+    if (!entry)
+        entry = map[field.fdDataType];
+    if (!entry)
+        entry = Object.values(map).find((item) => item.logicalType === field.fdType);
+    entry = entry ?? constants_1.FALLBACK_CONTROL;
+    const registry = options.registry;
+    const [meta, metaMobile] = registry
+        ? await Promise.all([registry.get(entry.desktop), registry.get(entry.mobile)])
+        : [null, null];
+    return {
+        desktopPkg: entry.desktop,
+        mobilePkg: entry.mobile,
+        logicalType: meta?.xform?.type || entry.logicalType,
+        meta,
+        metaMobile,
+    };
+}
+/** 从 fdFontExtendData 提取需要注入 controlProps 的前端扩展属性 */
+function pickFontExtend(data) {
+    const picked = {};
+    ['passValue', 'trace', 'encrypt', 'defaultValueType', 'relationControl'].forEach((key) => {
+        if (data[key] !== undefined)
+            picked[key] = data[key];
+    });
+    return picked;
+}
+/** 解析字段的 fdFontExtendData */
+function fontExtendOf(field) {
+    return pickFontExtend((0, random_1.safeJsonParse)(field.fdFontExtendData, {}));
+}
+/**
+ * 生成数据项的 fdAttribute。
+ *
+ * 对应前端 `configJson.ts#completeFdAttribute` + `generateConfigByDataField`：
+ *   { uuid, env:['xform'], config: { type, kind, key, label, controlProps, labelProps } }
+ *
+ * 该结构是前端加载表单时的**唯一控件来源**（`cacheConfig[uuid] = config`），
+ * 缺失或结构不符会导致控件无法渲染。
+ */
+function buildFieldAttribute(params) {
+    const { fieldUuid, langKey, fieldName, tableName, tableType, fdLength, span, resolved } = params;
+    const key = (0, random_1.generateCmptKey)(resolved.desktopPkg);
+    const logicalType = resolved.logicalType;
+    const xform = resolved.meta?.xform ?? {};
+    // 控件 config.json 中声明的默认值
+    const defaults = (0, widgets_1.collectWidgetDefaults)(resolved.meta);
+    const controlDefaults = {};
+    Object.keys(defaults).forEach((k) => {
+        if (!DEFAULT_EXCLUDE_KEYS.has(k))
+            controlDefaults[k] = defaults[k];
+    });
+    const showText = defaults.showText;
+    const controlProps = {
+        ...controlDefaults,
+        // 必填属性兜底默认值（config.json 声明 required 但无 default 的项）
+        ...constants_1.REQUIRED_PROP_DEFAULTS[resolved.desktopPkg],
+        ...params.fontExtend,
+        // 保留已有选项：本函数会重建 controlProps，不显式带回会丢失用户配置的 options
+        ...(params.options && params.options.length ? { options: params.options } : {}),
+        ...(params.placeholderKey ? { placeholder: params.placeholderKey } : {}),
+        id: key,
+        desktop: { type: resolved.desktopPkg },
+        mobile: { type: resolved.mobilePkg },
+        name: fieldName,
+        uuid: fieldUuid,
+        title: langKey,
+        span: xform.span || span,
+        $$tableType: tableType,
+        $$tableName: tableName,
+    };
+    if (typeof fdLength === 'number' && fdLength > 0) {
+        controlProps.maxLength = fdLength;
+    }
+    const labelProps = {
+        desktop: {},
+        mobile: {},
+        title: langKey,
+        // 控件布局：左右布局（前端 LayoutType.horizontal）
+        layout: 'horizontal',
+        // 左右布局下的标题对齐（前端 LabelTextAlign.left）
+        labelTextAlign: 'left',
+        ...(showText !== undefined ? { showText } : {}),
+        ...(params.fontExtend.trace !== undefined ? { trace: params.fontExtend.trace } : {}),
+    };
+    const config = {
+        key,
+        type: logicalType,
+        kind: 'control',
+        label: langKey,
+        controlProps,
+        labelProps,
+    };
+    return {
+        attribute: JSON.stringify({
+            uuid: fieldUuid,
+            env: resolved.meta?.env ?? ['xform'],
+            config,
+        }),
+        config,
+    };
+}
+/** 补全数据项属性（对齐前端 completeFieldAttribute / completeFdAttribute） */
+function enrichField(field, model, resolved) {
+    const xform = resolved.meta?.xform ?? {};
+    field.uuid = field.fdName;
+    field.fdType = resolved.logicalType;
+    if (xform.dataType)
+        field.fdDataType = xform.dataType;
+    if (xform.dictType)
+        field.fdDictType = xform.dictType;
+    if (typeof field.fdLength !== 'number' || Number.isNaN(field.fdLength)) {
+        field.fdLength = xform.defaultLength ?? 0;
+    }
+    field.fdTableName = model.fdTableName;
+    field.fdTableType = model.fdType;
+    field.fdDataModel = { fdId: model.fdId, fdName: model.fdName };
+    field.fdIsIndex = field.fdIsIndex ?? false;
+    field.fdDisplay = field.fdDisplay ?? true;
+    field.fdIsStored = field.fdIsStored ?? true;
+    field.fdState = field.fdState ?? 'effective';
+    if (field.fdIsSystem) {
+        field.$$fdLockMode = 'part';
+        field.fdLockMode = 'part';
+    }
+    else {
+        field.$$fdLockMode = 'none';
+        field.fdLockMode = 'none';
+        field.fdFontExtendData =
+            field.fdFontExtendData ??
+                JSON.stringify({
+                    passValue: false,
+                    trace: false,
+                    encrypt: false,
+                    // 初始值模式：config.json 默认 'null'（无初始值）。不能写 'formula'——
+                    // 公式模式下 defaultValueFormulaVO 必填，设计器提交会被拦截
+                    defaultValueType: 'null',
+                    encryptDefinition: {},
+                });
+    }
+    if (!field.fdIsSystem && (field.fdOrder === undefined || field.fdOrder === null)) {
+        field.fdOrder = 1;
+    }
+}
+/** 依据数据项生成（或补全）控件配置，并回写 fdAttribute / fdLabelLangKey */
+async function buildField(field, model, options, lang, locales) {
+    const resolved = await resolveControl(field, options);
+    const span = options.span ?? constants_1.DEFAULT_SPAN;
+    enrichField(field, model, resolved);
+    // 仅复用「前端可识别」的 key（!{仅含 [\w.]}）；其余（含历史 RFC4122 UUID）一律重建
+    const langKey = (0, random_1.isMessageKey)(field.fdLabelLangKey)
+        ? field.fdLabelLangKey
+        : (0, random_1.generateMessageKey)();
+    field.fdLabelLangKey = langKey;
+    lang[langKey] = {
+        prop: 'label',
+        name: field.fdName,
+        type: 'input',
+        content: buildLangContent(locales, field.fdLabel || field.fdName, field.fdName, options.messages),
+    };
+    // 控件占位提示多语言（约定 key：{pkg}###langs###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),
+            };
+        }
+    }
+    // 新建选项（--option）：写入 fdFontExtendData.options，作为选项的唯一来源
+    const specified = options.options?.[field.fdName];
+    if (specified?.length) {
+        const fontExtend = field.fdFontExtendData
+            ? (0, random_1.safeJsonParse)(field.fdFontExtendData, {})
+            : {};
+        // 结构对齐真实表单（拆分线等价物 colorSwitch / type 保留默认值）
+        fontExtend.options = specified.map((item, index) => ({
+            messageKey: '',
+            colorSwitch: false,
+            label: item.label,
+            type: '',
+            value: item.value ?? String(index + 1),
+        }));
+        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 ?? [])
+        : [];
+    // 已有 controlProps.options 原样保留（数据字典选项带有 messageKey，不能丢字段）；
+    // 新建选项时归一为 { label, value }，与真实表单的 controlProps 结构一致
+    const prevOptions = Array.isArray(attrOptions) && !specified?.length
+        ? attrOptions
+        : fontOptions.map((item) => ({
+            label: item?.label,
+            value: item?.value,
+        }));
+    const { attribute, config } = buildFieldAttribute({
+        fieldUuid: field.uuid,
+        langKey,
+        fieldName: field.fdName,
+        tableName: model.fdTableName,
+        tableType: model.fdType,
+        fdLength: field.fdLength,
+        span,
+        resolved,
+        placeholderKey,
+        fontExtend: fontExtendOf(field),
+        options: prevOptions.length ? prevOptions : undefined,
+    });
+    field.fdAttribute = attribute;
+    // 选项多语言（下拉/单选/多选）
+    const optionCount = completeOptionsI18n(field, lang, locales, options.messages);
+    // 控件必填属性校验（对齐设计器发布前校验）
+    const propErrors = (0, widgets_1.validateRequiredProps)(resolved.meta, config);
+    return { field, model, resolved, langKey, optionCount, propErrors };
+}
+/** 构建虚拟行：控件节点在持久化格式中**只保留 key 引用** */
+function buildRows(built, options) {
+    const perRow = Math.max(1, options.perRow ?? 2);
+    const span = options.span ?? constants_1.DEFAULT_SPAN;
+    const rows = [];
+    for (let i = 0; i < built.length; i += perRow) {
+        const group = built.slice(i, i + perRow);
+        const rowKey = (0, random_1.generateCmptKey)(constants_1.ROW);
+        rows.push({
+            key: rowKey,
+            type: constants_1.ROW,
+            kind: 'container',
+            controlProps: { id: rowKey, spans: group.map(() => span) },
+            children: group.map((item) => ({ key: item.field.uuid })),
+        });
+    }
+    return rows;
+}
+/**
+ * 栅格布局：`layout` → `@elem/layout-grid` → 若干 `@elem/layout-grid.GridItem`。
+ *
+ * 结构依据真实环境表单（`layout~xxxx` / `controlProps:{id}`）：
+ * ```
+ * layout                      { controlProps:{ id } }
+ *   └ @elem/layout-grid       { controlProps:{ id, columns, rows } }
+ *       └ GridItem            { controlProps:{ id, column, row, rowSpan, columnSpan, style:{backgroundColor:''} }, children:[{key:<fieldUuid>}] }
+ * ```
+ * 注意：栅格布局控件**不进** `controlMappings`（已核对真实表单）。
+ */
+function buildGrid(built, columns) {
+    const cols = Math.max(1, 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);
+    const items = built.map((item, index) => {
+        const itemKey = (0, random_1.generateCmptKey)(constants_1.LAYOUT_GRID_ITEM);
+        return {
+            key: itemKey,
+            type: constants_1.LAYOUT_GRID_ITEM,
+            kind: 'container',
+            controlProps: {
+                column: (index % cols) + 1,
+                row: Math.floor(index / cols) + 1,
+                id: itemKey,
+                rowSpan: 1,
+                columnSpan: 1,
+                style: { backgroundColor: '' },
+            },
+            children: [{ key: item.field.uuid }],
+        };
+    });
+    return [
+        {
+            key: layoutKey,
+            type: constants_1.LAYOUT,
+            kind: 'container',
+            controlProps: { id: layoutKey },
+            children: [
+                {
+                    key: gridKey,
+                    type: constants_1.LAYOUT_GRID,
+                    kind: 'container',
+                    controlProps: { columns: cols, rows, id: gridKey },
+                    children: items,
+                },
+            ],
+        },
+    ];
+}
+/**
+ * 解析页签并**一次性**写入页签标题多语言。
+ *
+ * 必须在 desktop / mobile 两棵树之前调用一次，
+ * 否则两棵树会各自生成一套随机 key，导致 `lang` 里出现重复条目。
+ */
+function resolveTabs(built, options, lang, locales) {
+    const byName = new Map(built.map((item) => [item.field.fdName, item]));
+    const used = new Set();
+    const panes = [];
+    for (const spec of options.tabs ?? []) {
+        const items = [];
+        for (const name of spec.fields ?? []) {
+            const item = byName.get(name);
+            if (item && !used.has(name)) {
+                used.add(name);
+                items.push(item);
+            }
+        }
+        panes.push({ title: spec.title, messageKey: (0, random_1.generateMessageKey)(), items });
+    }
+    // 未列入任何页签的字段 → 归入「其它」
+    const rest = built.filter((item) => !used.has(item.field.fdName));
+    if (rest.length || panes.length === 0) {
+        panes.push({ title: '其它', messageKey: (0, random_1.generateMessageKey)(), items: rest });
+    }
+    panes.forEach((pane) => {
+        const anchor = pane.items[0]?.field.fdName ?? built[0]?.field.fdName ?? '';
+        lang[pane.messageKey] = {
+            prop: constants_1.I18N_PROP_TABS,
+            name: anchor,
+            type: 'input',
+            // 真实数据中页签多语言额外带 default
+            content: {
+                ...buildLangContent(locales, pane.title, undefined, options.messages),
+                default: pane.title,
+            },
+        };
+    });
+    return panes;
+}
+/**
+ * 多页签布局：`@elem/xform-tabs` + 若干 `@elem/xform-tabpane`。
+ *
+ * 结构依据真实环境表单：
+ * - tabs 的 key 为 `<外观key>-tabItem`，外观 key 形如 `@elem/xform-tab-appearance~xxxxxx`
+ * - 渲染树中**没有**独立的 `@elem/xform-tab-appearance` 节点，仅用其 key 前缀
+ * - pane 的 key 为 `<外观key>-tabN`，`controlProps.parent` 指回外观
+ * - 页签控件**需要**写入 `controlMappings`（与栅格布局不同）
+ */
+function buildTabsNode(panes, mainTableName, options) {
+    const appearanceKey = (0, random_1.generateCmptKey)(constants_1.TAB_APPEARANCE);
+    // 页签内层布局：rows（默认）或 grid
+    const buildPaneChildren = (items) => options.tabLayout === 'grid'
+        ? buildGrid(items, options.gridColumns ?? options.perRow ?? 2)
+        : buildRows(items, options);
+    const children = panes.map((pane, index) => {
+        const paneKey = `${appearanceKey}-tab${index + 1}`;
+        return {
+            key: paneKey,
+            type: constants_1.TAB_PANE,
+            kind: 'container',
+            controlProps: {
+                forceRender: true,
+                title: pane.title,
+                tab: pane.title,
+                tabMessageKey: pane.messageKey,
+                key: paneKey,
+                $$id: paneKey,
+                parent: { name: constants_1.TAB_APPEARANCE, type: 'appearance' },
+                children: null,
+            },
+            children: buildPaneChildren(pane.items),
+        };
+    });
+    return [
+        {
+            key: `${appearanceKey}-tabItem`,
+            type: constants_1.TABS,
+            kind: 'container',
+            controlProps: {
+                $$tableName: mainTableName,
+                name: panes[0]?.items[0]?.field.fdName,
+                tabBarStyle: {},
+            },
+            children,
+        },
+    ];
+}
+/** 明细表在渲染树中的节点：`{ key:<表名>, children:[字段引用] }`（无 type） */
+function detailNodes(details) {
+    return details.map((detail) => ({
+        key: detail.model.fdTableName,
+        children: detail.fields.map((item) => ({ key: item.field.uuid })),
+    }));
+}
+/** 桌面端：`@elem/xform-appearance` → `main` → 布局容器（+ 明细表行） */
+function buildDesktopTree(built, mainTableName, options, panes, details) {
+    let containers;
+    switch (options.layout ?? 'rows') {
+        case 'grid':
+            containers = buildGrid(built, options.gridColumns ?? options.perRow ?? 2);
+            break;
+        case 'tabs':
+            containers = buildTabsNode(panes, mainTableName, options);
+            break;
+        default:
+            containers = buildRows(built, options);
+    }
+    // 明细表独立成行，追加在布局容器之后
+    return [wrapAppearance(mainTableName, [...containers, ...buildDetailRows(details)])];
+}
+/**
+ * 移动端：`@elem/xform-appearance` → `main` → **平铺的字段引用**。
+ *
+ * 实测真实表单的移动端渲染树不含任何布局容器（无 row / grid / tabs），
+ * 字段直接作为 `main.children` 的 `{ key }` 节点；明细表节点同理追加在末尾。
+ */
+function buildMobileTree(built, mainTableName, details) {
+    return [
+        wrapAppearance(mainTableName, [
+            ...built.map((item) => ({ key: item.field.uuid })),
+            ...detailNodes(details),
+        ]),
+    ];
+}
+function wrapAppearance(tableName, children) {
+    return {
+        key: constants_1.APPEARANCE,
+        type: constants_1.APPEARANCE,
+        kind: 'container',
+        controlProps: { $$tableName: tableName },
+        children: [
+            {
+                key: constants_1.MAIN,
+                type: constants_1.MAIN,
+                kind: 'container',
+                children,
+            },
+        ],
+    };
+}
+/**
+ * 构建控件映射（controlMappings）：平台 -> 用到的控件元数据。
+ *
+ * 注意：栅格布局（`layout` / `@elem/layout-grid` / `GridItem`）**不写入**此处，
+ * 而多页签（`tab-appearance` / `tabs` / `tabpane`）**需要写入** —— 均为真实表单核对结论。
+ */
+function buildControlMappings(built, options = {}) {
+    /** 布局控件的兜底元数据（控件包无 xform 时用，与真实表单的 xform.type 一致） */
+    const layoutDefaults = {
+        [constants_1.TAB_APPEARANCE]: 'tabAppearance',
+        [constants_1.TABS]: 'xformTabs',
+        [constants_1.TAB_PANE]: 'xformTabpane',
+    };
+    const build = (platform) => {
+        const seen = new Set();
+        const list = [];
+        built.forEach((item) => {
+            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;
+            seen.add(pkg);
+            const xform = { ...(meta?.xform ?? {}), type: item.resolved.logicalType };
+            // 前端 handleFindXFormWidgets 会把包级 env 同步进 xform.env
+            if (meta?.env && !xform.env) {
+                ;
+                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]
+                : [constants_1.TAB_APPEARANCE_MOBILE, constants_1.TABS_MOBILE, constants_1.TAB_PANE_MOBILE];
+            const defaults = platform === 'desktop'
+                ? layoutDefaults
+                : {
+                    [constants_1.TAB_APPEARANCE_MOBILE]: 'tabAppearance',
+                    [constants_1.TABS_MOBILE]: 'xformTabs',
+                    [constants_1.TAB_PANE_MOBILE]: 'xformTabpane',
+                };
+            pkgs.forEach((pkg) => {
+                if (seen.has(pkg))
+                    return;
+                seen.add(pkg);
+                list.push({ name: pkg, platform, xform: { type: defaults[pkg] } });
+            });
+        }
+        return list;
+    };
+    return { desktop: build('desktop'), mobile: build('mobile') };
+}
+/** 构建 viewModel（场景） */
+function buildViewModel(built, mainTableName, options = {}, lang = {}, locales = [constants_1.DEFAULT_LOCALE], details = [], detailMappings) {
+    const controlStyle = {};
+    built.forEach((item) => {
+        controlStyle[item.field.uuid] = { desktop: { ...constants_1.DEFAULT_CONTROL_STYLE } };
+    });
+    // 明细表自身需要 controlStyle 条目（明细字段不需要）——真实表单核对结论
+    details.forEach((detail) => {
+        controlStyle[detail.model.fdTableName] = { ...constants_1.DEFAULT_DETAIL_CONTROL_STYLE };
+    });
+    // 页签多语言只生成一次，供桌面端渲染树复用
+    const panes = options.layout === 'tabs' ? resolveTabs(built, options, lang, locales) : [];
+    const mappings = buildControlMappings(built, options);
+    if (detailMappings?.desktop.length)
+        mappings.desktop.push(...detailMappings.desktop);
+    if (detailMappings?.mobile.length)
+        mappings.mobile.push(...detailMappings.mobile);
+    const viewConfig = {
+        view: {
+            render: {
+                desktop: buildDesktopTree(built, mainTableName, options, panes, details),
+                mobile: buildMobileTree(built, mainTableName, details),
+            },
+            controlMappings: mappings,
+        },
+        theme: {
+            desktop: {
+                name: 'default',
+                status: 'done',
+                viewAttr: { logo: { isUpload: false }, ...constants_1.DEFAULT_DESKTOP_THEME },
+            },
+            mobile: { name: 'default', status: 'done', viewAttr: { ...constants_1.DEFAULT_MOBILE_THEME } },
+        },
+        controlStyle,
+    };
+    return [
+        {
+            fdCode: constants_1.DEFAULT_SCENE_CODE,
+            fdName: constants_1.DEFAULT_SCENE_NAME,
+            fdStatus: 'draft',
+            fdLockMode: 'none',
+            fdOrder: 0,
+            dynamicProps: {},
+            needDelete: false,
+            ...(options.formId ? { fdXForm: { fdId: options.formId, fdName: options.formName } } : {}),
+            // 持久化时内层 fdConfig 同样为 JSON 字符串
+            fdConfig: JSON.stringify(viewConfig),
+        },
+    ];
+}
+/**
+ * 构建权限（auth）。
+ *
+ * 对应前端控件属性面板的「字段权限」（各控件 config.json 中的
+ * `controlGroup > fieldPermission > { required, editable, visible }`），
+ * 落库位置是 `auth[0].{add|edit|view}[表名].fields[字段名]`：
+ * ```
+ * { visible: true, editable: true, required: false, hide: false }
+ * ```
+ */
+function buildAuth(models, options = {}) {
+    const add = {};
+    const edit = {};
+    const view = {};
+    const perm = options.permissions ?? {};
+    models.forEach((model) => {
+        // 明细表：字段 + 行操作（canAddRow/canDeleteRow/canImport/canExport）
+        if (model.fdType === 'detail') {
+            const bizFields = (model.fdFields ?? []).filter((f) => f.fdIsSystem !== true);
+            const addFields = {};
+            const editFields = {};
+            const viewFields = {};
+            bizFields.forEach((field) => {
+                addFields[field.fdName] = {
+                    visible: true,
+                    editable: true,
+                    required: false,
+                    hide: false,
+                    ...perm.add?.[field.fdName],
+                };
+                editFields[field.fdName] = {
+                    visible: true,
+                    editable: true,
+                    required: false,
+                    hide: false,
+                    ...perm.edit?.[field.fdName],
+                };
+                viewFields[field.fdName] = { visible: true, ...perm.view?.[field.fdName] };
+            });
+            add[model.fdTableName] = {
+                ...constants_1.DETAIL_ROW_FLAGS.add,
+                fields: addFields,
+                operations: constants_1.DETAIL_OPERATIONS.add,
+            };
+            edit[model.fdTableName] = {
+                ...constants_1.DETAIL_ROW_FLAGS.add,
+                fields: editFields,
+                operations: constants_1.DETAIL_OPERATIONS.add,
+            };
+            view[model.fdTableName] = {
+                canExport: true,
+                fields: viewFields,
+                operations: constants_1.DETAIL_OPERATIONS.view,
+            };
+            return;
+        }
+        const addFields = {};
+        const editFields = {};
+        const viewFields = {};
+        (model.fdFields ?? []).forEach((field) => {
+            addFields[field.fdName] = {
+                visible: true,
+                editable: true,
+                required: false,
+                hide: false,
+                ...perm.add?.[field.fdName],
+            };
+            editFields[field.fdName] = {
+                visible: true,
+                editable: true,
+                required: false,
+                hide: false,
+                ...perm.edit?.[field.fdName],
+            };
+            viewFields[field.fdName] = { visible: true, ...perm.view?.[field.fdName] };
+        });
+        add[model.fdTableName] = { fields: addFields };
+        edit[model.fdTableName] = { fields: editFields };
+        view[model.fdTableName] = { fields: viewFields };
+    });
+    return [
+        {
+            fdName: ':publicLang.sysFormAuth',
+            authOrg: [],
+            fdIsAvailable: true,
+            add,
+            edit,
+            view,
+        },
+    ];
+}
+/** 主题字段优先取文档标题，其次取第一个业务字段 */
+function pickSubjectField(main) {
+    const fields = main.fdFields ?? [];
+    return (fields.find((f) => f.fdName === 'fd_doc_subject') ??
+        fields.find((f) => !f.fdIsSystem) ??
+        fields[0]);
+}
+/**
+ * 构建「全局规则」（fdConfig.attribute）。
+ *
+ * @param prevFormAttr 已有表单的 `attribute.formAttr` JSON 串（autofill 时传入），
+ *   其中已配置的 `controlAction`（以及 formRule / dataUnique 等前端态数据）会被保留，
+ *   否则 autofill 每次都会把设计器里配置的动作清空。
+ */
+function buildAttribute(models, main, prevFormAttr) {
+    const subjectField = pickSubjectField(main);
+    const previous = (0, random_1.safeJsonParse)(prevFormAttr, {});
+    // controlAction 在已解析的 formAttr 中通常是对象，但也兼容嵌套 JSON 串的存法
+    const prevControlAction = typeof previous.controlAction === 'string'
+        ? (0, random_1.safeJsonParse)(previous.controlAction, {})
+        : (previous.controlAction ?? {});
+    const formAttr = {
+        subjectRule: subjectField
+            ? {
+                script: `\${data.biz.${subjectField.fdName}}`,
+                type: 'Eval',
+                vo: {
+                    // 注意：content 使用数据模型名称，而非表名
+                    content: `$${main.fdName}.${subjectField.fdLabel || subjectField.fdName}$`,
+                    mode: 'formula',
+                },
+            }
+            : previous.subjectRule ?? {},
+        // 保留已有的表单规则 / 数据唯一性（设计器配置，重新生成会丢）
+        formRule: previous.formRule ?? { pattern: {} },
+        dataUnique: previous.dataUnique ?? {},
+        controlAction: prevControlAction,
+        currentTableName: main.fdTableName,
+    };
+    return formAttr;
+}
+/** 从函数源码中解析函数名（`function xxx(` / `async function xxx(`） */
+function extractFunctionName(source) {
+    const matched = /(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/.exec(source);
+    return matched?.[1];
+}
+/** 深度收集 controlAction 中已占用的函数名，避免重名 */
+function collectActionNames(controlAction) {
+    const names = new Set();
+    for (const group of [controlAction.control, controlAction.global]) {
+        if (!group)
+            continue;
+        for (const events of Object.values(group)) {
+            if (!events)
+                continue;
+            for (const items of Object.values(events)) {
+                if (!Array.isArray(items))
+                    continue;
+                for (const item of items) {
+                    if (item?.name)
+                        names.add(item.name);
+                }
+            }
+        }
+    }
+    return names;
+}
+/**
+ * 将控件动作写入 `formAttr.controlAction`。
+ *
+ * 控件级事件的 key 为 **`表名.控件uuid`**（与运行时
+ * `runtime/business/action.ts#addActionToControlProps` 的查找规则一致：
+ * `controlAction.control[key] || controlAction.control[\`${$$tableName}.${uuid}\`]`）；
+ * 全局动作（`onLoad` / `onBeforeSubmit` / `onAfterSubmit`）写入 `controlAction.global`。
+ *
+ * @returns 实际写入的动作数量与告警（目标字段不存在、函数重名等）
+ */
+function applyControlActions(formAttr, targets, actions) {
+    var _a, _b;
+    if (!actions.length)
+        return { completed: 0, warnings: [] };
+    const controlAction = formAttr.controlAction ?? {};
+    formAttr.controlAction = controlAction;
+    controlAction.control = controlAction.control ?? {};
+    controlAction.global = controlAction.global ?? {};
+    const usedNames = collectActionNames(controlAction);
+    const controlMap = controlAction.control;
+    const globalMap = controlAction.global;
+    const sources = [];
+    const warnings = [];
+    let completed = 0;
+    for (const action of actions) {
+        // 函数名：显式指定 > 源码解析 > 自动生成；重名时按前端规则追加后缀
+        const base = 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}`);
+        }
+        usedNames.add(name);
+        const item = { name, id: (0, random_1.uuid)(), function: action.source };
+        if (action.target === exports.ACTION_GLOBAL_TARGET) {
+            ;
+            (globalMap[_a = action.event] ?? (globalMap[_a] = [])).push(item);
+        }
+        else {
+            const key = targets.get(action.target);
+            if (!key) {
+                warnings.push(`动作目标字段不存在，已跳过：${action.target}（事件 ${action.event}）`);
+                continue;
+            }
+            const events = (controlMap[key] ?? (controlMap[key] = {}));
+            (events[_b = action.event] ?? (events[_b] = [])).push(item);
+        }
+        sources.push(action.source);
+        completed++;
+    }
+    // javascript 为所有函数源码拼接（设计器 JS 面板按此展示/编辑）
+    if (sources.length) {
+        const prev = typeof controlAction.javascript === 'string' ? controlAction.javascript : '';
+        controlAction.javascript = [prev.trim(), ...sources].filter(Boolean).join('\n\n');
+    }
+    return { completed, warnings };
+}
+/**
+ * 补齐明细表的系统字段属性。
+ *
+ * 实测真实明细表的系统字段（`fd_id`/`fd_main_id`/`fd_order`）：
+ * - `fdAttribute = {"uuid":"<表名>.<字段名>"}`（如 `kjcx_ptdj_dt1.fd_id`）
+ * - `fdOrder = 9999`、`fdState = 'effective'`、`fdDataModel = {fdId, fdName}`
+ */
+function enrichSystemField(field, model) {
+    const table = model.fdTableName;
+    const current = (0, random_1.safeJsonParse)(field.fdAttribute, {});
+    if (!current.uuid) {
+        field.fdAttribute = JSON.stringify({ uuid: `${table}.${field.fdName}` });
+    }
+    field.fdTableName = table;
+    field.fdTableType = model.fdType;
+    field.fdDataModel = { fdId: model.fdId, fdName: model.fdName };
+    field.fdState = field.fdState === 'notEffective' ? 'effective' : (field.fdState ?? 'effective');
+    field.fdOrder = field.fdOrder ?? 9999;
+}
+/**
+ * 构建明细表控件（`@elem/xform-detail-table`）的 fdAttribute。
+ *
+ * 该配置挂在**明细模型自身**上（不是主表字段），结构依据真实表单：
+ * ```
+ * { uuid:<表名>, config:{ key, type:'detail', kind:'container',
+ *   controlProps:{ …config.json 默认值, id, desktop:{hiddenLabel:true,type}, mobile:{type},
+ *                  name:<表名>, uuid:<表名>, title:<langKey>, $$tableType:'detail', $$tableName:<表名>, type },
+ *   label:<langKey>, labelProps:{desktop:{}, mobile:{}} } }
+ * ```
+ */
+function buildDetailAttribute(model, langKey, meta) {
+    const table = model.fdTableName;
+    const key = (0, random_1.generateCmptKey)(constants_1.DETAIL_CONTROL.desktop);
+    const defaults = (0, widgets_1.collectWidgetDefaults)(meta);
+    const controlDefaults = {};
+    Object.keys(defaults).forEach((k) => {
+        if (!DEFAULT_EXCLUDE_KEYS.has(k))
+            controlDefaults[k] = defaults[k];
+    });
+    const controlProps = {
+        ...constants_1.DETAIL_CONTROL_DEFAULTS,
+        ...controlDefaults,
+        id: key,
+        desktop: { hiddenLabel: true, type: constants_1.DETAIL_CONTROL.desktop },
+        mobile: { type: constants_1.DETAIL_CONTROL.mobile },
+        name: table,
+        uuid: table,
+        title: langKey,
+        $$tableType: 'detail',
+        $$tableName: table,
+        type: constants_1.DETAIL_CONTROL.desktop,
+    };
+    return JSON.stringify({
+        uuid: table,
+        config: {
+            key,
+            type: 'detail',
+            controlProps,
+            kind: 'container',
+            label: langKey,
+            labelProps: { desktop: {}, mobile: {} },
+        },
+    });
+}
+/** 明细表渲染行：独立成行（span 24），节点形如 `{ key:<表名>, children:[字段引用] }` */
+function buildDetailRows(details) {
+    return details.map((detail) => {
+        const rowKey = (0, random_1.generateCmptKey)(constants_1.ROW);
+        return {
+            key: rowKey,
+            type: constants_1.ROW,
+            kind: 'container',
+            controlProps: { id: rowKey, spans: [24] },
+            children: [
+                {
+                    key: detail.model.fdTableName,
+                    children: detail.fields.map((item) => ({ key: item.field.uuid })),
+                },
+            ],
+        };
+    });
+}
+/** 构建完整表单配置 IXFormConfig（持久化格式） */
+async function buildFdConfig(models, options = {}, stats) {
+    if (!models || models.length === 0) {
+        throw new Error('无法生成表单配置：数据模型为空');
+    }
+    const main = models.find((m) => m.fdType === 'main') ?? models[0];
+    const mainTableName = main.fdTableName;
+    // 默认只把业务字段渲染成表单控件，系统字段保留在数据模型中
+    const renderFields = (main.fdFields ?? []).filter((f) => (options.includeSystem === true || f.fdIsSystem !== true) && f.fdDisplay !== false);
+    const locales = resolveLocales(options.locale);
+    const lang = {};
+    const built = [];
+    /** 动作目标索引：fdName -> 控件 key（`表名.控件uuid`，与运行时查找规则一致） */
+    const actionTargets = new Map();
+    /** 必填属性校验失败汇总（对齐设计器发布前校验） */
+    const validationErrors = [];
+    for (const field of renderFields) {
+        const builtField = await buildField(field, main, options, lang, locales);
+        built.push(builtField);
+        if (stats)
+            stats.optionsCompleted += builtField.optionCount;
+        actionTargets.set(builtField.field.fdName, `${mainTableName}.${builtField.field.uuid}`);
+        for (const error of builtField.propErrors) {
+            validationErrors.push(`字段 ${field.fdName}（${builtField.resolved.desktopPkg}）：请输入${error.label}（${error.key}）`);
+        }
+    }
+    // ---------- 明细表 ----------
+    const detailModels = models.filter((m) => m.fdType === 'detail');
+    const details = [];
+    let detailMappings;
+    if (detailModels.length) {
+        const registry = options.registry;
+        const [detailMeta, detailMetaMobile] = registry
+            ? await Promise.all([registry.get(constants_1.DETAIL_CONTROL.desktop), registry.get(constants_1.DETAIL_CONTROL.mobile)])
+            : [null, null];
+        for (const model of detailModels) {
+            model.fdFields.forEach((f) => {
+                if (f.fdIsSystem)
+                    enrichSystemField(f, model);
+            });
+            const fields = [];
+            for (const field of (model.fdFields ?? []).filter((f) => f.fdIsSystem !== true && f.fdDisplay !== false)) {
+                const builtField = await buildField(field, model, options, lang, locales);
+                fields.push(builtField);
+                if (stats)
+                    stats.optionsCompleted += builtField.optionCount;
+                actionTargets.set(builtField.field.fdName, `${model.fdTableName}.${builtField.field.uuid}`);
+                for (const error of builtField.propErrors) {
+                    validationErrors.push(`明细字段 ${model.fdTableName}.${field.fdName}（${builtField.resolved.desktopPkg}）：请输入${error.label}（${error.key}）`);
+                }
+            }
+            // 明细表标题多语言（prop:label，content 额外带 default）
+            const langKey = (0, random_1.isMessageKey)(model.fdLabelLangKey)
+                ? model.fdLabelLangKey
+                : (0, random_1.generateMessageKey)();
+            model.fdLabelLangKey = langKey;
+            lang[langKey] = {
+                prop: 'label',
+                name: model.fdTableName,
+                type: 'input',
+                content: {
+                    ...buildLangContent(locales, model.fdName, undefined, options.messages),
+                    default: model.fdName,
+                },
+            };
+            // 明细模型自身属性
+            model.fdAttribute = buildDetailAttribute(model, langKey, detailMeta);
+            // 明细表控件必填属性校验
+            const detailAttr = (0, random_1.safeJsonParse)(model.fdAttribute, {});
+            for (const error of (0, widgets_1.validateRequiredProps)(detailMeta, detailAttr?.config ?? {})) {
+                validationErrors.push(`明细表 ${model.fdTableName}（${constants_1.DETAIL_CONTROL.desktop}）：请输入${error.label}（${error.key}）`);
+            }
+            model.fdFontExtendData = model.fdFontExtendData ?? JSON.stringify({ passValue: false });
+            model.fdTableNameAlias = model.fdTableNameAlias ?? model.fdTableName;
+            model.dynamicProps = model.dynamicProps ?? {};
+            if (options.formId) {
+                model.fdXForm = model.fdXForm ?? { fdId: options.formId, fdName: options.formName };
+            }
+            details.push({ model, fields, langKey });
+        }
+        // 明细表控件需要写入 controlMappings（与栅格布局不同）
+        const detailEntry = (pkg, meta) => {
+            const xform = {
+                ...(meta?.xform ?? {}),
+                type: constants_1.DETAIL_CONTROL.logicalType,
+                defaultLength: 0,
+                maxLength: 0,
+            };
+            if (meta?.env && !xform.env)
+                xform.env = meta.env;
+            return {
+                name: pkg,
+                platform: pkg === constants_1.DETAIL_CONTROL.desktop ? 'desktop' : 'mobile',
+                xform,
+            };
+        };
+        detailMappings = {
+            desktop: [detailEntry(constants_1.DETAIL_CONTROL.desktop, detailMeta)],
+            mobile: [detailEntry(constants_1.DETAIL_CONTROL.mobile, detailMetaMobile)],
+        };
+    }
+    // 布局：--layout 未显式指定且已有视图合法时沿用（保持设计器布局不被重建为平铺）
+    const prevView = options.layout === undefined ? normalizePrevViewModel(options.prevViewModel) : undefined;
+    let viewModel;
+    if (prevView) {
+        viewModel = prevView.viewModel;
+        // 旧视图中引用的非字段级多语言（页签标题等）必须携带，否则页签标题会丢失
+        for (const [key, entry] of Object.entries(options.prevLang ?? {})) {
+            const prop = entry?.prop;
+            if (prop && !FIELD_LANG_PROPS.has(prop) && !lang[key])
+                lang[key] = entry;
+        }
+        if (stats) {
+            const missing = collectUnreferencedFields(prevView.referencedKeys, built, details);
+            if (missing.length) {
+                stats.layoutWarnings = [
+                    `已有布局未包含 ${missing.length} 个字段/明细表（${missing.join('、')}）；如需展示请显式指定 --layout 重建布局`,
+                ];
+            }
+        }
+    }
+    else {
+        viewModel = buildViewModel(built, mainTableName, options, lang, locales, details, detailMappings);
+    }
+    // 控件动作（onChange / onLoad / onBeforeSubmit…），写入 attribute.formAttr.controlAction
+    const formAttr = buildAttribute(models, main, options.prevFormAttr);
+    const actionResult = applyControlActions(formAttr, actionTargets, options.actions ?? []);
+    if (stats) {
+        stats.actionsCompleted = actionResult.completed;
+        if (actionResult.warnings.length)
+            stats.actionWarnings = actionResult.warnings;
+        if (validationErrors.length)
+            stats.validationErrors = validationErrors;
+    }
+    return {
+        id: options.formId ?? '',
+        name: options.formName ?? '',
+        tableName: mainTableName,
+        entityName: options.entityName ?? constants_1.ENTITY_NAME,
+        entityCode: options.entityCode ?? constants_1.ENTITY_CODE,
+        dataModel: models,
+        auth: buildAuth(models, options),
+        attribute: { formAttr: JSON.stringify(formAttr) },
+        error: JSON.stringify({}),
+        lang: JSON.stringify(lang),
+        authFilter: { detailAuthDefine: {} },
+        extendMap: {},
+        sign: { formula: {} },
+        viewModel,
+    };
+}
+/**
+ * 依据规格创建数据项（字段）定义，用于向数据模型追加新字段。
+ * 生成结果可直接放入 `IDataModel.fdFields`，随 fdConfig 一并保存。
+ */
+async function createDataField(spec, options = {}) {
+    const map = controlMapOf(options);
+    const alias = { ...constants_1.CONTROL_TYPE_MAP, ...(options.controlMap ?? {}) };
+    // 第三个 token 容错：既可写数据项类型（varchar/number），也可写控件类型（moneytext/select）
+    let controlType = spec.controlType;
+    let dataType = spec.dataType;
+    if (!controlType && dataType && alias[dataType] && !map[dataType]) {
+        controlType = dataType;
+        dataType = undefined;
+    }
+    let entry;
+    if (controlType) {
+        entry = alias[controlType];
+        if (!entry) {
+            const valid = Object.keys(constants_1.CONTROL_TYPE_MAP).join(', ');
+            throw new Error(`未知的控件类型：${controlType}，可选值：${valid}`);
+        }
+        dataType = alias[controlType].dataType ?? dataType;
+    }
+    else if (dataType && map[dataType]) {
+        entry = map[dataType];
+    }
+    if (!entry) {
+        dataType = dataType ?? 'varchar';
+        entry = map[dataType] ?? constants_1.FALLBACK_CONTROL;
+    }
+    const registry = options.registry;
+    const meta = registry ? await registry.get(entry.desktop) : null;
+    const xform = meta?.xform ?? {};
+    return {
+        fdName: spec.name || `${constants_1.FIELD_NAME_PREFIX}${Math.random().toString(36).slice(-6)}`,
+        fdLabel: spec.label,
+        fdDataType: xform.dataType ?? dataType,
+        fdType: xform.type || entry.logicalType,
+        fdDictType: xform.dictType,
+        fdLength: xform.defaultLength ?? 0,
+        fdIsSystem: false,
+        fdDisplay: true,
+        fdIsStored: true,
+        fdState: 'effective',
+    };
+}
+/** 解析 `name:label[:dataType|controlType[:controlType]]` 形式的字段规格 */
+function parseFieldSpec(raw) {
+    const parts = raw.split(':').map((s) => s.trim());
+    if (parts.length === 1) {
+        return { label: parts[0] };
+    }
+    return {
+        name: parts[0] || undefined,
+        label: parts[1] || parts[0],
+        dataType: parts[2] || undefined,
+        controlType: parts[3] || undefined,
+    };
+}
+/**
+ * 组装保存/发布请求体。
+ * 注意：外层 fdConfig 为 JSON 字符串，内层 viewModel[].fdConfig 同样为字符串。
+ */
+async function buildFormDefinePayload(models, options) {
+    const fdConfig = await buildFdConfig(models, options, options.stats);
+    return {
+        ...options.base,
+        fdConfig: JSON.stringify(fdConfig),
+    };
+}