weaver-e10-builder 1.1.9 → 1.2.3

package/dist/commands/form.js

@@ -3,8 +3,13 @@ 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 } from '../services/form-sub-detail.js';
-import { getRichType, richIdUnits } from '../services/rich-types.js';
+import { FormSubDetailService, resolveDetailTable } from '../services/form-sub-detail.js';
+import { RICH_TYPE_MAP, getRichType, richIdUnits, BROWSER_KINDS } from '../services/rich-types.js';
+import { dropFieldComponents, prepareLayoutForSave } from '../services/form-field-drop.js';
+import { describeEditBaseFailure, resolveEditBase as resolveEditBasePure } from '../services/form-edit-base.js';
+import { applyFieldPatches } from '../services/form-field-patch.js';
+import { ensureDisplayColumns } from '../services/form-ebuilder-columns.js';
+import { buildFormulaParameters, defaultReturnType } from '../services/formula-detail.js';
 import { registerOptionTemplateCommand } from './form-option-template.js';
 /**
  * componentKey 大小写归一：用户/示例常写 "Textarea"/"Ebuilder" 等小写变体，但代码各处
@@ -23,6 +28,62 @@ const CK_CANON = {
 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` 按选项名写数据会直接失效，且读回也看不出哪里错了。
+ */
+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',
@@ -61,6 +122,38 @@ function defaultEBuilderDataTitle(fields) {
     const byName = biz.find((f) => String(f.fieldName ?? f.title ?? '').includes('名称'));
     return byName?.fieldId || biz[0]?.fieldId || 'name';
 }
