weaver-e10-builder 1.2.5 → 1.5.1

package/dist/commands/form.js

@@ -1,14 +1,17 @@
 import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { AuthSession } from '../core/auth.js';
 import { ApiClient } from '../core/client.js';
-import { toColumnName, toTableName } from '../utils/column-name.js';
-import { createCustomPhysicalForm, addInitialFieldsToCustomPhysicalForm, placeholderFromFormat, reapplyGroupLayout } from '../services/form-create.js';
+import { toColumnName, toTableName, resolveFieldKeys } from '../utils/column-name.js';
+import { createCustomPhysicalForm, addInitialFieldsToCustomPhysicalForm, placeholderFromFormat, reapplyGroupLayout, queryFormStorageSetting } from '../services/form-create.js';
 import { FormSubDetailService, resolveDetailTable } from '../services/form-sub-detail.js';
 import { RICH_TYPE_MAP, getRichType, richIdUnits, BROWSER_KINDS } from '../services/rich-types.js';
 import { dropFieldComponents, prepareLayoutForSave } from '../services/form-field-drop.js';
 import { describeEditBaseFailure, resolveEditBase as resolveEditBasePure } from '../services/form-edit-base.js';
 import { applyFieldPatches, platformFieldShape } from '../services/form-field-patch.js';
 import { ensureDisplayColumns } from '../services/form-ebuilder-columns.js';
