weaver-e10-builder 1.5.1 → 1.5.3

package/dist/commands/form.js

@@ -2,97 +2,34 @@ import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { AuthSession } from '../core/auth.js';
 import { ApiClient } from '../core/client.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 { createCustomPhysicalForm, applyInitialFieldsToNewForm, placeholderFromFormat, reapplyGroupLayout, queryFormStorageSetting } from '../services/form-create.js';
+import { 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 { insertFieldIntoLayout, patchFieldLayout, NO_FIELD_TYPE_TEMPLATE } from '../services/form-layout-insert.js';
+import { fetchFieldTypeTemplates, findTemplateByType } from '../services/form-field-template.js';
 import { buildLinkageAddPayload, addLinkage, resolveEffect, readLinkageConfig } from '../services/form-linkage-condition.js';
-import { createMultilangLabel } from '../services/form-i18n-label.js';
+// 字段 jsonObj 的构造器（含 SYSTEM_FIELD_IDS / defaultEBuilderDataTitle）——
+// 原先内联在下面 add-field 的 action 里，为了给「按物理表加字段」第二个入口复用而抽出去。
+// 本文件仍有别处用这两个符号，所以在这里回导。
+import { SYSTEM_FIELD_IDS, defaultEBuilderDataTitle, buildFieldJsonObject } from '../services/form-field-build.js';
+// objId → 表单记录/formId。obj/getList 不含三方表单（专项应用），所以内部带了 getInfoById 兜底。
+import { resolveFormRecord, resolveFormId, appendThirdPartyForms, resolveObjIdByFormId } from '../services/form-id.js';
+// 字段类型归一 / 校验：与「专项建表」共用同一份（原为本文件内联）。
+import { FIELD_TYPE_CHOICES, canonComponentKey, assertFieldType, normalizeFieldDef } from '../services/form-field-validate.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';
 /**
- * componentKey 大小写归一：用户/示例常写 "Textarea"/"Ebuilder" 等小写变体，但代码各处
- * `=== 'TextArea'`、storageFieldType 按 canonical 大小写匹配。不归一会导致 type 存成小写
- * "Textarea"（FLOW 渲染器按 type 查组件查不到 → 多行文本在流式布局下渲染异常）、TextArea
- * 分支（content/maxLen）漏跑。建表 create 和加字段 add-field 都用。
- */
-const CK_CANON = {
-    textarea: 'TextArea', ebuilder: 'EBuilder', datetime: 'DateTime',
-    idcard: 'IDCard', mobile: 'Mobile', email: 'Email', phone: 'Phone',
-    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',
-};
-function canonComponentKey(ck) {
-    return CK_CANON[String(ck).toLowerCase()] || ck;
-}
-/**
- * 代码里另有分支/别名、不在 CK_CANON 与 RICH_TYPE_MAP 两处的字段类型。
- * **宁宽勿窄**：多列一个只是照旧送服务器，漏一个会把合法类型误杀，所以这里尽量收全。
- * 新增字段类型时记得同步。
- */
-const EXTRA_FIELD_TYPES = [
-    'Flow', 'SelectMultiple', 'DateInterval', 'ColorPicker', 'DataTable',
-    'DocFolder', 'DocFloder', 'Fold', 'Placeholder', 'Sharer', 'FileComponent',
-    'EbuilderAppTag', 'Attachment', 'Image', 'Signature', 'RichText', 'RelateBrowser',
-    // EInvoice 电子发票：下方 add-field 有专属构建分支（isSingle/invoiceType），此前漏登记 →
-    // 被 assertFieldType 挡成死代码。AudioRecord/VideoRecord 语音视频：极简 jsonObj，平台原样透传
-    // （见 rich-types.ts 的说明），无需富组件模板。
-    'EInvoice', 'AudioRecord', 'VideoRecord',
-];
-/** 可用的字段类型 = 基础组件（CK_CANON 的值）∪ 富组件（RICH_TYPE_MAP 的键）∪ 上述补充。
- * 导出仅为让测试能盯住"平台支持的合法类型不许漏登记"（漏了会被 assertFieldType 误杀）。 */
-export const FIELD_TYPE_CHOICES = [...new Set([
-        ...Object.values(CK_CANON),
-        ...Object.keys(RICH_TYPE_MAP),
-        ...EXTRA_FIELD_TYPES,
-    ])].sort();
-/**
- * 校验字段类型名。不校验的话错类型会**直送服务器**，换回一段
- * `Cannot invoke "ComponentType.name()" because ... getComponentKey() is null`——
- * 既看不出哪错了，也看不出该填什么。这里先拦下来并列出可选值。
- */
-function assertFieldType(fieldType, where = '') {
-    if (FIELD_TYPE_CHOICES.includes(fieldType))
-        return;
-    console.error(`${where}不支持的字段类型: ${fieldType}`);
-    console.error(`  可选: ${FIELD_TYPE_CHOICES.join(' / ')}`);
-    process.exit(1);
-}
-/**
- * 校验选项定义。**键名必须是 `name` / `valueKey`**——写成 `{value,label}` 这类
- * 不会被拦下，而是静默存成「没有名字的选项」（平台侧 fieldOptionName 为空），
- * 之后 `form data add` 按选项名写数据会直接失效，且读回也看不出哪里错了。
+ * 字段类型归一 / 校验 / 校验清单已抽到 `services/form-field-validate.ts` ——
+ * 「标准建表」与「专项建表」两个入口共用同一份，避免两处真相。
+ *
+ * `FIELD_TYPE_CHOICES` 在这里**原样 re-export**：
+ * `form-add-physical-field.ts` 与 `test/form-field-types.test.ts` 仍从本模块取它。
  */
-function assertFieldOptions(fieldName, options) {
-    options.forEach((o, i) => {
-        if (typeof o === 'string')
-            return; // 字符串简写，归一化时会补成 {name}
-        const where = `字段「${fieldName}」第 ${i + 1} 个选项`;
-        if (typeof o?.name !== 'string' || !o.name.trim()) {
-            const got = o && typeof o === 'object' ? Object.keys(o).join(' / ') : String(o);
-            console.error(`${where}缺少 name（收到键：${got || '(无)'}）`);
-            console.error('  正确写法: {"name":"待入职","valueKey":"1"}（valueKey 省略则由平台生成）');
-            process.exit(1);
-        }
-        const vk = o.valueKey;
-        if (vk !== undefined && vk !== null && String(vk) !== '' && !/^\d+$/.test(String(vk))) {
-            console.error(`${where}的 valueKey「${vk}」必须是数字（平台规范，下游按数字引用）`);
-            process.exit(1);
-        }
-    });
-}
-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',
-]);
+export { FIELD_TYPE_CHOICES };
 /** 系统字段的中文名 → 物理字段 id（form read 实测的平台自带字段）。建表时字段与此完全重名 → 跳过新建、直接复用系统字段。 */
 const SYSTEM_FIELD_NAME_TO_ID = {
     '标题': 'name',
@@ -117,14 +54,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` 眼里这个字段长什么样 —— **仅用于把错误信息说清楚，绝不作为写回基底**。
  *
@@ -149,11 +78,21 @@ async function peekViaGetFields(client, baseUrl, objId, fieldId, auth) {
  * 单独抽出来是为了让「读不到 → 中止」这条路清晰：**失败要能被调用方看见**，
  * 不能吞掉之后改走别的接口重建一个定义。
  */
-async function fetchFieldPageRecords(client, baseUrl, appId, formId) {
+/**
+ * 读表单的字段记录。
+ *
+ * ⚠ **主表与明细表是两套结果，不带 `subFormId` 时只返主表字段。**
+ * 明细字段必须显式带 `subFormId` 才查得到 —— 少了这个参数，刚建好的明细字段会「查不到」，
+ * 表现为「字段已建立，但读回字段定义失败」。
+ */
+async function fetchFieldPageRecords(client, baseUrl, appId, formId, subFormId) {
     const r = await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/getFormFieldPage?apid=${appId}`, {
         pageNo: 1, pageSize: 500, module: 'ebuilderform',
         customParam: { appId },
-        formFieldSearchEntity: { isDelete: 0, status: 'enable', formId },
+        formFieldSearchEntity: {
+            isDelete: 0, status: 'enable', formId,
+            ...(subFormId ? { subFormId: String(subFormId) } : {}),
+        },
     }, { ebbusinessid: formId });
     return r?.data?.pageDatas?.result || r?.data?.data?.records || r?.data?.data || [];
 }
