bdip-office-assistant-cli 0.0.0-stage → 1.0.0

package/dist/kq.js

@@ -0,0 +1,280 @@
+/**
+ * BDIP5 考勤（kq）打卡模块。
+ *
+ * 抓包+实跑确认的接口（测试环境，2026-08-12）：
+ *   POST /api/hrm/kq/attendanceButton/getButtons    页面加载预发：取 timeline 班次参数（无 body）
+ *   POST /api/hrm/kq/attendanceButton/punchButton   打卡（带 timeline 班次参数 + signTime + encryptObj）
+ *
+ * signSecret 签名算法从前端 signFunc.js 逆向（webpack source map 虚拟路径，靠 Sources 复制源码）：
+ *   signSecret(str) = md5("wea" + str) + "ver"（小写；标准 MD5，但输入前缀加 "wea"）
+ *   encryptObj = [timestamp, userid, signSecret(userid + groupid)] = `${ts},${uid},${md5("wea"+uid+gid)+"ver"}`
+ *   timestamp = Date.now()（现算，服务端不校验时效）；signTime = 现算 HH:mm:ss
+ *   groupid = 考勤组 id（222222600 默认考勤组=1；每用户可能不同，待校准，CLI 可配 --group-id）
+ *
+ * 走当前 baseUrl（单一环境），aiAgentToken 鉴权（服务端只校验 md5(uid+gid) 防篡改，不校验会话/时效）。
+ */
+import * as crypto from 'crypto';
+import { createApiFromProfile } from './client.js';
+import { buildRequestFormUrl } from './wfcreate.js';
+// ───────────────── signSecret（前端 signFunc.js 逆向）─────────────────
+/** md5 小写。 */
+function md5Hex(s) {
+    return crypto.createHash('md5').update(s, 'utf8').digest('hex');
+}
+/**
+ * 考勤签名：signSecret(str) = md5("wea" + str) + "ver"（与前端 signFunc.js 一致）。
+ * 前端输入经 uTF8Encode，但纯 ASCII（"wea"+uid+gid）无变化，故直接 md5。
+ */
+export function signSecret(str) {
+    return md5Hex(`wea${str}`) + 'ver';
+}
+/**
+ * 构造 encryptObj = `${timestamp},${userid},${signSecret(userid+groupid)}ver`。
+ * 与 DataList.js 的 `signData=[generateTimeStamp(), userid, signSecret(userid+groupid)]` 一致
+ * （数组 toString() = "ts,uid,signSecret结果"，signSecret 已含 ver 后缀）。
+ */
+export function buildEncryptObj(userid, groupId, timestamp) {
+    const ts = (timestamp ?? Date.now()) + '';
+    return `${ts},${userid},${signSecret(`${userid}${groupId}`)}`;
+}
+/**
+ * 取打卡班次 timeline。POST /api/hrm/kq/attendanceButton/getButtons（无 body）。
+ * 返回 timeline[]（每项=一个打卡时段，含全部班次参数）+ date/now/groupname。
+ * 不返回 encryptObj/groupid/signature（前端 JS 现算）。
+ */
+export async function getButtons(cfg) {
+    const api = await createApiFromProfile(cfg);
+    const r = await api.post('/api/hrm/kq/attendanceButton/getButtons', {});
+    const j = r.json || {};
+    const tlRaw = Array.isArray(j.timeline) ? j.timeline : [];
+    const timeline = tlRaw.map((t) => ({
+        date: s(t.date),
+        type: s(t.type),
+        belongtime: s(t.belongtime),
+        canSignTime: s(t.canSignTime),
+        across: s(t.across),
+        belongdate: s(t.belongdate),
+        datetime: s(t.datetime),
+        min: s(t.min),
+        signSectionEndTime: s(t.signSectionEndTime),
+        islastsign: s(t.islastsign),
+        signSectionTime: s(t.signSectionTime),
+        signSectionBeginTime: s(t.signSectionBeginTime),
+        isYellow: s(t.isYellow),
+        isPunchOpen: s(t.isPunchOpen),
+        isacross: s(t.isacross),
+        pre: s(t.pre),
+        signSection: s(t.signSection),
+        signbelongspan: s(t.signbelongspan),
+        active: s(t.active),
+        needSign: s(t.needSign),
+        workmins: s(t.workmins),
+        signbelong: s(t.signbelong),
+        reSign: s(t.reSign),
+        min_next: s(t.min_next),
+        signfrom: s(t.signfrom),
+        serialid: s(t.serialid),
+        signAcross: s(t.signAcross),
+        signAcross_next: s(t.signAcross_next),
+        time: s(t.time),
+        signTime: s(t.signTime),
+        position: s(t.position),
+        isfirstsign: s(t.isfirstsign),
+    }));
+    return {
+        date: s(j.date),
+        now: s(j.now),
+        groupname: s(j.groupname),
+        lastname: s(j.lastname),
+        timeline,
+        raw: j,
+    };
+}
+/**
+ * 解析本次允许操作的打卡时段。
+ *
+ * getButtons 是当天考勤页的状态，不是历史补签查询接口。历史日期若在
+ * timeline 中不存在，绝不能回退到同卡种的当天记录，否则一次失败的补卡会
+ * 变成对今天记录的真实写入。
+ */
+export function resolvePunchItem(buttons, opts) {
+    const targetDate = String(opts?.date ?? buttons?.date ?? '');
+    const type = String(opts?.type ?? '');
+    const currentDate = String(buttons?.date ?? '');
+    if (!currentDate)
+        throw new Error('考勤接口未返回当前日期，无法安全打卡');
+    if (targetDate !== currentDate) {
+        throw new Error(`当前考勤接口只支持当天(${currentDate})打卡；不能安全处理 ${targetDate || '未指定日期'} 的历史补卡，请在 OA 考勤补签流程办理`);
+    }
+    const item = (buttons?.timeline ?? []).find((t) => String(t.date) === targetDate && String(t.type) === type);
+    if (!item)
+        throw new Error(`未找到当天打卡时段（date=${targetDate}, type=${type}），已停止执行以避免误写其他记录`);
+    return { targetDate, item };
+}
+/**
+ * 打卡。链路：getButtons（取 timeline 班次参数）→ 生成 encryptObj → punchButton。
+ * - type=on 上班卡 / off 下班卡，按 date（默认今天）匹配 timeline 时段。
+ * - encryptObj = [Date.now(), userid, signSecret(userid+groupId)+"ver"]（前端 signFunc.js 算法）。
+ * - signTime = 当前时刻 HH:mm:ss（或传入）。
+ * 服务端只校验 md5("wea"+uid+gid) 防篡改，不校验 timestamp/会话，token 鉴权可行。
+ */
+export async function punch(cfg, opts) {
+    const api = await createApiFromProfile(cfg);
+    const buttons = await getButtons(cfg);
+    const { item } = resolvePunchItem(buttons, opts);
+    // userid：优先传入；否则从 config.cookie 的 loginuuids 解析（token-login 写回 cookie 含用户 id）
+    const userid = opts.userid ?? parseUserIdFromCookie(cfg.cookie) ?? '';
+    if (!userid) {
+        throw new Error('未取到 userid：punch 需 --userid，或 config.cookie 须含 loginuuids（token-login 会写回）');
+    }
+    const groupId = opts.groupId ?? '1';
+    // punchButton 的 signTime 是本次打卡时刻，不是修改既有打卡时间的参数。
+    // 始终现算，避免调用方把历史或任意时间写入当天记录。
+    const signTime = nowHHmmss();
+    const encryptObj = buildEncryptObj(userid, groupId, opts.timestamp);
+    const body = {
+        date: item.date,
+        belongtime: item.belongtime,
+        type: item.type,
+        canSignTime: item.canSignTime,
+        across: item.across,
+        belongdate: item.belongdate,
+        datetime: item.datetime,
+        min: item.min,
+        islastsign: item.islastsign,
+        signSectionTime: item.signSectionTime,
+        signSectionBeginTime: item.signSectionBeginTime ?? '',
+        isYellow: item.isYellow,
+        isPunchOpen: item.isPunchOpen,
+        isacross: item.isacross,
+        pre: item.pre ?? '0',
+        signSection: item.signSection,
+        signbelongspan: item.signbelongspan ?? '今天',
+        active: item.active ?? '0',
+        needSign: item.needSign ?? '0',
+        workmins: item.workmins,
+        signbelong: item.signbelong ?? '今天',
+        reSign: item.reSign ?? '1',
+        min_next: item.min_next,
+        signfrom: item.signfrom ?? 'e9pc',
+        serialid: item.serialid,
+        signAcross: item.signAcross,
+        signAcross_next: item.signAcross_next,
+        time: item.time,
+        position: '',
+        longitude: '',
+        latitude: '',
+        sid: '',
+        mac: '',
+        deviceId: '',
+        deviceInfo: '',
+        signTime,
+        encryptObj,
+        ...(item.isfirstsign !== undefined ? { isfirstsign: item.isfirstsign } : {}),
+    };
+    const r = await api.post('/api/hrm/kq/attendanceButton/punchButton', body);
+    const j = r.json || {};
+    return {
+        success: s(j.success),
+        message: s(j.message),
+        signtime: s(j.signtime),
+        signdate: s(j.signdate),
+        kqstatus: s(j.kqstatus),
+        status: s(j.status),
+        raw: j,
+    };
+}
+/** 本人考勤按网页“我的考勤”读取，不使用 Cookie 组合推断账号。 */
+export async function getKqCurrentUser(cfg) {
+    const api = await createApiFromProfile(cfg);
+    const r = await api.get('/api/hrm/login/getAccountList', {}, { forceCookie: true });
+    const current = r.json?.data?.accountlist?.filter(a => String(a.iscurrent) === '1');
+    if (!Array.isArray(current) || current.length !== 1)
+        throw new Error('未能核验当前考勤账号，请重新登录；不能将鉴权失败视为零考勤');
+    return String(current[0].userid);
+}
+async function readMyAttendance(cfg, opts, method) {
+    const current = await getKqCurrentUser(cfg);
+    if (opts.resourceId && String(opts.resourceId) !== current)
+        throw new Error('当前仅验证了本人“我的考勤”接口；指定他人查询尚未验证，不返回本人结果代替');
+    const type = String(opts.type ?? '2');
+    if (type !== '2') throw new Error('本人考勤年视图尚未验证，请使用 --month 查询月视图');
+    const typevalue = String(opts.typevalue ?? defaultKqTypeValue('2'));
+    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(typevalue)) throw new Error('月份必须为YYYY-MM');
+    const api = await createApiFromProfile(cfg);
+    const r = await api.post('/api/kq/myattendance/' + method,
+        { loaddata: '1', type, typevalue }, { forceCookie: true });
+    if (String(r.json?.status) !== '1' || r.json?.api_status === false)
+        throw new Error('我的考勤读取失败或鉴权失效，不能归零：' + String(r.json?.msg ?? r.json?.message ?? '非预期响应'));
+    if (await getKqCurrentUser(cfg) !== current) throw new Error('查询期间账号发生变化，请重新查询');
+    return { j: r.json, type, typevalue, resourceId: current };
+}
+export function normalizeKqReport(j) {
+    const g1 = j.groupitem1;
+    if (!g1 || g1.value === undefined || !Array.isArray(g1.items) ||
+        !g1.items.some(x => x.id === 'leaveDays') || !g1.items.some(x => x.id === 'realWorkDays') ||
+        !Array.isArray(j.groupitem2?.items) || !Array.isArray(j.groupitem3?.items) ||
+        !Array.isArray(j.groupitem4?.items) || !Array.isArray(j.groupitem5?.items))
+        throw new Error('我的考勤统计结构不匹配，不能按零或全正常输出');
+    const flat = g => g.items.map(it => ({ id: s(it.id), title: s(it.title || it.name), value: s(it.value), type: s(it.type), unit: s(it.unit) }));
+    const attendance = flat(g1);
+    return {
+        attendance: { workDays: s(g1.value), unit: '天',
+            leaveDays: s(g1.items.find(x => x.id === 'leaveDays').value),
+            realWorkDays: s(g1.items.find(x => x.id === 'realWorkDays').value), items: attendance },
+        durations: flat(j.groupitem2), exceptions: flat(j.groupitem3),
+        leave: j.groupitem4.items.map(g => ({ title: s(g.title), unit: s(g.unit),
+            items: (g.item ?? []).filter(x => x && x.title).map(x => ({title: s(x.title), value: s(x.value), unit: s(x.unit)})) })),
+        leaveDurations: flat(j.groupitem5),
+        notes: j.groupitem5.items.length ? [] : ['服务器未返回请假明细'],
+    };
+}
+export async function getKqReport(cfg, opts = {}) {
+    const {j, ...meta} = await readMyAttendance(cfg, opts, 'getHrmKQReportInfo');
+    return {...meta, ...normalizeKqReport(j), status: j.status, raw: j};
+}
+export function normalizeKqDays(j, baseUrl = '') {
+    const res = j.result;
+    if (!res || typeof res !== 'object' || !Object.keys(res).length)
+        throw new Error('我的考勤月明细为空或结构不匹配，不能宣称无异常');
+    return Object.values(res).sort((a,b) => String(a.date).localeCompare(String(b.date))).map(d => {
+        if (!d.date || !Array.isArray(d.types) || (d.signInfo !== undefined && !Array.isArray(d.signInfo)) || (d.signInfo === undefined && d.isWorkDay !== false) || !Array.isArray(d.workflow))
+            throw new Error('我的考勤每日明细结构不匹配');
+        const pick = title => s((d.signInfo ?? []).find(x => x.title === title)?.signTime);
+        return {date: s(d.date), types: d.types, signInfo: d.signInfo ?? [],
+            signIn: pick('上班打卡'), signOut: pick('下班打卡'), isWorkDay: d.isWorkDay,
+            workflow: d.workflow.map(w => ({...w,
+                url: w.requestId && baseUrl ? buildRequestFormUrl(baseUrl, w.requestId) : undefined}))};
+    });
+}
+export async function getKqMonthReport(cfg, opts = {}) {
+    const {j, ...meta} = await readMyAttendance(cfg, {...opts, type: '2'}, 'getHrmKQMonthReportInfo');
+    return {...meta, days: normalizeKqDays(j, cfg.baseUrl), status: j.status, raw: j};
+}
+
+/** 默认 typevalue：type=1 → "YYYY"，type=2 → "YYYY-MM"（本地时区）。 */
+function defaultKqTypeValue(type) {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    return String(type) === '1' ? `${d.getFullYear()}` : `${d.getFullYear()}-${p(d.getMonth() + 1)}`;
+}
+
+// ───────────────── 工具 ─────────────────
+function s(v) {
+    if (v === undefined || v === null)
+        return '';
+    return String(v);
+}
+/** 从 cookie 串解析 loginuuids（当前登录用户 id）。token-login 写回 cookie 含此字段。 */
+function parseUserIdFromCookie(cookie) {
+    if (!cookie)
+        return '';
+    const m = cookie.match(/loginuuids=([^;]+)/);
+    return m ? m[1].trim() : '';
+}
+/** 当前时刻 HH:mm:ss（本地时区）。 */
+function nowHHmmss() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}

