weaver-e9-assistant-cli 1.1.4 → 1.1.11

package/dist/teamreport.js

@@ -0,0 +1,77 @@
+/**
+ * 下属日报批量查询（按人并发）。
+ *
+ * 背景：CLI 原先没有「一次查多个下属日报」的入口，AI 只能逐个下属调用，
+ * 每次都是新进程 + 一次请求，N 个下属就 N 次排队。
+ *
+ * 本模块按人并发调用微博主页接口（blogUserId 不同、彼此独立，可安全并发）：
+ *   1) subordinateinfo/getSearchResult → dataKey（一次）
+ *   2) table/datas 大页拉全下属（串行翻页，同一 dataKey 不可并发）
+ *   3) 每个下属 GET /api/blog/base/getBlogHomepageList?blogUserId=<id>&startDate=endDate=date
+ *      并发上限 TEAM_REPORT_CONCURRENCY
+ *
+ * 判定：当天存在 isReCalled=0（非撤回）的微博 → 已写日报；仅撤回/无记录 → 未写。
+ */
+import { getBlogHomepageList, isBlogRecalled } from './blog.js';
+import { listAllSubordinates } from './subordinate.js';
+import { mapLimit, todayStr } from './util.js';
+
+/** 按人并发上限：下属数量可能很多，限流避免打满服务端。 */
+export const TEAM_REPORT_CONCURRENCY = 5;
+
+/** 条目是否属于目标日期（workdate 优先，回退 createdate；无日期字段时按接口已按日期过滤处理）。 */
+export function isReportOnDate(item, date) {
+    const workdate = String(item?.workdate ?? '').trim();
+    if (workdate)
+        return workdate.startsWith(date);
+    const createdate = String(item?.createdate ?? '').trim();
+    if (createdate)
+        return createdate.startsWith(date);
+    return true;
+}
+
+/**
+ * 批量查询下属日报。
+ * 返回 { date, allLevel, total, writtenCount, items, unmatched, complete }。
+ * items[i] = { id, name, written, count, recalled, posts, error }。
+ */
+export async function collectSubordinateReports(cfg, { date, allLevel = false, names = [], concurrency = TEAM_REPORT_CONCURRENCY } = {}) {
+    const targetDate = date ?? todayStr();
+    const subs = await listAllSubordinates(cfg, { allLevel, names });
+    const items = await mapLimit(subs.items, concurrency, async (person) => {
+        try {
+            const r = await getBlogHomepageList(cfg, {
+                scope: '全部',
+                blogUserId: person.id,
+                startDate: targetDate,
+                endDate: targetDate,
+            });
+            const dayItems = r.items.filter((it) => isReportOnDate(it, targetDate));
+            const normal = dayItems.filter((it) => !isBlogRecalled(it));
+            return {
+                id: person.id,
+                name: person.name,
+                written: normal.length > 0,
+                count: normal.length,
+                recalled: dayItems.length - normal.length,
+                posts: normal,
+                error: null,
+            };
+        }
+        catch (e) {
+            // 单人失败不拖垮整批：保留错误，由调用方展示
+            return {
+                id: person.id, name: person.name, written: false, count: 0, recalled: 0, posts: [], error: e?.message ?? String(e),
+            };
+        }
+    });
+    return {
+        date: targetDate,
+        allLevel: !!allLevel,
+        total: items.length,
+        writtenCount: items.filter((x) => x.written).length,
+        items,
+        unmatched: subs.unmatched,
+        complete: subs.complete,
+    };
+}

package/dist/todobatch.js

@@ -39,16 +39,25 @@ function pickRandomFields(row) {
     return out;
 }
 
