weaver-e10-builder 1.2.5 → 1.5.2

package/dist/commands/form.js

@@ -1,14 +1,21 @@
 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 { FormSubDetailService, resolveDetailTable } from '../services/form-sub-detail.js';
+import { toColumnName, toTableName, resolveFieldKeys } from '../utils/column-name.js';
+import { createCustomPhysicalForm, addInitialFieldsToCustomPhysicalForm, placeholderFromFormat, reapplyGroupLayout, queryFormStorageSetting } from '../services/form-create.js';
+import { FormSubDetailService } 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';
+// 字段 jsonObj 的构造器（含 SYSTEM_FIELD_IDS / defaultEBuilderDataTitle）——
+// 原先内联在下面 add-field 的 action 里，为了给「按物理表加字段」第二个入口复用而抽出去。
+// 本文件仍有别处用这两个符号，所以在这里回导。
+import { SYSTEM_FIELD_IDS, defaultEBuilderDataTitle, buildFieldJsonObject } from '../services/form-field-build.js';
+import { listFormTables, readFieldRecords, mapFieldsToTables } from '../services/form-physical-table.js';
 import { buildFormulaParameters, defaultReturnType } from '../services/formula-detail.js';
 import { registerOptionTemplateCommand } from './form-option-template.js';
 /**
@@ -20,7 +27,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',
@@ -84,12 +91,6 @@ function assertFieldOptions(fieldName, options) {
         }
     });
 }
-const SYSTEM_FIELD_IDS = new Set([
-    'name', 'creator', 'create_time', 'update_time', 'id',
-    'updater', 'data_status', 'flow_status', 'current_step',
-    'batchpubtags', 'batchmytags', 'operate', 'data_read_status',
-    'flow_system_number',
-]);
 /** 系统字段的中文名 → 物理字段 id（form read 实测的平台自带字段）。建表时字段与此完全重名 → 跳过新建、直接复用系统字段。 */
 const SYSTEM_FIELD_NAME_TO_ID = {
     '标题': 'name',
@@ -114,14 +115,6 @@ const SYSTEM_FIELD_CFG_ID = {
     '最后更新人': 'updater',
     '数据状态': 'dataStatus',
 };
-// EBuilder dataTitle（关联字段标题栏）默认解析：优先字段名含「名称」的业务字段，无则第一个业务字段。
-// 需求：默认选带"名称"二字的字段（如 客户名称/类型名称），没有就默认选第一个。
-function defaultEBuilderDataTitle(fields) {
-    const isBiz = (id) => /^\d{15,}$/.test(id) && !SYSTEM_FIELD_IDS.has(id);
-    const biz = (fields || []).filter((f) => isBiz(String(f.fieldId ?? '')));
-    const byName = biz.find((f) => String(f.fieldName ?? f.title ?? '').includes('名称'));
-    return byName?.fieldId || biz[0]?.fieldId || 'name';
-}
 /**
  * 只读地看一眼 `getFields` 眼里这个字段长什么样 —— **仅用于把错误信息说清楚，绝不作为写回基底**。
  *
@@ -281,6 +274,22 @@ export function registerFormCommands(program) {
             }
             catch { /* 布局属性补读失败不影响主流程 */ }
         }