+import { insertFieldIntoLayout, patchFieldLayout } from '../services/form-layout-insert.js';
+import { buildLinkageAddPayload, addLinkage, resolveEffect, readLinkageConfig } from '../services/form-linkage-condition.js';
+import { createMultilangLabel } from '../services/form-i18n-label.js';
 import { buildFormulaParameters, defaultReturnType } from '../services/formula-detail.js';
 import { registerOptionTemplateCommand } from './form-option-template.js';
 /**
@@ -20,7 +23,7 @@ import { registerOptionTemplateCommand } from './form-option-template.js';
 const CK_CANON = {
     textarea: 'TextArea', ebuilder: 'EBuilder', datetime: 'DateTime',
     idcard: 'IDCard', mobile: 'Mobile', email: 'Email', phone: 'Phone',
-    employee: 'Employee', department: 'Department', location: 'Location',
+    employee: 'Employee', department: 'Department', subcompany: 'SubCompany', location: 'Location',
     switch: 'Switch', select: 'Select', checkbox: 'CheckBox', radiobox: 'RadioBox',
     money: 'Money', number: 'Number', date: 'Date', text: 'Text',
     daterange: 'DateRange', detailtable: 'DetailTable', city: 'City',
@@ -354,6 +357,8 @@ export function registerFormCommands(program) {
         + 'valueKey 须为数字、省略则平台生成）')
         .option('--menu', '建表后添加台账菜单（默认不加；漏加可用 `e10-cli menu add-table` 补）')
         .option('--layout <type>', '表单布局类型：FLOW(流式)/EXCEL(表格，缺省)。布局类型建表后不可切换', 'EXCEL')
+        .option('--table-name <name>', '自定义数据库表名。平台前缀（如 uf_）由 CLI 自动补，传 uf_xxx 或只传自定义部分都可以；'
+        + '须字母开头、只含字母数字下划线。缺省按表单名拼音首字母 + 随机数生成')
         .action(async (appId, name, cmdOpts) => {
         const opts = program.opts();
         const auth = await AuthSession.fromOptions(opts);
@@ -560,8 +565,10 @@ export function registerFormCommands(program) {
                 if (f.formName)
                     field.formName = f.formName;
             }
-            field.dataKey = toColumnName(f.fieldName);
-            field.columnName = field.dataKey;
+            // fields.json 可分别指定 dataKey / columnName；默认同值（都是拼音首字母）
+            const fKeys = resolveFieldKeys(f.fieldName, f);
+            field.dataKey = fKeys.dataKey;
+            field.columnName = fKeys.columnName;
             formFields.push(field);
             // DetailTable occupies 2 rows of layout space
             rowIdx += isDetail ? 2 : 1;
@@ -592,7 +599,17 @@ export function registerFormCommands(program) {
             formValues: { formName: name, formTitle: name, tableName, tableType: 'physical' },
         };
         // Use standard creation flow for controllable table names
-        const tableSuffix = toTableName(name);
+        // --table-name 指定物理表名（uf_ 前缀由服务层 resolveCustomPhysicalTableName 补）；缺省按表单名生成
+        const customTableName = cmdOpts.tableName?.trim();
+        if (customTableName) {
+            const setting = await queryFormStorageSetting(client, baseUrl, appId);
+            if (!setting.storageSettings.includes('physical')) {
+                console.error(`该应用未启用物理表（storageSettings=${setting.storageSettings.join('/') || '空'}），`
+                    + '没有独立的数据库表名，--table-name 不适用');
+                process.exit(1);
+            }
+        }
+        const requestedTableName = customTableName || toTableName(name);
         const layoutType = String(cmdOpts.layout || 'EXCEL').toUpperCase();
         if (layoutType !== 'FLOW' && layoutType !== 'EXCEL') {
             console.error(`--layout 只支持 FLOW(流式) 或 EXCEL(表格)，收到: ${cmdOpts.layout}`);
@@ -602,7 +619,7 @@ export function registerFormCommands(program) {
         let formId = '';
         let fieldGroups = [];
         try {
-            const result = await createCustomPhysicalForm(client, baseUrl, appId, name, tableSuffix, false, layoutType);
+            const result = await createCustomPhysicalForm(client, baseUrl, appId, name, requestedTableName, false, layoutType);
             objId = result.objId;
             formId = result.formId;
             console.error(`表单已创建，ID: ${objId}` + (formId ? `  formId: ${formId}` : ''));
@@ -626,6 +643,9 @@ export function registerFormCommands(program) {
                 // 文本最大长度（Text 缺省 100、TextArea 缺省 4000）+ 日期精度 format（Date/DateTime）需透传，
                 // 否则 fields.json 标注的 maxLen/format 被丢（bug：长度默认 100 不生效、日期精度丢失）。
                 maxLen: f.maxLen, format: f.format,
+                // 字段编码 dataKey / 数据库列名 columnName —— 两者是两个东西，可分别指定。
+                // 这里是**白名单透传**，漏一项就会静默丢（maxLen/format 历史上就漏过）。
+                dataKey: f.dataKey, columnName: f.columnName,
             }));
             const fieldResult = await addInitialFieldsToCustomPhysicalForm(client, baseUrl, appId, objId, formId, fieldDefsForStandard, auth.tenantKey, layoutType, systemOverrides);
             fieldGroups = fieldResult.fieldGroups || [];
@@ -769,7 +789,8 @@ export function registerFormCommands(program) {
                 const colName = df?.columnName || df?.dataKey || '';
                 fieldByName.set(f.fieldName, {
                     fieldId: f.fieldId,
-                    dataKey: colName,
+                    // dataKey 与 columnName 是两个东西，各自保留真值 —— 回写时不能互相顶替
+                    dataKey: df?.dataKey || colName,
                     columnName: colName,
                     formTableId: df?.formTableId || formTableId,
                 });
@@ -805,7 +826,7 @@ export function registerFormCommands(program) {
                     openRelateView: false,
                     title: ef.fieldName, type: 'EBuilder',
                     dataCount: 0,
-                    dataKey: finfo.columnName,
+                    dataKey: finfo.dataKey,
                     systemField: true,
                     columnTypeSwitch: false,
                     appId,
@@ -1041,7 +1062,8 @@ export function registerFormCommands(program) {
                 const colName = df?.columnName || df?.dataKey || '';
                 rfByName.set(f.fieldName, {
                     fieldId: f.fieldId,
-                    dataKey: colName,
+                    // dataKey 与 columnName 是两个东西，各自保留真值
+                    dataKey: df?.dataKey || colName,
                     columnName: colName,
                     formTableId: df?.formTableId || rfFormTableId,
                 });
@@ -1066,7 +1088,7 @@ export function registerFormCommands(program) {
                     title: rf.fieldName,
                     type: rf.componentKey === 'Text' ? 'Text' : rf.componentKey,
                     dataCount: 0,
-                    dataKey: myInfo.columnName,
+                    dataKey: myInfo.dataKey,
                     systemField: true,
                     readonlyTransLink: false,
                     columnTypeSwitch: false,
@@ -1111,7 +1133,7 @@ export function registerFormCommands(program) {
         // （batch/save 初建不带 isSingle 到 layout comp）。之前只对 defaultValue:true 的跑 → 没标默认值
         // 的 Employee/Department 漏 isSingle → 平台默认多选（bug：标记单选仍多选）。现对所有 Employee/Department
         // 跑设 isSingle；defaultExtend（默认当前用户/部门）仅 defaultValue:true 时加。
-        const personFields = fieldDefs.filter(f => f.componentKey === 'Employee' || f.componentKey === 'Department');
+        const personFields = fieldDefs.filter(f => f.componentKey === 'Employee' || f.componentKey === 'Department' || f.componentKey === 'SubCompany');
         if (personFields.length > 0) {
             const withDefault = personFields.filter(f => f.defaultValue === true);
             console.error(`  配置 ${personFields.length} 个 人员/部门 字段 isSingle${withDefault.length ? `（其中 ${withDefault.length} 个带默认当前用户/部门）` : ''}...`);
@@ -1140,10 +1162,12 @@ export function registerFormCommands(program) {
                 const colName = perDetail?.columnName || perDetail?.dataKey || '';
                 const colType = perDetail?.columnType || 'BIGINT';
                 const isDept = pf.componentKey === 'Department';
-                const typeLabel = isDept ? 'Department' : 'Employee';
-                const labelCN = isDept ? '部门' : '人员';
+                const isSubCompany = pf.componentKey === 'SubCompany';
+                const typeLabel = isSubCompany ? 'SubCompany' : isDept ? 'Department' : 'Employee';
+                const labelCN = isSubCompany ? '分部' : isDept ? '部门' : '人员';
                 const jsonObj = {
                     type: typeLabel,
+                    ...(isSubCompany ? { componentKey: 'Subcompany', defaultExtend: { type: 'custom', relation: 'current' } } : {}),
                     title: pf.fieldName,
                     isSingle: pf.multiple ? false : true,
                     allList: [],
@@ -1154,7 +1178,8 @@ export function registerFormCommands(program) {
                     pcDisplaySelectedCount: { type: 'default' },
                     mobileDisplaySelectedCount: { type: 'default' },
                     formTableId: perDetail?.formTableId || '',
-                    dataKey: colName,
+                    // dataKey 与 columnName 是两个东西，各自保留真值
+                    dataKey: perDetail?.dataKey || colName,
                     columnName: colName,
                     fieldId: perField.fieldId,
                     formId: resolvedFormId,
@@ -1190,7 +1215,7 @@ export function registerFormCommands(program) {
         const detailPersonDefs = fieldDefs
             .filter(f => f.componentKey === 'DetailTable' && Array.isArray(f.formFields))
             .flatMap(dt => (dt.formFields || [])
-            .filter(sf => sf.componentKey === 'Employee' || sf.componentKey === 'Department')
+            .filter(sf => sf.componentKey === 'Employee' || sf.componentKey === 'Department' || sf.componentKey === 'SubCompany')
             .map(sf => ({ ...sf, __detailTable: dt.fieldName })));
         if (detailPersonDefs.length > 0) {
             const withDefault = detailPersonDefs.filter(sf => sf.defaultValue === true);
@@ -1241,14 +1266,16 @@ export function registerFormCommands(program) {
                         continue;
                     }
                     const isDept = sfDef.componentKey === 'Department';
-                    const typeLabel = isDept ? 'Department' : 'Employee';
-                    const labelCN = isDept ? '部门' : '人员';
+                    const isSubCompany = sfDef.componentKey === 'SubCompany';
+                    const typeLabel = isSubCompany ? 'SubCompany' : isDept ? 'Department' : 'Employee';
+                    const labelCN = isSubCompany ? '分部' : isDept ? '部门' : '人员';
                     // spread cur 全量（保留子字段所有结构，防最小 jsonObj 覆盖破坏）+ 设 isSingle。
                     // 子字段单/多选由布局 comp 的 isSingle 控制（实测：getFields 的 multiSelect 是 dataset 元数据，
                     // 不控制渲染；布局 comp isSingle 才是渲染源）。saveFormFieldNew 会同步更新布局 comp 的 isSingle。
                     const jsonObj = {
                         ...cur,
                         type: typeLabel,
+                        ...(isSubCompany ? { componentKey: 'Subcompany', defaultExtend: { type: 'custom', relation: 'current' } } : {}),
                         title: sfDef.fieldName,
                         isSingle: sfDef.multiple ? false : true,
                         formTableId: subFormTableId || cur.formTableId || '',
@@ -1324,7 +1351,8 @@ export function registerFormCommands(program) {
                     ...(dtMinTargetId ? { min: { type: 'dateField', checkValue: String(dtMinTargetId) }, earlyDate: true } : {}),
                     ...(dtMaxTargetId ? { max: { type: 'dateField', checkValue: String(dtMaxTargetId) }, lateDate: true } : {}),
                     formTableId: dtDetail?.formTableId || '',
-                    dataKey: colName, columnName: colName,
+                    // dataKey 与 columnName 是两个东西，各自保留真值
+                    dataKey: dtDetail?.dataKey || colName, columnName: colName,
                     fieldId: dtField.fieldId, formId: resolvedFormId,
                     showOrder: '0.00', groupId: '-1',
                 };
@@ -1814,23 +1842,13 @@ export function registerFormCommands(program) {
             process.exit(1);
         const client = new ApiClient(auth);
         const baseUrl = auth.getBaseUrl();
-        // Parse config
-        let configStr = cmdOpts.config;
-        if (configStr.startsWith('@')) {
-            const { readFileSync, existsSync } = await import('fs');
-            const filePath = configStr.slice(1);
-            if (!existsSync(filePath)) {
-                console.error(`配置文件不存在: ${filePath}`);
-                process.exit(1);
-            }
-            configStr = readFileSync(filePath, 'utf-8');
-        }
+        // Parse config（@文件 / 内联 JSON 两种写法与 `wf-form linkage` 共用同一份实现）
         let config;
         try {
-            config = JSON.parse(configStr);
+            config = readLinkageConfig(cmdOpts.config);
         }
-        catch {
-            console.error('JSON 解析失败');
+        catch (e) {
+            console.error(e.message);
             process.exit(1);
         }
         // 校验联动 prop：必填且平台支持 hide/show/edit/readonly/required/hideLine（隐藏行，抓包实测平台枚举是 hideLine；
@@ -1859,59 +1877,21 @@ export function registerFormCommands(program) {
             console.error('无法获取 formId，请确认 appId 和 objId 正确');
             process.exit(1);
         }
-        // Build payload
-        const payload = {
-            fdEffect: {
-                formId,
-                effectModule: 'ebuilderform',
-                effectType: 'form',
-                effectName: '当前表单',
-                optionList: [{ effectValue: formId, effectName: '当前表单' }],
-            },
-            condition: {
-                targetId: formId,
-                targetName: formInfo?.formName || '表单',
-                targetModule: 'ebuilderform',
-                conditionType: 'FIELD',
-                conditionDetails: config.conditions.map((c) => ({
-                    targetId: c.fieldId,
-                    detailSymbol: c.operator || 'EQUAL',
-                    sourceType: 'CONSTANT',
-                    sourceContent: JSON.stringify({
-                        formField: { id: c.fieldId },
-                        ...(c.options ? { dataOptions: c.options } : { content: c.value }),
-                    }),
-                })),
-                formulaId: '',
-                formulaName: '',
-            },
-            linkageDetails: config.actions.map((a) => ({
-                formId,
-                id: '0',
-                linkageObj: 'field',
-                linkageProp: a.prop, // hide, show, edit, readonly, required, hideRow
-                linkageShowValue: a.fields.map((f) => ({
-                    dataKey: f.dataKey || '',
-                    groupName: '表单字段',
-                    address: f.isDetail ? '明细表' : '主表',
-                    addressType: f.isDetail ? 'detail' : 'form',
-                    groupId: 'formField',
-                    name: f.name,
-                    descType: f.fieldType || '',
-                    id: f.fieldId,
-                    content: f.name,
-                    desc: f.desc || '',
-                })),
-                detailOptions: [],
-            })),
-            module: 'ebuilderform',
-            formId,
-            refId: formId,
-            enableState: '1',
-            linkageName: name,
-            customParam: { appId, objId },
-        };
-        const data = await client.post(`${baseUrl}/api/ebuilder/form/form/setting/viewlinkage/add?apid=${appId}`, payload, { ebbusinessid: formId });
+        // 报文的拼法（尤其条件的算子与生效维度）收在 services/form-linkage-condition.ts ——
+        // 那里记着「为空要写 NULL 且不能带 sourceContent」「表单布局维度的值取 layoutId」这类
+        // 不看设计器实际报文就想不到的约束。
+        const formName = formInfo?.formName || formInfo?.objName || '表单';
+        const effect = await resolveEffect(client, baseUrl, formId, formName, config.effect);
+        const { payload, warnings } = buildLinkageAddPayload({
+            appId, objId, formId, formName, name,
+            conditions: config.conditions || [],
+            detailType: config.detailType,
+            actions: config.actions || [],
+            effect,
+        });
+        for (const w of warnings)
+            console.error(`  ⚠ ${w}`);
+        const data = await addLinkage(client, baseUrl, appId, formId, payload);
         if (data?.code === 200 && data?.status) {
             const linkageId = data?.data || '';
             console.log(opts.json
@@ -2122,15 +2102,20 @@ export function registerFormCommands(program) {
         .option('--precision <n>', '小数位数（Number/Money 类型，缺省 Number=0 整数、Money=2、百分比=1）')
         .option('--percent', 'Number 百分比显示（numberType=percentage）')
         .option('--default <value>', '默认值（Text / TextArea / Number / Money，如 工时单价默认 1000）')
-        .option('--data-key <key>', '数据库字段名（默认按字段名生成拼音；字母数字下划线，不以数字开头）')
+        .option('--data-key <key>', '字段编码 dataKey（默认按字段名生成拼音；字母数字下划线，不以数字开头）')
+        .option('--column-name <name>', '数据库列名 columnName。**与 dataKey 是两个东西，可分别指定**；'
+        + '不给时跟随 --data-key（两者都没给则同为拼音首字母）')
         .option('--desc <text>', '字段描述（设计器字段属性里的「描述」）')
         .option('--delimiter', 'Number/Money 千分位（Money 默认开，--no-delimiter 关闭）')
         .option('--capital', 'Number/Money 大写金额显示')
         .option('--sub-form-id <id>', '明细表 subFormId（在指定明细表里加字段）')
-        .option('--multiple', '多选（人员/部门/EBuilder/关联类字段/下拉Select；下拉多选=SelectMultiple 类型）')
+        .option('--multiple', '多选（人员/部门/分部/EBuilder/关联类字段/下拉Select；下拉多选=SelectMultiple 类型）')
         .option('--max-len <n>', '文本最大长度（Text 缺省 100、TextArea 缺省 4000）')
         .option('--single-row', '独占一行显示（布局 singleRow:true，其余字段仍两列）')
         .option('--option-template <idOrName>', 'Select 绑定选项预设模板（ID 或名称；选项不内联，options=[]）')
+        .option('--required', '设为必填（同时写字段记录与布局组件，两处都写才完整）')
+        .option('--reinit', '整表重建布局（initLayout）而不是增量插入：会换样式模板、重排所有已有位置、'
+        + '并重建标签组件。只在自己建的表上用；不是自己建的表用默认的增量插入')
         .action(async (objId, appId, fieldName, fieldType, title, cmdOptsRaw) => {
         // fieldType 大小写归一（与建表一致）：用户常传 "Textarea"/"Ebuilder"，不归一则 type 存小写
         // "Textarea"（FLOW 渲染异常）、TextArea 分支漏跑。
@@ -2156,25 +2141,33 @@ export function registerFormCommands(program) {
         // DateRange 需要 3 个字段 ID（主 + 开始 + 结束），普通字段 1 个，富组件按 richIdUnits
         const isDateRange = fieldType === 'DateRange' || fieldType === 'DateInterval';
         const idCount = isDateRange ? 3 : richIdUnits(fieldType, {});
-        const genData = await client.post(`${baseUrl}/api/form/local/generatorIds?size=${idCount}&apid=${appId}`, {});
+        // 多要一个：布局里字段占**两个** comp，值组件用 fieldId，标签组件的 `config.fieldId`
+        // 是布局自己另生成的一个雪花 id（与字段定义无关，只需在布局内唯一）。
+        const genData = await client.post(`${baseUrl}/api/form/local/generatorIds?size=${idCount + 1}&apid=${appId}`, {});
         const genIds = genData?.data?.generatorIds || [];
         const fieldId = genIds[0] || String(Date.now());
         const startId = genIds[1] || '';
         const endId = genIds[2] || '';
+        const labelFieldId = genIds[idCount] || String(Date.now());
         const cmdOpts = cmdOptsRaw || {};
         const sformId = cmdOpts.sformId || '';
         const dataTitle = cmdOpts.dataTitle || '';
         const formName = cmdOpts.formName || '';
-        // Generate column name: pinyin initials + timestamp suffix
-        const colName = toColumnName(fieldName);
+        // dataKey（字段编码）与 columnName（数据库列名）是两个东西，默认同值。
+        // 只给 --data-key 时列名跟随（历史行为）；给了 --column-name 才分开。
+        const keys = resolveFieldKeys(fieldName, {
+            dataKey: cmdOpts.dataKey,
+            columnName: cmdOpts.columnName,
+        });
+        const colName = keys.dataKey; // 布局 comp 等仍按字段编码引用
         // Build jsonObj based on field type
         const jsonObj = {
             type: fieldType,
             title: title || fieldName,
             formTableId, fieldId, groupId: '-1', formId,
             showOrder: '0.00',
-            dataKey: colName,
-            columnName: colName,
+            dataKey: keys.dataKey,
+            columnName: keys.columnName,
         };
         // 明细表字段：--sub-form-id 时 jsonObj 带 subFormId —— **字段落点由它决定**。
         // 必须用 resolveDetailTable 而不是直接查 getEbField：后者列不出空明细表，
@@ -2208,7 +2201,7 @@ export function registerFormCommands(program) {
                         multiple: cmdOpts.multiple,
                         browserType: cmdOpts.browserType,
                         browserFormSource: cmdOpts.browserFormSource,
-                    }, fieldId, formId, formTableId, dataKey: colName, columnName: colName,
+                    }, fieldId, formId, formTableId, dataKey: keys.dataKey, columnName: keys.columnName,
                     showOrder: '0.00', extraIds,
                 });
                 Object.assign(jsonObj, extraCfg);
@@ -2305,6 +2298,19 @@ export function registerFormCommands(program) {
             delete jsonObj.scan;
             delete jsonObj.readonlyTransLink;
         }
+        else if (fieldType === 'SubCompany') {
+            Object.assign(jsonObj, {
+                componentKey: 'Subcompany', isSingle: cmdOpts.multiple ? false : true,
+                displayType: 'space', defaultExtend: { type: 'custom', relation: 'current' },
+                viewDataDetail: true, showDimension: true,
+                pcDisplaySelectedCount: { type: 'default' },
+                mobileDisplaySelectedCount: { type: 'default' },
+            });
+            delete jsonObj.maxLen;
+            delete jsonObj.unique;
+            delete jsonObj.scan;
+            delete jsonObj.readonlyTransLink;
+        }
         else if (fieldType === 'City') {
             // 城市/地区选择（对齐浏览器 payload：region 模式 + 系统级联层级 + 字母索引）
             Object.assign(jsonObj, {
@@ -2522,6 +2528,7 @@ export function registerFormCommands(program) {
         const patch = applyFieldPatches(jsonObj, {
             defaultValue: cmdOpts.default,
             dataKey: cmdOpts.dataKey,
+            columnName: cmdOpts.columnName,
             desc: cmdOpts.desc,
         });
         if (patch.errors.length > 0) {
@@ -2532,6 +2539,23 @@ export function registerFormCommands(program) {
         }
         for (const w of patch.warnings)
             console.error(`  ⚠ ${w}`);
+        // 必填**只存在于布局 comp 里**（`config.required`）—— 字段记录没有这个键。所以下面那句
+        // 只是形式上的补齐，真正生效的是布局落点：增量插入的 `overrides.required`，
+        // 或 --reinit 时 configs 里那条 newFieldConfig。两处都写全了用户才看不出差别。
+        if (cmdOpts.required === true)
+            jsonObj.required = true;
+        // 字段标题在平台里存的是**多语言标签 id**（字段记录的 `labelObj.title`），不是文本本身。
+        // 不建标签也能显示（设计器退回读 `title`），但只要有谁引用了标签而这个标签不存在，
+        // 标题就会**静默变空** —— 平台既不校验也不报错。所以顺手建一个真的，不留自造 id 的口子。
+        // 建失败只告警：字段本身才是主操作，不该被标签服务拖垮。
+        try {
+            const titleLabelId = await createMultilangLabel(client, baseUrl, title || fieldName, 'ebuilderform');
+            jsonObj.labelObj = { ...(jsonObj.labelObj || {}), title: titleLabelId };
+            jsonObj.titleLabelId = titleLabelId;
+        }
+        catch (e) {
+            console.error(`  ⚠ 标题的多语言标签未建立（字段不受影响，设计器会退回用 title 显示）: ${e.message}`);
+        }
         const payload = {
             formId, module: 'ebuilderform',
             customParam: { appId, objId },
@@ -2553,83 +2577,116 @@ export function registerFormCommands(program) {
                     console.error(`  关联显示列设置失败: ${e.message}`);
                 }
             }
-            // Always relayout so new field appears in the form
-            console.error('  重新生成布局...');
-            try {
-                const preLayout = await client.post(`${baseUrl}/api/ebuilder/form/builder/getFormLayout`, {
-                    formId, module: 'ebuilderform', customParam: {}, formTableIdList: [],
-                    designerParam: { onlyLayout: false, convert: false }, form: { id: formId },
-                }, { ebbusinessid: formId });
-                const layoutId = preLayout?.data?.formLayout?.id || '';
-                const layoutMultiId = preLayout?.data?.formLayout?.multipleLayoutId || '';
-                const layoutName = preLayout?.data?.formLayoutMultiple?.name || preLayout?.data?.formLayout?.name || '';
-                const layoutType = preLayout?.data?.formLayoutMultiple?.layoutType || 'EXCEL';
-                const configRes = await client.post(`${baseUrl}/api/ebuilder/form/form/view/relate/getConfig`, {
-                    formId, module: 'ebuilderform', apiModule: 'ebuilder/form',
-                    layoutId, customParam: { terminal: '', objId: formId },
-                    initMode: 5, groupFieldIds: [], designerParam: { sourceModule: 'ebuilderform' },
-                }, { ebbusinessid: formId });
-                const rawConfigs = configRes?.data?.configs || [];
-                // saveFormFieldNew fields may not appear in getConfig — manually append
-                const CK = {
-                    Text: 'Text', Textarea: 'TextArea', Number: 'NumberComponent', Money: 'Money',
-                    Date: 'DateComponent', DateTime: 'DateComponent', Select: 'Select', CheckBox: 'CheckBox', RadioBox: 'RadioBox',
-                    Employee: 'Employee', Department: 'Department', EBuilder: 'Ebuilder',
-                    Phone: 'Phone', Email: 'Email', Mobile: 'Mobile', Location: 'Location', Switch: 'Switch', IDCard: 'IDCard',
-                };
-                const newFieldConfig = {
-                    id: fieldId, name: title || fieldName,
-                    componentKey: jsonObj.componentKey || CK[fieldType] || fieldType,
-                    display: true, show: true, readOnly: false,
-                    required: false, disableEdit: false, singleRow: cmdOpts.singleRow === true,
-                    isDelete: false, type: fieldType, dataKey: colName,
-                };
-                const existingIds = new Set(rawConfigs.map((c) => String(c.id)));
-                if (cmdOpts.subFormId) {
-                    // 明细字段：加进对应 DetailTable 的 children（明细字段嵌在 DetailTable 里，不是顶层）
-                    const dtComp = rawConfigs.find((c) => String(c.id) === String(cmdOpts.subFormId) && c.type === 'DetailTable');
-                    if (dtComp) {
-                        const childIds = new Set((dtComp.children || []).map((x) => String(x.id)));
-                        if (!childIds.has(fieldId)) {
-                            dtComp.children = dtComp.children || [];
-                            dtComp.children.push({ ...newFieldConfig, showOrder: dtComp.children.length });
+            // 布局落点：**默认走增量插入** —— 读快照 → 塞一对 comp → saveFormAndLayout，全程不碰
+            // initLayout。initLayout 是整表重建（换样式模板、重排所有位置、把标签组件全换成新 id），
+            // 对不是我们建的表是破坏性的；详见 services/form-layout-insert.ts。
+            //
+            // 增量失败**不自动回落**到 initLayout —— 那等于把「悄悄毁掉别人的布局」变成默认行为。
+            // 把错误讲清楚，让用户自己决定要不要 --reinit。
+            if (!cmdOpts.reinit) {
+                try {
+                    const fieldDef = (await fetchFieldPageRecords(client, baseUrl, appId, formId))
+                        .find((f) => String(f.fieldId) === String(fieldId));
+                    if (!fieldDef)
+                        throw new Error('字段已建立，但读回字段定义失败');
+                    const placed = await insertFieldIntoLayout(client, baseUrl, formId, {
+                        fieldId, labelFieldId, title: title || fieldName, fieldDef,
+                        subFormId: cmdOpts.subFormId,
+                        // 对齐 initLayout 那条路对新字段的默认：可编辑、显示。
+                        // 不写的话会**继承模板字段的状态** —— 模板若恰好是只读的，新字段一出生就只读。
+                        overrides: {
+                            readOnly: false, disableEdit: false, display: true,
+                            required: cmdOpts.required === true,
+                            ...(cmdOpts.singleRow === true ? { singleRow: true } : {}),
+                        },
+                    });
+                    console.error(`  布局已更新: excel[${placed.row},${placed.col}]（增量插入，未重建）`);
+                }
+                catch (e) {
+                    console.error(`  布局更新失败: ${e.message}`);
+                    console.error('  字段本身已建立，但没进布局。按上面那条修好重跑本命令即可（重跑不会重复建字段）。');
+                }
+            }
+            else {
+                console.error('  重新生成布局（整表重建）...');
+                try {
+                    const preLayout = await client.post(`${baseUrl}/api/ebuilder/form/builder/getFormLayout`, {
+                        formId, module: 'ebuilderform', customParam: {}, formTableIdList: [],
+                        designerParam: { onlyLayout: false, convert: false }, form: { id: formId },
+                    }, { ebbusinessid: formId });
+                    const layoutId = preLayout?.data?.formLayout?.id || '';
+                    const layoutMultiId = preLayout?.data?.formLayout?.multipleLayoutId || '';
+                    const layoutName = preLayout?.data?.formLayoutMultiple?.name || preLayout?.data?.formLayout?.name || '';
+                    const layoutType = preLayout?.data?.formLayoutMultiple?.layoutType || 'EXCEL';
+                    const configRes = await client.post(`${baseUrl}/api/ebuilder/form/form/view/relate/getConfig`, {
+                        formId, module: 'ebuilderform', apiModule: 'ebuilder/form',
+                        layoutId, customParam: { terminal: '', objId: formId },
+                        initMode: 5, groupFieldIds: [], designerParam: { sourceModule: 'ebuilderform' },
+                    }, { ebbusinessid: formId });
+                    const rawConfigs = configRes?.data?.configs || [];
+                    // saveFormFieldNew fields may not appear in getConfig — manually append
+                    const CK = {
+                        Text: 'Text', Textarea: 'TextArea', Number: 'NumberComponent', Money: 'Money',
+                        Date: 'DateComponent', DateTime: 'DateComponent', Select: 'Select', CheckBox: 'CheckBox', RadioBox: 'RadioBox',
+                        Employee: 'Employee', Department: 'Department', SubCompany: 'Subcompany', EBuilder: 'Ebuilder',
+                        Phone: 'Phone', Email: 'Email', Mobile: 'Mobile', Location: 'Location', Switch: 'Switch', IDCard: 'IDCard',
+                    };
+                    const newFieldConfig = {
+                        id: fieldId, name: title || fieldName,
+                        componentKey: jsonObj.componentKey || CK[fieldType] || fieldType,
+                        display: true, show: true, readOnly: false,
+                        required: cmdOpts.required === true, disableEdit: false, singleRow: cmdOpts.singleRow === true,
+                        isDelete: false, type: fieldType, dataKey: colName,
+                    };
+                    const existingIds = new Set(rawConfigs.map((c) => String(c.id)));
+                    if (cmdOpts.subFormId) {
+                        // 明细字段：加进对应 DetailTable 的 children（明细字段嵌在 DetailTable 里，不是顶层）
+                        const dtComp = rawConfigs.find((c) => String(c.id) === String(cmdOpts.subFormId) && c.type === 'DetailTable');
+                        if (dtComp) {
+                            const childIds = new Set((dtComp.children || []).map((x) => String(x.id)));
+                            if (!childIds.has(fieldId)) {
+                                dtComp.children = dtComp.children || [];
+                                dtComp.children.push({ ...newFieldConfig, showOrder: dtComp.children.length });
+                            }
+                        }
+                        else {
+                            console.error(`  ⚠ 布局里未找到明细表 subFormId=${cmdOpts.subFormId}，字段已加但未进布局`);
                         }
                     }
-                    else {
-                        console.error(`  ⚠ 布局里未找到明细表 subFormId=${cmdOpts.subFormId}，字段已加但未进布局`);
+                    else if (!existingIds.has(fieldId)) {
+                        rawConfigs.push({ ...newFieldConfig, showOrder: rawConfigs.length });
                     }
+                    const configs = rawConfigs.map((c) => ({
+                        ...c,
+                        display: c.system ? c.display : true,
+                        show: c.system ? c.show : true,
+                        // 新加字段 saveFormFieldNew 后 getConfig 返回 readOnly:true（未铺列默认），
+                        // existingIds 命中时 newFieldConfig(readOnly:false) 会被丢弃，这里强制覆盖回 false，
+                        // 否则任何 add-field 新字段（Text/Employee/EBuilder 都中招）默认不可编辑。
+                        ...(String(c.id) === String(fieldId)
+                            ? { readOnly: false, required: cmdOpts.required === true }
+                            : {}),
+                    }));
+                    // DetailTable 置末（对齐 form create / form layout init）：getConfig 可能把明细表夹中间，
+                    // 重排避免明细跑到普通字段上面。
+                    const orderedConfigs = [
+                        ...configs.filter((c) => c.type !== 'DetailTable' && c.componentKey !== 'DataTable'),
+                        ...configs.filter((c) => c.type === 'DetailTable' || c.componentKey === 'DataTable'),
+                    ];
+                    await client.post(`${baseUrl}/api/ebuilder/form/form/view/relate/initLayout?apid=${appId}`, {
+                        formId, module: 'ebuilderform', apiModule: 'ebuilder/form',
+                        layoutId, generateCollapse: true,
+                        styleTemplateId: layoutType === 'FLOW' ? '820000000000000001' : '700000000000000008', styleTemplateType: 1,
+                        configs: orderedConfigs, addLayout: false, ecodeType: ['js', 'css'],
+                        initMode: '1', customParam: { terminal: '', objId: formId },
+                        formLayoutMultiple: { isSys: true, id: layoutMultiId, name: layoutName, terminalType: 'PC', layoutType },
+                        designerParam: { onlyLayout: false },
+                    }, { ebbusinessid: formId });
+                    console.error('  布局已更新');
+                }
+                catch (e) {
+                    console.error(`  布局更新失败: ${e.message}`);
                 }
-                else if (!existingIds.has(fieldId)) {
-                    rawConfigs.push({ ...newFieldConfig, showOrder: rawConfigs.length });
-                }
-                const configs = rawConfigs.map((c) => ({
-                    ...c,
-                    display: c.system ? c.display : true,
-                    show: c.system ? c.show : true,
-                    // 新加字段 saveFormFieldNew 后 getConfig 返回 readOnly:true（未铺列默认），
-                    // existingIds 命中时 newFieldConfig(readOnly:false) 会被丢弃，这里强制覆盖回 false，
-                    // 否则任何 add-field 新字段（Text/Employee/EBuilder 都中招）默认不可编辑。
-                    ...(String(c.id) === String(fieldId) ? { readOnly: false } : {}),
-                }));
-                // DetailTable 置末（对齐 form create / form layout init）：getConfig 可能把明细表夹中间，
-                // 重排避免明细跑到普通字段上面。
-                const orderedConfigs = [
-                    ...configs.filter((c) => c.type !== 'DetailTable' && c.componentKey !== 'DataTable'),
-                    ...configs.filter((c) => c.type === 'DetailTable' || c.componentKey === 'DataTable'),
-                ];
-                await client.post(`${baseUrl}/api/ebuilder/form/form/view/relate/initLayout?apid=${appId}`, {
-                    formId, module: 'ebuilderform', apiModule: 'ebuilder/form',
-                    layoutId, generateCollapse: true,
-                    styleTemplateId: layoutType === 'FLOW' ? '820000000000000001' : '700000000000000008', styleTemplateType: 1,
-                    configs: orderedConfigs, addLayout: false, ecodeType: ['js', 'css'],
-                    initMode: '1', customParam: { terminal: '', objId: formId },
-                    formLayoutMultiple: { isSys: true, id: layoutMultiId, name: layoutName, terminalType: 'PC', layoutType },
-                    designerParam: { onlyLayout: false },
-                }, { ebbusinessid: formId });
-                console.error('  布局已更新');
-            }
-            catch (e) {
-                console.error(`  布局更新失败: ${e.message}`);
             }
         }
         else {
@@ -2658,7 +2715,9 @@ export function registerFormCommands(program) {
         .option('--max-len <n>', '最大长度（正整数）。日期/时间/省市区/身份证/电子发票/下拉多选这几类没有该属性')
         .option('--default <value>', '默认值（Text / TextArea / Number / Money）')
         .option('--clear-default', '清空默认值')
-        .option('--data-key <key>', '数据库字段名（同时改 dataKey 与 columnName；字段已有数据时平台会拒绝）')
+        .option('--data-key <key>', '字段编码 dataKey（字母数字下划线，不以数字开头；字段已有数据时平台会拒绝）')
+        .option('--column-name <name>', '数据库列名 columnName。**与 dataKey 是两个东西，可分别指定**；'
+        + '不给时跟随 --data-key。字段已有数据时平台会拒绝改列名')
         .option('--desc <text>', '字段描述（设计器字段属性里的「描述」）')
         .action(async (objId, appId, fieldId, editOpts) => {
         const opts = program.opts();
@@ -2842,7 +2901,8 @@ export function registerFormCommands(program) {
                 }
             }
         }
-        // Apply required
+        // `required` 不是字段记录的键（整张表的字段记录里都没有），写到 jsonObj 只是**保持与
+        // 既有代码一致的形式**，真正生效的是保存成功之后那段布局 comp 补丁 —— 见下面 `patchFieldLayout`。
         if (editOpts.required) {
             jsonObj.required = true;
         }
@@ -2990,6 +3050,7 @@ export function registerFormCommands(program) {
             defaultValue: editOpts.default,
             clearDefault: editOpts.clearDefault,
             dataKey: editOpts.dataKey,
+            columnName: editOpts.columnName,
             desc: editOpts.desc,
         });
         if (patch.errors.length > 0) {
@@ -3015,10 +3076,10 @@ export function registerFormCommands(program) {
             if (editOpts.type) {
                 changes.push(typeChangeApplied ? `type=${editOpts.type}` : `type=${editOpts.type}(未变化)`);
             }
-            if (editOpts.required)
-                changes.push('required');
-            if (editOpts.noRequired)
-                changes.push('!required');
+            // commander 把 `--no-required` 映射成 `required: false`（不是 `noRequired`），
+            // 所以只判 noRequired 的话反向操作会漏报成「no changes」—— 改了却说没改。
+            if (editOpts.required !== undefined)
+                changes.push(editOpts.required ? 'required' : '!required');
             if (editOpts.sformId)
                 changes.push(`EBuilder→${editOpts.sformId}`);
             if (editOpts.dataTitle !== undefined)
@@ -3028,6 +3089,19 @@ export function registerFormCommands(program) {
             if (editOpts.multiple !== undefined)
                 changes.push(editOpts.multiple ? 'multiple' : '!multiple');
             changes.push(...patch.applied);
+            // 必填**只存在于布局 comp 里**：字段记录没有 `required` 这个键（整张表的字段记录里都没有），
+            // 所以上面写进 jsonObj 的那一下落不了库。只写字段记录 = 接口回 200、命令报成功、表单上行为
+            // 一点没变。真正生效的是布局 comp 的 `config.required`，这里补上。
+            if (editOpts.required !== undefined) {
+                try {
+                    const { updated } = await patchFieldLayout(client, baseUrl, formId, fieldId, { required: editOpts.required === true });
+                    if (!updated)
+                        console.error('  警告: 布局里没找到该字段的组件，必填未生效');
+                }
+                catch (e) {
+                    console.error(`  警告: 布局里的必填未更新（字段本身已改好）: ${e.message}`);
+                }
+            }
             // EBuilder 字段的浏览显示列：add-field 建出来的会自动配，edit-field 改出来的此前漏了这一步
             // —— 字段能建出来，但浏览弹窗回落平台默认列，会把目标表的系统字段也列出来。
             // ensureDisplayColumns 只在「没配过」或「旧列对不上当前目标表」时才写，不会冲掉手工配好的列。