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

package/dist/commands/form.js

@@ -0,0 +1,1294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFormCommand = registerFormCommand;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const formDefine_1 = require("../api/formDefine");
+const client_1 = require("../client");
+const config_1 = require("../config");
+const constants_1 = require("../constants");
+const generator_1 = require("../generator");
+const types_1 = require("../types");
+const logger_1 = require("../utils/logger");
+const icon_1 = require("../utils/icon");
+const locale_1 = require("../utils/locale");
+const random_1 = require("../utils/random");
+const widgets_1 = require("../widgets");
+function createClient(opts) {
+    return new client_1.LcodeClient((0, config_1.resolveRuntime)({ baseUrl: opts.baseUrl, token: opts.token }));
+}
+/** 控件元数据注册表（站点根不变时复用磁盘缓存） */
+function createRegistry(opts) {
+    const runtime = (0, config_1.resolveRuntime)({ baseUrl: opts.baseUrl, token: opts.token });
+    return new widgets_1.WidgetRegistry({ baseUrl: runtime.baseUrl, token: runtime.token });
+}
+/** 解析表单类型别名 */
+function parseFormType(input) {
+    if (input === undefined || input === '')
+        return types_1.EFormDefineType.General;
+    const numeric = Number(input);
+    if (!Number.isNaN(numeric) && numeric >= 1 && numeric <= 6) {
+        return numeric;
+    }
+    const alias = types_1.FORM_TYPE_ALIAS[String(input).trim().toLowerCase()];
+    if (alias === undefined) {
+        const valid = Object.keys(types_1.FORM_TYPE_ALIAS).filter((k) => /^[a-z]+$/.test(k)).join(', ');
+        throw new Error(`未知的表单类型：${input}，可选值：${valid}（或数字 1-6）`);
+    }
+    return alias;
+}
+/**
+ * 决定使用哪个接口族。
+ *  - 显式指定 --api general/design/modeling 时以指定为准
+ *  - auto：给出了 --app-id 走建模应用（modeling）；否则审批意见表单(2)走 general，其余走 design
+ */
+function resolveApiFamily(type, requested, appId) {
+    if (requested === 'general' || requested === 'design' || requested === 'modeling') {
+        return requested;
+    }
+    if (requested && requested !== 'auto') {
+        throw new Error(`未知的 --api 取值：${requested}，可选 auto | general | design | modeling`);
+    }
+    if (appId)
+        return 'modeling';
+    if (type === undefined || type === types_1.EFormDefineType.General)
+        return 'general';
+    return 'design';
+}
+const FAMILY_LABEL = {
+    general: 'generalFormDefine',
+    design: 'sysXFormDesign',
+    modeling: 'sysModelingXForm',
+};
+/**
+ * 解析 `--locale` / `--lang-file`。
+ *
+ * - 默认 `['Cn']`；`all` 展开为 `LOCALES`；第一个为主语言
+ * - 文案文件结构：`{ "Us": { "姓名": "Name" } }`，内层 key 可为标题或字段名
+ */
+function resolveI18n(opts) {
+    const raw = opts.locale ?? [];
+    const items = raw
+        .flatMap((item) => String(item).split(','))
+        .map((item) => item.trim())
+        .filter(Boolean);
+    const locale = [];
+    for (const item of items) {
+        const expanded = item.toLowerCase() === constants_1.LOCALE_ALL ? constants_1.LOCALES : [(0, locale_1.normalizeLocale)(item)];
+        for (const code of expanded) {
+            if (!locale.includes(code))
+                locale.push(code);
+        }
+    }
+    if (locale.length === 0)
+        locale.push(constants_1.DEFAULT_LOCALE);
+    let messages;
+    const file = opts.langFile;
+    if (file) {
+        let parsed;
+        try {
+            parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(file), 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`读取多语言文案文件失败：${file}（${error.message}）`);
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`多语言文案文件格式错误：${file}，应为 { "Us": { "标题": "翻译" } }`);
+        }
+        // 语言码大小写归一到 getLocale 产物（Us/us → Us）
+        messages = {};
+        for (const [code, dict] of Object.entries(parsed)) {
+            if (!dict || typeof dict !== 'object' || Array.isArray(dict)) {
+                throw new Error(`多语言文案文件格式错误：${file} 中 "${code}" 应为对象`);
+            }
+            messages[(0, locale_1.normalizeLocale)(code)] = dict;
+        }
+    }
+    return { locale, messages };
+}
+/** 控件动作的合法性：标识符形式（onChange / onFocus / …） */
+const ACTION_EVENT_PATTERN = /^[A-Za-z_$][\w$]*$/;
+/** 读取动作函数源码：`@js文件` 读文件，否则视为内联源码 */
+function readActionSource(raw, context) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('@'))
+        return trimmed;
+    const file = (0, path_1.resolve)(trimmed.slice(1));
+    let source;
+    try {
+        source = (0, fs_1.readFileSync)(file, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`读取动作函数文件失败：${file}（${error.message}），位置：${context}`);
+    }
+    if (!source.trim()) {
+        throw new Error(`动作函数文件为空：${file}，位置：${context}`);
+    }
+    return source;
+}
+/** 解析 `--action` 规格：`字段名:事件:函数源码` 或 `字段名:事件:@js文件`；全局动作用 `$global` */
+function parseActionSpecs(specs) {
+    return specs.map((raw) => {
+        const matched = /^([^:]+):([^:]+):([\s\S]+)$/.exec(raw.trim());
+        if (!matched) {
+            throw new Error(`--action 格式错误：${raw}（应为 字段名:事件:函数源码 或 字段名:事件:@js文件；全局动作用 $global）`);
+        }
+        const [, target, event, sourceRaw] = matched;
+        if (!ACTION_EVENT_PATTERN.test(event)) {
+            throw new Error(`--action 非法事件名：${event}（应为 onChange / onFocus 这类标识符）`);
+        }
+        if (target === generator_1.ACTION_GLOBAL_TARGET && !generator_1.GLOBAL_ACTION_EVENTS.includes(event)) {
+            throw new Error(`全局动作仅支持：${generator_1.GLOBAL_ACTION_EVENTS.join(' / ')}，收到 "${event}"`);
+        }
+        return {
+            target: target.trim(),
+            event,
+            source: readActionSource(sourceRaw, raw),
+        };
+    });
+}
+/**
+ * 解析 `--action-file`（JSON）。两种写法：
+ *
+ * ```json
+ * {
+ *   "fd_col_x": { "onChange": "function onChange(value){ … }" },
+ *   "$global":  { "onLoad": "function onLoad(){ … }" }
+ * }
+ * ```
+ * 或数组形式 `[{ "target": "fd_col_x", "event": "onChange", "source": "…", "name": "可选" }]`
+ */
+function parseActionFile(file) {
+    if (!file)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(file), 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`读取动作定义文件失败：${file}（${error.message}）`);
+    }
+    const pushSource = (target, event, source, name) => {
+        if (!ACTION_EVENT_PATTERN.test(event)) {
+            throw new Error(`动作定义文件 ${file} 中非法事件名：${event}`);
+        }
+        if (typeof source !== 'string' || !source.trim()) {
+            throw new Error(`动作定义文件 ${file} 中 ${target}.${event} 的函数源码必须是非空字符串`);
+        }
+        if (target === generator_1.ACTION_GLOBAL_TARGET && !generator_1.GLOBAL_ACTION_EVENTS.includes(event)) {
+            throw new Error(`全局动作仅支持：${generator_1.GLOBAL_ACTION_EVENTS.join(' / ')}，收到 "${event}"`);
+        }
+        return { target, event, source: source.trim(), ...(name ? { name } : {}) };
+    };
+    if (Array.isArray(parsed)) {
+        return parsed.map((item) => {
+            const spec = item;
+            if (typeof spec.target !== 'string' || typeof spec.event !== 'string') {
+                throw new Error(`动作定义文件 ${file} 数组项应为 { target, event, source, name? }`);
+            }
+            return pushSource(spec.target, spec.event, spec.source, spec.name);
+        });
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`动作定义文件 ${file} 格式错误，应为 { "字段名": { "onChange": "函数源码" }, "$global": { "onLoad": "…" } }`);
+    }
+    const result = [];
+    for (const [target, events] of Object.entries(parsed)) {
+        if (!events || typeof events !== 'object' || Array.isArray(events)) {
+            throw new Error(`动作定义文件 ${file} 中 "${target}" 应为 { 事件: 函数源码 } 对象`);
+        }
+        for (const [event, source] of Object.entries(events)) {
+            result.push(pushSource(target, event, source));
+        }
+    }
+    return result;
+}
+/** 汇总 `--action` + `--action-file` */
+function resolveActions(opts) {
+    const specs = parseActionSpecs(opts.action ?? []);
+    const fromFile = parseActionFile(opts.actionFile);
+    return [...specs, ...fromFile];
+}
+/** 加载已有表单的 formAttr / viewModel / lang（autofill 时用于合并保留） */
+async function loadPrevDesign(client, family, formId) {
+    try {
+        const vo = family === 'modeling'
+            ? await formDefine_1.modelingXFormApi.loadDesign(client, formId)
+            : await formDefine_1.formDefineApi.get(client, formId).catch(() => formDefine_1.designApi.load(client, formId));
+        const cfg = typeof vo.fdConfig === 'string' ? JSON.parse(vo.fdConfig) : vo.fdConfig;
+        const formAttr = cfg?.attribute?.formAttr;
+        const lang = cfg?.lang;
+        return {
+            prevFormAttr: typeof formAttr === 'string' ? formAttr : undefined,
+            prevViewModel: Array.isArray(cfg?.viewModel) &&
+                cfg.viewModel.length
+                ? cfg.viewModel
+                : undefined,
+            prevLang: typeof lang === 'string'
+                ? (() => {
+                    try {
+                        return JSON.parse(lang);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })()
+                : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 发布前控件必填属性校验（对齐设计器）。
+ *
+ * 设计器发布时会执行 `dispatch.validates.validating()`，存在控件属性错误即阻断发布；
+ * CLI 在保存/发布前按同样规则校验，失败则中止（`--force` 可跳过）。
+ * 预览模式（--json / --dry-run / 未加 --apply）只提示不中止。
+ */
+function assertPropValidation(stats, opts, willSave) {
+    const errors = stats.validationErrors ?? [];
+    if (!errors.length)
+        return;
+    for (const message of errors)
+        logger_1.logger.error(message);
+    if (opts.force) {
+        logger_1.logger.warn(`已按 --force 跳过控件必填属性校验（${errors.length} 项）`);
+        return;
+    }
+    if (!willSave) {
+        logger_1.logger.warn(`控件必填属性校验失败（共 ${errors.length} 项）；实际保存/发布将被中止。修正后重试，或加 --force 跳过校验`);
+        return;
+    }
+    throw new Error(`控件必填属性校验失败（共 ${errors.length} 项），已中止保存/发布。请修正属性值后重试，或加 --force 跳过校验`);
+}
+/** 解析逗号分隔的字段名列表 */
+function parseFieldList(input) {
+    return String(input ?? '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+/**
+ * 解析 `--tabs`：`标题:字段1,字段2|标题2:字段3`。
+ * 未列入任何页签的字段由生成器自动归入末尾的「其它」页。
+ */
+function parseTabsSpec(input) {
+    const raw = String(input ?? '').trim();
+    if (!raw)
+        return undefined;
+    return raw
+        .split('|')
+        .map((part) => {
+        const index = part.indexOf(':');
+        return index < 0
+            ? { title: part.trim(), fields: [] }
+            : { title: part.slice(0, index).trim(), fields: parseFieldList(part.slice(index + 1)) };
+    })
+        .filter((item) => item.title);
+}
+/**
+ * 解析 `--layout` / `--grid-columns` / `--tabs` / `--tab-layout`。
+ *
+ * `--layout` 未指定时返回 `layout: undefined`：
+ * - `create` 由生成器默认按 `rows` 平铺；
+ * - `autofill` 则**沿用已有视图**（保持设计器布局不动），显式传入 `--layout` 才重建。
+ */
+function resolveLayout(opts) {
+    const raw = String(opts.layout ?? '').trim().toLowerCase();
+    if (!raw) {
+        return {
+            layout: undefined,
+            gridColumns: opts.gridColumns === undefined ? undefined : Number(opts.gridColumns),
+            tabs: undefined,
+            tabLayout: undefined,
+        };
+    }
+    const allowed = ['rows', 'grid', 'tabs'];
+    if (!allowed.includes(raw)) {
+        throw new Error(`未知的布局模式：${opts.layout}，可选值：${allowed.join(' | ')}`);
+    }
+    const layout = raw;
+    const tabs = parseTabsSpec(opts.tabs);
+    if (layout === 'tabs' && !tabs?.length) {
+        logger_1.logger.warn('布局为 tabs 但未提供 --tabs，全部字段将放入单个「其它」页');
+    }
+    let tabLayout;
+    if (opts.tabLayout !== undefined) {
+        const value = String(opts.tabLayout).trim().toLowerCase();
+        if (value !== 'rows' && value !== 'grid') {
+            throw new Error(`未知的 --tab-layout 取值：${opts.tabLayout}，可选 rows | grid`);
+        }
+        tabLayout = value;
+    }
+    return {
+        layout,
+        gridColumns: opts.gridColumns === undefined ? undefined : Number(opts.gridColumns),
+        tabs,
+        tabLayout,
+    };
+}
+/**
+ * 解析 `--option`：`字段名=选项1,选项2:值2,...`（可重复，同一字段的选项会合并）。
+ * 未写 `:值` 时按序号 `1..n` 取值（与设计器默认一致）。
+ */
+function parseOptionSpecs(items) {
+    const result = {};
+    for (const raw of items) {
+        const eq = raw.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`--option 格式错误：${raw}，应为 "字段名=选项1,选项2:值2"`);
+        }
+        const field = raw.slice(0, eq).trim();
+        const list = raw
+            .slice(eq + 1)
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean)
+            .map((item, index) => {
+            const colon = item.indexOf(':');
+            return colon < 0
+                ? { label: item, value: String(index + 1) }
+                : {
+                    label: item.slice(0, colon).trim(),
+                    value: item.slice(colon + 1).trim() || String(index + 1),
+                };
+        });
+        if (!field || list.length === 0) {
+            throw new Error(`--option 格式错误：${raw}，字段名与选项都不能为空`);
+        }
+        result[field] = [...(result[field] ?? []), ...list];
+    }
+    return result;
+}
+/** 合并某个操作的字段权限 */
+function mergePermissions(target, fields, patch) {
+    const result = { ...(target ?? {}) };
+    fields.forEach((name) => {
+        result[name] = { ...(result[name] ?? {}), ...patch };
+    });
+    return result;
+}
+/**
+ * 解析字段权限（必填 / 可见 / 可编辑）。
+ *
+ * 落库位置为 `auth.{add|edit|view}[表名].fields[字段名]`，
+ * 对应控件属性面板的「字段权限」。
+ */
+function resolvePermissions(opts) {
+    const result = {};
+    const required = parseFieldList(opts.required);
+    const readonly = parseFieldList(opts.readonly);
+    const hidden = parseFieldList(opts.hidden);
+    if (required.length) {
+        result.add = mergePermissions(result.add, required, { required: true });
+        result.edit = mergePermissions(result.edit, required, { required: true });
+    }
+    if (readonly.length) {
+        result.add = mergePermissions(result.add, readonly, { editable: false });
+        result.edit = mergePermissions(result.edit, readonly, { editable: false });
+    }
+    if (hidden.length) {
+        ;
+        ['add', 'edit', 'view'].forEach((op) => {
+            result[op] = mergePermissions(result[op], hidden, { visible: false });
+        });
+    }
+    const file = opts.authFile;
+    if (file) {
+        let parsed;
+        try {
+            parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.resolve)(file), 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`读取权限文件失败：${file}（${error.message}）`);
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`权限文件格式错误：${file}，应为 { "add": { "fd_col_a": { "required": true } } }`);
+        }
+        ;
+        ['add', 'edit', 'view'].forEach((op) => {
+            const dict = parsed[op];
+            if (!dict || typeof dict !== 'object' || Array.isArray(dict))
+                return;
+            const target = { ...(result[op] ?? {}) };
+            Object.entries(dict).forEach(([name, patch]) => {
+                target[name] = { ...(target[name] ?? {}), ...patch };
+            });
+            result[op] = target;
+        });
+    }
+    return result;
+}
+/** 解析逗号分隔的人员列表 */
+function parseIdList(input) {
+    if (!input)
+        return undefined;
+    return input
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((fdId) => ({ fdId }));
+}
+/** 解析字段过滤列表 */
+function parseFieldFilter(input) {
+    if (!input)
+        return undefined;
+    return input
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function selectFields(models, fields) {
+    if (!fields || fields.length === 0)
+        return models;
+    const set = new Set(fields);
+    return models.map((model) => ({
+        ...model,
+        fdFields: (model.fdFields ?? []).filter((f) => set.has(f.fdName) || set.has(f.fdLabel)),
+    }));
+}
+function countFields(models, includeSystem = false) {
+    return models.reduce((sum, m) => sum + (m.fdFields ?? []).filter((f) => includeSystem || f.fdIsSystem !== true).length, 0);
+}
+/** commander 可重复选项收集器 */
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+/**
+ * 向主数据模型追加字段定义。
+ *
+ * 若 `--add-field` 指定的字段名**已存在**，则视为「调整该字段」：
+ * 覆盖其标题与控件类型（保留 fdId / fdOrder / 已有属性），否则追加为新字段。
+ * 新字段随 fdConfig.dataModel 一起保存，发布时由后端创建真实列。
+ */
+async function injectNewFields(models, specs, controlMap, registry) {
+    if (!specs || specs.length === 0)
+        return models;
+    const mainIndex = Math.max(0, models.findIndex((m) => m.fdType === 'main'));
+    const main = models[mainIndex];
+    const existing = new Map((main.fdFields ?? []).map((f) => [f.fdName, f]));
+    const added = [];
+    const patched = new Map();
+    for (const spec of specs) {
+        const parsed = (0, generator_1.parseFieldSpec)(spec);
+        const created = await (0, generator_1.createDataField)(parsed, { controlMap, registry });
+        const target = parsed.name ? existing.get(parsed.name) : undefined;
+        if (target && !patched.has(parsed.name) && !target.fdIsSystem) {
+            // 已有字段：只覆盖标题与控件类型，其余属性保留
+            patched.set(parsed.name, {
+                ...target,
+                fdLabel: created.fdLabel || target.fdLabel,
+                fdType: created.fdType,
+                fdDataType: created.fdDataType,
+                fdDictType: created.fdDictType,
+                fdLength: created.fdLength || target.fdLength,
+            });
+        }
+        else {
+            added.push(created);
+        }
+    }
+    if (patched.size === 0 && added.length === 0)
+        return models;
+    const fdFields = (main.fdFields ?? []).map((f) => patched.get(f.fdName) ?? f);
+    return models.map((m, i) => (i === mainIndex ? { ...m, fdFields: [...fdFields, ...added] } : m));
+}
+/** 解析 `--detail`：`明细表标题=字段1:标题1[:控件类型],字段2:标题2,...` */
+function parseDetailSpecs(items) {
+    return items.map((raw) => {
+        const eq = raw.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`--detail 格式错误：${raw}，应为 "明细表标题=字段1:标题1,字段2:标题2"`);
+        }
+        const title = raw.slice(0, eq).trim();
+        const fields = raw
+            .slice(eq + 1)
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (!title || fields.length === 0) {
+            throw new Error(`--detail 格式错误：${raw}，明细表标题与字段都不能为空`);
+        }
+        return { title, fields };
+    });
+}
+/**
+ * 构建明细表数据模型。
+ *
+ * 新建时向服务端取权威模板：`getSystemDefaultModel({fdType:'detail'})`（含 fdId 与
+ * `fd_id`/`fd_main_id`/`fd_order` 系统字段），表名由 `generateTableName` 生成；
+ * 若已存在同名明细表（按标题或表名匹配）则复用，实现「调整」而非重复创建。
+ */
+async function buildDetailModels(client, formId, formName, specs, controlMap, registry, existing = []) {
+    const result = [];
+    for (const spec of specs) {
+        const found = existing.find((m) => m.fdType === 'detail' && (m.fdName === spec.title || m.fdTableName === spec.title));
+        let template;
+        let tableName;
+        if (found) {
+            logger_1.logger.info(`  复用已有明细表：${found.fdName}（表名 ${found.fdTableName}）`);
+            template = found;
+            tableName = found.fdTableName;
+        }
+        else {
+            template = await formDefine_1.dataModelApi.getSystemDefaultModel(client, { fdType: 'detail' });
+            tableName = await formDefine_1.dataModelApi.generateTableName(client, {
+                fdXForm: { fdId: formId },
+                fdType: 'detail',
+            });
+        }
+        const templateFields = template.fdFields ?? [];
+        const added = [];
+        for (const raw of spec.fields) {
+            const parsed = (0, generator_1.parseFieldSpec)(raw);
+            const created = await (0, generator_1.createDataField)(parsed, { controlMap, registry });
+            const exist = templateFields.find((f) => f.fdName === parsed.name && !f.fdIsSystem);
+            if (exist) {
+                // 已有字段：覆盖标题与控件类型
+                exist.fdLabel = created.fdLabel || exist.fdLabel;
+                exist.fdType = created.fdType;
+                exist.fdDataType = created.fdDataType;
+                exist.fdDictType = created.fdDictType;
+                exist.fdLength = created.fdLength || exist.fdLength;
+            }
+            else {
+                added.push(created);
+            }
+        }
+        const text = spec.title;
+        result.push({
+            ...template,
+            fdType: 'detail',
+            fdName: text,
+            fdTableName: tableName,
+            fdTableNameAlias: tableName,
+            fdFields: [...templateFields, ...added],
+            fdXForm: { fdId: formId, fdName: formName },
+            fdOuterMapping: false,
+            needDelete: false,
+            deletePhysicalTable: false,
+            dynamicProps: {},
+        });
+    }
+    return result;
+}
+/** 公共的生成器选项 */
+function generatorOptions(opts, formType, appId) {
+    const family = resolveApiFamily(formType, opts.api, appId);
+    return {
+        family,
+        mechanismEntityName: opts.mechanismEntityName ??
+            (family === 'general' ? constants_1.ENTITY_NAME : constants_1.MODELING_ENTITY_NAME),
+        mechanismEntityCode: opts.mechanismEntityCode ??
+            (family === 'general' ? constants_1.ENTITY_CODE : constants_1.MODELING_ENTITY_CODE),
+    };
+}
+/** 读取表单的 fdFormDefineType（general 族带，design 族可能不带） */
+async function resolveFormFamily(client, fdId, requested) {
+    // modeling 族的表单先从建模接口读：能读到就是建模应用下的表单
+    if (requested !== 'design' && requested !== 'general') {
+        try {
+            const vo = await formDefine_1.modelingXFormApi.loadBase(client, fdId);
+            if (vo && (vo.fdId || vo.fdAppId)) {
+                return { family: 'modeling', vo };
+            }
+        }
+        catch {
+            /* 忽略，回落到通用读取 */
+        }
+    }
+    const vo = await formDefine_1.formDefineApi.get(client, fdId).catch(() => formDefine_1.designApi.load(client, fdId));
+    const family = resolveApiFamily(vo.fdFormDefineType ?? types_1.EFormDefineType.General, requested);
+    return { family, vo };
+}
+/** 加载字段来源数据模型 */
+async function loadModels(client, formId, fromModel) {
+    if (fromModel) {
+        const model = await formDefine_1.dataModelApi.load(client, fromModel);
+        return [model];
+    }
+    return (await formDefine_1.dataModelApi.loadByFormId(client, formId)) ?? [];
+}
+function registerFormCommand(program) {
+    const form = program.command('form').description('表单相关操作（创建 / 查询 / 发布 / 自动完善字段）');
+    // ------------------------------------------------------------------ create
+    form
+        .command('create')
+        .description('创建表单，并（可选）根据数据模型自动完善字段配置')
+        .requiredOption('--name <name>', '表单名称')
+        .option('--code <code>', '表单业务编码，默认自动生成')
+        .option('--type <type>', '表单类型：common|general|config|modal|template|refer。缺省时 general 族用 general、其余用 common')
+        .option('--app-id <appId>', '表单所属应用 id（应用主键 fdId）。给出后默认走 modeling 族，写入 fdAppId')
+        .option('--fd-entity-id <id>', '业务建模对应 appId / 应用模块对应 templateId（默认取 --app-id）')
+        .option('--fd-entity-name <name>', '所属实体 model 名称，例如 com.xxx.YourEntity')
+        .option('--fd-entity-key <key>', '实体扩展键（预留）')
+        .option('--fd-run-entity-name <name>', '表单运行时实体名称')
+        .option('--table-name <name>', '主表名（不传则调用对应接口自动生成）')
+        .option('--api <family>', '接口族：auto（默认）| modeling | general | design')
+        .option('--group-id <fdGroupId>', '表单所属分组 id（modeling 族）')
+        .option('--edit-draft', '草稿状态允许编辑（modeling 族，默认 true）')
+        .option('--no-edit-draft', '草稿状态不允许编辑（modeling 族）')
+        .option('--reader-flag', '阅读者为空时所有人可阅读（modeling 族）')
+        .option('--data-source-id <id>', '外部数据源 id（modeling 族）')
+        .option('--outer-mapping', '是否映射外部表（modeling 族）')
+        .option('--source-form-id <fdId>', '引用源表单 id（type=refer 时必填）')
+        .option('--category <fdId>', '表单分类 id')
+        .option('--icon <icon>', '页面图标（图标名或图标 JSON），默认使用内置默认图标')
+        .option('--readers <ids>', '可阅读者，逗号分隔的组织/人员 id')
+        .option('--editors <ids>', '可编辑者，逗号分隔的组织/人员 id')
+        .option('--mechanism-entity-name <name>', '机制实体名（决定控件库），默认按接口族推导')
+        .option('--mechanism-entity-code <code>', '机制编码，默认按接口族推导')
+        .option('--from-model <fdId>', '从指定数据模型 id 拷贝字段（默认使用新表单自身的数据模型）')
+        .option('--fields <names>', '仅生成指定字段，逗号分隔（字段名或标题）')
+        .option('--add-field <spec>', '新增字段，格式 name:label[:dataType|controlType[:controlType]]，可重复；例 "fd_text:单行文本"、"fd_amt:预算金额:moneytext"', collect, [])
+        .option('--option <spec>', '为下拉/单选/多选新建选项："字段名=选项1,选项2:值2"，可重复', collect, [])
+        .option('--detail <spec>', '新建/调整明细表："明细表标题=字段1:标题1,字段2:标题2:控件类型"，可重复', collect, [])
+        .option('--include-system', '同时把系统字段渲染到表单上（默认只渲染业务字段）')
+        .option('--per-row <n>', '每行控件数量', (v) => Number(v), 2)
+        .option('--span <n>', '控件栅格宽度', (v) => Number(v))
+        .option('--locale <locales>', '多语言，逗号分隔，第一个为主语言（默认 Cn）；all=Cn,Us,Tw', collect, [])
+        .option('--lang-file <path>', '多语言文案文件（JSON），如 {"Us":{"姓名":"Name"}}')
+        .option('--layout <mode>', '渲染布局：rows（默认）| grid 栅格 | tabs 多页签')
+        .option('--grid-columns <n>', '栅格列数（--layout grid，默认取 --per-row）', (v) => Number(v))
+        .option('--tabs <spec>', '多页签定义："标题:字段1,字段2|标题2:字段3"（--layout tabs）')
+        .option('--tab-layout <mode>', '页签内层布局：rows（默认）| grid 栅格')
+        .option('--required <fields>', '必填字段（逗号分隔，作用于 add/edit）')
+        .option('--readonly <fields>', '只读字段（逗号分隔，作用于 add/edit）')
+        .option('--hidden <fields>', '隐藏字段（逗号分隔，visible=false，作用于 add/edit/view）')
+        .option('--auth-file <path>', '精细字段权限（JSON），如 {"add":{"fd_col_a":{"required":true}}}')
+        .option('--action <spec>', '控件动作："字段名:事件:函数源码或@js文件"，可重复；全局动作用 $global（onLoad/onBeforeSubmit/onAfterSubmit）', collect, [])
+        .option('--action-file <path>', '控件动作定义文件（JSON），见 README「控件动作」章节')
+        .option('--force', '跳过控件必填属性校验（默认校验失败会中止保存/发布）')
+        .option('--no-config', '仅创建空表单，不生成字段配置')
+        .option('--publish', '创建后立即发布')
+        .option('--dry-run', '仅打印将要提交的数据，不实际请求')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .option('--json', '以 JSON 输出结果')
+        .action(async (opts) => {
+        const client = createClient(opts);
+        const appId = opts.appId;
+        const explicitType = opts.type;
+        const parsedType = explicitType ? parseFormType(explicitType) : undefined;
+        const { family, mechanismEntityName, mechanismEntityCode } = generatorOptions(opts, parsedType, appId);
+        // 未显式指定类型时：审批意见表单(general) 用 2，其余（含建模应用表单）用 1（普通表单）
+        const formType = parsedType ?? (family === 'general' ? types_1.EFormDefineType.General : types_1.EFormDefineType.Common);
+        // 引用了通用模板的引用者表单必须给出源表单
+        if (formType === types_1.EFormDefineType.Refer && !opts.sourceFormId) {
+            throw new Error('表单类型为「引用者表单(refer)」时必须提供 --source-form-id');
+        }
+        // generalFormDefine 接口对表单类型有强校验
+        if (family === 'general' && formType !== types_1.EFormDefineType.General) {
+            throw new Error(`generalFormDefine 接口仅支持「审批意见表单(general)」。` +
+                `当前类型为 ${types_1.FORM_TYPE_LABEL[formType]}，请使用 --api design（auto 模式下会自动切换）`);
+        }
+        // 应用下建表单必须指定应用
+        if (family === 'modeling' && !appId) {
+            throw new Error('modeling 接口族（应用下建表单）必须提供 --app-id');
+        }
+        const fdEntityId = opts.fdEntityId ?? appId;
+        // 各接口族通用的字段（均存在于基类 SysXFormDesignVO）
+        const baseCommon = stripUndefined({
+            fdName: opts.name,
+            fdCode: opts.code ?? (0, random_1.generateTemplateCode)(),
+            fdFormDefineType: formType,
+            fdIcon: (0, icon_1.normalizeIcon)(opts.icon),
+            fdSourceFormId: opts.sourceFormId,
+            appId,
+            fdEntityId,
+            fdEntityName: opts.fdEntityName,
+            fdEntityKey: opts.fdEntityKey,
+            fdRunEntityName: opts.fdRunEntityName,
+        });
+        // 仅 generalFormDefine 的 VO（SysGeneralFormDefineVO）支持的字段
+        const generalExtra = stripUndefined({
+            fdCategory: opts.category ? { fdId: opts.category } : undefined,
+            fdReaders: parseIdList(opts.readers),
+            fdEditors: parseIdList(opts.editors),
+        });
+        // 仅 sysModelingXForm 的 VO（SysModelingXFormDesignVO）支持的字段
+        const modelingExtra = stripUndefined({
+            fdAppId: appId,
+            fdGroupId: opts.groupId,
+            fdEditDraft: opts.editDraft !== false,
+            fdReaderFlag: Boolean(opts.readerFlag),
+            fdDataSourceId: opts.dataSourceId,
+            fdOuterMapping: Boolean(opts.outerMapping),
+        });
+        logger_1.logger.info(logger_1.color.gray(`接口族：${FAMILY_LABEL[family]}　` +
+            `类型：${types_1.FORM_TYPE_LABEL[formType]}　应用：${appId ?? '（未指定）'}`));
+        let fdId;
+        let base;
+        if (family === 'modeling') {
+            // ---------- 0. 应用下建表单：sysModelingXForm/create ----------
+            let tableName = opts.tableName;
+            if (!tableName) {
+                logger_1.logger.step('生成主表名（sysModelingXForm/generateTableName）');
+                try {
+                    tableName = await formDefine_1.modelingXFormApi.generateTableName(client);
+                }
+                catch (err) {
+                    logger_1.logger.warn(`生成表名失败，需自行指定 --table-name：${err.message}`);
+                }
+            }
+            base = {
+                ...baseCommon,
+                ...modelingExtra,
+                fdTableName: tableName,
+                fdStatus: 'draft',
+                mechanisms: { load: '*' },
+            };
+            if (opts.dryRun) {
+                logger_1.logger.title('【dry-run】将提交（sysModelingXForm/create）');
+                logger_1.logger.json(base);
+                return;
+            }
+            logger_1.logger.step(`创建表单：${base.fdName}`);
+            const created = await formDefine_1.modelingXFormApi.create(client, base);
+            fdId = created?.fdId ?? created;
+        }
+        else if (family === 'general') {
+            // ---------- A. 审批意见表单：init -> add ----------
+            logger_1.logger.step('获取表单默认配置（generalFormDefine/init）');
+            let defaults = {};
+            try {
+                defaults = (await formDefine_1.formDefineApi.init(client, {
+                    mechanisms: { load: '*' },
+                    appId,
+                    fdEntityId,
+                })) ?? {};
+            }
+            catch (err) {
+                logger_1.logger.warn(`init 调用失败，将仅使用用户输入：${err.message}`);
+            }
+            base = {
+                ...defaults,
+                ...baseCommon,
+                fdCode: baseCommon.fdCode ?? defaults.fdCode,
+                fdCategory: generalExtra.fdCategory ?? defaults.fdCategory,
+                fdReaders: generalExtra.fdReaders ?? defaults.fdReaders,
+                fdEditors: generalExtra.fdEditors ?? defaults.fdEditors,
+                fdIcon: baseCommon.fdIcon ?? defaults.fdIcon,
+                // --app-id 显式指定时覆盖 init 给的 fdEntityId
+                fdEntityId: fdEntityId ?? defaults.fdEntityId,
+            };
+            if (opts.dryRun) {
+                logger_1.logger.title('【dry-run】将提交（generalFormDefine/add）');
+                logger_1.logger.json(base);
+                return;
+            }
+            logger_1.logger.step(`创建表单：${base.fdName}`);
+            const created = await formDefine_1.formDefineApi.add(client, base);
+            fdId = created?.fdId ?? created;
+        }
+        else {
+            // ---------- B. 其余类型：sysXFormDesign/create ----------
+            let tableName = opts.tableName;
+            if (!tableName && !opts.dryRun) {
+                try {
+                    tableName = await formDefine_1.dataModelApi.generateTableName(client, { fdType: 'main' });
+                }
+                catch (err) {
+                    logger_1.logger.warn(`生成表名失败：${err.message}`);
+                }
+            }
+            base = {
+                ...baseCommon,
+                fdTableName: tableName,
+                fdStatus: 'draft',
+                mechanisms: { load: '*' },
+            };
+            if (opts.dryRun) {
+                logger_1.logger.title('【dry-run】将提交（sysXFormDesign/create）');
+                logger_1.logger.json(base);
+                return;
+            }
+            logger_1.logger.step(`创建表单：${base.fdName}`);
+            const created = await formDefine_1.designApi.create(client, base);
+            fdId = created?.fdId ?? created;
+        }
+        logger_1.logger.success(`表单创建成功，fdId = ${fdId}`);
+        const skipConfig = opts.config === false || formType === types_1.EFormDefineType.Refer;
+        if (skipConfig) {
+            if (formType === types_1.EFormDefineType.Refer) {
+                logger_1.logger.warn('引用者表单自身不保存 fdConfig，将直接使用源表单配置');
+            }
+            if (opts.json)
+                logger_1.logger.json({ fdId, apiFamily: family });
+            if (opts.publish)
+                await doPublish(client, family, fdId, base);
+            return;
+        }
+        // ---------- 生成字段配置 ----------
+        logger_1.logger.step('加载数据模型与可用字段');
+        const models = await loadModels(client, fdId, opts.fromModel);
+        if (models.length === 0) {
+            logger_1.logger.warn(`未获取到数据模型，跳过字段生成。可稍后执行 \`llc form autofill --id ${fdId}\``);
+        }
+        else {
+            const controlMap = (0, config_1.resolveControlMap)();
+            const registry = createRegistry(opts);
+            const i18n = resolveI18n(opts);
+            if (i18n.locale.length > 1) {
+                logger_1.logger.info(`  多语言：${i18n.locale.join('、')}（主语言 ${i18n.locale[0]}）`);
+            }
+            const layoutOptions = resolveLayout(opts);
+            const permissions = resolvePermissions(opts);
+            const optionSpecs = parseOptionSpecs(opts.option ?? []);
+            const actionSpecs = resolveActions(opts);
+            if (actionSpecs.length) {
+                logger_1.logger.info(`  控件动作：${actionSpecs.length} 个`);
+            }
+            if (layoutOptions.layout && layoutOptions.layout !== 'rows') {
+                logger_1.logger.info(`  布局：${layoutOptions.layout}`);
+            }
+            const filtered = selectFields(models, parseFieldFilter(opts.fields));
+            const withNew = await injectNewFields(filtered, opts.addField, controlMap, registry);
+            // 明细表：新建或调整已有明细表
+            const detailSpecs = parseDetailSpecs(opts.detail ?? []);
+            let withDetail = withNew;
+            if (detailSpecs.length) {
+                const details = await buildDetailModels(client, fdId, base.fdName, detailSpecs, controlMap, registry, withNew);
+                withDetail = [...withNew, ...details];
+                logger_1.logger.info(`  明细表：${details.length} 个`);
+            }
+            if (opts.addField?.length) {
+                logger_1.logger.info(`  新增字段：${opts.addField.length} 个（${opts.addField.join('、')}）`);
+            }
+            logger_1.logger.info(`  表单字段：${countFields(withDetail, opts.includeSystem)} 个（含明细 ${withDetail.filter((m) => m.fdType === 'detail').length} 张）`);
+            const stats = { optionsCompleted: 0, actionsCompleted: 0 };
+            const payload = await (0, generator_1.buildFormDefinePayload)(withDetail, {
+                base: { ...base, fdId },
+                formId: fdId,
+                formName: base.fdName,
+                formDefineType: formType,
+                entityName: mechanismEntityName,
+                entityCode: mechanismEntityCode,
+                includeSystem: Boolean(opts.includeSystem),
+                perRow: opts.perRow,
+                span: opts.span,
+                controlMap,
+                registry,
+                stats,
+                ...i18n,
+                ...layoutOptions,
+                permissions,
+                options: optionSpecs,
+                actions: actionSpecs,
+            });
+            if (stats.optionsCompleted) {
+                logger_1.logger.info(`  完善选项多语言：${stats.optionsCompleted} 个`);
+            }
+            if (stats.actionsCompleted) {
+                logger_1.logger.info(`  配置控件动作：${stats.actionsCompleted} 个`);
+            }
+            for (const warning of stats.actionWarnings ?? []) {
+                logger_1.logger.warn(warning);
+            }
+            assertPropValidation(stats, opts, true);
+            if (family === 'modeling') {
+                if (opts.publish) {
+                    logger_1.logger.step('保存并发布表单（sysModelingXForm/saveDesignAndPublish）');
+                    await formDefine_1.modelingXFormApi.saveDesignAndPublish(client, payload);
+                    logger_1.logger.success('表单字段配置已保存并发布');
+                }
+                else {
+                    logger_1.logger.step('保存表单字段配置（sysModelingXForm/saveDesign）');
+                    await formDefine_1.modelingXFormApi.saveDesign(client, payload);
+                    logger_1.logger.success('表单字段配置已保存');
+                }
+            }
+            else {
+                logger_1.logger.step(`保存表单字段配置（${FAMILY_LABEL[family]}/save）`);
+                if (family === 'general') {
+                    await formDefine_1.formDefineApi.save(client, payload);
+                }
+                else {
+                    await formDefine_1.designApi.save(client, payload);
+                }
+                logger_1.logger.success('表单字段配置已保存');
+            }
+        }
+        // modeling 族若已通过 saveDesignAndPublish 发布，则不再重复发布
+        const publishedAlready = family === 'modeling' && opts.publish && models.length > 0;
+        if (opts.publish && !publishedAlready)
+            await doPublish(client, family, fdId, base);
+        if (opts.json) {
+            logger_1.logger.json({ fdId, name: base.fdName, formDefineType: formType, appId, apiFamily: family });
+        }
+        else {
+            logger_1.logger.info('');
+            logger_1.logger.success(`完成。表单 id：${fdId}`);
+        }
+    });
+    // -------------------------------------------------------------------- list
+    form
+        .command('list')
+        .description('查询表单列表（generalFormDefine/list，即审批意见表单）')
+        .option('--keyword <keyword>', '按名称模糊搜索')
+        .option('--page-no <n>', '页码', (v) => Number(v), 1)
+        .option('--page-size <n>', '每页数量', (v) => Number(v), 20)
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .option('--json', '以 JSON 输出')
+        .action(async (opts) => {
+        const client = createClient(opts);
+        const conditions = opts.keyword
+            ? { fdName: { $contains: String(opts.keyword).trim() } }
+            : undefined;
+        const result = await formDefine_1.formDefineApi.list(client, {
+            pageNo: opts.pageNo,
+            pageSize: opts.pageSize,
+            conditions,
+            sorts: { fdCreateTime: 'DESC' },
+            columns: ['fdId', 'fdName', 'fdCode', 'fdFormDefineType', 'fdStatus', 'fdCreateTime'],
+        });
+        if (opts.json) {
+            logger_1.logger.json(result);
+            return;
+        }
+        const content = result?.content ?? [];
+        logger_1.logger.table(content.map((item) => ({
+            fdId: item.fdId ?? '',
+            名称: item.fdName ?? '',
+            编码: item.fdCode ?? '',
+            类型: item.fdFormDefineType
+                ? types_1.FORM_TYPE_LABEL[item.fdFormDefineType]
+                : '',
+            状态: item.fdStatus ?? '',
+        })));
+        logger_1.logger.info(logger_1.color.gray(`共 ${content.length} 条`));
+    });
+    // --------------------------------------------------------------------- get
+    form
+        .command('get')
+        .description('查看表单详情')
+        .requiredOption('--id <fdId>', '表单 id')
+        .option('--with-config', '同时解析并展示 fdConfig 概要')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .option('--json', '以 JSON 输出')
+        .action(async (opts) => {
+        const client = createClient(opts);
+        let vo;
+        // 依次尝试 建模应用接口 -> 审批意见表单接口 -> 表单引擎接口
+        try {
+            vo = await formDefine_1.modelingXFormApi.loadBase(client, opts.id);
+        }
+        catch {
+            try {
+                vo = await formDefine_1.formDefineApi.get(client, opts.id, { mechanisms: { load: '*' } });
+            }
+            catch {
+                vo = await formDefine_1.designApi.load(client, opts.id);
+            }
+        }
+        if (opts.json || !opts.withConfig) {
+            logger_1.logger.json(vo);
+            return;
+        }
+        logger_1.logger.json(vo);
+        try {
+            const fdConfig = typeof vo.fdConfig === 'string' ? JSON.parse(vo.fdConfig) : vo.fdConfig;
+            const viewModel = fdConfig?.viewModel ?? [];
+            const dataModel = fdConfig?.dataModel ?? [];
+            logger_1.logger.title('\nfdConfig 概要');
+            logger_1.logger.table(dataModel.map((m) => ({
+                表: m.fdName,
+                表名: m.fdTableName,
+                类型: m.fdType,
+                字段数: m.fdFields?.length ?? 0,
+            })));
+            logger_1.logger.info(logger_1.color.gray(`场景数：${viewModel.length}`));
+        }
+        catch {
+            logger_1.logger.warn('fdConfig 解析失败，已原样输出');
+        }
+    });
+    // ----------------------------------------------------------------- publish
+    form
+        .command('publish')
+        .description('发布表单')
+        .requiredOption('--id <fdId>', '表单 id')
+        .option('--api <family>', '接口族：auto（默认）| modeling | general | design')
+        .option('--desc <desc>', '发布说明', '')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .action(async (opts) => {
+        const client = createClient(opts);
+        const { family, vo } = await resolveFormFamily(client, opts.id, opts.api);
+        await doPublish(client, family, opts.id, vo, opts.desc);
+        logger_1.logger.success(`表单 ${opts.id} 已发布`);
+    });
+    // ---------------------------------------------------------------- autofill
+    form
+        .command('autofill')
+        .description('自动完善表单字段：依据数据模型重建字段配置并保存')
+        .requiredOption('--id <fdId>', '表单 id')
+        .option('--from-model <fdId>', '使用指定数据模型 id 的字段（默认使用表单自身数据模型）')
+        .option('--fields <names>', '仅处理指定字段，逗号分隔')
+        .option('--add-field <spec>', '新增字段，格式 name:label[:dataType|controlType[:controlType]]，可重复', collect, [])
+        .option('--option <spec>', '为下拉/单选/多选新建选项："字段名=选项1,选项2:值2"，可重复', collect, [])
+        .option('--detail <spec>', '新建/调整明细表："明细表标题=字段1:标题1,字段2:标题2:控件类型"，可重复', collect, [])
+        .option('--include-system', '同时把系统字段渲染到表单上（默认只渲染业务字段）')
+        .option('--icon <icon>', '页面图标（图标名或图标 JSON）；缺失时会自动补默认图标')
+        .option('--per-row <n>', '每行控件数量', (v) => Number(v), 2)
+        .option('--span <n>', '控件栅格宽度', (v) => Number(v))
+        .option('--locale <locales>', '多语言，逗号分隔，第一个为主语言（默认 Cn）；all=Cn,Us,Tw', collect, [])
+        .option('--lang-file <path>', '多语言文案文件（JSON），如 {"Us":{"姓名":"Name"}}')
+        .option('--layout <mode>', '渲染布局：rows（默认）| grid 栅格 | tabs 多页签')
+        .option('--grid-columns <n>', '栅格列数（--layout grid，默认取 --per-row）', (v) => Number(v))
+        .option('--tabs <spec>', '多页签定义："标题:字段1,字段2|标题2:字段3"（--layout tabs）')
+        .option('--tab-layout <mode>', '页签内层布局：rows（默认）| grid 栅格')
+        .option('--required <fields>', '必填字段（逗号分隔，作用于 add/edit）')
+        .option('--readonly <fields>', '只读字段（逗号分隔，作用于 add/edit）')
+        .option('--hidden <fields>', '隐藏字段（逗号分隔，visible=false，作用于 add/edit/view）')
+        .option('--auth-file <path>', '精细字段权限（JSON），如 {"add":{"fd_col_a":{"required":true}}}')
+        .option('--action <spec>', '控件动作："字段名:事件:函数源码或@js文件"，可重复；全局动作用 $global（onLoad/onBeforeSubmit/onAfterSubmit）', collect, [])
+        .option('--action-file <path>', '控件动作定义文件（JSON），见 README「控件动作」章节')
+        .option('--force', '跳过控件必填属性校验（默认校验失败会中止保存/发布）')
+        .option('--mechanism-entity-name <name>', '机制实体名（决定控件库）')
+        .option('--mechanism-entity-code <code>', '机制编码')
+        .option('--apply', '确认写入（不加该参数仅预览生成结果）')
+        .option('--publish', '写入后同时发布（保持发布态，避免掉回草稿）')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .option('--json', '以 JSON 输出生成结果')
+        .action(async (opts) => {
+        const client = createClient(opts);
+        logger_1.logger.step(`加载表单：${opts.id}`);
+        const { family, vo } = await resolveFormFamily(client, opts.id);
+        /** 保存前的状态：saveDesign 会置为草稿态，用于提示/重新发布 */
+        const fdStatusBefore = vo.fdStatus;
+        // 图标缺失会让 sys-modeling 编辑器进入时报 "undefined" is not valid JSON（必须走 saveBase 写镜像表）
+        const currentIcon = vo.fdIcon;
+        if (family === 'modeling' && (!currentIcon || opts.icon)) {
+            const icon = (0, icon_1.normalizeIcon)(opts.icon);
+            if (icon !== currentIcon) {
+                logger_1.logger.step('更新表单图标（sysModelingXForm/saveBase）');
+                await formDefine_1.modelingXFormApi.saveBase(client, {
+                    fdId: opts.id,
+                    fdName: vo.fdName,
+                    fdCode: vo.fdCode,
+                    fdIcon: icon,
+                });
+                vo.fdIcon = icon;
+                logger_1.logger.success('表单图标已更新');
+            }
+        }
+        const formType = vo.fdFormDefineType ?? types_1.EFormDefineType.General;
+        const mechanismEntityName = opts.mechanismEntityName ??
+            (family === 'general' ? constants_1.ENTITY_NAME : constants_1.MODELING_ENTITY_NAME);
+        const mechanismEntityCode = opts.mechanismEntityCode ??
+            (family === 'general' ? constants_1.ENTITY_CODE : constants_1.MODELING_ENTITY_CODE);
+        logger_1.logger.step('加载数据模型字段');
+        const models = await loadModels(client, opts.id, opts.fromModel);
+        if (models.length === 0) {
+            throw new Error('未获取到数据模型字段，无法自动完善');
+        }
+        const controlMap = (0, config_1.resolveControlMap)();
+        const registry = createRegistry(opts);
+        const i18n = resolveI18n(opts);
+        if (i18n.locale.length > 1) {
+            logger_1.logger.info(`  多语言：${i18n.locale.join('、')}（主语言 ${i18n.locale[0]}）`);
+        }
+        const layoutOptions = resolveLayout(opts);
+        const permissions = resolvePermissions(opts);
+        const optionSpecs = parseOptionSpecs(opts.option ?? []);
+        if (layoutOptions.layout && layoutOptions.layout !== 'rows') {
+            logger_1.logger.info(`  布局：${layoutOptions.layout}`);
+        }
+        const filtered = selectFields(models, parseFieldFilter(opts.fields));
+        const withNew = await injectNewFields(filtered, opts.addField, controlMap, registry);
+        // 明细表：新建或调整已有明细表
+        const detailSpecs = parseDetailSpecs(opts.detail ?? []);
+        let withDetail = withNew;
+        if (detailSpecs.length) {
+            const details = await buildDetailModels(client, opts.id, vo.fdName, detailSpecs, controlMap, registry, withNew);
+            withDetail = [...withNew, ...details];
+            logger_1.logger.info(`  明细表：${details.length} 个（新建 ${details.filter((d) => !withNew.some((m) => m.fdId === d.fdId)).length}，复用 ${details.filter((d) => withNew.some((m) => m.fdId === d.fdId)).length}）`);
+        }
+        const actionSpecs = resolveActions(opts);
+        // 已有设计：保留控件动作/表单规则；--layout 未指定时沿用已有视图（布局不动）
+        const prev = await loadPrevDesign(client, family, opts.id);
+        if (actionSpecs.length) {
+            logger_1.logger.info(`  控件动作：${actionSpecs.length} 个`);
+        }
+        const stats = { optionsCompleted: 0, actionsCompleted: 0 };
+        const payload = await (0, generator_1.buildFormDefinePayload)(withDetail, {
+            base: {
+                ...vo,
+                fdId: opts.id,
+                // 图标缺失会导致 sys-modeling 编辑器进入时报 "undefined" is not valid JSON
+                fdIcon: vo.fdIcon || (0, icon_1.normalizeIcon)(undefined),
+            },
+            formId: opts.id,
+            formName: vo.fdName,
+            formDefineType: formType,
+            entityName: mechanismEntityName,
+            entityCode: mechanismEntityCode,
+            includeSystem: Boolean(opts.includeSystem),
+            perRow: opts.perRow,
+            span: opts.span,
+            registry,
+            controlMap: (0, config_1.resolveControlMap)(),
+            stats,
+            ...i18n,
+            ...layoutOptions,
+            permissions,
+            options: optionSpecs,
+            actions: actionSpecs,
+            prevFormAttr: prev.prevFormAttr,
+            prevViewModel: prev.prevViewModel,
+            prevLang: prev.prevLang,
+        });
+        logger_1.logger.info(`  使用字段：${countFields(withNew, opts.includeSystem)} 个（接口族：${family}）`);
+        if (stats.optionsCompleted) {
+            logger_1.logger.info(`  完善选项多语言：${stats.optionsCompleted} 个`);
+        }
+        if (stats.actionsCompleted) {
+            logger_1.logger.info(`  配置控件动作：${stats.actionsCompleted} 个`);
+        }
+        for (const warning of [...(stats.actionWarnings ?? []), ...(stats.layoutWarnings ?? [])]) {
+            logger_1.logger.warn(warning);
+        }
+        assertPropValidation(stats, opts, Boolean(opts.apply));
+        if (opts.json) {
+            logger_1.logger.json(JSON.parse(payload.fdConfig));
+            if (!opts.apply)
+                return;
+        }
+        if (!opts.apply) {
+            logger_1.logger.warn('预览模式：未写入。确认无误后追加 --apply 执行保存');
+            return;
+        }
+        if (family === 'modeling' && opts.publish) {
+            logger_1.logger.step('保存并发布表单（sysModelingXForm/saveDesignAndPublish）');
+            await formDefine_1.modelingXFormApi.saveDesignAndPublish(client, payload);
+            logger_1.logger.success(`表单 ${opts.id} 字段配置已更新并发布`);
+            return;
+        }
+        if (family === 'general') {
+            await formDefine_1.formDefineApi.save(client, payload);
+        }
+        else if (family === 'modeling') {
+            await formDefine_1.modelingXFormApi.saveDesign(client, payload);
+        }
+        else {
+            await formDefine_1.designApi.save(client, payload);
+        }
+        logger_1.logger.success(`表单 ${opts.id} 字段配置已更新`);
+        // saveDesign 会把表单置为草稿态，已发布表单需显式再发布
+        if (opts.publish) {
+            await doPublish(client, family, opts.id, payload);
+            logger_1.logger.success(`表单 ${opts.id} 已重新发布`);
+        }
+        else if (fdStatusBefore === 'official') {
+            logger_1.logger.warn('保存后表单状态变为草稿态，如需保持发布态请追加 --publish');
+        }
+    });
+    // ---------------------------------------------------------------- category
+    form
+        .command('category-list')
+        .description('查询表单分类列表')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .option('--json', '以 JSON 输出')
+        .action(async (opts) => {
+        const client = createClient(opts);
+        const result = await formDefine_1.formCategoryApi.list(client, {
+            pageNo: 1,
+            pageSize: 1000,
+            columns: ['fdId', 'fdName', 'fdCode', 'fdCreator', 'fdCreateTime'],
+            sorts: { fdCreateTime: 'DESC' },
+        });
+        if (opts.json) {
+            logger_1.logger.json(result);
+            return;
+        }
+        const content = result?.content ?? [];
+        logger_1.logger.table(content.map((c) => ({ fdId: c.fdId, 名称: c.fdName, 编码: c.fdCode ?? '' })));
+    });
+    // ---------------------------------------------------------------- delete
+    form
+        .command('delete')
+        .description('删除表单（连同其数据模型，不可逆；需 --yes 确认）')
+        .requiredOption('--id <fdId>', '表单 id')
+        .option('--yes', '确认执行删除')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .action(async (opts) => {
+        const fdId = String(opts.id ?? '').trim();
+        if (!fdId)
+            throw new Error('表单 id 不能为空');
+        if (!opts.yes) {
+            logger_1.logger.warn('已取消：删除表单属于不可逆操作，请追加 --yes 确认执行');
+            return;
+        }
+        const client = createClient(opts);
+        logger_1.logger.step(`删除表单：${fdId}`);
+        await formDefine_1.modelingXFormApi.remove(client, fdId);
+        logger_1.logger.success(`表单 ${fdId} 已删除`);
+    });
+    form
+        .command('delete-data')
+        .description('删除表单的运行时业务数据（保留表单定义；需 --yes 确认）')
+        .requiredOption('--id <fdId>', '表单 id')
+        .option('--yes', '确认执行删除')
+        .option('--base-url <url>', '服务端基址（覆盖配置）')
+        .option('--token <token>', '鉴权 Token（覆盖配置）')
+        .action(async (opts) => {
+        const fdId = String(opts.id ?? '').trim();
+        if (!fdId)
+            throw new Error('表单 id 不能为空');
+        if (!opts.yes) {
+            logger_1.logger.warn('已取消：删除业务数据属于不可逆操作，请追加 --yes 确认执行');
+            return;
+        }
+        const client = createClient(opts);
+        logger_1.logger.step(`删除表单业务数据：${fdId}`);
+        await formDefine_1.modelingXFormApi.removeData(client, fdId);
+        logger_1.logger.success(`表单 ${fdId} 的业务数据已删除`);
+    });
+}
+/** 按接口族发布表单 */
+async function doPublish(client, family, fdId, base, desc = '') {
+    logger_1.logger.step(`发布表单（${FAMILY_LABEL[family]}/publish）`);
+    if (family === 'general') {
+        const fresh = await formDefine_1.formDefineApi.get(client, fdId);
+        await formDefine_1.formDefineApi.publish(client, {
+            ...base,
+            ...fresh,
+            fdId,
+            fdBuildNew: true,
+            fdDescribe: desc,
+        });
+    }
+    else if (family === 'modeling') {
+        await formDefine_1.modelingXFormApi.publish(client, {
+            ...base,
+            fdId,
+            fdDescribe: desc,
+        });
+    }
+    else {
+        await formDefine_1.designApi.publish(client, {
+            fdId,
+            fdBuildNew: true,
+            fdDescribe: desc,
+            mechanisms: base.mechanisms ?? { load: '*' },
+        });
+    }
+    logger_1.logger.success('表单已发布');
+}
+/** 去掉值为 undefined 的键，避免覆盖 init 返回的默认值 */
+function stripUndefined(obj) {
+    const result = {};
+    Object.keys(obj).forEach((key) => {
+        if (obj[key] !== undefined)
+            result[key] = obj[key];
+    });
+    return result;
+}