+/**
+ * 只读地看一眼 `getFields` 眼里这个字段长什么样 —— **仅用于把错误信息说清楚，绝不作为写回基底**。
+ *
+ * `getFields` 的 `fieldKey` 是粗粒度的：CLI 不认识的字段类型（如「文档赋权对象」）一律报 `Text`，
+ * 拿它当 `type` 回写就会把真实类型改掉。
+ */
+async function peekViaGetFields(client, baseUrl, objId, fieldId, auth) {
+    try {
+        const res = await client.post(`${baseUrl}/api/ebuilder/form/dataset/v1/getFields`, {
+            objId, userid: auth.userId, tenantKey: auth.tenantKey,
+        });
+        const all = [...(res?.data?.mainFields || []), ...(res?.data?.subFields || [])];
+        return all.find((f) => String(f.fieldId) === String(fieldId)) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 读 `getFormFieldPage` 的字段记录（扁平形态）。
+ *
+ * 单独抽出来是为了让「读不到 → 中止」这条路清晰：**失败要能被调用方看见**，
+ * 不能吞掉之后改走别的接口重建一个定义。
+ */
+async function fetchFieldPageRecords(client, baseUrl, appId, formId) {
+    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 },
+    }, { ebbusinessid: formId });
+    return r?.data?.pageDatas?.result || r?.data?.data?.records || r?.data?.data || [];
+}
 export function registerFormCommands(program) {
     const form = program.command('form').description('表单管理');
     registerOptionTemplateCommand(form, program);
@@ -255,7 +348,10 @@ export function registerFormCommands(program) {
         .description('创建表单')
         .argument('<appId>', '应用 ID')
         .argument('<name>', '表单名称')
-        .requiredOption('--fields <json>', '字段定义 JSON 文件路径（如 @fields.json），格式：[{"componentKey":"Text","fieldName":"姓名"}]')
+        .requiredOption('--fields <json>', '字段定义 JSON 文件路径（**必须 @ 开头**，如 @fields.json）。格式：'
+        + '[{"componentKey":"Text","fieldName":"姓名"}]；Select 的选项写 '
+        + 'options 或 fieldOptions：[{"name":"待入职","valueKey":"1"}]（键名必须是 name / valueKey，'
+        + 'valueKey 须为数字、省略则平台生成）')
         .option('--menu', '建表后添加台账菜单（默认不加；漏加可用 `e10-cli menu add-table` 补）')
         .option('--layout <type>', '表单布局类型：FLOW(流式)/EXCEL(表格，缺省)。布局类型建表后不可切换', 'EXCEL')
         .action(async (appId, name, cmdOpts) => {
@@ -295,27 +391,28 @@ export function registerFormCommands(program) {
         // componentKey 大小写归一（canonComponentKey）：用户/示例常写 "Textarea"/"Ebuilder" 等，
         // 但 storageFieldType 与各 `=== 'TextArea'` 分支按 canonical 大小写匹配，不归一会导致 type 存成
         // 小写 "Textarea"（FLOW 渲染异常）、TextArea 分支（content/maxLen）漏跑。
-        fieldDefs = fieldDefs.map((f) => {
-            const out = { ...f };
+        // 归一化 + 就地校验（类型名/选项键名）。顶层与明细子字段共用，避免两边校验不一致。
+        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);
             }
-            // DetailTable 子字段的 options 同样归一化：之前只转顶层，子表 Select 用 options 简写时
+            if (Array.isArray(out.fieldOptions))
+                assertFieldOptions(label, out.fieldOptions);
+            return out;
+        };
+        fieldDefs = fieldDefs.map((f) => {
+            const out = normalizeFieldDef(f);
+            // DetailTable 子字段同样归一化：之前只转顶层，子表 Select 用 options 简写时
             // Step 7b 找不到 fieldOptions，子表选项配不上（布局 + 选项配置两处都依赖 fieldOptions）
             if (out.componentKey === 'DetailTable' && Array.isArray(out.formFields)) {
-                out.formFields = out.formFields.map((sf) => {
-                    const so = { ...sf };
-                    if (so.componentKey)
-                        so.componentKey = canonComponentKey(so.componentKey);
-                    if (Array.isArray(so.options) && !so.fieldOptions) {
-                        so.fieldOptions = so.options.map((o) => typeof o === 'string' ? { name: o } : o);
-                    }
-                    return so;
-                });
+                out.formFields = out.formFields.map((sf) => normalizeFieldDef(sf));
             }
             return out;
         });
@@ -1551,8 +1648,9 @@ export function registerFormCommands(program) {
             catch { /* 读不到字段则公式会报"引用字段不存在" */ }
             for (const fd of formulaDefs) {
                 try {
+                    // formula 写字符串时**不再默认 Number** —— 返回类型留空，由下面按目标字段类型推断。
                     const formula = (typeof fd.formula === 'string')
-                        ? { expression: fd.formula, returnType: 'Number' }
+                        ? { expression: fd.formula }
                         : (fd.formula || {});
                     const expression = formula.expression || formula.formulaExpress || '';
                     if (!expression) {
@@ -1573,52 +1671,25 @@ export function registerFormCommands(program) {
                         continue;
                     }
                     const targetFieldId = String(targetField.fieldId);
-                    // 解析 {主表.字段名} / {明细表名.字段名} 引用（不去重：同一字段引用多次时每个出现位置
-                    // 都要一个参数，否则平台报「参数列表与执行语句不一致」）
-                    const refRegex = /\{(?:主表|([^.}]+))\.([^}]+)\}/g;
-                    const refNames = [];
-                    let rm;
-                    while ((rm = refRegex.exec(expression)) !== null) {
-                        const table = rm[1] ? rm[1].trim() : '主表';
-                        const field = rm[2].trim();
-                        refNames.push({ table, field });
-                    }
-                    const parameters = [];
-                    let refMissing = false;
-                    for (const ref of refNames) {
-                        let rf;
-                        if (ref.table === '主表') {
-                            rf = allFields.find((f) => f.fieldName === ref.field || f.title === ref.field || String(f.fieldId) === ref.field);
-                        }
-                        else {
-                            const dt = detailFields.find((d) => d.name === ref.table || String(d.id) === ref.table);
-                            rf = dt && (dt.fields || []).find((f) => f.fieldName === ref.field || String(f.fieldId) === ref.field);
-                        }
-                        if (!rf) {
-                            console.error(`    ⚠ 公式引用字段不存在: ${ref.table}.${ref.field}`);
-                            refMissing = true;
-                            break;
-                        }
-                        const param = {
-                            fieldId: String(rf.fieldId), formId: resolvedFormId, module: 'ebuilderform',
-                            properKey: rf.fieldKey || rf.type || 'Text', title: rf.title || rf.fieldName,
-                            name: rf.fieldName || rf.title, appId, id: null,
-                        };
-                        if (ref.table !== '主表') {
-                            const dt = detailFields.find((d) => d.name === ref.table || String(d.id) === ref.table);
-                            if (dt) {
-                                param.sFormId = String(dt.id);
-                                param.sFormName = dt.name;
-                            }
-                        }
-                        parameters.push(param);
-                    }
-                    if (refMissing)
+                    // 引用解析与归一化**统一走 services/formula-detail.ts**，与 `form formula set` 同一套：
+                    // 两种写法都收（`{主表.x}` 与编辑器里的 `[x]`），方括号一律归一化成花括号再存 ——
+                    // 方括号直接下发会「保存成功但字段没接上」；参数按出现位置逐个给，不去重。
+                    const parsed = await buildFormulaParameters(client, baseUrl, objId, appId, resolvedFormId, expression);
+                    if (parsed.errors.length > 0) {
+                        for (const e of parsed.errors)
+                            console.error(`    ⚠ ${e}`);
                         continue;
+                    }
+                    for (const w of parsed.warnings)
+                        console.error(`    ⚠ ${w}`);
+                    const parameters = parsed.parameters;
                     const formulaName = formula.name || `公式_${fd.fieldName}`;
                     const savePayload = {
-                        expressSql: expression, name: formulaName, parameters,
-                        returnType: formula.returnType || 'Number', validateType: 'normal',
+                        expressSql: parsed.normalizedExpression, name: formulaName, parameters,
+                        // 返回类型：显式给了就用，否则按目标字段类型推断。此前一律 Number，
+                        // 给文本/日期字段挂公式必被平台拒（「公式计算结果必须为: 数字」）。
+                        returnType: formula.returnType || defaultReturnType(targetField.fieldKey || targetField.type),
+                        validateType: 'normal',
                         referenceType: 'assign',
                         extendParam: JSON.stringify({ exceptIds: targetFieldId, createType: 'once' }),
                         formulaId: null, dataSources: [], formulaType: 'normal',
@@ -2043,14 +2114,16 @@ export function registerFormCommands(program) {
         .option('--sform-id <id>', '关联的目标表单 objId（仅 EBuilder 类型）')
         .option('--data-title <field>', '目标表单的显示字段名（仅 EBuilder；缺省 name=目标表含"名称"的字段，无则第一个业务字段）')
         .option('--form-name <name>', '目标表单名称（仅 EBuilder 类型，可选）')
-        .option('--browser-type <type>', '通用浏览类型：workflow、hrcontract、form、role、archive')
+        .option('--browser-type <type>', `通用浏览类型：${BROWSER_KINDS.join('、')}`)
         .option('--browser-form-source <source>', '表单浏览数据源：business 或 ebuilder（仅 --browser-type form）')
         .option('--format <fmt>', '日期精度格式（Date/DateTime/DateRange），如 yyyy-MM-dd、yyyy-MM-dd HH:mm')
         .option('--min-field <field>', 'Date/DateTime 日期限制：最早不得早于该字段（字段名，min.dateField）')
         .option('--max-field <field>', 'Date/DateTime 日期限制：最晚不得晚于该字段（字段名，max.dateField）')
         .option('--precision <n>', '小数位数（Number/Money 类型，缺省 Number=0 整数、Money=2、百分比=1）')
         .option('--percent', 'Number 百分比显示（numberType=percentage）')
-        .option('--default <value>', 'Number/Money 默认值（content + isDefault，如 工时单价默认 1000）')
+        .option('--default <value>', '默认值（Text / TextArea / Number / Money，如 工时单价默认 1000）')
+        .option('--data-key <key>', '数据库字段名（默认按字段名生成拼音；字母数字下划线，不以数字开头）')
+        .option('--desc <text>', '字段描述（设计器字段属性里的「描述」）')
         .option('--delimiter', 'Number/Money 千分位（Money 默认开，--no-delimiter 关闭）')
         .option('--capital', 'Number/Money 大写金额显示')
         .option('--sub-form-id <id>', '明细表 subFormId（在指定明细表里加字段）')
@@ -2062,6 +2135,9 @@ export function registerFormCommands(program) {
         // fieldType 大小写归一（与建表一致）：用户常传 "Textarea"/"Ebuilder"，不归一则 type 存小写
         // "Textarea"（FLOW 渲染异常）、TextArea 分支漏跑。
         fieldType = canonComponentKey(fieldType);
+        // 先本地拦错类型：否则会直送服务器，换回一段 Java 异常（ComponentType.name() ... null），
+        // 既看不出哪错了也看不出该填什么。
+        assertFieldType(fieldType, 'add-field ');
         const opts = program.opts();
         const auth = await AuthSession.fromOptions(opts);
         if (!auth)
@@ -2100,18 +2176,19 @@ export function registerFormCommands(program) {
             dataKey: colName,
             columnName: colName,
         };
-        // 明细表字段：--sub-form-id 时 formTableId 用明细表的，jsonObj 带 subFormId
+        // 明细表字段：--sub-form-id 时 jsonObj 带 subFormId —— **字段落点由它决定**。
+        // 必须用 resolveDetailTable 而不是直接查 getEbField：后者列不出空明细表，
+        // 用户把明细字段删光后就再也加不回去（详见 services/form-sub-detail.ts）。
         if (cmdOpts.subFormId) {
-            const eb = await client.post(`${baseUrl}/api/bs/esb/setting/component/getEbField`, { tableId: objId, appId });
-            const dt = (eb?.data?.detail || []).find((d) => String(d.detailTableId) === String(cmdOpts.subFormId));
-            if (!dt) {
-                console.error(`未找到明细表 subFormId=${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 });
-            const detailFormTableId = dt.fields?.[0]?.formTableId || '';
-            if (detailFormTableId)
-                jsonObj.formTableId = detailFormTableId;
+            // 空表拿不到物理表 id，保持主表的值不动：实测带主表 formTableId 一样落进明细表。
+            if (sub.formTableId)
+                jsonObj.formTableId = sub.formTableId;
         }
         // 富组件：映射到平台真实 type/componentKey + 附加配置（对齐 batch/save/formField 抓包）。
         // 之前 jsonObj 只有 type 没有 componentKey → 平台 FormFieldDto.getComponentKey() 为 null → NPE。
@@ -2440,6 +2517,21 @@ export function registerFormCommands(program) {
                 console.error('提示：模板下拉当前按单选（currentLevel=1）绑定；多选+模板组合未验证');
             }
         }
+        // 默认值 / 数据库字段名 / 描述：与 edit-field 共用同一套补丁规则。
+        // 放在最后 —— 前面各类型分支会写 content（如 TextArea 恒置 ''），先打补丁会被冲掉。
+        const patch = applyFieldPatches(jsonObj, {
+            defaultValue: cmdOpts.default,
+            dataKey: cmdOpts.dataKey,
+            desc: cmdOpts.desc,
+        });
+        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 },
@@ -2449,26 +2541,13 @@ export function registerFormCommands(program) {
         if (data?.code === 200 && data?.status) {
             const msg = opts.json ? JSON.stringify({ fieldId, fieldName }) : `字段已添加: ${fieldName} (fieldId=${fieldId})`;
             console.log(msg);
-            // 关联浏览弹窗显示列：add-field 的 EBuilder 字段自动配 ffDisplayColumns = 目标表全部业务字段（去系统字段），
-            // 对齐 create Step2。直接带 ffDisplayColumns 进 jsonObj 不落库，需 getFormField 完整配置 + 单独 save。
+            // 关联浏览弹窗显示列：新建的 EBuilder 字段自动配 ffDisplayColumns = 目标表业务字段（去系统字段，最多 5 个）。
+            // 直接带 ffDisplayColumns 进 jsonObj 不落库，需 getFormField 完整配置 + 单独 save。
             if (fieldType === 'EBuilder' && sformId) {
                 try {
-                    const tfd = await client.post(`${baseUrl}/api/ebuilder/form/dataset/v1/getFields`, {
-                        objId: sformId, userid: auth.userId, tenantKey: auth.tenantKey,
-                    });
-                    // 默认显示列最多 5 个（去系统字段后取前 5 个业务字段）
-                    const bizCols = (tfd?.data?.mainFields || [])
-                        .filter((f) => /^\d+$/.test(String(f.fieldId)))
-                        .map((f) => ({ id: String(f.fieldId), name: String(f.fieldName || f.title || '') }))
-                        .slice(0, 5);
-                    if (bizCols.length) {
-                        const gf = await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/getFormField`, { module: 'ebuilderform', formTableField: { formField: { id: fieldId, form: { id: formId } } } }, { ebbusinessid: formId });
-                        const full = gf?.data || {};
-                        if (full.fieldId) {
-                            await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/saveFormFieldNew?apid=${appId}`, { formId, module: 'ebuilderform', customParam: { appId, objId }, jsonObj: JSON.stringify({ ...full, ffDisplayColumns: bizCols }) }, { ebbusinessid: formId });
-                            console.error(`  关联显示列已自动配置 (${bizCols.length} 列)`);
-                        }
-                    }
+                    const applied = await ensureDisplayColumns(client, baseUrl, appId, objId, formId, fieldId, sformId, auth.userId, auth.tenantKey);
+                    if (applied)
+                        console.error(`  关联显示列已自动配置 (${applied} 列)`);
                 }
                 catch (e) {
                     console.error(`  关联显示列设置失败: ${e.message}`);
@@ -2564,6 +2643,8 @@ export function registerFormCommands(program) {
         .argument('<appId>', '应用 ID')
         .argument('<fieldId>', '字段 ID')
         .option('--title <title>', '修改字段标题')
+        .option('--type <type>', '修改字段类型（如 Text/Number/Date/Select/Department；取值同 form add-field 的 <fieldType>）。'
+        + '⚠ 字段已有数据时平台会拒绝')
         .option('--required', '设为必填')
         .option('--no-required', '取消必填')
         .option('--sform-id <id>', 'EBuilder 关联的目标表单 objId（更新关联）')
@@ -2573,6 +2654,11 @@ export function registerFormCommands(program) {
         .option('--relate-from-source <fieldId>', '目标表单源字段 fieldId（复制哪个字段的值）')
         .option('--multiple', '设为多选（人员/部门/EBuilder/关联类字段）')
         .option('--no-multiple', '设为单选（人员/部门/EBuilder/关联类字段）')
+        .option('--max-len <n>', '最大长度（正整数）。日期/时间/省市区/身份证/电子发票/下拉多选这几类没有该属性')
+        .option('--default <value>', '默认值（Text / TextArea / Number / Money）')
+        .option('--clear-default', '清空默认值')
+        .option('--data-key <key>', '数据库字段名（同时改 dataKey 与 columnName；字段已有数据时平台会拒绝）')
+        .option('--desc <text>', '字段描述（设计器字段属性里的「描述」）')
         .action(async (objId, appId, fieldId, editOpts) => {
         const opts = program.opts();
         const auth = await AuthSession.fromOptions(opts);
@@ -2609,48 +2695,35 @@ export function registerFormCommands(program) {
         }
         // Get formTableId for the payload
         const formTableId = formInfo?.formTableId || '';
-        // Try to get current field config, but if it fails (e.g. workflow sub-table),
-        // construct a minimal jsonObj from known parameters
-        let jsonObj = null;
-        try {
-            const fieldDetailRes = await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/getFormFieldPage?apid=${appId}`, {
-                pageNo: 1, pageSize: 200, module: 'ebuilderform',
-                customParam: { appId },
-                formFieldSearchEntity: { isDelete: 0, status: 'enable', formId },
-            }, { ebbusinessid: formId });
-            const records = fieldDetailRes?.data?.pageDatas?.result || fieldDetailRes?.data?.data?.records || fieldDetailRes?.data?.data || [];
-            const fieldDetail = records.find((r) => String(r.fieldId) === String(fieldId));
-            if (fieldDetail?.jsonObj) {
-                jsonObj = typeof fieldDetail.jsonObj === 'string'
-                    ? JSON.parse(fieldDetail.jsonObj)
-                    : fieldDetail.jsonObj;
-                if (fieldDetail.formId)
-                    formId = fieldDetail.formId;
-            }
-        }
-        catch { /* fall through to minimal jsonObj */ }
-        if (!jsonObj) {
-            // Couldn't get field via getFormFieldPage — try getFields
-            const fieldsRes = await client.post(`${baseUrl}/api/ebuilder/form/dataset/v1/getFields`, {
-                objId: resolvedObjId, userid: auth.userId, tenantKey: auth.tenantKey,
-            });
-            const allFields = [...(fieldsRes?.data?.mainFields || []), ...(fieldsRes?.data?.subFields || [])];
-            const gf = allFields.find((f) => String(f.fieldId) === String(fieldId));
-            let colName = gf?.columnName || gf?.dataKey || '';
-            if (!colName || /[^\x00-\x7F]/.test(colName)) {
-                // 中文/空 columnName（getFields 对 EBuilder 不返回 columnName）：用拼音首字母，
-                // 不用 fld_<id>（否则物理列变 fld_xxx，破坏"数据库字段名=首字母拼音"约定）
-                colName = toColumnName(String(gf?.fieldName || '')) || 'fld_' + fieldId.slice(-8);
-            }
-            jsonObj = {
-                type: gf?.fieldKey || gf?.fieldType || 'Text',
-                title: gf?.fieldName || '',
-                fieldId, formId, groupId: '-1',
-                formTableId: gf?.formTableId || formTableId,
-                showOrder: '0.00',
-                dataKey: colName, columnName: colName,
-                optionSerials: [],
-            };
+        // 读当前字段配置，作为**写回基底**。
+        // `saveFormFieldNew` 是全量覆盖：没带上的键会被服务端按默认值重置，所以基底必须尽量完整。
+        // `getFormFieldPage` 返回的是**扁平记录**（属性直接铺平，没有嵌套 jsonObj），
+        // 它本身就是该字段的属性集 —— 判定逻辑见 services/form-edit-base.ts。
+        // **读不到就中止**，绝不用 getFields 拼一个最小定义顶上（那会把真实类型改成 Text）。
+        const pageRecords = await fetchFieldPageRecords(client, baseUrl, appId, formId).catch(() => null);
+        const baseResult = resolveEditBasePure(pageRecords, fieldId);
+        if (!baseResult.ok) {
+            const seen = await peekViaGetFields(client, baseUrl, resolvedObjId, fieldId, auth);
+            console.error(`${describeEditBaseFailure(baseResult, fieldId)}，已中止，未做任何改动。`);
+            if (seen) {
+                console.error(`  getFields 里它被报成 type=${seen.fieldKey || seen.fieldType || '?'}` +
+                    `${seen.fieldName ? `（${seen.fieldName}）` : ''} —— 这是粗粒度信息，` +
+                    '拿它回写会把真实类型改掉，所以 CLI 不这么做。');
+            }
+            console.error('  该字段的类型可能是 CLI 暂不支持的（如「文档赋权对象」），请在表单设计器里维护。');
+            process.exit(1);
+        }
+        const jsonObj = baseResult.base;
+        if (pageRecords) {
+            const rec = pageRecords.find((r) => String(r?.fieldId) === String(fieldId));
+            if (rec?.formId)
+                formId = rec.formId;
+        }
+        // 写回前的最后一道闸：没有 type 就绝不落库。
+        // saveFormFieldNew 是全量覆盖，缺 type 会被服务端按默认类型（Text）补上。
+        if (!jsonObj.type && !editOpts.type) {
+            console.error(`读到的字段定义里没有 type（fieldId=${fieldId}），拒绝写回 —— 全量覆盖会把它改成默认类型。`);
+            process.exit(1);
         }
         // 兜底补 componentKey：saveFormFieldNew 要求（getComponentKey() 为 null 会 NPE）。
         // getFields 兜底路径建不出 componentKey，这里按类型映射补上。
@@ -2667,6 +2740,54 @@ export function registerFormCommands(program) {
         if (editOpts.title) {
             jsonObj.title = editOpts.title;
         }
+        // Apply type change（改字段类型）。
+        // 平台走的就是这个接口：读回字段 jsonObj → 改 `type` → 原样回写，不需要删字段重建。
+        // `type` 取值与 add-field 一致（CLI 规范名；富组件换成 platformType + componentKey），
+        // 回读时对应显示为 `form read` 的 fieldKey（如 Number→NumberComponent）。
+        // ⚠ 字段**已存在数据**时平台会拒绝改结构（报「此列已存在数据不可修改数据库字段名称」）。
+        if (editOpts.type) {
+            const targetType = canonComponentKey(editOpts.type);
+            assertFieldType(targetType, 'edit-field ');
+            // 关联类字段必须同时给目标表单，否则切出来的是个指不到东西的残缺字段
+            if (['EBuilder', 'Flow'].includes(targetType) && !editOpts.sformId && targetType !== String(jsonObj.type)) {
+                console.error(`改成 ${targetType} 需要同时指定 --sform-id <目标表 objId>（Flow 用流程绑定的表单 objId）`);
+                process.exit(1);
+            }
+            if (targetType !== String(jsonObj.type)) {
+                const richTarget = getRichType(targetType);
+                jsonObj.type = richTarget ? richTarget.platformType : targetType;
+                if (richTarget)
+                    jsonObj.componentKey = richTarget.platformComponentKey;
+                // 旧类型残留的组件键会在回读时盖过新类型，清掉让平台按新 type 推导
+                else
+                    delete jsonObj.componentKey;
+                // 富组件还要补**附加配置**，否则改出来的字段是残缺的：
+                // add-field 走的是同一张表的 build()，两边不一致会导致「新建的对、改类型的错」
+                // （实测 Time：改出来缺 minuteStep/timePanelStyle/defaultExtend，earlyDate/lateDate
+                //   还被平台兜底成 false，等于把时间选择器的可选范围锁死）。
+                if (richTarget?.build) {
+                    const extra = richIdUnits(targetType, {}) - 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 richTarget.build({
+                        // edit-field 没有 --format / --browser-* 选项：能带的只有 multiple，
+                        // 其余交给富组件模板的默认值（与 add-field 缺省时同一套默认）。
+                        def: { multiple: editOpts.multiple },
+                        fieldId,
+                        formId,
+                        formTableId,
+                        dataKey: String(jsonObj.dataKey || jsonObj.columnName || ''),
+                        columnName: String(jsonObj.columnName || jsonObj.dataKey || ''),
+                        showOrder: String(jsonObj.showOrder ?? '0.00'),
+                        extraIds,
+                    });
+                    Object.assign(jsonObj, extraCfg);
+                }
+            }
+        }
         // Apply required
         if (editOpts.required) {
             jsonObj.required = true;
@@ -2808,6 +2929,23 @@ export function registerFormCommands(program) {
                 };
             }
         }
+        // 长度 / 默认值 / 数据库字段名 / 描述：共用一套补丁规则（哪些类型适用、取值边界）。
+        // 放在类型变更之后 —— 改完 type 才知道该不该放行 maxLen 这类按类型受限的属性。
+        const patch = applyFieldPatches(jsonObj, {
+            maxLen: editOpts.maxLen,
+            defaultValue: editOpts.default,
+            clearDefault: editOpts.clearDefault,
+            dataKey: editOpts.dataKey,
+            desc: editOpts.desc,
+        });
+        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: resolvedObjId },
@@ -2818,6 +2956,8 @@ export function registerFormCommands(program) {
             const changes = [];
             if (editOpts.title)
                 changes.push(`title="${editOpts.title}"`);
+            if (editOpts.type)
+                changes.push(`type=${editOpts.type}`);
             if (editOpts.required)
                 changes.push('required');
             if (editOpts.noRequired)
@@ -2830,6 +2970,23 @@ export function registerFormCommands(program) {
                 changes.push(`relateFrom ${editOpts.relateFrom}→${editOpts.relateFromSource || ''}`);
             if (editOpts.multiple !== undefined)
                 changes.push(editOpts.multiple ? 'multiple' : '!multiple');
+            changes.push(...patch.applied);
+            // EBuilder 字段的浏览显示列：add-field 建出来的会自动配，edit-field 改出来的此前漏了这一步
+            // —— 字段能建出来，但浏览弹窗回落平台默认列，会把目标表的系统字段也列出来。
+            // ensureDisplayColumns 只在「没配过」或「旧列对不上当前目标表」时才写，不会冲掉手工配好的列。
+            if (['EBuilder', 'Ebuilder'].includes(String(jsonObj.type))) {
+                const targetId = String(jsonObj.sformId || '');
+                if (targetId) {
+                    try {
+                        const applied = await ensureDisplayColumns(client, baseUrl, appId, objId, formId, fieldId, targetId, auth.userId, auth.tenantKey);
+                        if (applied)
+                            changes.push(`浏览显示列=${applied}列`);
+                    }
+                    catch (e) {
+                        console.error(`  警告: 浏览显示列设置失败（字段本身已改好）: ${e.message}`);
+                    }
+                }
+            }
             const msg = opts.json ? JSON.stringify({ fieldId, changes }) : `字段已更新: ${fieldId} (${changes.join(', ') || 'no changes'})`;
             console.log(msg);
         }
@@ -2859,6 +3016,76 @@ export function registerFormCommands(program) {
             process.exit(1);
         }
     });
+    form.command('delete-field')
+        .description('删除表单字段（可批量）。**仍被表单布局引用的字段删不掉**，需先从布局移除')
+        .argument('<objId>', '表单 objId')
+        .argument('<appId>', '应用 ID')
+        .argument('<fieldIds...>', '字段 ID（可多个，一次批量删）')
+        .option('--force', '字段仍被布局引用时，先从布局移除再删（写操作，失败会中止）')
+        .action(async (objId, appId, fieldIds, cmdOpts) => {
+        const opts = program.opts();
+        const auth = await AuthSession.fromOptions(opts);
+        if (!auth)
+            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 formId = formInfo?.formId || '';
+        if (!formId) {
+            console.error('无法获取 formId，请确认 objId 和 appId 正确');
+            process.exit(1);
+        }
+        const del = async (ids) => client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/batchDeleteFormField?apid=${appId}`, { module: 'ebuilderform', formId, ids, customParam: { appId, objId } }, { ebbusinessid: formId });
+        let res = await del(fieldIds);
+        // 被布局引用的字段平台拒删。--force 时先从布局摘掉这些组件再重试。
+        // 布局的读/存沿用 form-layout.ts 那套已验证的端点（getFormLayout + saveFormAndLayout），不另造。
+        if (cmdOpts.force && (res?.code !== 200 || !res?.status)) {
+            const layoutRes = await client.post(`${baseUrl}/api/ebuilder/form/builder/getFormLayout`, {
+                formId, module: 'ebuilderform', customParam: {}, formTableIdList: [],
+                designerParam: { onlyLayout: false, convert: false }, form: { id: formId },
+            }, { ebbusinessid: formId });
+            if (layoutRes?.code !== 200 || !layoutRes?.status) {
+                console.error(`读取布局失败，未继续删除: ${layoutRes?.msg || '未知错误'}`);
+                process.exit(1);
+            }
+            const snapshot = layoutRes.data || {};
+            const pageLayouts = snapshot.formLayout?.pageLayouts;
+            if (!Array.isArray(pageLayouts)) {
+                console.error('布局数据格式异常（无 formLayout.pageLayouts），未继续删除');
+                process.exit(1);
+            }
+            // 摘组件（含「一个字段 = 本体 + 标题标签，靠 associatedId 配对」的坑）见
+            // services/form-field-drop.ts，与流程表单侧共用。
+            const removed = dropFieldComponents(pageLayouts, fieldIds);
+            if (!removed) {
+                console.error('布局里没找到这些字段的组件，无法自动移除；请到设计器里手动删除');
+                process.exit(1);
+            }
+            const formLayout = prepareLayoutForSave(snapshot.formLayout, formId);
+            const saveRes = await client.post(`${baseUrl}/api/ebuilder/form/builder/saveFormAndLayout`, {
+                module: 'ebuilderform', customParam: {},
+                designerParam: { onlyLayout: false, convert: false },
+                form: JSON.parse(JSON.stringify(snapshot.form || {})), formLayout,
+            }, { ebbusinessid: formId });
+            if (saveRes?.code !== 200 || !saveRes?.status) {
+                console.error(`从布局移除失败，未继续删除: ${saveRes?.msg || '未知错误'}`);
+                process.exit(1);
+            }
+            console.error(`  已从布局移除 ${removed} 个组件`);
+            res = await del(fieldIds);
+        }
+        if (res?.code === 200 && res?.status) {
+            console.log(opts.json
+                ? JSON.stringify({ success: true, deleted: fieldIds })
+                : `字段已删除: ${fieldIds.join(', ')}`);
+        }
+        else {
+            console.error(`删除失败: ${res?.msg || '未知错误'}`);
+            console.error('  提示: 仍被表单布局引用的字段平台不允许删除，请先从布局移除（或加 --force 让 CLI 代做）');
+            process.exit(1);
+        }
+    });
     form.command('list-view')
         .description('查看表单的台账/数据列表')
         .argument('<objId>', '表单 objId')