package/dist/links.js

@@ -0,0 +1,34 @@
+function baseUrl(base) {
+    return String(base ?? '').replace(/\/+$/, '');
+}
+
+export function buildBlogMyUrl(base) {
+    return `${baseUrl(base)}/wui/index.html#/main/blog/myBlog?menuIds=392,393&menuPathIds=392,393`;
+}
+
+export function buildCubeCardUrl(base, { modeId, formId, billid, customid }) {
+    if ([modeId, formId, billid, customid].some((value) => value === undefined || value === null || value === ''))
+        return undefined;
+    return `${baseUrl(base)}/spa/cube/index.html#/main/cube/card?type=0&modeId=${modeId}&formId=${formId}&billid=${billid}&opentype=0&customid=${customid}&viewfrom=fromsearchlist`;
+}
+
+export function buildCubeSearchUrl(base, customid) {
+    if (customid === undefined || customid === null || customid === '')
+        return undefined;
+    return `${baseUrl(base)}/spa/cube/index.html#/main/cube/search?customid=${encodeURIComponent(String(customid))}`;
+}
+
+/** 把 BDIP5 菜单返回的相对地址补成可点击的绝对地址。 */
+export function normalizeE9Url(base, value) {
+    const raw = String(value ?? '').trim();
+    if (!raw)
+        return undefined;
+    if (/^https?:\/\//i.test(raw))
+        return raw;
+    const b = baseUrl(base);
+    if (raw.startsWith('#/'))
+        return `${b}/spa/cube/index.html${raw}`;
+    if (raw.startsWith('/main/cube/'))
+        return `${b}/spa/cube/index.html#${raw}`;
+    return `${b}/${raw.replace(/^\/+/, '')}`;
+}

package/dist/nodemap.js

@@ -0,0 +1,242 @@
+/**
+ * 流程节点名解析：nodeid → nodename。
+ *
+ * 背景：待办/已办/我发起列表服务端**只给当前节点的 id**——行字段 `currentnodeid` 的值形如 "2882"，
+ *   且行里没有节点名（实测 `currentnodeidspan` 也只是 id 本身，整行不含 currentnodename/currentnodespan）。
+ *   要显示名字只能按流程另取节点表。
+ *
+ * 接口（2026-10-14 实测 e9pc.e-cology.com.cn）：
+ *   POST /api/workflow/test/getNodeInfo   body: { workflowId }
+ *     → { nodeInfo: [{id, name, type}], wfInfo: {workflowName, version}, authority, tabInfo, ... }
+ *   - 只需 workflowId；文档里的 requestid/userId/type 都非必需（逐个试过）。
+ *   - ⚠️ 路径必须带 `/api` 前缀：`/workflow/test/getNodeInfo`（无前缀）返回登录页 HTML。
+ *   - ⚠️ 接口挂在「流程测试」模块下，非所有部署/版本都有 → **一律 fail-soft**：
+ *       拿不到就返回 null，调用方退回显示节点 id，绝不让列表整体报错。
+ *   - `type`：0=发起节点 / 1=审批节点 / 3=归档节点。
+ *
+ * 缓存：`~/.bdip/node_map_<envkey>.json`，按 workflowId 存，TTL 30 天
+ *   （节点表几乎不变；响应带 version，流程改版后重新拉取自然覆盖）。
+ *   - `E9_NODEMAP_CACHE_DIR` 覆盖缓存目录（测试隔离用，避免污染真实 ~/.e9）。
+ *   - `E9_NO_NODE_NAME=1` 或 CLI `--no-node-name` 整体停用解析。
+ */
+import { createApiFromProfile } from './client.js';
+import { endpointFor, profileNameFromBaseUrl } from './config.js';
+import { stripHtml } from './parse.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/** 节点表缓存 TTL（天）。 */
+export const NODEMAP_TTL_MS = (Number(process.env.E9_NODEMAP_TTL_DAYS ?? '30') || 30) * 24 * 3600 * 1000;
+/** 并发拉取上限（一次列表页通常 ≤10 个流程，全量拉取路径可能几十个，别一次打满）。 */
+const FETCH_CHUNK = 6;
+
+function str(v) {
+    if (v === undefined || v === null || v === '')
+        return undefined;
+    return String(v);
+}
+
+/** 缓存目录（测试可用 E9_NODEMAP_CACHE_DIR 覆盖）。 */
+export function nodeMapCacheDir() {
+    return process.env.E9_NODEMAP_CACHE_DIR || path.join(os.homedir(), '.bdip');
+}
+/** 缓存文件路径：~/.bdip/node_map_<envkey>.json（按环境隔离，nodeid 不跨环境通用）。 */
+export function nodeMapCachePath(cfg) {
+    const baseUrl = endpointFor(cfg).baseUrl.replace(/\/+$/, '');
+    return path.join(nodeMapCacheDir(), `node_map_${profileNameFromBaseUrl(baseUrl)}.json`);
+}
+
+/** 是否停用节点名解析（E9_NO_NODE_NAME=1）。 */
+export function isNodeNameDisabled() {
+    return process.env.E9_NO_NODE_NAME === '1';
+}
+
+/**
+ * 纯函数：把 getNodeInfo 响应归一化为 { workflowName, version, nodes:{id:name} }。
+ * 结构不符（登录页/空表/非 JSON）返回 null——调用方据此 fail-soft。
+ */
+export function parseNodeInfo(json) {
+    const list = json?.nodeInfo;
+    if (!Array.isArray(list))
+        return null;
+    const nodes = {};
+    for (const n of list) {
+        const id = str(n?.id);
+        if (!id)
+            continue;
+        nodes[id] = stripHtml(n?.name) || id;
+    }
+    if (Object.keys(nodes).length === 0)
+        return null;
+    return {
+        workflowName: str(json?.wfInfo?.workflowName),
+        version: str(json?.wfInfo?.version),
+        nodes,
+    };
+}
+
+/** 读缓存文件；坏文件/不存在返回 {}。 */
+function readCache(cfg) {
+    try {
+        const p = nodeMapCachePath(cfg);
+        if (!fs.existsSync(p))
+            return {};
+        const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return raw && typeof raw === 'object' && raw.workflows ? raw.workflows : {};
+    }
+    catch {
+        return {};
+    }
+}
+
+/** 写回缓存（单流程）；写入失败不阻断（节点名只是锦上添花）。 */
+function writeCache(cfg, workflowId, entry) {
+    try {
+        const p = nodeMapCachePath(cfg);
+        const workflows = readCache(cfg);
+        workflows[workflowId] = entry;
+        const baseUrl = endpointFor(cfg).baseUrl.replace(/\/+$/, '');
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify({
+            envkey: profileNameFromBaseUrl(baseUrl),
+            baseUrl,
+            updatedAt: new Date().toISOString(),
+            workflows,
+        }, null, 2) + '\n', 'utf8');
+    }
+    catch { /* 忽略：缓存写失败不影响本次结果 */ }
+}
+
+function isStale(entry) {
+    if (!entry || !entry.fetchedAt)
+        return true;
+    return Date.now() - new Date(entry.fetchedAt).getTime() > NODEMAP_TTL_MS;
+}
+
+/**
+ * 取某流程的节点表（带缓存）。任何失败返回 null（fail-soft，不抛）。
+ * @returns {Promise<{workflowName?:string, version?:string, nodes:Record<string,string>}|null>}
+ */
+export async function getNodeMap(cfg, workflowId, opts = {}) {
+    const wfId = str(workflowId);
+    if (!wfId)
+        return null;
+    const cached = readCache(cfg)[wfId];
+    if (!opts.refresh && cached && !isStale(cached) && cached.nodes)
+        return { workflowName: cached.workflowName, version: cached.version, nodes: cached.nodes };
+    const api = opts.api ?? await createApiFromProfile(cfg);
+    let json = null;
+    try {
+        const r = await api.post('/api/workflow/test/getNodeInfo', { workflowId: wfId });
+        json = r?.json ?? null;
+    }
+    catch {
+        json = null; // 网络/鉴权异常同上：降级，不打断列表
+    }
+    const parsed = parseNodeInfo(json);
+    if (!parsed)
+        return null;
+    writeCache(cfg, wfId, { ...parsed, workflowId: wfId, fetchedAt: new Date().toISOString() });
+    return parsed;
+}
+
+/**
+ * 列出**本地缓存**里所有流程的节点表（供「按节点名跨流程解析」用）。
+ * 缓存来自历次列表查询；从没查过的流程不在其中。
+ */
+export function listCachedNodeMaps(cfg) {
+    const workflows = readCache(cfg);
+    return Object.entries(workflows)
+        .filter(([, w]) => w && w.nodes && Object.keys(w.nodes).length)
+        .map(([workflowId, w]) => ({ workflowId: String(workflowId), workflowName: w.workflowName, nodes: w.nodes }));
+}
+
+/**
+ * 按**节点名**解析节点 id（供 CLI `--node-name`）。
+ *
+ * 节点 id 是**流程内编号**（每个流程一套），故解析必须先限定流程范围：
+ *   - 给了 `workflowId`：只在该流程的节点表内找（按需拉取，不依赖缓存）；
+ *   - 未给：在**本地缓存**的所有流程节点表内找（缓存来自历次列表查询）。
+ *
+ * 匹配规则：**先精确同名**；无精确才做模糊（互相包含）。多候选一律**全部返回**，
+ * 由调用方列给用户选——严禁自动取首条（本仓库硬规则）。
+ *
+ * @returns {Promise<{candidates:Array<{workflowId,workflowName,nodeId,nodeName,matchType}>,
+ *                    exact:Array, scoped:boolean, poolSize:number, unavailable:boolean}>}
+ *   `unavailable`：限定了流程但节点表取不到（接口不存在/异常）——与"确实没有同名节点"要区分开。
+ */
+export async function resolveNodeByName(cfg, name, opts = {}) {
+    const want = String(name ?? '').trim();
+    const empty = { candidates: [], exact: [], scoped: Boolean(opts.workflowId), poolSize: 0, unavailable: false };
+    if (!want)
+        return empty;
+    let pool = [];
+    if (opts.workflowId) {
+        const m = await getNodeMap(cfg, opts.workflowId, opts);
+        if (!m)
+            return { ...empty, unavailable: true };
+        pool = [{ workflowId: String(opts.workflowId), workflowName: m.workflowName, nodes: m.nodes }];
+    }
+    else {
+        pool = listCachedNodeMaps(cfg);
+    }
+    const candidates = [];
+    for (const w of pool) {
+        for (const [nodeId, nodeName] of Object.entries(w.nodes)) {
+            if (!nodeName)
+                continue;
+            const isExact = nodeName === want;
+            const isFuzzy = !isExact && (nodeName.includes(want) || want.includes(nodeName));
+            if (isExact || isFuzzy)
+                candidates.push({ workflowId: w.workflowId, workflowName: w.workflowName, nodeId, nodeName, matchType: isExact ? 'exact' : 'fuzzy' });
+        }
+    }
+    return {
+        candidates,
+        exact: candidates.filter((c) => c.matchType === 'exact'),
+        scoped: Boolean(opts.workflowId),
+        poolSize: pool.length,
+        unavailable: false,
+    };
+}
+
+/** 从列表行取流程 id（normalizeRow 归一字段优先，回退原始行）。 */
+function workflowIdOf(item) {
+    return str(item?.workflowId) ?? str(item?.raw?.workflowid) ?? str(item?.raw?.workflowId);
+}
+
+/**
+ * 给列表行补 `nodeName`（就地写回）。返回补上的行数。
+ *
+ * - 行需带 `node`（节点 id）；流程 id 取 `workflowId` 或 `raw.workflowid`。
+ * - 按流程去重，每个流程只请求一次；同一流程的多行共用一张表。
+ * - 任何失败都不抛：拿不到节点表的行保持原样（渲染层回退显示 id）。
+ */
+export async function annotateNodeNames(cfg, items, opts = {}) {
+    if (!Array.isArray(items) || items.length === 0)
+        return 0;
+    if (opts.disabled)
+        return 0;
+    // 只对「node 是纯数字 id」的行解析：服务端不同列表的 span 给的东西不一样——
+    // 待办/公文给的是**节点 id**（需要解析），流程代理办理记录给的是**节点名**（解析无从匹配，纯浪费请求）。
+    const rows = items.filter((it) => /^\d+$/.test(str(it?.node) ?? '') && workflowIdOf(it));
+    if (rows.length === 0)
+        return 0;
+    const wfIds = [...new Set(rows.map(workflowIdOf))];
+    const maps = new Map();
+    for (let i = 0; i < wfIds.length; i += FETCH_CHUNK) {
+        const chunk = wfIds.slice(i, i + FETCH_CHUNK);
+        const got = await Promise.all(chunk.map((w) => getNodeMap(cfg, w, opts)));
+        chunk.forEach((w, idx) => maps.set(w, got[idx]));
+    }
+    let filled = 0;
+    for (const it of rows) {
+        const name = maps.get(workflowIdOf(it))?.nodes?.[str(it.node)];
+        if (name) {
+            it.nodeName = name;
+            filled++;
+        }
+    }
+    return filled;
+}