+        // 所属物理表（设计器「字段管理」的主表/其他）—— getFields 不带这个信息，
+        // 得用 getFormAGroupList（表清单）+ getFormFieldPage（字段记录上的 formTableId）拼出来。
+        if (formId && cmdOpts?.appId) {
+            try {
+                const scope = { formId, appId: cmdOpts.appId, objId };
+                const tables = await listFormTables(client, baseUrl, cmdOpts.appId, scope);
+                const records = await readFieldRecords(client, baseUrl, cmdOpts.appId, scope);
+                const byField = mapFieldsToTables(records, tables);
+                for (const f of allFields) {
+                    const t = byField[String(f.fieldId)];
+                    if (t)
+                        f.formTable = { id: t.formTableId, name: t.name, type: t.tableType, tableName: t.tableName };
+                }
+            }
+            catch { /* 物理表归属读不到不影响主流程 */ }
+        }
         if (cmdOpts?.out) {
             // Write JSON to file with UTF-8 encoding, bypassing terminal encoding
             writeFileSync(cmdOpts.out, JSON.stringify(allFields, null, 2), 'utf-8');
@@ -291,10 +300,13 @@ export function registerFormCommands(program) {
         }
         else {
             console.log(`表单 ${objId} 共 ${fields.length} 个主表字段${subFields.length ? ` + ${subFields.length} 个明细表字段` : ''}:`);
+            // 主表那排 chip 上写的是表单名，逐行重复没信息量，显示成「主表」；附属物理表用它的真名
+            const tableLabel = (f) => (f.formTable ? (f.formTable.type === 'MAIN' ? '主表' : f.formTable.name) : '');
             for (const f of fields) {
                 if (SYSTEM_FIELD_IDS.has(f.fieldId))
                     continue;
-                console.log(`  [${f.fieldKey || f.fieldType}] ${f.fieldName}  (fieldId: ${f.fieldId || f.id})`);
+                const t = tableLabel(f);
+                console.log(`  [${f.fieldKey || f.fieldType}] ${f.fieldName}  (fieldId: ${f.fieldId || f.id})${t ? `  · 物理表: ${t}` : ''}`);
                 if (f.options)
                     console.log(`    选项: ${JSON.stringify(f.options)}`);
                 if (f.optionTemplate)
@@ -354,6 +366,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 +574,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 +608,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 +628,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 +652,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 +798,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 +835,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 +1071,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 +1097,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 +1142,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 +1171,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 +1187,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 +1224,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 +1275,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 +1360,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 +1851,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 +1886,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 +2111,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,382 +2150,35 @@ 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);
-        // 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,
-        };
-        // 明细表字段：--sub-form-id 时 jsonObj 带 subFormId —— **字段落点由它决定**。
-        // 必须用 resolveDetailTable 而不是直接查 getEbField：后者列不出空明细表，
-        // 用户把明细字段删光后就再也加不回去（详见 services/form-sub-detail.ts）。
-        if (cmdOpts.subFormId) {
-            const sub = await resolveDetailTable(client, baseUrl, appId, objId, formId, cmdOpts.subFormId);
-            if (!sub) {
-                console.error(`未找到明细表 subFormId=${cmdOpts.subFormId}（getEbField 与 querySubForms 均无此表，请确认 id）`);
-                process.exit(1);
-            }
-            Object.assign(jsonObj, { subFormId: cmdOpts.subFormId });
-            // 空表拿不到物理表 id，保持主表的值不动：实测带主表 formTableId 一样落进明细表。
-            if (sub.formTableId)
-                jsonObj.formTableId = sub.formTableId;
-        }
-        // 富组件：映射到平台真实 type/componentKey + 附加配置（对齐 batch/save/formField 抓包）。
-        // 之前 jsonObj 只有 type 没有 componentKey → 平台 FormFieldDto.getComponentKey() 为 null → NPE。
-        const rich = getRichType(fieldType);
-        if (rich) {
-            jsonObj.type = rich.platformType;
-            jsonObj.componentKey = rich.platformComponentKey;
-            if (rich.build) {
-                const extra = richIdUnits(fieldType, {}) - 1;
-                let extraIds = [];
-                if (extra > 0) {
-                    const extraRes = await client.post(`${baseUrl}/api/form/local/generatorIds?size=${extra}&apid=${appId}`, {});
-                    extraIds = (extraRes?.data?.generatorIds || []).map(String);
-                }
-                const extraCfg = await rich.build({
-                    def: {
-                        multiple: cmdOpts.multiple,
-                        browserType: cmdOpts.browserType,
-                        browserFormSource: cmdOpts.browserFormSource,
-                    }, fieldId, formId, formTableId, dataKey: colName, columnName: colName,
-                    showOrder: '0.00', extraIds,
-                });
-                Object.assign(jsonObj, extraCfg);
-            }
-        }
-        // 非富组件也补 componentKey（平台要求，否则 FormFieldDto.getComponentKey() 为 null → NPE）。
-        // 富组件已在上方设置 platformComponentKey；此处 fallback 到类型名（平台对常见类型有归一容错）。
-        if (!jsonObj.componentKey)
-            jsonObj.componentKey = fieldType;
-        // Number/Money decimal precision: --precision 指定，缺省 Number=0 整数、Money=2、百分比=1
-        // 百分比：--percent → numberType=percentage；默认值：--default → content+isDefault
-        // 实测：设默认值必须连 isDelimiter/stepMode/step/isCapital 一起，否则平台丢默认（只设 content+isDefault 不落库）
-        if (fieldType === 'Number' || fieldType === 'Money') {
-            const defaultPrec = fieldType === 'Money' ? '2' : '0';
-            const isPercent = fieldType === 'Number' && cmdOpts.percent === true;
-            // 注意：commander 把 --default 映射到 opts.default（非 defaultValue）
-            const hasDefault = cmdOpts.default !== undefined && cmdOpts.default !== null && cmdOpts.default !== '';
-            // 千分位：Money 默认开（--no-delimiter 关闭）、Number 默认关（--delimiter 开启）
-            const isDelim = fieldType === 'Money' ? cmdOpts.delimiter !== false : cmdOpts.delimiter === true;
-            const isCap = cmdOpts.capital === true;
-            const patch = {
-                pointSize: cmdOpts.precision !== undefined ? cmdOpts.precision : (isPercent ? '1' : defaultPrec),
-                isDefault: hasDefault,
-                isDelimiter: isDelim,
-                isCapital: isCap,
-                capitalFormat: 'onlyUpperCase',
-                capitalPosition: 'outside',
-                capitalSetting: 'system',
-                capitalPrecision: 'yuan',
-                isExchangeRates: false,
-            };
-            if (fieldType === 'Number')
-                patch.numberType = isPercent ? 'percentage' : 'number';
-            // content 始终带（无默认值时空串）——浏览器抓包 Number 字段 getFormField 恒有 content:""，
-            // 缺 content 在 FLOW 渲染异常（与多行文本同因）。
-            if (fieldType === 'Number')
-                patch.content = hasDefault ? String(cmdOpts.default) : '';
-            if (hasDefault) {
-                patch.stepMode = false;
-                patch.step = 1;
-            }
-            Object.assign(jsonObj, patch);
-        }
-        if (fieldType === 'TextArea') {
-            // 多行文本：对齐浏览器抓包——content 恒 ""（无默认值时空串）、maxLen=4000。
-            // 缺 content 在 FLOW 渲染异常；maxLen 不发则前端最大长度回显异常。
-            Object.assign(jsonObj, { content: '', maxLen: 4000 });
-        }
-        if (fieldType === 'EInvoice') {
-            Object.assign(jsonObj, {
-                isSingle: false,
-                invoiceType: 1,
-            });
-            delete jsonObj.maxLen;
-            delete jsonObj.unique;
-            delete jsonObj.scan;
-            delete jsonObj.readonlyTransLink;
-        }
-        else if (fieldType === 'Date' || fieldType === 'DateTime') {
-            // 日期：默认精度 年月日（yyyy-MM-dd，对齐浏览器抓包）；DateTime：默认带时:分（yyyy-MM-dd HH:mm 不含秒）。
-            // 默认值不填（isDefault:false）；--format 覆盖精度。
-            const isDt = fieldType === 'DateTime';
-            const fmt = cmdOpts.format || (isDt ? 'yyyy-MM-dd HH:mm' : 'yyyy-MM-dd');
-            Object.assign(jsonObj, {
-                type: 'Date',
-                format: fmt,
-                placeholder: placeholderFromFormat(fmt),
-                timePanelStyle: { type: 'system' },
-                isDefault: false,
-            });
-            // 日期限制：--min-field 最早不得早于 / --max-field 最晚不得晚于另一字段（对齐抓包 min.dateField）。
-            // 目标字段 fieldId 从 getFields mainFields 按字段名解析。
-            if (cmdOpts.minField || cmdOpts.maxField) {
-                try {
-                    const tfd = await client.post(`${baseUrl}/api/ebuilder/form/dataset/v1/getFields`, {
-                        objId, userid: auth.userId, tenantKey: auth.tenantKey,
-                    });
-                    const tfields = tfd?.data?.mainFields || [];
-                    const minTarget = cmdOpts.minField ? tfields.find((f) => f.fieldName === cmdOpts.minField)?.fieldId : '';
-                    const maxTarget = cmdOpts.maxField ? tfields.find((f) => f.fieldName === cmdOpts.maxField)?.fieldId : '';
-                    if (minTarget) {
-                        jsonObj.min = { type: 'dateField', checkValue: String(minTarget) };
-                        jsonObj.earlyDate = true;
-                    }
-                    if (maxTarget) {
-                        jsonObj.max = { type: 'dateField', checkValue: String(maxTarget) };
-                        jsonObj.lateDate = true;
-                    }
-                }
-                catch { /* 解析失败则不加限制 */ }
-            }
-            delete jsonObj.maxLen;
-            delete jsonObj.unique;
-            delete jsonObj.scan;
-            delete jsonObj.readonlyTransLink;
-        }
-        else if (fieldType === 'City') {
-            // 城市/地区选择（对齐浏览器 payload：region 模式 + 系统级联层级 + 字母索引）
-            Object.assign(jsonObj, {
-                isSingle: false,
-                levelSetting: 'system',
-                isDefault: false,
-                useLetterIndex: true,
-                mode: 'region',
-            });
-            delete jsonObj.maxLen;
-            delete jsonObj.unique;
-            delete jsonObj.scan;
-            delete jsonObj.readonlyTransLink;
-        }
-        else if (fieldType === 'EBuilder') {
-            if (!sformId) {
-                console.error('EBuilder 类型必须指定 --sform-id（目标表单 objId）');
-                process.exit(1);
-            }
-            // Resolve formName from target form if not provided
-            let resolvedFormName = formName;
-            if (!resolvedFormName) {
-                try {
-                    const tlist = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-                    const tf = (tlist?.data || []).find((f) => String(f.id) === String(sformId));
-                    resolvedFormName = tf?.formName || tf?.name || sformId;
-                }
-                catch {
-                    resolvedFormName = sformId;
-                }
-            }
-            // Resolve dataTitle：纯数字 fieldId 直接用；'name'/字段名 → 查目标表字段。
-            // 未传 --data-title 时按 name 处理：默认优先字段名含「名称」的业务字段（如 客户名称/类型名称），无则第一个业务字段。
-            let resolvedDataTitle = dataTitle || 'name';
-            if (!/^\d{15,}$/.test(resolvedDataTitle)) {
-                try {
-                    const tfd = await client.post(`${baseUrl}/api/ebuilder/form/dataset/v1/getFields`, {
-                        objId: sformId, userid: auth.userId, tenantKey: auth.tenantKey,
-                    });
-                    const tfields = tfd?.data?.mainFields || [];
-                    if (resolvedDataTitle === 'name') {
-                        resolvedDataTitle = defaultEBuilderDataTitle(tfields);
-                    }
-                    else {
-                        const m = tfields.find((f) => f.fieldName === resolvedDataTitle)
-                            || tfields.find((f) => String(f.fieldName || '').includes(resolvedDataTitle));
-                        resolvedDataTitle = m?.fieldId || resolvedDataTitle;
-                    }
-                }
-                catch { /* 解析失败保留原值 */ }
-            }
-            Object.assign(jsonObj, {
-                sformId,
-                dataTitle: resolvedDataTitle || 'name',
-                formName: resolvedFormName,
-                virtualForm: false,
-                displayType: 'line',
-                isAddForRelation: true,
-                isSingle: cmdOpts.multiple ? false : true, // 默认单选；--multiple 多选
-                viewDataDetail: true,
-                pcDisplaySelectedCount: { type: 'default' },
-                mobileDisplaySelectedCount: { type: 'default' },
-                quickAddParams: [],
-                relateViewData: [],
-                relateField: null,
-                appId,
-                virtualTable: false,
-            });
-        }
-        else if (fieldType === 'Flow') {
-            // 浏览-流程字段（对齐浏览器 payload：type=Flow + relateExt.module=workflow）
-            if (!sformId) {
-                console.error('Flow 类型必须指定 --sform-id（目标流程绑定的表单 objId）');
-                process.exit(1);
-            }
-            let resolvedFormName = formName;
-            if (!resolvedFormName) {
-                try {
-                    const tlist = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-                    const tf = (tlist?.data || []).find((f) => String(f.id) === String(sformId));
-                    resolvedFormName = tf?.formName || tf?.name || sformId;
-                }
-                catch {
-                    resolvedFormName = sformId;
-                }
-            }
-            Object.assign(jsonObj, {
-                isAddForRelation: true,
-                sformId,
-                formName: resolvedFormName,
-                conditionOperate: 'and',
-                filterParams: '{}',
-                filterQueryParams: '{}',
-                columnFields: [],
-                displayType: 'line',
-                viewDataDetail: true,
-                pcDisplaySelectedCount: { type: 'default' },
-                mobileDisplaySelectedCount: { type: 'default' },
-                relateExt: { module: 'workflow' },
-                relateField: null,
-                quickAddParams: [],
-            });
-        }
-        else if (isDateRange) {
-            // 日期区间：补 start/end 两个 DateComponent + rangeInterval（对齐浏览器 payload）
-            const format = cmdOpts.format || 'yyyy-MM-dd';
-            const rangeTitle = title || fieldName;
-            const start = {
-                componentKey: 'DateComponent', content: '', describe: '', earlyDate: 'false',
-                format, isDefault: 'false', lateDate: 'false',
-                placeholder: placeholderFromFormat(format),
-                position: '', relateMultiple: 'false', required: 'false', size: 'medium',
-                title: `${rangeTitle}(开始时间)`, fieldId: startId,
-                min: { type: 'currentHour' }, max: { type: 'currentHour' },
-            };
-            const end = { ...start, title: `${rangeTitle}(结束时间)`, fieldId: endId };
-            Object.assign(jsonObj, {
-                isDefault: false,
-                start, end,
-                hasDisplayFormat: true,
-                rangeInterval: { limitType: 'max', timeUnit: 'day' },
-            });
-        }
-        else if (fieldType === 'IDCard') {
-            // 身份证号：平台原生简单字段，浏览器抓包 payload 极简（type/title/formTableId/dataKey/
-            // columnName/fieldId/formId/showOrder/groupId 即全部）——无 componentKey、无文本长度配置。
-            delete jsonObj.componentKey;
-            delete jsonObj.maxLen;
-            delete jsonObj.unique;
-            delete jsonObj.scan;
-            delete jsonObj.readonlyTransLink;
-        }
-        else {
-            // 文本最大长度：--max-len 指定，缺省 Text=100、TextArea=4000（对齐浏览器抓包；TextArea 在上面分支已设 content:""）
-            const defaultMaxLen = fieldType === 'TextArea' ? 4000 : 100;
-            const maxLen = cmdOpts.maxLen !== undefined ? Number(cmdOpts.maxLen) : defaultMaxLen;
-            Object.assign(jsonObj, {
-                maxLen: Number.isFinite(maxLen) && maxLen > 0 ? maxLen : defaultMaxLen,
-                unique: false, scan: false,
-                readonlyTransLink: false,
-            });
-        }
-        // 人员/部门多选：默认单选，--multiple 改多选（isSingle:false）。EBuilder 已在上文分支设过。
-        if (fieldType === 'Employee' || fieldType === 'Department') {
-            jsonObj.isSingle = cmdOpts.multiple ? false : true;
-        }
-        // 下拉多选是独立类型 SelectMultiple（非 Select + 开关）。浏览器抓包：type:"SelectMultiple"，
-        // 无 componentKey/maxLen/unique/scan（else 分支给 Select 加的 junk 要清掉），options 单独配。
-        if (fieldType === 'Select' && cmdOpts.multiple) {
-            jsonObj.type = 'SelectMultiple';
-            jsonObj.componentKey = 'SelectMultiple';
-            delete jsonObj.maxLen;
-            delete jsonObj.unique;
-            delete jsonObj.scan;
-            delete jsonObj.readonlyTransLink;
-        }
-        // Select 绑定选项预设模板：--option-template（ID 或名称）。
-        // 浏览器抓包（2026-09-09）：jsonObj 带 templateId+templateName+publicTemplate:false+options:[]（选项不内联），
-        // 平台渲染时按模板拉选项。模板管理见 `form option-template`。
-        if (fieldType === 'Select' && cmdOpts.optionTemplate) {
-            // 先清 else 分支给文本类加的 junk + options 占位（模板字段不发选项）
-            delete jsonObj.maxLen;
-            delete jsonObj.unique;
-            delete jsonObj.scan;
-            delete jsonObj.readonlyTransLink;
-            const tplIdOrName = cmdOpts.optionTemplate;
-            // 解析模板：纯数字按 ID 直查详情；否则在 custom+system 列表按名称精确匹配
-            let tplId = '';
-            let tplName = '';
-            const readTpl = async (id) => {
-                const r = await client.post(`${baseUrl}/api/form/datasources/queryDataSourcesByTemplateValueKey`, { templateId: id });
-                return r?.formDataTemplate?.id ? r.formDataTemplate : null;
-            };
-            if (/^\d+$/.test(tplIdOrName)) {
-                const t = await readTpl(tplIdOrName);
-                if (!t) {
-                    console.error(`选项模板 ${tplIdOrName} 不存在`);
-                    process.exit(1);
-                }
-                tplId = String(t.id);
-                tplName = String(t.name);
-            }
-            else {
-                for (const type of ['custom', 'system']) {
-                    const list = await client.post(`${baseUrl}/api/form/datasources/queryDataList`, { pageNo: 1, pageSize: 100, name: tplIdOrName, type });
-                    const hit = (list?.templatePage?.result || []).find((r) => r.name === tplIdOrName);
-                    if (hit) {
-                        tplId = String(hit.id);
-                        tplName = String(hit.name);
-                        break;
-                    }
-                }
-                if (!tplId) {
-                    console.error(`未找到名为「${tplIdOrName}」的选项模板（custom+system 均已查）`);
-                    process.exit(1);
-                }
-            }
-            Object.assign(jsonObj, {
-                hideScore: true,
-                optionBackgroundStyle: 'default',
-                options: [],
-                templateScore: {},
-                currentLevel: '1',
-                templateId: tplId,
-                templateName: tplName,
-                publicTemplate: false,
-                parentId: [],
-            });
-            if (cmdOpts.multiple) {
-                console.error('提示：模板下拉当前按单选（currentLevel=1）绑定；多选+模板组合未验证');
-            }
-        }
-        // 默认值 / 数据库字段名 / 描述：与 edit-field 共用同一套补丁规则。
-        // 放在最后 —— 前面各类型分支会写 content（如 TextArea 恒置 ''），先打补丁会被冲掉。
-        const patch = applyFieldPatches(jsonObj, {
-            defaultValue: cmdOpts.default,
+        // dataKey（字段编码）与 columnName（数据库列名）是两个东西，默认同值。
+        // 只给 --data-key 时列名跟随（历史行为）；给了 --column-name 才分开。
+        const keys = resolveFieldKeys(fieldName, {
             dataKey: cmdOpts.dataKey,
-            desc: cmdOpts.desc,
+            columnName: cmdOpts.columnName,
+        });
+        const colName = keys.dataKey; // 布局 comp 等仍按字段编码引用
+        // 字段 jsonObj 的构造抽到 services/form-field-build.ts —— 与「按物理表加字段」共用同一份。
+        // 原先这约 340 行内联在这里，多一个入口就会变成两处真相。
+        const jsonObj = await buildFieldJsonObject({
+            client, baseUrl, appId, objId,
+            userId: auth.userId, tenantKey: auth.tenantKey,
+            fieldType, fieldName, title, formId, formTableId,
+            fieldId, startId, endId,
+            dataKey: keys.dataKey, columnName: keys.columnName,
+            opts: cmdOpts,
         });
-        if (patch.errors.length > 0) {
-            for (const e of patch.errors)
-                console.error(`  ❌ ${e}`);
-            console.error('  已中止，未做任何改动。');
-            process.exit(1);
-        }
-        for (const w of patch.warnings)
-            console.error(`  ⚠ ${w}`);
         const payload = {
             formId, module: 'ebuilderform',
             customParam: { appId, objId },
@@ -2553,83 +2200,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 +2338,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 +2524,8 @@ export function registerFormCommands(program) {
                 }
             }
         }
-        // Apply required
+        // `required` 不是字段记录的键（整张表的字段记录里都没有），写到 jsonObj 只是**保持与
+        // 既有代码一致的形式**，真正生效的是保存成功之后那段布局 comp 补丁 —— 见下面 `patchFieldLayout`。
         if (editOpts.required) {
             jsonObj.required = true;
         }
@@ -2990,6 +2673,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 +2699,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 +2712,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 只在「没配过」或「旧列对不上当前目标表」时才写，不会冲掉手工配好的列。