weaver-e10-builder 1.1.3 → 1.1.5

package/dist/commands/form.js

@@ -1,9 +1,11 @@
-import { writeFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
+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 } from '../services/form-sub-detail.js';
 import { getRichType, richIdUnits } from '../services/rich-types.js';
+import { registerOptionTemplateCommand } from './form-option-template.js';
 /**
  * componentKey 大小写归一：用户/示例常写 "Textarea"/"Ebuilder" 等小写变体，但代码各处
  * `=== 'TextArea'`、storageFieldType 按 canonical 大小写匹配。不归一会导致 type 存成小写
@@ -27,6 +29,30 @@ const SYSTEM_FIELD_IDS = new Set([
     'batchpubtags', 'batchmytags', 'operate', 'data_read_status',
     'flow_system_number',
 ]);
+/** 系统字段的中文名 → 物理字段 id（form read 实测的平台自带字段）。建表时字段与此完全重名 → 跳过新建、直接复用系统字段。 */
+const SYSTEM_FIELD_NAME_TO_ID = {
+    '标题': 'name',
+    '创建者': 'creator',
+    '创建时间': 'create_time',
+    '最后更新时间': 'update_time',
+    '数据ID': 'id',
+    '最后更新人': 'updater',
+    '数据状态': 'data_status',
+    '流程状态': 'flow_status',
+    '当前节点': 'current_step',
+    '流程编号': 'flow_system_number',
+};
+/** 布局 config 里可置可见的系统字段：中文名 → 布局 config 逻辑 id（getConfig/initLayout configs 用驼峰 id）。
+ * 命中的系统字段把布局置为可见（display/show）+ 独占一行；不在此表的（如流程状态）无布局 config 可置，仅跳过新建。 */
+const SYSTEM_FIELD_CFG_ID = {
+    '标题': 'name',
+    '创建者': 'creator',
+    '创建时间': 'createTime',
+    '最后更新时间': 'updateTime',
+    '数据ID': 'id',
+    '最后更新人': 'updater',
+    '数据状态': 'dataStatus',
+};
 // EBuilder dataTitle（关联字段标题栏）默认解析：优先字段名含「名称」的业务字段，无则第一个业务字段。
 // 需求：默认选带"名称"二字的字段（如 客户名称/类型名称），没有就默认选第一个。
 function defaultEBuilderDataTitle(fields) {
@@ -37,13 +63,13 @@ function defaultEBuilderDataTitle(fields) {
 }
 export function registerFormCommands(program) {
     const form = program.command('form').description('表单管理');
+    registerOptionTemplateCommand(form, program);
     form.command('read')
         .description('读取表单字段结构')
         .argument('<objId>', '表单 objId')
-        .argument('[dir]', '输出目录（可选，用于写入 memo.md）')
         .option('--out <file>', '将 JSON 输出写入文件（UTF-8，避免终端编码问题）')
         .option('--app-id <id>', '应用 ID（提供时自动获取 Select 字段的选项）')
-        .action(async (objId, dir, cmdOpts) => {
+        .action(async (objId, cmdOpts) => {
         const opts = program.opts();
         const auth = await AuthSession.fromOptions(opts);
         if (!auth)
@@ -69,7 +95,7 @@ export function registerFormCommands(program) {
                 for (const dt of detailTables) {
                     const dtName = dt.name || dt.subFormName || '(未命名明细表)';
                     for (const sf of (dt.fields || [])) {
-                        // 标注所属明细表名/subFormName，渲染与 memo 都用得上
+                        // 标注所属明细表名/subFormName，渲染展示用
                         if (!sf.subFormName)
                             sf.subFormName = dtName;
                         subFields.push(sf);
@@ -89,8 +115,13 @@ export function registerFormCommands(program) {
                     // Fetch options for Select/RadioBox/CheckBox fields (skip system fields with string IDs)
                     // 主表 + 明细表（子表）字段都取：之前只遍历主表，子表 Select 的 options 一直拿不到
                     const fetchOptions = async (f) => {
+                        // 多选下拉：摘要/读取里 fieldKey 是 SelectMultiple（fieldType 仍是 Select），
+                        // 类型判断必须同时认 SelectMultiple，否则选项不拉取、读取摘要不展示（D02）。
                         const ftype = f.fieldType || f.fieldKey || '';
-                        const isOptionField = ftype === 'Select' || ftype === 'RadioBox' || ftype === 'CheckBox';
+                        const fkey = f.fieldKey || f.fieldType || '';
+                        const isOptionField = ftype === 'Select' || ftype === 'SelectMultiple'
+                            || fkey === 'Select' || fkey === 'SelectMultiple'
+                            || ftype === 'RadioBox' || ftype === 'CheckBox';
                         // Use fieldId (actual field ID) not id (sequence number), and skip non-numeric IDs (system fields)
                         if (!isOptionField || !f.fieldId || !/^\d+$/.test(String(f.fieldId)))
                             return;
@@ -108,6 +139,10 @@ export function registerFormCommands(program) {
                             if (options.length > 0) {
                                 f.options = options.map((o) => ({ valueKey: o.valueKey, name: o.name }));
                             }
+                            // 选项预设模板：模板字段的 options 为空，回显模板引用（选项用 form option-template read 查）
+                            if (!options.length && fieldData?.data?.templateId) {
+                                f.optionTemplate = { id: String(fieldData.data.templateId), name: String(fieldData.data.templateName || '') };
+                            }
                         }
                         catch { /* ignore individual field failures */ }
                     };
@@ -132,8 +167,12 @@ export function registerFormCommands(program) {
                         customParam: { terminal: '', objId: formId }, initMode: 5, groupFieldIds: [],
                         designerParam: { sourceModule: 'ebuilderform' } }, { ebbusinessid: formId });
                     const attrByFieldId = {};
-                    for (const c of (cfgRes?.data?.configs || []))
+                    for (const c of (cfgRes?.data?.configs || [])) {
                         attrByFieldId[String(c.id)] = c;
+                        // DetailTable 子字段属性补读：子字段 required/readOnly 在布局 DetailTable children（D03）
+                        for (const ch of (c.children || []))
+                            attrByFieldId[String(ch.id)] = ch;
+                    }
                     for (const f of allFields) {
                         const c = attrByFieldId[String(f.fieldId)];
                         if (!c)
@@ -165,6 +204,8 @@ export function registerFormCommands(program) {
                 console.log(`  [${f.fieldKey || f.fieldType}] ${f.fieldName}  (fieldId: ${f.fieldId || f.id})`);
                 if (f.options)
                     console.log(`    选项: ${JSON.stringify(f.options)}`);
+                if (f.optionTemplate)
+                    console.log(`    选项模板: ${f.optionTemplate.name} (${f.optionTemplate.id})`);
             }
             if (subFields.length) {
                 console.log(`  -- 明细表字段 --`);
@@ -178,32 +219,6 @@ export function registerFormCommands(program) {
                 }
             }
         }
-        // Write memo.md if dir specified
-        if (dir && allFields.length > 0) {
-            if (!existsSync(dir))
-                mkdirSync(dir, { recursive: true });
-            let memo = `## 表单\n- 表单ID：${objId}\n`;
-            for (const f of fields) {
-                if (SYSTEM_FIELD_IDS.has(f.fieldId))
-                    continue;
-                memo += `- 字段名称：${f.fieldName}, 字段类型：${f.fieldKey}, 字段id:${f.fieldId || f.id}\n`;
-                if (f.fieldOptions)
-                    memo += `  选项：${JSON.stringify(f.fieldOptions)}\n`;
-            }
-            if (subFields.length) {
-                memo += `\n### 明细表字段\n`;
-                for (const f of subFields) {
-                    if (SYSTEM_FIELD_IDS.has(f.fieldId))
-                        continue;
-                    memo += `- 字段名称：${f.fieldName}, 字段类型：${f.fieldKey}, 字段id:${f.fieldId}${f.subFormName ? `, 明细表:${f.subFormName}` : ''}\n`;
-                    if (f.fieldOptions)
-                        memo += `  选项：${JSON.stringify(f.fieldOptions)}\n`;
-                }
-            }
-            memo += '- 字段名称：数据ID, 字段类型：Number, 字段id:id\n';
-            writeFileSync(`${dir}/memo.md`, memo, 'utf-8');
-            console.error('表单信息已记录于 memo.md');
-        }
     });
     form.command('list')
         .description('列出应用下的表单')
@@ -240,11 +255,10 @@ export function registerFormCommands(program) {
         .description('创建表单')
         .argument('<appId>', '应用 ID')
         .argument('<name>', '表单名称')
-        .argument('[dir]', '输出目录（可选，记录 memo.md）')
         .requiredOption('--fields <json>', '字段定义 JSON 文件路径（如 @fields.json），格式：[{"componentKey":"Text","fieldName":"姓名"}]')
         .option('--menu', '建表后添加台账菜单（默认不加；漏加可用 `e10-cli menu add-table` 补）')
         .option('--layout <type>', '表单布局类型：FLOW(流式)/EXCEL(表格，缺省)。布局类型建表后不可切换', 'EXCEL')
-        .action(async (appId, name, dir, cmdOpts) => {
+        .action(async (appId, name, cmdOpts) => {
         const opts = program.opts();
         const auth = await AuthSession.fromOptions(opts);
         if (!auth)
@@ -262,6 +276,8 @@ export function registerFormCommands(program) {
             console.error(`文件不存在: ${filePath}`);
             process.exit(1);
         }
+        const skippedSys = [];
+        const systemOverrides = [];
         let fieldDefs;
         try {
             fieldDefs = JSON.parse(readFileSync(filePath, 'utf-8'));
@@ -309,6 +325,24 @@ export function registerFormCommands(program) {
                 process.exit(1);
             }
         }
+        // 系统字段重名：字段名与平台自带系统字段完全重名 → 不新建物理字段（避免出现两条「标题」/「创建者」），
+        // 直接复用系统字段。可布局的系统字段（标题/创建者等）额外收进 systemOverrides → 布局置为可见/独占一行。
+        // 仅主表顶层字段参与；DetailTable 子字段（子表无系统字段名冲突）不在此列。
+        fieldDefs = fieldDefs.filter((f) => {
+            const sysId = SYSTEM_FIELD_NAME_TO_ID[String(f.fieldName ?? '').trim()];
+            if (sysId && f.componentKey !== 'DetailTable') {
+                skippedSys.push({ name: String(f.fieldName), sysId });
+                const cfgId = SYSTEM_FIELD_CFG_ID[String(f.fieldName ?? '').trim()];
+                if (cfgId) {
+                    systemOverrides.push({ configId: cfgId, singleRow: f.singleRow === true, hidden: f.hidden === true });
+                }
+                return false;
+            }
+            return true;
+        });
+        if (skippedSys.length) {
+            console.error(`⚠ 跳过 ${skippedSys.length} 个与系统字段重名的字段（平台已自带，复用不新建）: ${skippedSys.map((s) => `${s.name}`).join('、')}${systemOverrides.length ? '（已置为布局可见）' : ''}`);
+        }
         const makeField = (fid, fname, ck, row, col, fieldOptions, isDetail, subFields) => {
             const x = col * 950;
             const y = 35 + row * 52;
@@ -486,6 +520,8 @@ export function registerFormCommands(program) {
                 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,
@@ -494,13 +530,24 @@ export function registerFormCommands(program) {
                 // 否则 fields.json 标注的 maxLen/format 被丢（bug：长度默认 100 不生效、日期精度丢失）。
                 maxLen: f.maxLen, format: f.format,
             }));
-            const fieldResult = await addInitialFieldsToCustomPhysicalForm(client, baseUrl, appId, objId, formId, fieldDefsForStandard, auth.tenantKey, layoutType);
+            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 为空`);
+                }
+            }
         }
         catch (e) {
             console.error(`创建失败: ${e.message}`);
@@ -722,6 +769,85 @@ export function registerFormCommands(program) {
                 }
             }
         }
+        // Step 2a: Select 绑定选项预设模板（fields.json optionTemplate 属性）。
+        // 建表时字段已建成裸 Select（无选项），此处补 templateId/templateName/publicTemplate:false/options:[]。
+        // 浏览器抓包（2026-09-09）：带模板引用后平台渲染时按模板拉选项；回读 hasTemplate:true。
+        const tplFields = fieldDefs.filter(f => f.componentKey === 'Select' && f.optionTemplate && !(f.fieldOptions && f.fieldOptions.length));
+        if (tplFields.length > 0) {
+            console.error(`  绑定 ${tplFields.length} 个选项模板字段...`);
+            await resolveFormId();
+            // 字段名 → fieldId（建表后回查）
+            const fieldsRes = await client.post(`${baseUrl}/api/ebuilder/form/dataset/v1/getFields`, {
+                objId, userid: auth.userId, tenantKey: auth.tenantKey,
+            });
+            const mainFields = fieldsRes?.data?.mainFields || [];
+            // 模板解析缓存：ID 直查详情；名称在 custom+system 列表精确匹配
+            const tplCache = new Map();
+            const resolveTpl = async (idOrName) => {
+                if (tplCache.has(idOrName))
+                    return tplCache.get(idOrName);
+                let hit = null;
+                try {
+                    if (/^\d+$/.test(idOrName)) {
+                        const r = await client.post(`${baseUrl}/api/form/datasources/queryDataSourcesByTemplateValueKey`, { templateId: idOrName });
+                        if (r?.formDataTemplate?.id)
+                            hit = { id: String(r.formDataTemplate.id), name: String(r.formDataTemplate.name) };
+                    }
+                    else {
+                        for (const type of ['custom', 'system']) {
+                            const list = await client.post(`${baseUrl}/api/form/datasources/queryDataList`, { pageNo: 1, pageSize: 100, name: idOrName, type });
+                            const m = (list?.templatePage?.result || []).find((x) => x.name === idOrName);
+                            if (m) {
+                                hit = { id: String(m.id), name: String(m.name) };
+                                break;
+                            }
+                        }
+                    }
+                }
+                catch { /* keep null */ }
+                tplCache.set(idOrName, hit);
+                return hit;
+            };
+            for (const tf of tplFields) {
+                const tpl = await resolveTpl(tf.optionTemplate);
+                if (!tpl) {
+                    console.error(`    ⚠ 未找到选项模板「${tf.optionTemplate}」（字段 ${tf.fieldName} 跳过，仍为无选项 Select）`);
+                    continue;
+                }
+                const target = mainFields.find(f => f.fieldName === tf.fieldName);
+                if (!target) {
+                    console.error(`    ⚠ 未找到字段: ${tf.fieldName}`);
+                    continue;
+                }
+                try {
+                    // 取完整字段配置后叠加模板引用（保留平台已落的 columnName/formTableId 等）
+                    const gf = await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/getFormField`, { module: 'ebuilderform', formTableField: { formField: { id: target.fieldId, form: { id: resolvedFormId } } } }, { ebbusinessid: resolvedFormId });
+                    const full = gf?.data || {};
+                    if (!full.fieldId) {
+                        console.error(`    ⚠ 字段详情读取失败: ${tf.fieldName}`);
+                        continue;
+                    }
+                    const jsonObj = {
+                        ...full,
+                        options: [],
+                        templateId: tpl.id,
+                        templateName: tpl.name,
+                        publicTemplate: false,
+                        parentId: [],
+                    };
+                    const res = await client.post(`${baseUrl}/api/ebuilder/form/form/field/manage/saveFormFieldNew?apid=${appId}`, { formId: resolvedFormId, module: 'ebuilderform', customParam: { appId, objId }, jsonObj: JSON.stringify(jsonObj) }, { ebbusinessid: resolvedFormId });
+                    if (res?.code === 200 && res?.status) {
+                        console.error(`    已绑定模板: ${tf.fieldName} → ${tpl.name} (${tpl.id})`);
+                    }
+                    else {
+                        console.error(`    绑定失败: ${tf.fieldName} — ${res?.msg || '未知错误'}`);
+                    }
+                }
+                catch (e) {
+                    console.error(`    绑定异常: ${tf.fieldName} — ${e.message}`);
+                }
+            }
+        }
         // Step 2b: Flow 字段（浏览-流程）绑 sformId —— 对齐 EBuilder Step 2。
         // 之前 form create 只对 EBuilder 事后绑 sformId（Step 2），Flow 无对应步骤 → fields.json 里 Flow 的
         // sformId 被丢弃，字段建成无关联裸 Flow（"该字段未配置"）。此处补 Flow 的 sformId/relateExt 等，
@@ -1169,8 +1295,11 @@ export function registerFormCommands(program) {
             }
         }
         // Step 7: Configure Select/RadioBox/CheckBox field options and defaults
+        // D02: 多选下拉可直写 componentKey=SelectMultiple（不只是 Select+multiple:true），
+        // 类型判断漏掉它导致选项从不上配、保存后为空 —— 一并纳入。
         const optionFields = fieldDefs.filter(f => f.fieldOptions && f.fieldOptions.length > 0
-            && (f.componentKey === 'Select' || f.componentKey === 'RadioBox' || f.componentKey === 'CheckBox'));
+            && (f.componentKey === 'Select' || f.componentKey === 'SelectMultiple'
+                || f.componentKey === 'RadioBox' || f.componentKey === 'CheckBox'));
         if (optionFields.length > 0) {
             await resolveFormId();
             console.error(`  配置 ${optionFields.length} 个选项字段...`);
@@ -1214,17 +1343,27 @@ export function registerFormCommands(program) {
                     }
                     const { randomUUID } = await import('crypto');
                     const defaultVk = ofd.defaultValue;
+                    // valueKey 硬约束：必须是纯数字（平台规范+下游引用按数字处理）。非数字直接报错，不静默转换。
+                    for (const o of ofd.fieldOptions) {
+                        if (o.valueKey !== undefined && o.valueKey !== null && String(o.valueKey) !== '' && !/^\d+$/.test(String(o.valueKey))) {
+                            throw new Error(`字段「${ofd.fieldName}」选项「${o.name}」的 valueKey "${o.valueKey}" 必须是数字`);
+                        }
+                    }
                     const options = ofd.fieldOptions.map((o, i) => {
-                        const optId = genIds[genIdx++] || String(Date.now() + i);
+                        // valueKey=用户自定义选项值，必须为数字（平台规范，抓包样本均为数字）；
+                        // selectionId 与 valueKey 分离、留空由平台自动生成雪花号。未给 valueKey 时自动生成。
+                        const hasVk = o.valueKey !== undefined && o.valueKey !== null && String(o.valueKey) !== '';
+                        const fallback = genIds[genIdx++] || String(Date.now() + i);
+                        const valueKey = hasVk ? String(o.valueKey) : fallback;
                         return {
                             other: false,
-                            selectionId: optId,
-                            defOption: defaultVk ? (o.valueKey === defaultVk) : false,
+                            selectionId: '',
+                            defOption: defaultVk ? (valueKey === String(defaultVk)) : false,
                             styleConfig: {}, archive: false, divisionBranch: false,
                             subCompanyCatalogues: [], dataCount: i === 0 ? ofd.fieldOptions.length : 0,
                             score: '0', uid: randomUUID(), children: [], extra: {},
                             name: o.name, isLimit: false,
-                            valueKey: optId,
+                            valueKey,
                             componentKey: 'Option', order: i, fieldId: targetField.fieldId,
                         };
                     });
@@ -1276,7 +1415,8 @@ export function registerFormCommands(program) {
             .filter(f => f.componentKey === 'DetailTable' && Array.isArray(f.formFields))
             .flatMap(dt => (dt.formFields || [])
             .filter(sf => sf.fieldOptions && sf.fieldOptions.length > 0
-            && (sf.componentKey === 'Select' || sf.componentKey === 'RadioBox' || sf.componentKey === 'CheckBox'))
+            && (sf.componentKey === 'Select' || sf.componentKey === 'SelectMultiple'
+                || sf.componentKey === 'RadioBox' || sf.componentKey === 'CheckBox'))
             .map(sf => ({ ...sf, __detailTable: dt.fieldName })));
         if (detailOptionDefs.length > 0) {
             await resolveFormId();
@@ -1340,13 +1480,16 @@ export function registerFormCommands(program) {
                     const dataKey = cur.dataKey || toColumnName(sfDef.fieldName);
                     const { randomUUID } = await import('crypto');
                     const options = sfDef.fieldOptions.map((o, i) => {
-                        const optId = subGenIds[subGenIdx++] || String(Date.now() + i);
+                        // 同主表：valueKey=用户自定义必须数字；selectionId 留空平台生成
+                        const hasVk = o.valueKey !== undefined && o.valueKey !== null && String(o.valueKey) !== '';
+                        const fallback = subGenIds[subGenIdx++] || String(Date.now() + i);
+                        const valueKey = hasVk ? String(o.valueKey) : fallback;
                         return {
-                            other: false, selectionId: optId, defOption: false,
+                            other: false, selectionId: '', defOption: false,
                             styleConfig: {}, archive: false, divisionBranch: false,
                             subCompanyCatalogues: [], dataCount: i === 0 ? sfDef.fieldOptions.length : 0,
                             score: '0', uid: randomUUID(), children: [], extra: {},
-                            name: o.name, isLimit: false, valueKey: optId,
+                            name: o.name, isLimit: false, valueKey,
                             componentKey: 'Option', order: i, fieldId: subFieldId,
                         };
                     });
@@ -1580,10 +1723,10 @@ export function registerFormCommands(program) {
             console.error(`  显示列兜底失败: ${e.message}（可用 \`e10-cli form table-view ensure ${objId} ${appId}\` 手动补加）`);
         }
         if (opts.json) {
-            console.log(JSON.stringify({ objId, name, menuId }));
+            console.log(JSON.stringify({ objId, name, menuId, skippedSys }));
         }
         else {
-            console.log(`完成: ${objId}`);
+            console.log(`完成: ${objId}${skippedSys.length ? `（跳过系统字段重名: ${skippedSys.map((s) => s.name).join('、')}）` : ''}`);
         }
     });
     const linkageCmd = form.command('linkage').description('表单字段显隐联动管理');
@@ -1809,10 +1952,15 @@ export function registerFormCommands(program) {
         catch { /* best effort */ }
         // Build options with defOption
         const { randomUUID } = await import('crypto');
-        // valueKey 统一由平台生成（与 form create 一致）。已有数据的字段系统会拒绝修改（保险），
-        // 所以无需保留旧 key：能改的字段必然没数据，全新生成最安全、也绝不会踩 selectionId 的 parseLong。
-        // 用户显式传纯数字 valueKey 时尊重（进阶用），非数字忽略并告警。
-        const isNumeric = (vk) => vk !== undefined && vk !== null && vk !== '' && /^\d+$/.test(String(vk));
+        // valueKey=用户自定义选项值，必须是纯数字（平台规范+下游引用按数字处理），非数字直接报错；
+        // selectionId 与 valueKey 分离、留空由平台自动生成雪花号。未给 valueKey 自动生成。
+        // 已有数据的字段平台会拒绝修改，无需保留旧 selectionId。
+        for (const o of optionDefs) {
+            if (o.valueKey !== undefined && o.valueKey !== null && String(o.valueKey) !== '' && !/^\d+$/.test(String(o.valueKey))) {
+                console.error(`❌ 选项「${o.name}」的 valueKey "${o.valueKey}" 必须是数字`);
+                process.exit(1);
+            }
+        }
         let genIds = [];
         try {
             const genRes = await client.post(`${baseUrl}/api/form/local/generatorIds?size=${optionDefs.length + 1}&apid=${appId}`, {});
@@ -1820,17 +1968,12 @@ export function registerFormCommands(program) {
         }
         catch { /* fallback to timestamp */ }
         const options = optionDefs.map((o, i) => {
-            // 优先级：纯数字 valueKey > 平台新 ID > 时间戳兜底
-            let valueKey = isNumeric(o.valueKey) ? String(o.valueKey) : '';
-            if (!valueKey)
-                valueKey = genIds[i] || String(Date.now() + i);
-            if (o.valueKey && !isNumeric(o.valueKey)) {
-                console.error(`  ⚠ ${o.name}: 忽略非数字 valueKey "${o.valueKey}"（平台 selectionId 只接受数字），已重新生成 ${valueKey}`);
-            }
+            const hasVk = o.valueKey !== undefined && o.valueKey !== null && String(o.valueKey) !== '';
+            const valueKey = hasVk ? String(o.valueKey) : (genIds[i] || String(Date.now() + i));
             return {
                 other: false,
-                selectionId: valueKey,
-                defOption: cmdOpts.default === valueKey,
+                selectionId: '',
+                defOption: cmdOpts.default !== undefined && cmdOpts.default !== null && String(cmdOpts.default) === valueKey,
                 styleConfig: {}, archive: false, divisionBranch: false, subCompanyCatalogues: [],
                 dataCount: i === 0 ? optionDefs.length : 0,
                 score: '0', uid: randomUUID(), children: [], extra: {},
@@ -1912,6 +2055,7 @@ export function registerFormCommands(program) {
         .option('--multiple', '多选（人员/部门/EBuilder/Browser/下拉Select，默认单选。下拉多选=SelectMultiple 类型）')
         .option('--max-len <n>', '文本最大长度（Text 缺省 100、TextArea 缺省 4000）')
         .option('--single-row', '独占一行显示（布局 singleRow:true，其余字段仍两列）')
+        .option('--option-template <idOrName>', 'Select 绑定选项预设模板（ID 或名称；选项不内联，options=[]）')
         .action(async (objId, appId, fieldName, fieldType, title, cmdOptsRaw) => {
         // fieldType 大小写归一（与建表一致）：用户常传 "Textarea"/"Ebuilder"，不归一则 type 存小写
         // "Textarea"（FLOW 渲染异常）、TextArea 分支漏跑。
@@ -2234,6 +2378,62 @@ export function registerFormCommands(program) {
             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）绑定；多选+模板组合未验证');
+            }
+        }
         const payload = {
             formId, module: 'ebuilderform',
             customParam: { appId, objId },