@@ -204,8 +143,7 @@ export function registerFormCommands(program) {
         if (cmdOpts?.appId) {
             try {
                 // Get formId from appId
-                const listData = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${cmdOpts.appId}?apid=${cmdOpts.appId}`, { ebbusinessid: cmdOpts.appId });
-                const formInfo = (listData?.data || []).find((f) => f.id === objId);
+                const formInfo = await resolveFormRecord(client, baseUrl, cmdOpts.appId, objId);
                 formId = formInfo?.formId || '';
                 if (formId) {
                     // Fetch options for Select/RadioBox/CheckBox fields (skip system fields with string IDs)
@@ -284,6 +222,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');
@@ -294,10 +248,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)
@@ -333,6 +290,8 @@ export function registerFormCommands(program) {
             process.exit(1);
         }
         const forms = data.data || [];
+        // obj/getList 不含三方表单（专项应用）—— 补上。标准应用没有三方表单，等于空转。
+        await appendThirdPartyForms(client, baseUrl, appId, forms);
         if (cmdOpts?.out) {
             writeFileSync(cmdOpts.out, JSON.stringify(forms, null, 2), 'utf-8');
             console.error(`已写入: ${cmdOpts.out}`);
@@ -396,22 +355,8 @@ export function registerFormCommands(program) {
         // componentKey 大小写归一（canonComponentKey）：用户/示例常写 "Textarea"/"Ebuilder" 等，
         // 但 storageFieldType 与各 `=== 'TextArea'` 分支按 canonical 大小写匹配，不归一会导致 type 存成
         // 小写 "Textarea"（FLOW 渲染异常）、TextArea 分支（content/maxLen）漏跑。
-        // 归一化 + 就地校验（类型名/选项键名）。顶层与明细子字段共用，避免两边校验不一致。
-        const normalizeFieldDef = (raw) => {
-            const out = { ...raw };
-            if (!out.componentKey && out.fieldType)
-                out.componentKey = out.fieldType;
-            if (out.componentKey)
-                out.componentKey = canonComponentKey(out.componentKey);
-            const label = out.fieldName || out.title || '(未命名)';
-            assertFieldType(out.componentKey || '', `字段「${label}」`);
-            if (Array.isArray(out.options) && !out.fieldOptions) {
-                out.fieldOptions = out.options.map((o) => typeof o === 'string' ? { name: o } : o);
-            }
-            if (Array.isArray(out.fieldOptions))
-                assertFieldOptions(label, out.fieldOptions);
-            return out;
-        };
+        // 归一化 + 就地校验（类型名/选项键名）见 services/form-field-validate.ts 的 normalizeFieldDef ——
+        // 顶层与明细子字段共用它，且与「专项建表」共用同一份实现。
         fieldDefs = fieldDefs.map((f) => {
             const out = normalizeFieldDef(f);
             // DetailTable 子字段同样归一化：之前只转顶层，子表 Select 用 options 简写时
@@ -629,42 +574,10 @@ export function registerFormCommands(program) {
             else {
                 console.error(`  数据库表名: ${result.tableName}`);
             }
-            // Create fields and layout
-            const fieldDefsForStandard = fieldDefs.map(f => ({
-                componentKey: f.componentKey, fieldName: f.fieldName,
-                required: f.required, readOnly: f.readOnly, unique: f.unique,
-                hidden: f.hidden, formFields: f.formFields,
-                enableSubDetail: f.enableSubDetail, defaultExpandRow: f.defaultExpandRow,
-                subDetailConfig: f.subDetailConfig,
-                precision: f.precision, pointSize: f.pointSize,
-                percent: f.percent, defaultValue: f.defaultValue,
-                group: f.group, multiple: f.multiple,
-                singleRow: f.singleRow,
-                // 文本最大长度（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 || [];
-            console.error(`  字段+布局已写入: ${fieldDefsForStandard.length} 个字段`);
-            const detailTables = fieldResult.detailTables || [];
-            for (const dt of detailTables) {
-                console.error(`  明细表: ${dt.definition.fieldName}  subFormId: ${dt.subFormId}`);
-            }
-            const subDetailService = new FormSubDetailService(client, baseUrl, appId, objId, formId);
-            for (const dt of detailTables) {
-                const def = dt.definition;
-                if (def.enableSubDetail && Array.isArray(def.subDetailConfig) && def.subDetailConfig.length > 0) {
-                    await subDetailService.set(def.fieldName, def.subDetailConfig, Boolean(def.defaultExpandRow));
-                    console.error(`  二级明细已配置: ${def.fieldName} → ${def.subDetailConfig.map((x) => x.subForm).join(', ')}`);
-                }
-                else if (def.enableSubDetail) {
-                    throw new Error(`明细表 ${def.fieldName} 已声明 enableSubDetail，但 subDetailConfig 为空`);
-                }
-            }
+            // Create fields and layout —— 白名单映射 + 明细/二级明细那一整步已抽到
+            // services/form-create.ts 的 applyInitialFieldsToNewForm，「专项建表」共用同一条链。
+            const fieldResult = await applyInitialFieldsToNewForm(client, baseUrl, appId, objId, formId, fieldDefs, { tenantKey: auth.tenantKey, layoutType, systemOverrides });
+            fieldGroups = fieldResult.fieldGroups;
         }
         catch (e) {
             console.error(`创建失败: ${e.message}`);
@@ -708,8 +621,7 @@ export function registerFormCommands(program) {
         let resolvedFormId = formId || '';
         const resolveFormId = async () => {
             if (!resolvedFormId) {
-                const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-                const formInfo = (formList?.data || []).find((f) => f.id === objId);
+                const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
                 resolvedFormId = formInfo?.formId || '';
             }
             return resolvedFormId;
@@ -729,6 +641,8 @@ export function registerFormCommands(program) {
             // Resolve target form names and field IDs from sformId
             const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
             const allForms = formList?.data || [];
+            // 目标表可能是三方表单（专项应用），它不在 getList 里 —— 补上
+            await appendThirdPartyForms(client, baseUrl, appId, allForms);
             const formNameById = new Map();
             for (const fm of allForms) {
                 formNameById.set(fm.id, fm.formName || fm.name || fm.id);
@@ -763,8 +677,7 @@ export function registerFormCommands(program) {
             };
             await resolveFormId();
             if (!resolvedFormId) {
-                const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-                const formInfo = (formList?.data || []).find((f) => f.id === objId);
+                const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
                 resolvedFormId = formInfo?.formId || '';
             }
             // Use getFormFieldPage to get full field info including columnName
@@ -979,6 +892,8 @@ export function registerFormCommands(program) {
             try {
                 const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
                 allForms = formList?.data || [];
+                // 目标可能是三方表单（专项应用），它不在 getList 里 —— 补上
+                await appendThirdPartyForms(client, baseUrl, appId, allForms);
             }
             catch { /* 查不到则 formName 用 sformId */ }
             // 读已建字段（拿 fieldId）
@@ -1870,8 +1785,7 @@ export function registerFormCommands(program) {
             process.exit(1);
         }
         // Get formId from appId
-        const listData = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-        const formInfo = (listData?.data || []).find((f) => f.id === objId);
+        const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
         const formId = formInfo?.formId || '';
         if (!formId) {
             console.error('无法获取 formId，请确认 appId 和 objId 正确');
@@ -1916,8 +1830,7 @@ export function registerFormCommands(program) {
         const client = new ApiClient(auth);
         const baseUrl = auth.getBaseUrl();
         // objId → formId
-        const listData = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-        const formInfo = (listData?.data || []).find((f) => String(f.id) === String(objId));
+        const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
         const formId = formInfo?.formId || '';
         if (!formId) {
             console.error('无法获取 formId，请确认 objId 正确');
@@ -1964,8 +1877,7 @@ export function registerFormCommands(program) {
         const client = new ApiClient(auth);
         const baseUrl = auth.getBaseUrl();
         // Get formId
-        const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-        const formInfo = (formList?.data || []).find((f) => f.id === objId);
+        const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
         const formId = formInfo?.formId || '';
         const formTableId = formInfo?.formTableId || '';
         if (!formId) {
@@ -1994,13 +1906,33 @@ export function registerFormCommands(program) {
             console.error('--options 必须是非空数组');
             process.exit(1);
         }
-        // Get current field info for title, dataKey etc.
-        let currentField = {};
+        // 读**现状**（title / dataKey / type / labelObj …）—— 这是「读现状 → 改 → 写回」的底。
+        //
+        // ⚠ 这里**不许降级成 `{}`**。以前读失败只在 catch 里吞掉、`currentField` 变成空对象，
+        // 于是 title 写成空串，平台回「字段标题不能为空」—— 报的是标题，真因是**读没成功**，
+        // 用户怎么去补 title 都没用。宁可中止：拿不到现状就写，等于拿一份空对象覆盖整个字段。
+        let currentField = null;
+        let readErr = '';
         try {
             const fData = await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/getFormField`, { module: 'ebuilderform', formTableField: { formField: { id: fieldId, form: { id: formId } } } }, { ebbusinessid: formId });
-            currentField = fData?.data || {};
+            if (fData?.code === 200 && fData?.status !== false && fData?.data)
+                currentField = fData.data;
+            else
+                readErr = fData?.msg || `code=${fData?.code}`;
+        }
+        catch (e) {
+            readErr = e.message;
+        }
+        if (!currentField || !Object.keys(currentField).length) {
+            console.error(`读取字段现状失败（${readErr || '接口未返回字段'}），已中止、未改动任何东西。`);
+            console.error('  本命令是「读现状 → 改 → 写回」，读不到现状就写会把字段的其余属性清空。');
+            process.exit(1);
+        }
+        if (!String(currentField.title ?? '').trim()) {
+            console.error(`读回的字段没有 title（fieldId=${fieldId}），已中止、未改动任何东西。`);
+            console.error('  标题在平台里存的是多语言标签 id（labelObj.title）；请先用 `form read` 确认这个字段的状态。');
+            process.exit(1);
         }
-        catch { /* best effort */ }
         // Build options with defOption
         const { randomUUID } = await import('crypto');
         // valueKey=用户自定义选项值，必须是纯数字（平台规范+下游引用按数字处理），非数字直接报错；
@@ -2052,7 +1984,7 @@ export function registerFormCommands(program) {
             hideScore: true,
             groupId: currentField.groupId || '-1',
             hasDisplayFormat: currentField.hasDisplayFormat ?? false,
-            title: currentField.title || '',
+            title: currentField.title,
             dataCount: currentField.dataCount || 1,
             dataKey: currentField.dataKey || '',
             systemField: currentField.systemField ?? true,
@@ -2130,8 +2062,7 @@ export function registerFormCommands(program) {
         const client = new ApiClient(auth);
         const baseUrl = auth.getBaseUrl();
         // Get formId from objId
-        const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-        const formInfo = (formList?.data || []).find((f) => f.id === objId);
+        const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
         const formId = formInfo?.formId || '';
         const formTableId = formInfo?.formTableId || '';
         if (!formId) {
@@ -2160,402 +2091,16 @@ export function registerFormCommands(program) {
             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: keys.dataKey,
-            columnName: keys.columnName,
-        };
-        // 明细表字段：--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: keys.dataKey, columnName: keys.columnName,
-                    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 === '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, {
-                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: cmdOpts.dataKey,
-            columnName: cmdOpts.columnName,
-            desc: cmdOpts.desc,
+        // 字段 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}`);
-        // 必填**只存在于布局 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 },
@@ -2585,11 +2130,13 @@ export function registerFormCommands(program) {
             // 把错误讲清楚，让用户自己决定要不要 --reinit。
             if (!cmdOpts.reinit) {
                 try {
-                    const fieldDef = (await fetchFieldPageRecords(client, baseUrl, appId, formId))
+                    // ⚠ 明细字段**必须带 subFormId** 才查得到（不带只返主表字段）——
+                    //    少了它，刚建好的明细字段会「查不到」，报成「读回字段定义失败」。
+                    const fieldDef = (await fetchFieldPageRecords(client, baseUrl, appId, formId, cmdOpts.subFormId))
                         .find((f) => String(f.fieldId) === String(fieldId));
                     if (!fieldDef)
                         throw new Error('字段已建立，但读回字段定义失败');
-                    const placed = await insertFieldIntoLayout(client, baseUrl, formId, {
+                    const insertArgs = {
                         fieldId, labelFieldId, title: title || fieldName, fieldDef,
                         subFormId: cmdOpts.subFormId,
                         // 对齐 initLayout 那条路对新字段的默认：可编辑、显示。
@@ -2599,12 +2146,38 @@ export function registerFormCommands(program) {
                             required: cmdOpts.required === true,
                             ...(cmdOpts.singleRow === true ? { singleRow: true } : {}),
                         },
-                    });
+                    };
+                    let placed;
+                    try {
+                        placed = await insertFieldIntoLayout(client, baseUrl, formId, insertArgs);
+                    }
+                    catch (e) {
+                        // 本表还没有这个类型 → 去要一份**平台按该字段生成的模板**再试一次。
+                        // 只在真缺模板时才多打这一次接口，正常路径零开销。
+                        if (e?.code !== NO_FIELD_TYPE_TEMPLATE)
+                            throw e;
+                        const templates = await fetchFieldTypeTemplates(client, baseUrl, appId, formId);
+                        // 主表字段按 fieldId 命中；明细表字段拿不到（接口不返回明细），
+                        // 退而借**主表同类型**的那一份 —— 模板是按类型而不是按作用域的
+                        // （`config.flow` 是空对象、没有 `excel`），作用域由插入方自己写。
+                        const tpl = templates.get(String(fieldId))?.comp
+                            ?? findTemplateByType(templates, String(fieldDef.componentKey ?? fieldType))?.comp;
+                        if (!tpl)
+                            throw e;
+                        console.error('  本表还没有这个类型，改用平台给的字段模板合成组件...');
+                        placed = await insertFieldIntoLayout(client, baseUrl, formId, { ...insertArgs, fieldTypeTemplate: tpl });
+                    }
                     console.error(`  布局已更新: excel[${placed.row},${placed.col}]（增量插入，未重建）`);
+                    // 网格补格这类「改成功了但不干净」的情况要让人看见，不能闷掉。
+                    for (const w of placed.warnings)
+                        console.error(`  ⚠ ${w}`);
                 }
                 catch (e) {
                     console.error(`  布局更新失败: ${e.message}`);
-                    console.error('  字段本身已建立，但没进布局。按上面那条修好重跑本命令即可（重跑不会重复建字段）。');
+                    // ⚠ 别写「重跑不会重复建字段」——字段已经建出来了，重跑这条命令会再次去建同一个
+                    //    字段，撞库列重名而失败。要说清是「先删掉再重跑」。
+                    console.error('  字段本身已建立，但没进布局。要重试请先 `form delete-field` 删掉这个字段再跑，');
+                    console.error('  或直接按上面那条修好布局（字段不用重建）。');
                 }
             }
             else {
@@ -2729,8 +2302,11 @@ export function registerFormCommands(program) {
         // Get formId — try getList first, fall back to searching by fieldId
         let formId = '';
         let resolvedObjId = objId;
+        // 这份列表下面还要再用一次（formId → objId 的反查），所以保留不动；
+        // formInfo 走共用解析 —— obj/getList 命不中时按 id 直取，覆盖三方表单。
         const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-        const formInfo = (formList?.data || []).find((f) => String(f.id) === String(objId));
+        const formInfo = (formList?.data || []).find((f) => String(f.id) === String(objId))
+            || await resolveFormRecord(client, baseUrl, appId, objId);
         formId = formInfo?.formId || '';
         // If not found in getList (e.g. workflow sub-table objId), search by fieldId
         if (!formId) {
@@ -2747,6 +2323,12 @@ export function registerFormCommands(program) {
                 const matchForm = (formList?.data || []).find((f) => f.formId === formId);
                 if (matchForm)
                     resolvedObjId = matchForm.id;
+                else {
+                    // 三方表单不在 getList 里 —— 按 formId 反查补一次
+                    const byFormId = await resolveObjIdByFormId(client, baseUrl, appId, formId);
+                    if (byFormId)
+                        resolvedObjId = byFormId;
+                }
             }
         }
         if (!formId) {
@@ -2963,8 +2545,7 @@ export function registerFormCommands(program) {
                 let formName = editOpts.formName || fallbackFormName || '';
                 if (!formName) {
                     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));
+                        const tf = await resolveFormRecord(client, baseUrl, appId, sformId);
                         formName = tf?.formName || tf?.name || sformId;
                     }
                     catch {
@@ -3160,8 +2741,7 @@ export function registerFormCommands(program) {
             process.exit(1);
         const client = new ApiClient(auth);
         const baseUrl = auth.getBaseUrl();
-        const formList = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${appId}?apid=${appId}`, { ebbusinessid: appId });
-        const formInfo = (formList?.data || []).find((f) => String(f.id) === String(objId));
+        const formInfo = await resolveFormRecord(client, baseUrl, appId, objId);
         const formId = formInfo?.formId || '';
         if (!formId) {
             console.error('无法获取 formId，请确认 objId 和 appId 正确');
@@ -3269,9 +2849,8 @@ export function registerFormCommands(program) {
         // eb 表 layout/field-manage 接口认 formId（≠objId）：从应用表单列表按 objId 解析 formId
         let formId = '';
         try {
-            const listRes = await client.get(`${baseUrl}/api/bs/ebuilder/form/obj/getList/${encodeURIComponent(appId)}?apid=${encodeURIComponent(appId)}`);
-            const hit = (listRes?.data || []).find((f) => String(f.id) === String(objId));
-            formId = hit?.formId || '';
+            // 原实现这条请求没带 ebbusinessid 头；走共用解析后会带上（与其余 12 处一致）。
+            formId = await resolveFormId(client, baseUrl, appId, objId);
         }
         catch { /* 忽略，下面报错 */ }
         if (!formId)