-/** 拉待办列表并取出与 requestIds 匹配的原始行（含 randomField）+ dataKey。跨页匹配直到全部命中或到末尾。 */
-async function loadRowsFor(cfg, requestIds) {
-    // 修复 #6：逐页定位待办是最耗时环节，实时打印进度，避免长时间无输出被误判卡死。
+/** 分类 → 人类可读列表名（用于进度与报错文案）。 */
+const CATEGORY_LABEL = { todo: '待办（待处理）', done: '已办', mine: '我发起的' };
+
+/**
+ * 在指定分类列表中取出与 requestIds 匹配的原始行（含 randomField）+ dataKey。跨页匹配直到全部命中或到末尾。
+ * opts.category：'todo'（默认，待处理）/ 'done'（已办）/ 'mine'（我发起的）——关注在三个分类里都可用；
+ *   提交/转发只对待办有意义，调用方自行传 'todo'。
+ */
+async function loadRowsFor(cfg, requestIds, opts = {}) {
+    const category = opts.category ?? 'todo';
+    const label = CATEGORY_LABEL[category] ?? category;
+    // 修复 #6：逐页定位是最耗时环节，实时打印进度，避免长时间无输出被误判卡死。
     const wanted = new Set(requestIds.map(String));
     const found = new Map();
     let dataKey = '';
-    console.error(`  [批量] 正在待办列表定位 ${requestIds.length} 条流程（按请求顺序逐页搜索）...`);
+    console.error(`  [批量] 正在「${label}」列表定位 ${requestIds.length} 条流程（按请求顺序逐页搜索）...`);
     for (let current = 1; current <= 10; current++) {
-        console.error(`  [批量] 读取待办第 ${current} 页...`);
-        const list = await getWfList(cfg, { category: 'todo', page: current, pageSize: '100' });
+        console.error(`  [批量] 读取${label}第 ${current} 页...`);
+        const list = await getWfList(cfg, { category, page: current, pageSize: '100' });
         dataKey = list.dataKey || dataKey;
         const rows = extractRows(list.raw?.datas);
         for (const row of rows) {
@@ -64,7 +73,7 @@ async function loadRowsFor(cfg, requestIds) {
     }
     const missing = requestIds.map(String).filter((id) => !found.has(id));
     if (missing.length)
-        throw new Error(`批量操作需要在待办列表中定位这 ${missing.length} 条，未找到：${missing.join(', ')}。请确认 request-id 属于当前待办（待处理），或该待办已不在列表中。`);
+        throw new Error(`批量操作需要在「${label}」列表中定位这 ${missing.length} 条，未找到：${missing.join(', ')}。请确认 request-id 属于该列表（可用 --category 切换 待办/已办/我发起），或该流程已不在列表中。`);
     // 保持调用方传入顺序，便于回执与 multiSubIds 对应
     const rows = requestIds.map((id) => found.get(String(id)));
     return { dataKey, rows };
@@ -150,12 +159,14 @@ export async function batchAttention(cfg, opts) {
     const attentionId = String(opts.attentionId ?? types[0]?.id ?? '');
     if (!attentionId)
         throw new Error('未能获取关注类型（getAttentionTypeSet 返回空），请确认该环境的“关注类型”已配置，或手动传 --attention-id。');
-    const { dataKey, rows } = await loadRowsFor(cfg, requestIds);
+    // 关注在 待办/已办/我发起 三个分类下都有「我的关注」页签，故定位列表可指定（默认待办）
+    const category = opts.category ?? 'todo';
+    const { dataKey, rows } = await loadRowsFor(cfg, requestIds, { category });
     const gate = await runGate(api, 'batchAttention', rows, dataKey);
     const result = await api.post('/api/workflow/requestAttention/saveAttention', {
         src: 'batchadd',
         requestids: requestIds.join(','),
         ids: attentionId + ',',
     });
-    return { requestIds, attentionTypes: types, attentionId, gate, result };
+    return { requestIds, category, attentionTypes: types, attentionId, gate, result };
 }

package/dist/tododetail.js

@@ -0,0 +1,516 @@
+/**
+ * 待办提交的明细行规划（添加 / 修改 / 删除）。
+ *
+ * 权威格式来自 E9 前端 `/spa/workflow/static4form/index.js` 的 `generateFormData`：
+ *   - nodesnum<idx>      = 存活行数
+ *   - indexnum<idx>      = 明细表行下标计数器（新增行 +1，删除不回退）
+ *   - submitdtlid<idx>   = 存活行下标升序 + 尾逗号（如 "0,1,3,"）
+ *   - dtl_id_<idx>_<row> = 已有行的 keyid（新增行不写）
+ *   - deldtlid<idx>      = 被删除已有行的 keyid，逗号分隔
+ *   - field<id>_<row>    = 本次提交的明细字段值（浏览器会全量提交；这里只提交改动行/新增行）
+ *   - detailFieldUnEmptyCount = 所有存活行中非空明细字段总数
+ *
+ * 已有行的 keyid / indexnum 来自 POST /api/workflow/reqform/detailData：
+ *   body { requestid, detailmark: "detail_1,detail_2", reqParams: JSON.stringify(commonApiParam) }
+ *   响应 { detail_1: { indexnum, rowDatas: { row_0: { keyid, field<id>: { value } } } } }
+ */
+
+export const COMMON_API_PARAM_RANGE = [
+    'requestid', 'workflowid', 'nodeid', 'formid', 'isbill',
+    'f_weaver_belongto_userid', 'f_weaver_belongto_usertype',
+    'authStr', 'authSignatureStr', 'signatureSecretKey', 'signatureAttributesStr',
+    'nodetype', 'iscreate', 'isfromtab', 'isviewonly', 'isaffirmance', 'isshared',
+    'iswfshare', 'ismode', 'modeid', 'isagent', 'beagenter', 'toexcel', 'creater',
+    'needconfirm', 'creatertype', 'requestType', 'isSelfAuth', 'isprint',
+    'wfmonitor', 'isurger', 'intervenorright', 'isSubmitDirect', 'selectNextFlow',
+    'agentType', 'agentorByAgentId', 'layouttype', 'freeNodeExtendNodeId',
+    'apiResultCacheKey',
+];
+
+const DETAIL_KEY_RE = /^(?:field)?(-?\d+)_(\d+)$/;
+
+export function isDetailTableKey(key) {
+    return /^detail_\d+$/.test(String(key ?? ''));
+}
+
+export function detailIndexFromKey(key) {
+    const m = String(key ?? '').match(/^detail_(\d+)$/);
+    return m ? Number(m[1]) - 1 : null;
+}
+
+export function normalizeFieldId(key) {
+    const s = String(key ?? '').trim();
+    return s.startsWith('field') ? s.slice('field'.length) : s;
+}
+
+/** 从 loadForm 的 tableInfo 构造字段元数据表（fieldId → { table, htmltype, raw, ... }）。 */
+export function fieldMetaMap(tableInfo) {
+    const map = new Map();
+    for (const [tableKey, table] of Object.entries(tableInfo ?? {})) {
+        const fmap = table?.fieldinfomap;
+        if (!fmap || typeof fmap !== 'object')
+            continue;
+        for (const [fid, f] of Object.entries(fmap)) {
+            map.set(String(fid), {
+                id: String(fid),
+                label: f?.fieldlabel,
+                table: tableKey,
+                htmltype: f?.htmltype === undefined || f?.htmltype === null || f?.htmltype === '' ? undefined : Number(f.htmltype),
+                detailtype: f?.detailtype === undefined || f?.detailtype === null || f?.detailtype === '' ? undefined : String(f.detailtype),
+                raw: f ?? {},
+            });
+        }
+    }
+    return map;
+}
+
+/** 该键是否是「已知明细字段 + 行号」的明细键；主表字段带 _<row> 的旧用法不在此列。 */
+export function isDetailValueKey(key, fieldById) {
+    const m = String(key ?? '').match(DETAIL_KEY_RE);
+    if (!m)
+        return false;
+    const meta = fieldById?.get(m[1]);
+    return Boolean(meta && isDetailTableKey(meta.table));
+}
+
+export function pickCommonApiParams(params = {}) {
+    const out = {};
+    for (const k of COMMON_API_PARAM_RANGE) {
+        const v = params?.[k];
+        if (v !== undefined && v !== null && v !== '')
+            out[k] = String(v);
+    }
+    return out;
+}
+
+/**
+ * 读取当前请求的明细行（keyid + 字段值 + indexnum）。
+ * @returns Map<number, { key: string, indexnum: number, rows: Map<number,{keyid:number|null, values:Object}> }>
+ */
+export async function fetchTodoDetailRows(api, params, tableInfo) {
+    const marks = Object.keys(tableInfo ?? {}).filter(isDetailTableKey);
+    const out = new Map();
+    if (marks.length === 0)
+        return out;
+    // 与前端 urlParams 一致：把 loadForm.params 的非空项全部带上（674 实测：只带子集时
+    // detailData 会 500；带全量后正常）。reqParams 仍按 commonApiParamRange 裁剪。
+    const top = {};
+    for (const [k, v] of Object.entries(params ?? {})) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        top[k] = String(v);
+    }
+    const body = {
+        ...top,
+        requestid: String(params?.requestid ?? ''),
+        detailmark: marks.join(','),
+        reqParams: JSON.stringify(pickCommonApiParams(params)),
+    };
+    const r = await api.post('/api/workflow/reqform/detailData', body);
+    const j = r.json ?? {};
+    const root = marks.some((k) => j[k] && typeof j[k] === 'object')
+        ? j
+        : (j.datas && typeof j.datas === 'object' ? j.datas : j);
+    for (const key of marks) {
+        const idx = detailIndexFromKey(key);
+        const t = root?.[key];
+        if (!t || typeof t !== 'object')
+            continue;
+        if (!t.rowDatas || typeof t.rowDatas !== 'object') {
+            throw new Error(`明细数据接口未返回 ${key}.rowDatas，无法安全计算行控制字段（可能无权限或接口结构变化）`);
+        }
+        const indexnum = Number(t.indexnum);
+        if (!Number.isFinite(indexnum) || indexnum < 0) {
+            throw new Error(`明细数据接口未返回合法的 ${key}.indexnum，无法安全新增/删除行`);
+        }
+        const rows = new Map();
+        for (const [rowKey, rowData] of Object.entries(t.rowDatas)) {
+            const m = String(rowKey).match(/^row_(\d+)$/);
+            if (!m || !rowData || typeof rowData !== 'object')
+                continue;
+            const rowIndex = Number(m[1]);
+            let keyid = null;
+            if (rowData.keyid !== undefined && rowData.keyid !== null && rowData.keyid !== '') {
+                keyid = Number(rowData.keyid);
+                if (!Number.isFinite(keyid))
+                    throw new Error(`明细表 ${key} 第 ${rowIndex} 行的 keyid 非法：${rowData.keyid}`);
+            }
+            const values = {};
+            for (const [k, v] of Object.entries(rowData)) {
+                const fm = k.match(/^field(-?\d+)$/);
+                if (!fm)
+                    continue;
+                const value = v && typeof v === 'object' && Object.prototype.hasOwnProperty.call(v, 'value')
+                    ? v.value
+                    : v;
+                values[fm[1]] = value === undefined || value === null ? '' : String(value);
+            }
+            rows.set(rowIndex, { keyid, values });
+        }
+        out.set(idx, { key, indexnum, rows });
+    }
+    return out;
+}
+
+/** 规范化 --detail-file 的 JSON（CLI 已完成 JSON.parse；这里只做结构与类型校验）。 */
+export function parseDetailFileSpec(spec) {
+    if (!Array.isArray(spec))
+        throw new Error('--detail-file 应为数组 [{index, rows:[...], deleteRows:[...]}]');
+    const out = [];
+    spec.forEach((entry, i) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            throw new Error(`--detail-file 第 ${i + 1} 项不是对象`);
+        const index = Number(entry.index);
+        if (!Number.isInteger(index) || index < 0)
+            throw new Error(`--detail-file 第 ${i + 1} 项 index 非法：${entry.index}（应为 0 起的明细表序号）`);
+        const rows = [];
+        const rawRows = entry.rows ?? [];
+        if (!Array.isArray(rawRows))
+            throw new Error(`--detail-file 第 ${i + 1} 项 rows 应为数组`);
+        rawRows.forEach((raw, ri) => {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                throw new Error(`--detail-file 第 ${i + 1} 项第 ${ri + 1} 行不是对象`);
+            const row = { values: {} };
+            if (raw.rowIndex !== undefined && raw.rowIndex !== null && raw.rowIndex !== '') {
+                const rowIndex = Number(raw.rowIndex);
+                if (!Number.isInteger(rowIndex) || rowIndex < 0)
+                    throw new Error(`--detail-file 第 ${i + 1} 项第 ${ri + 1} 行 rowIndex 非法：${raw.rowIndex}`);
+                row.rowIndex = rowIndex;
+            }
+            for (const [k, v] of Object.entries(raw)) {
+                if (k === 'rowIndex')
+                    continue;
+                const id = normalizeFieldId(k);
+                if (!/^-?\d+$/.test(id))
+                    continue;
+                row.values[id] = v === undefined || v === null ? '' : String(v);
+            }
+            if (Object.keys(row.values).length === 0)
+                throw new Error(`--detail-file 第 ${i + 1} 项第 ${ri + 1} 行没有任何字段值`);
+            rows.push(row);
+        });
+        const deleteRows = [];
+        const rawDeletes = entry.deleteRows ?? [];
+        if (!Array.isArray(rawDeletes))
+            throw new Error(`--detail-file 第 ${i + 1} 项 deleteRows 应为数组`);
+        rawDeletes.forEach((v) => {
+            const rowIndex = Number(v);
+            if (!Number.isInteger(rowIndex) || rowIndex < 0)
+                throw new Error(`--detail-file 第 ${i + 1} 项 deleteRows 含非法行号：${v}`);
+            deleteRows.push(rowIndex);
+        });
+        out.push({ index, rows, deleteRows });
+    });
+    return out;
+}
+
+/**
+ * 规划待办明细变更（纯函数，不发送请求）。
+ *
+ * @param {object} args
+ * @param {object} args.tableInfo loadForm.tableInfo
+ * @param {Map}    args.detailRows fetchTodoDetailRows 的结果
+ * @param {object} args.fieldValues --field-values 原始对象
+ * @param {Array}  args.detailFile parseDetailFileSpec 的结果
+ * @param {Array}  args.files [{fieldId, filePath}]
+ * @returns {{tables:Array, mainChanges:Object, changedMainKeys:string[], changedDetailKeys:string[], fileTargets:Array, warnings:string[]}}
+ */
+export function planTodoDetails({ tableInfo, detailRows, fieldValues = {}, detailFile = [], files = [] }) {
+    const fieldById = fieldMetaMap(tableInfo);
+    const touched = new Map();
+    const warnings = [];
+
+    const ensureTable = (idx) => {
+        if (touched.has(idx))
+            return touched.get(idx);
+        const key = `detail_${idx + 1}`;
+        const table = tableInfo?.[key];
+        if (!table)
+            throw new Error(`明细表 ${key} 不在当前表单（index=${idx}）`);
+        const data = detailRows?.get(idx);
+        if (!data || !(data.rows instanceof Map))
+            throw new Error(`未取到 ${key} 的明细数据，无法安全修改明细行（detailData 未返回该表）`);
+        const rows = new Map();
+        for (const [rowIndex, row] of data.rows)
+            rows.set(rowIndex, { keyid: row.keyid ?? null, values: { ...row.values }, send: {}, isNew: false, changed: false });
+        const indexnum = Number(data.indexnum);
+        if (!Number.isFinite(indexnum) || indexnum < 0)
+            throw new Error(`明细表 ${key} 的 indexnum 非法：${data.indexnum}`);
+        const attr = table.detailtableattr ?? {};
+        if (Number(attr.isopenpaging) === 1)
+            warnings.push(`明细表 ${key} 开启了分页（isopenpaging=1）；已按 detailData 全量行处理，请提交后核对行数。`);
+        const maxRow = rows.size > 0 ? Math.max(...rows.keys()) + 1 : 0;
+        const t = {
+            idx, key, attr, rows,
+            indexnum,
+            nextIndex: Math.max(indexnum, maxRow),
+            userSet: new Map(),
+            changedRows: new Set(),
+            changedKeys: new Set(),
+            deleted: new Set(),
+            deletedKeyids: [],
+            added: [],
+        };
+        touched.set(idx, t);
+        return t;
+    };
+
+    const requireFieldInTable = (meta, t, fid) => {
+        if (!meta)
+            throw new Error(`字段 ${fid} 不在当前表单`);
+        if (meta.table !== t.key)
+            throw new Error(`字段 ${fid} 属于 ${meta.table}，不能写入明细表 ${t.key}（行号写错或明细表 index 不对）`);
+    };
+
+    const setUserValue = (t, rowIndex, fid, value, source) => {
+        const row = t.rows.get(rowIndex);
+        if (!row)
+            throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行不存在；新增行请不要带 rowIndex`);
+        if (t.deleted.has(rowIndex))
+            throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行已被 deleteRows 删除，不能再修改`);
+        const userKey = `${rowIndex}:${fid}`;
+        const text = String(value ?? '');
+        const prev = t.userSet.get(userKey);
+        if (prev && prev.value !== text) {
+            throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行字段 ${fid} 同时被 ${prev.source} 和 ${source} 设置为不同值（"${prev.value}" vs "${text}"）`);
+        }
+        t.userSet.set(userKey, { value: text, source });
+        row.values[fid] = text;
+        row.send[fid] = text;
+        row.changed = true;
+        t.changedRows.add(rowIndex);
+        t.changedKeys.add(`field${fid}_${rowIndex}`);
+    };
+
+    // ① --detail-file：更新已有行 / 新增行 / 删除行
+    for (const entry of detailFile) {
+        const t = ensureTable(entry.index);
+        for (const rowSpec of entry.rows) {
+            if (rowSpec.rowIndex !== undefined) {
+                for (const [fid, value] of Object.entries(rowSpec.values)) {
+                    requireFieldInTable(fieldById.get(fid), t, fid);
+                    setUserValue(t, rowSpec.rowIndex, fid, value, '--detail-file');
+                }
+                continue;
+            }
+            if (Number(t.attr.isadd) !== 1)
+                throw new Error(`明细表 ${t.key} 当前节点不允许新增行（detailtableattr.isadd=${t.attr.isadd}）`);
+            const rowIndex = t.nextIndex++;
+            const row = { keyid: null, values: {}, send: {}, isNew: true, changed: true };
+            t.rows.set(rowIndex, row);
+            t.added.push(rowIndex);
+            t.changedRows.add(rowIndex);
+            for (const [fid, value] of Object.entries(rowSpec.values)) {
+                requireFieldInTable(fieldById.get(fid), t, fid);
+                row.values[fid] = String(value ?? '');
+                row.send[fid] = String(value ?? '');
+                t.changedKeys.add(`field${fid}_${rowIndex}`);
+                t.userSet.set(`${rowIndex}:${fid}`, { value: String(value ?? ''), source: '--detail-file' });
+            }
+        }
+        for (const rowIndex of entry.deleteRows) {
+            if (t.deleted.has(rowIndex))
+                continue;
+            if (Number(t.attr.isdelete) !== 1)
+                throw new Error(`明细表 ${t.key} 当前节点不允许删除行（detailtableattr.isdelete=${t.attr.isdelete}）`);
+            const row = t.rows.get(rowIndex);
+            if (!row)
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行不存在，无法删除`);
+            if (row.isNew)
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行是本次新增行，删除请直接从 --detail-file 移除该行`);
+            if (row.changed || [...t.userSet.keys()].some((k) => k.startsWith(`${rowIndex}:`)))
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行同时被修改和删除，请二选一`);
+            if (row.keyid === null || row.keyid === undefined)
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行缺少 keyid，无法安全删除`);
+            t.deleted.add(rowIndex);
+            t.deletedKeyids.push(row.keyid);
+        }
+    }
+
+    // ② --field-values 里的明细键（field<id>_<row>）
+    for (const [key, value] of Object.entries(fieldValues ?? {})) {
+        if (!isDetailValueKey(key, fieldById))
+            continue;
+        const m = String(key).match(DETAIL_KEY_RE);
+        const fid = m[1];
+        const rowIndex = Number(m[2]);
+        const meta = fieldById.get(fid);
+        const idx = detailIndexFromKey(meta.table);
+        const t = ensureTable(idx);
+        if (t.deleted.has(rowIndex))
+            throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行已被 deleteRows 删除，不能再修改`);
+        setUserValue(t, rowIndex, fid, value, '--field-values');
+    }
+
+    // ③ --file：附件目标（主表 / 明细行）
+    const fileTargets = [];
+    const seenFileKeys = new Set();
+    for (const fl of files ?? []) {
+        const raw = String(fl?.fieldId ?? '').trim();
+        const m = raw.match(/^(?:field)?(\d+)(?:_(\d+))?$/);
+        if (!m)
+            throw new Error(`--file 字段目标非法：${raw}（应为 <字段id> 或 <字段id>_<行号>）`);
+        const fid = m[1];
+        const rowIndex = m[2] !== undefined ? Number(m[2]) : null;
+        const meta = fieldById.get(fid);
+        if (!meta)
+            throw new Error(`附件字段 ${fid} 不在当前表单`);
+        if (meta.htmltype !== 6)
+            throw new Error(`字段 ${meta.label ?? fid}（${fid}）不是附件/图片字段（htmltype=${meta.htmltype ?? '?'}）`);
+        if (isDetailTableKey(meta.table)) {
+            if (rowIndex === null)
+                throw new Error(`明细附件必须写成 <字段id>_<行号>（如 ${fid}_0=${fl.filePath}）`);
+            const idx = detailIndexFromKey(meta.table);
+            const t = ensureTable(idx);
+            const row = t.rows.get(rowIndex);
+            if (!row)
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行不存在，无法上传附件；请先在 --detail-file 中新增该行`);
+            if (t.deleted.has(rowIndex))
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行已被删除，不能上传附件`);
+            const targetKey = `field${fid}_${rowIndex}`;
+            if (seenFileKeys.has(targetKey))
+                throw new Error(`同一附件字段/行重复指定文件：${targetKey}（当前仅支持单文件）`);
+            if (t.userSet.has(`${rowIndex}:${fid}`))
+                throw new Error(`明细字段 ${fid} 第 ${rowIndex} 行已有手填值，不能再上传附件`);
+            seenFileKeys.add(targetKey);
+            fileTargets.push({ key: targetKey, fieldId: fid, rowIndex, filePath: fl.filePath, meta });
+            row.changed = true;
+            t.changedRows.add(rowIndex);
+            t.changedKeys.add(targetKey);
+            continue;
+        }
+        if (rowIndex !== null)
+            throw new Error(`主表附件字段 ${fid} 不能带行号`);
+        const targetKey = `field${fid}`;
+        if (seenFileKeys.has(targetKey))
+            throw new Error(`同一附件字段重复指定文件：${targetKey}（当前仅支持单文件）`);
+        seenFileKeys.add(targetKey);
+        fileTargets.push({ key: targetKey, fieldId: fid, rowIndex: null, filePath: fl.filePath, meta });
+    }
+
+    // ④ 汇总
+    const tables = [];
+    for (const t of touched.values()) {
+        for (const rowIndex of t.deleted)
+            t.rows.delete(rowIndex);
+        const rowOrder = [...t.rows.keys()].sort((a, b) => a - b);
+        for (const rowIndex of rowOrder) {
+            const row = t.rows.get(rowIndex);
+            if (!row.isNew && (row.keyid === null || row.keyid === undefined))
+                throw new Error(`明细表 ${t.key} 第 ${rowIndex} 行缺少 keyid，无法安全提交（detailData 结构可能变化）`);
+            // 与浏览器 generateFormData 一致：存活行全量字段都进提交体（用户改动值覆盖原值），
+            // 只发改动行会被服务端判定为「数据丢失」。
+            row.send = { ...row.values, ...row.send };
+        }
+        const detailUnEmpty = rowOrder.reduce((n, rowIndex) =>
+            n + Object.values(t.rows.get(rowIndex).values).filter((v) => String(v ?? '') !== '').length, 0);
+        tables.push({
+            idx: t.idx,
+            key: t.key,
+            attr: t.attr,
+            rows: t.rows,
+            rowOrder,
+            indexnum: t.nextIndex,
+            nodesnum: rowOrder.length,
+            submitdtlid: rowOrder.length > 0 ? rowOrder.map(String).join(',') + ',' : '',
+            deletedKeyids: t.deletedKeyids,
+            addedRowIndexes: t.added,
+            changedRowIndexes: t.changedRows,
+            changedKeys: t.changedKeys,
+            detailUnEmpty,
+        });
+    }
+
+    const mainChanges = {};
+    const changedMainKeys = [];
+    for (const [key, value] of Object.entries(fieldValues ?? {})) {
+        if (isDetailValueKey(key, fieldById))
+            continue;
+        const id = normalizeFieldId(key);
+        mainChanges[id] = value;
+        changedMainKeys.push(`field${id}`);
+    }
+    for (const target of fileTargets) {
+        if (target.rowIndex === null) {
+            mainChanges[target.fieldId] = null; // 真实值在上传后写入
+            changedMainKeys.push(target.key);
+        }
+    }
+    const changedDetailKeys = tables.flatMap((t) => [...t.changedKeys]);
+
+    return {
+        tables,
+        mainChanges,
+        changedMainKeys: [...new Set(changedMainKeys)],
+        changedDetailKeys: [...new Set(changedDetailKeys)],
+        fileTargets,
+        warnings,
+    };
+}
+
+/** 明细行控制字段 + 已改动行的字段值（未改动行只带 keyid/行下标，不重发字段值）。 */
+export function buildDetailBodyKeys(plan) {
+    const out = {};
+    for (const t of plan?.tables ?? []) {
+        out[`nodesnum${t.idx}`] = String(t.nodesnum);
+        out[`indexnum${t.idx}`] = String(t.indexnum);
+        out[`submitdtlid${t.idx}`] = t.submitdtlid;
+        out[`deldtlid${t.idx}`] = t.deletedKeyids.join(',');
+        for (const rowIndex of t.rowOrder) {
+            const row = t.rows.get(rowIndex);
+            if (row.keyid !== null && row.keyid !== undefined)
+                out[`dtl_id_${t.idx}_${rowIndex}`] = String(row.keyid);
+            for (const [fid, value] of Object.entries(row.send ?? {})) {
+                out[`field${fid}_${rowIndex}`] = String(value ?? '');
+                const name = row.names?.[fid];
+                if (name)
+                    out[`field${fid}_${rowIndex}name`] = String(name);
+            }
+        }
+    }
+    return out;
+}
+
+/** 上传附件后重算明细非空计数（行值可能被文件 id 填充）。 */
+export function countDetailUnEmpty(plan) {
+    let n = 0;
+    for (const t of plan?.tables ?? [])
+        for (const row of t.rows.values())
+            n += Object.values(row.values).filter((v) => String(v ?? '') !== '').length;
+    return n;
+}
+
+/** 主表非空字段计数：maindata 现有值 + 本次改动，只算 id>0 的主表字段。 */
+export function countMainUnEmpty(maindata, changedMain = {}) {
+    const vals = {};
+    for (const [key, cell] of Object.entries(maindata ?? {})) {
+        const m = String(key).match(/^field(-?\d+)$/);
+        if (!m)
+            continue;
+        const id = Number(m[1]);
+        if (id <= 0)
+            continue;
+        vals[id] = cell?.value;
+    }
+    for (const [key, value] of Object.entries(changedMain ?? {})) {
+        const id = Number(normalizeFieldId(key));
+        if (!Number.isFinite(id) || id <= 0)
+            continue;
+        vals[id] = value;
+    }
+    return Object.values(vals).filter((v) => v !== undefined && v !== null && String(v) !== '').length;
+}
+
+/** 明细规划摘要（dry-run 展示用）。 */
+export function describeDetailPlan(plan) {
+    const lines = [];
+    for (const t of plan?.tables ?? []) {
+        const added = t.addedRowIndexes.length ? `新增行 ${t.addedRowIndexes.join(',')}` : '';
+        const deleted = t.deletedKeyids.length ? `删除行 keyid ${t.deletedKeyids.join(',')}` : '';
+        const changed = [...t.changedRowIndexes].filter((ri) => !t.addedRowIndexes.includes(ri));
+        const changedText = changed.length ? `修改行 ${changed.join(',')}` : '';
+        lines.push(`${t.key}：存活 ${t.nodesnum} 行（indexnum=${t.indexnum}）` +
+            [added, changedText, deleted].filter(Boolean).map((x) => ` · ${x}`).join(''));
+    }
+    return lines;
+}