@qinsilk/scm-agent-tools 0.0.0-stage → 0.2.0

package/reports/processFollowup.js

@@ -0,0 +1,312 @@
+// 生产单工序跟进表：导出待生产与生产中（状态 4、2）生产单的工序汇报情况，
+// 每个工序取最晚一条汇报记录，最后汇报日期不在允许天数内的判定为「需跟进」，
+// 在需跟进工序列标红。原脚本的判定口径是「最后汇报不是今天就需跟进」，
+// 本模块保持该默认（days=0），并允许用 days 参数放宽到 N 天。
+// 数据流：GET /api/agent/v1/produce/list 按状态 4、2 分别分页取全量后合并
+// （agent 接口的 state 参数只接受单个状态值），
+// 逐单 GET /api/agent/v1/produce/work-processes 取工序节点，
+// 再逐工序 GET /api/agent/v1/produce/work-process-detail 取汇报记录。
+// 这是请求数最多的报表：每张生产单 1 次工序列表 + 每个工序 1 次明细，
+// 100 张生产单按平均 6 个工序估算约 700 次请求，配合 2.1 秒节流约需 25 分钟。
+// 生成逻辑从原 Python 报表脚本 export_production_process_followup.py 移植，
+// 表结构、列名、文件名与原脚本一致；与原脚本的差异：
+// 1. 原脚本按 businessTime 近 90 天取单；agent 接口用 from/to 日期区间表达，
+//    默认近 90 天（含今天，可用 from/to 覆盖）。
+// 2. 单张生产单的工序列表或单个工序明细查询失败时跳过该部分继续生成
+//    （原脚本直接报错终止），失败数量在汇总中说明。
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../cli/api');
+const { dateStr, shiftDate, createThrottle, fetchAll } = require('./util');
+const { createWorkbook, saveWorkbook, markCellColor } = require('./excel');
+
+/** 服务器对同一 AI Key 每分钟限 30 次请求，两次请求间隔至少 2100 毫秒 */
+const REQUEST_INTERVAL_MS = 2100;
+/** 列表分页大小（服务端单页上限 100） */
+const PAGE_LIMIT = 100;
+/** 取单的业务日期窗口天数（原脚本 businessTime 近 90 天） */
+const DEFAULT_DAYS = 90;
+/** 生产单状态：4 待生产、2 生产中 */
+const STATES = [4, 2];
+/** 需跟进判定天数：最后汇报日期距今天超过该天数即需跟进（原脚本默认 0，即不是今天） */
+const DEFAULT_FOLLOWUP_DAYS = 0;
+/** 平均每张生产单的工序数，用于生成前的耗时估算提示 */
+const ESTIMATED_PROCESSES_PER_ORDER = 6;
+
+/** 表头底色（浅蓝，与原脚本一致） */
+const HEADER_FILL = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9EAF7' } };
+const BORDER = {
+  top: { style: 'thin', color: { argb: 'FF000000' } },
+  left: { style: 'thin', color: { argb: 'FF000000' } },
+  bottom: { style: 'thin', color: { argb: 'FF000000' } },
+  right: { style: 'thin', color: { argb: 'FF000000' } },
+};
+const CENTER = { vertical: 'middle', horizontal: 'center', wrapText: true };
+
+/** 空值转空字符串，其余转去空白字符串 */
+function text(value) {
+  return value === null || value === undefined ? '' : String(value).trim();
+}
+
+/** yyyy-MM-dd 转 UTC 毫秒，用于日期差计算 */
+function toUtc(dayStr) {
+  const [y, m, d] = dayStr.split('-').map(Number);
+  return Date.UTC(y, m - 1, d);
+}
+
+/** 两个 yyyy-MM-dd 之间相差的天数（to - from） */
+function dayDiff(fromStr, toStr) {
+  return Math.round((toUtc(toStr) - toUtc(fromStr)) / 86400000);
+}
+
+/**
+ * 取一个工序全部汇报记录中最晚的汇报时间。
+ * 汇报时间优先取业务时间，为空时取创建时间；接口已格式化为
+ * yyyy-MM-dd HH:mm:ss，字符串按字典序比较即得最晚值。
+ */
+function latestReportTime(records) {
+  let latest = '';
+  for (const record of records || []) {
+    const value = text(record.businessTime) || text(record.createTime);
+    if (value && value > latest) {
+      latest = value;
+    }
+  }
+  return latest;
+}
+
+/** 是否需要跟进：没有汇报记录，或最后汇报日期距今超过 followupDays 天 */
+function needsFollowup(latest, todayStr, followupDays) {
+  if (!latest) {
+    return true;
+  }
+  const day = latest.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) {
+    return true;
+  }
+  return dayDiff(day, todayStr) > followupDays;
+}
+
+/** 商品列显示：商品名(货号)，缺一个时只显示另一个 */
+function goodsText(order) {
+  const name = text(order.goodsName);
+  const sn = text(order.goodsSn);
+  if (name && sn) {
+    return `${name}(${sn})`;
+  }
+  return name || sn;
+}
+
+/**
+ * 按状态 4、2 分别取全量生产单后合并。
+ * 两个状态的结果理论上不重叠，合并时仍按生产单号去重，防止服务端重复返回。
+ */
+async function fetchOrders(throttle, from, to) {
+  const merged = [];
+  const seen = new Set();
+  for (const state of STATES) {
+    const { list } = await fetchAll(
+      (page, limit) => throttle(() => call('GET', '/api/agent/v1/produce/list', {
+        state,
+        from,
+        to,
+        page,
+        limit,
+      })),
+      { limit: PAGE_LIMIT },
+    );
+    for (const row of list) {
+      const key = text(row.ordersSn);
+      if (key && seen.has(key)) {
+        continue;
+      }
+      if (key) {
+        seen.add(key);
+      }
+      merged.push(row);
+    }
+  }
+  return merged;
+}
+
+/**
+ * 查询一张生产单的全部工序跟进情况。
+ * 工序列表失败或工序明细失败时计数并继续（明细失败的工序按无汇报处理）。
+ */
+async function followupOrder(throttle, order, todayStr, followupDays, progress) {
+  const sn = text(order.ordersSn);
+  if (!sn) {
+    return { skipped: true };
+  }
+  let processes = [];
+  try {
+    processes = await throttle(() => call('GET', '/api/agent/v1/produce/work-processes', { sn }));
+  } catch (e) {
+    return { sn, error: e };
+  }
+  if (!Array.isArray(processes)) {
+    processes = [];
+  }
+
+  const processValues = [];
+  const followups = [];
+  let failedDetails = 0;
+  for (let index = 0; index < processes.length; index += 1) {
+    const process = processes[index];
+    const workProcessId = process.id ?? process.workProcessId;
+    if (workProcessId === null || workProcessId === undefined) {
+      continue;
+    }
+    const name = text(process.workProcessName) || text(process.name) || `未命名工序${index + 1}`;
+    let latest = '';
+    try {
+      const detail = await throttle(() => call('GET', '/api/agent/v1/produce/work-process-detail', {
+        workProcessId,
+      }));
+      latest = latestReportTime(detail.reportRecords);
+    } catch (e) {
+      failedDetails += 1;
+    }
+    const follow = needsFollowup(latest, todayStr, followupDays);
+    processValues.push({ name, latest, follow });
+    if (follow) {
+      followups.push(name);
+    }
+    progress.processed += 1;
+    if (progress.processed % 10 === 0) {
+      const elapsed = Math.round((Date.now() - progress.startedAt) / 1000);
+      const minutes = Math.floor(elapsed / 60);
+      const seconds = elapsed % 60;
+      process.stdout.write(
+        `工序跟进进度：已查询 ${progress.processed} 个工序，生产单 ${progress.orderIndex}/${progress.orderTotal}，`
+        + `已耗时 ${minutes}分${String(seconds).padStart(2, '0')}秒\n`,
+      );
+    }
+  }
+  return { sn, goods: goodsText(order), processValues, followups, failedDetails };
+}
+
+/** 写 Excel：标题行 + 表头行 + 数据行，需跟进工序列标红 */
+async function writeWorkbook(filePath, records) {
+  const workbook = createWorkbook();
+  const sheet = workbook.addWorksheet('生产工序跟进表', { views: [{ state: 'frozen', ySplit: 2 }] });
+
+  // 第 1 行：表标题，整行合并
+  const titleRow = sheet.getRow(1);
+  titleRow.getCell(1).value = '生产单工序汇报跟进表';
+  titleRow.height = 32;
+  titleRow.eachCell({ includeEmpty: true }, (cell) => {
+    cell.font = { bold: true, size: 16 };
+    cell.border = BORDER;
+    cell.alignment = { vertical: 'middle', horizontal: 'center' };
+  });
+  sheet.mergeCells(1, 1, 1, 3);
+
+  // 第 2 行：表头
+  const headerRow = sheet.getRow(2);
+  ['生产单号', '商品', '需跟进工序'].forEach((header, i) => {
+    headerRow.getCell(i + 1).value = header;
+  });
+  headerRow.height = 25;
+  headerRow.eachCell({ includeEmpty: true }, (cell) => {
+    cell.font = { bold: true };
+    cell.fill = HEADER_FILL;
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+  });
+
+  // 数据行：无表框（与原脚本一致），需跟进工序列标红
+  records.forEach((record, index) => {
+    const rowNumber = index + 3;
+    const row = sheet.getRow(rowNumber);
+    row.getCell(1).value = record.sn;
+    row.getCell(2).value = record.goods;
+    row.getCell(3).value = record.followups.join('、');
+    row.height = 24;
+    if (record.followups.length) {
+      markCellColor(sheet, rowNumber, 3, 'FFFF0000');
+    }
+  });
+
+  sheet.getColumn(1).width = 23;
+  sheet.getColumn(2).width = 30;
+  sheet.getColumn(3).width = 28;
+  if (records.length) {
+    sheet.autoFilter = `A2:C${records.length + 2}`;
+  }
+  await saveWorkbook(workbook, filePath);
+}
+
+/**
+ * 生成生产单工序跟进表。
+ * argv：{ from/to 业务日期区间（可选，默认近 90 天含今天）,
+ *         days 需跟进判定天数（可选，默认 0，即最后汇报不是今天就需跟进）,
+ *         out 输出目录 }。
+ * 输出文件名 生产单工序跟进表-YYYY-MM-DD.xlsx，已存在时报错，不覆盖。
+ */
+async function generate(argv = {}) {
+  const throttle = createThrottle(REQUEST_INTERVAL_MS);
+  // 后端对业务日期结束时间用严格小于比较，因此默认结束日期传明天以包含今天；
+  // 显式传入 from/to 时按传入值使用
+  const from = argv.from ? String(argv.from) : shiftDate(-(DEFAULT_DAYS - 1));
+  const to = argv.to ? String(argv.to) : shiftDate(1);
+  const followupDays = Number.isFinite(Number(argv.days)) && Number(argv.days) > 0
+    ? Number(argv.days)
+    : DEFAULT_FOLLOWUP_DAYS;
+  const outDir = argv.out ? path.resolve(String(argv.out)) : process.cwd();
+  const todayStr = dateStr();
+
+  const orders = await fetchOrders(throttle, from, to);
+  if (!orders.length) {
+    throw new Error('没有符合条件的生产单');
+  }
+  const estimatedRequests = orders.length + orders.length * ESTIMATED_PROCESSES_PER_ORDER;
+  process.stdout.write(
+    `将检查 ${orders.length} 张生产单的工序汇报：按平均每单 ${ESTIMATED_PROCESSES_PER_ORDER} 个工序估算，`
+    + `约 ${estimatedRequests} 次请求，每次间隔 ${REQUEST_INTERVAL_MS / 1000} 秒，`
+    + `预计需要 ${Math.round((estimatedRequests * REQUEST_INTERVAL_MS) / 60000)} 分钟以上，请耐心等待\n`,
+  );
+
+  const progress = { processed: 0, orderIndex: 0, orderTotal: orders.length, startedAt: Date.now() };
+  const records = [];
+  let noSnCount = 0;
+  let orderFailedCount = 0;
+  let detailFailedCount = 0;
+  let processCount = 0;
+  for (const order of orders) {
+    progress.orderIndex += 1;
+    const result = await followupOrder(throttle, order, todayStr, followupDays, progress);
+    if (result.skipped) {
+      noSnCount += 1;
+      continue;
+    }
+    if (result.error) {
+      orderFailedCount += 1;
+      continue;
+    }
+    detailFailedCount += result.failedDetails;
+    if (!result.processValues.length) {
+      continue;
+    }
+    processCount += result.processValues.length;
+    records.push(result);
+  }
+
+  const filePath = path.resolve(outDir, `生产单工序跟进表-${todayStr}.xlsx`);
+  if (fs.existsSync(filePath)) {
+    throw new Error(`输出文件已存在：${filePath}；如需替换请先删除旧文件`);
+  }
+  await writeWorkbook(filePath, records);
+
+  const followupTotal = records.reduce((sum, record) => sum + record.followups.length, 0);
+  const elapsed = Math.round((Date.now() - progress.startedAt) / 1000);
+  let summary = `生产单工序跟进表已生成：检查生产单 ${orders.length} 张，其中 ${records.length} 张有工序、`
+    + `共 ${processCount} 个工序；需跟进工序 ${followupTotal} 个（最后汇报超过 ${followupDays} 天或无汇报）`;
+  if (orderFailedCount || detailFailedCount || noSnCount) {
+    summary += `；工序列表失败 ${orderFailedCount} 张、工序明细失败 ${detailFailedCount} 个、缺少单号 ${noSnCount} 张已跳过`;
+  }
+  summary += `；耗时 ${Math.floor(elapsed / 60)}分${String(elapsed % 60).padStart(2, '0')}秒；文件：${filePath}`;
+  return { filePaths: [filePath], summary };
+}
+
+module.exports = { generate };

package/reports/produceBoard.js

@@ -0,0 +1,353 @@
+// 生产节点看板 HTML 报表：近 N 天生产单按「生产中/结束/超期」分组，
+// 每组内按未完成工序节点分列，卡片展示款式图与单号。
+// 数据来自 agent 接口 produce/list（列表行带工序进度），从原 Python 看板脚本移植。
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../cli/api');
+const { readConfig, DEFAULT_SERVER } = require('../cli/config');
+const { timestamp, dateStr, shiftDate, createThrottle } = require('./util');
+
+/** 服务器对同一 AI Key 每分钟限 30 次请求，两次请求间隔至少 2100 毫秒 */
+const REQUEST_INTERVAL_MS = 2100;
+
+/** 服务器单页上限 */
+const PAGE_LIMIT = 100;
+
+/** 分页保护上限，防止服务端分页异常导致无限请求 */
+const MAX_PAGES = 500;
+
+/** 工序节点状态：1 未完成 2 完成（与后端 ProduceOrderConstants 一致） */
+const NODE_STATE_FINISHED = 2;
+
+/** 生产单没有任何未完成工序节点时的兜底列名 */
+const UNCONFIGURED_NODE = '未配置节点';
+
+/** 生产单状态到名称的映射（与后端 ProduceOrderConstants 一致；接口给不出名称时兜底） */
+const STATE_LABELS = {
+  1: '草稿',
+  2: '生产中',
+  3: '生产完成',
+  4: '待生产',
+  9: '撤销',
+  11: '待接单',
+  12: '拒绝接单',
+  13: '待审批',
+  14: '拒绝',
+};
+
+/**
+ * 三个看板分组：[标题, 生产单状态集合, 是否只保留交货日期早于今天的生产单]。
+ * 三个分组一律按工序节点分列，口径保持一致。
+ * 与原脚本相同：生产中=待生产+生产中；结束=生产完成；超期=三种状态且交货日期早于今天。
+ */
+const BOARDS = [
+  { title: '生产中', states: [2, 4], overdueOnly: false },
+  { title: '结束', states: [3], overdueOnly: false },
+  { title: '超期', states: [2, 3, 4], overdueOnly: true },
+];
+
+/** 款式图 CDN 压缩别名：SCM CDN 用 query 形式，qinsilk 图片用 @! 形式 */
+const SCM_IMAGE_ALIAS = '?x-image-process=style/pic200wh';
+const CDN_IMAGE_ALIAS = '@!pic200wh';
+/** 前端同款占位图路径（商品无款式图时使用） */
+const NO_IMAGE_PATH = '/scm-front/assets/no-content-img-BQFT23u5.png';
+
+/** HTML 转义，等价于 Python html.escape(quote=True) */
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+
+/** 取第一个非空值（null、undefined、空字符串视为空），转为去空白字符串 */
+function text(raw) {
+  return raw === null || raw === undefined || raw === '' ? '' : String(raw).trim();
+}
+
+/**
+ * 拉取一组状态的生产单并分页取全量。
+ * 时间范围：业务日期近 days 天（含今天）。后端 SQL 对业务日期结束时间用严格小于比较，
+ * 因此结束日期传明天（today+1）才能包含今天的生产单，等价于原脚本 timeRules 的 lastNdays 规则。
+ * agent 接口的 state 参数只接受单个状态，因此按状态分别分页取全量再合并；
+ * 分页间按生产单号去重（服务端跨页可能重复返回），每个状态的去重计数与接口声明的总条数不一致时报错。
+ */
+async function fetchBoardOrders(states, days, overdueOnly, throttle) {
+  const from = shiftDate(-(days - 1));
+  const to = shiftDate(1);
+  const today = dateStr();
+  const orders = [];
+  const seen = new Set();
+  for (const state of states) {
+    let declared = null;
+    let uniqueCount = 0;
+    let fetched = 0;
+    let page = 1;
+    do {
+      const data = await throttle(() => call('GET', '/api/agent/v1/produce/list', { state, from, to, page, limit: PAGE_LIMIT }));
+      if (declared === null && typeof data.total === 'number') {
+        declared = data.total;
+      }
+      for (const row of data.list || []) {
+        const key = text(row.ordersSn);
+        // 生产单号为空时不参与去重，避免多张无单号的单被错误合并
+        if (key && seen.has(key)) {
+          continue;
+        }
+        if (key) {
+          seen.add(key);
+        }
+        orders.push(row);
+        uniqueCount += 1;
+      }
+      fetched = (data.list || []).length;
+      page += 1;
+    } while (fetched === PAGE_LIMIT && page <= MAX_PAGES);
+    if (declared !== null && uniqueCount !== declared) {
+      throw new Error(`生产单数据不完整：状态 ${state} 接口声明 ${declared} 条，实际获取 ${uniqueCount} 条`);
+    }
+  }
+  if (!overdueOnly) {
+    return orders;
+  }
+  // 超期分组：只保留计划交货日期早于今天的生产单；未设置交货日期的不算超期（与原脚本 before 规则一致）
+  return orders.filter((row) => {
+    const delivery = text(row.deliveryTime);
+    return delivery && delivery < today;
+  });
+}
+
+/** 工序节点显示名：节点名为空时归入「未配置节点」列 */
+function nodeKey(node) {
+  return text(node.workProcessName) || UNCONFIGURED_NODE;
+}
+
+/** 工序显示顺序：showOrder 缺失或非法时用节点在列表中的位置兜底 */
+function nodeOrder(node, fallback) {
+  const value = Number(node.showOrder);
+  return Number.isInteger(value) ? value : fallback;
+}
+
+/** 按 SCM 前端 dealWithPic 的规则给款式图加压缩别名 */
+function aliasImage(url) {
+  if (!url || url.includes('?') || url.includes('@!')) {
+    return url;
+  }
+  if (url.includes('is-scm.cdn.qinsilk.com') || url.includes('is-scm-dev.cdn.qinsilk.com')) {
+    return url + SCM_IMAGE_ALIAS;
+  }
+  if (url.includes('qinsilk.com')) {
+    return url + CDN_IMAGE_ALIAS;
+  }
+  return url;
+}
+
+/** 从接口行构造看板卡片 */
+function buildCard(order) {
+  const ordersSn = text(order.ordersSn);
+  const batchSn = text(order.produceBatchSn);
+  const state = order.state;
+  return {
+    ordersSn,
+    displaySn: batchSn || ordersSn || '未填写单号',
+    goodsSn: text(order.goodsSn),
+    goodsImg: text(order.goodsImgUrl),
+    state,
+    stateName: STATE_LABELS[state] || text(order.stateName) || '未知状态',
+  };
+}
+
+/**
+ * 把每张生产单挂到它全部未完成工序节点列下（扇出）。
+ * 同一张单会出现在多个节点列，卡片数因此大于生产单数——这反映「这些节点都还没做完」。
+ * 去重按（生产单, 节点列名）生效：同一张单在每个节点列内只出现一次，同名节点也只挂一张卡。
+ * 没有任何未完成节点的单（未配置工序，或工序已全部完成）只进「未配置节点」列一次。
+ * 列顺序取该列所有节点 showOrder 的最小值，再按列名字典序。
+ */
+function splitNodes(orderRows) {
+  const columns = new Map();
+  const unconfigured = [];
+  for (const order of orderRows) {
+    const card = buildCard(order);
+    const nodes = (order.workProcesses || []).filter((node) => node && typeof node === 'object');
+    const pending = nodes.map((node, index) => ({ node, index })).filter(({ node }) => node.state !== NODE_STATE_FINISHED);
+    if (!pending.length) {
+      unconfigured.push(card);
+      continue;
+    }
+    const attached = new Set();
+    for (const { node, index } of pending) {
+      const name = nodeKey(node);
+      if (attached.has(name)) {
+        continue;
+      }
+      attached.add(name);
+      let entry = columns.get(name);
+      if (!entry) {
+        entry = { name, cards: [], order: nodeOrder(node, index) };
+        columns.set(name, entry);
+      }
+      entry.order = Math.min(entry.order, nodeOrder(node, index));
+      entry.cards.push(card);
+    }
+  }
+  const ordered = [...columns.values()].sort((a, b) => (a.order - b.order) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { columns: ordered, unconfigured };
+}
+
+/**
+ * 分组统计：orders 按生产单号去重计数；cards 是节点列里实际渲染的卡片总数（扇出后大于单数）；
+ * columns 是工序节点列数；largest 是最大单列卡片数。
+ */
+function boardSummary(columns, unconfigured) {
+  const orders = new Set();
+  for (const column of columns) {
+    for (const card of column.cards) {
+      orders.add(card.ordersSn);
+    }
+  }
+  for (const card of unconfigured) {
+    orders.add(card.ordersSn);
+  }
+  const cards = columns.reduce((sum, column) => sum + column.cards.length, 0) + unconfigured.length;
+  const largest = columns.reduce((max, column) => Math.max(max, column.cards.length), 0);
+  return { orders: orders.size, cards, columns: columns.length, largest };
+}
+
+/**
+ * 渲染一张卡片：款式图 + 单号 + 款号，点击跳转生产单详情页。
+ * 无图片时用前端同款占位图；图片加载失败时 onerror 也切到占位图，避免浏览器裂图。
+ */
+function cardHtml(card, server) {
+  const target = `${server}/scm-front/#/production/production-order-details?ordersSn=${encodeURIComponent(card.ordersSn)}`;
+  const title = `${card.displaySn}　${card.stateName}` + (card.goodsSn ? `　${card.goodsSn}` : '');
+  const placeholder = escapeHtml(`${server}${NO_IMAGE_PATH}`);
+  const source = card.goodsImg ? escapeHtml(aliasImage(card.goodsImg)) : placeholder;
+  const image = `<img src="${source}" alt="${escapeHtml(card.goodsSn || card.displaySn)}" loading="lazy" referrerpolicy="no-referrer" onerror="this.onerror=null;this.src='${placeholder}'">`;
+  const goods = card.goodsSn ? `<span class="card-goods">${escapeHtml(card.goodsSn)}</span>` : '';
+  const inner = `${image}<span class="card-sn">${escapeHtml(card.displaySn)}</span>${goods}`;
+  if (!card.ordersSn) {
+    return `<div class="card" title="${escapeHtml(title)}">${inner}</div>`;
+  }
+  return `<a class="card" title="${escapeHtml(title)}" href="${escapeHtml(target)}" target="_blank" rel="noopener noreferrer">${inner}</a>`;
+}
+
+/** 渲染一个卡片容器；无卡片时显示占位说明 */
+function renderCards(cards, server, emptyText, containerClass) {
+  if (!cards.length) {
+    return `<p class="empty">${escapeHtml(emptyText)}</p>`;
+  }
+  const attr = containerClass ? ` class="${containerClass}"` : '';
+  return `<div${attr}>${cards.map((card) => cardHtml(card, server)).join('')}</div>`;
+}
+
+/** 渲染一个节点列：列头显示节点名与卡片数，列内为卡片 */
+function nodeColumnHtml(name, cards, server, emptyHeader = false) {
+  const headClass = emptyHeader ? 'node-head node-head-empty' : 'node-head';
+  return (
+    '<div class="node-column">'
+    + `<div class="${headClass}">${escapeHtml(name)}<em>${cards.length}</em></div>`
+    + renderCards(cards, server, '暂无生产单', 'node-cells')
+    + '</div>'
+  );
+}
+
+/** 渲染一个分组的节点表：未配置节点列固定放第一列，避免随节点增多被排到最右侧 */
+function renderNodeTable(columns, unconfigured, server) {
+  const output = unconfigured.length ? [nodeColumnHtml(UNCONFIGURED_NODE, unconfigured, server, true)] : [];
+  output.push(...columns.map((column) => nodeColumnHtml(column.name, column.cards, server)));
+  if (!output.length) {
+    return '<p class="empty">暂无生产单</p>';
+  }
+  return `<div class="node-scroll">${output.join('')}</div>`;
+}
+
+/** 渲染一个分组区块：标题 + 单数/卡片数/节点数统计 + 节点表 */
+function renderBoard(board, server) {
+  const summary = boardSummary(board.columns, board.unconfigured);
+  const detail = `${summary.orders} 张生产单　${summary.cards} 张卡片　${summary.columns} 个工序节点`;
+  return (
+    `<section><h2>${escapeHtml(board.title)}<span class="count">${escapeHtml(detail)}</span></h2>`
+    + renderNodeTable(board.columns, board.unconfigured, server)
+    + '</section>'
+  );
+}
+
+/** 组装完整 HTML 文档（样式与说明文案与原脚本一致） */
+function render(boards, day, server, days) {
+  const title = `生产节点看板 - ${day}`;
+  const sections = boards.map((board) => renderBoard(board, server)).join('');
+  return `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(title)}</title><style>
+*{box-sizing:border-box}body{font-family:"Microsoft YaHei",Arial,sans-serif;color:#1f2937;margin:24px;background:#f1f5f9}.report{max-width:100%}h1{font-size:24px;margin:0 0 6px}h2{font-size:20px;margin:0 0 14px;display:flex;align-items:baseline;gap:10px}.count{font-size:13px;font-weight:400;color:#64748b}p{color:#64748b;margin:0 0 16px}section{background:#fff;border:1px solid #dbe3ee;border-radius:8px;padding:18px}section+section{margin-top:26px}
+/* 每个节点固定等宽，横向滚动，列宽不再参差 */
+.node-scroll{display:flex;gap:12px;overflow-x:auto;padding-bottom:6px;align-items:flex-start}
+.node-column{flex:0 0 208px;width:208px;display:flex;flex-direction:column;gap:8px}
+.node-head{border:1px solid #cbd5e1;background:#e8f1fb;color:#1e3a5f;font-size:14px;font-weight:600;padding:8px 10px;border-radius:6px;overflow-wrap:break-word;word-break:break-word}
+.node-head em{font-style:normal;font-weight:400;color:#64748b;margin-left:6px}.node-head-empty{background:#fef3c7;color:#92400e}
+.node-cells{display:flex;flex-direction:column;gap:8px;min-height:60px;padding:8px;border:1px solid #e5eaf2;border-radius:8px;background:#f8fafc}
+.card{display:flex;flex-direction:column;align-items:center;gap:4px;background:#fff;border:1px solid #dbe3ee;border-radius:6px;padding:6px;text-decoration:none;color:#1f2937}.card:hover{border-color:#2563eb;box-shadow:0 1px 6px rgba(37,99,235,.18)}
+.card img{width:100%;height:108px;object-fit:contain;background:#fff;border-radius:4px;display:block}
+.card-sn{font-size:13px;font-weight:600;word-break:break-all;text-align:center}.card-goods{font-size:12px;color:#64748b;word-break:break-all;text-align:center}.hint{font-size:13px;color:#94a3b8;margin:-8px 0 18px}.empty{text-align:center;color:#94a3b8;font-size:13px;padding:18px 0;margin:0}
+</style></head><body><div class="report"><h1>${escapeHtml(title)}</h1><p>订单范围：业务日期近 ${escapeHtml(days)} 天　|　生产中=待生产+生产中　结束=生产完成　超期=待生产+生产中+生产完成且计划交货日期早于今天　|　一张生产单出现在它的全部未完成工序节点下，卡片数大于生产单数属正常</p><p class="hint">Shift + 鼠标滚轮可以横向移动看板</p>${sections}</div></body></html>`;
+}
+
+/** 校验生成结果：文档结构完整、分组数量正确 */
+function validate(document, expectedSections) {
+  if (!document.startsWith('<!doctype html>') || !document.endsWith('</html>')) {
+    throw new Error('生成的 HTML 结构不完整');
+  }
+  const sectionCount = document.split('<section>').length - 1;
+  if (sectionCount !== expectedSections) {
+    throw new Error('生成的 HTML 分组数量不正确');
+  }
+}
+
+/**
+ * 生成生产节点看板 HTML。
+ * 数据流：每个分组按状态分别分页取全量（合并去重并与声明总数比对）→
+ * 按未完成工序节点扇出分列 → 渲染三组看板。
+ * 输出文件已存在时报错，不覆盖。
+ */
+async function generate(argv = {}) {
+  const days = argv.days === undefined ? 7 : Number(argv.days);
+  if (!Number.isFinite(days) || days < 1) {
+    throw new Error('--days 必须大于 0');
+  }
+  if (days > 365) {
+    throw new Error('--days 不能超过 365');
+  }
+  const throttle = createThrottle(REQUEST_INTERVAL_MS);
+  const config = readConfig() || {};
+  const server = config.server || DEFAULT_SERVER;
+
+  const boards = [];
+  for (const board of BOARDS) {
+    const rows = await fetchBoardOrders(board.states, days, board.overdueOnly, throttle);
+    const { columns, unconfigured } = splitNodes(rows);
+    boards.push({ title: board.title, columns, unconfigured });
+    const summary = boardSummary(columns, unconfigured);
+    console.log(`${board.title}：${summary.orders} 张生产单，${summary.cards} 张卡片，${summary.columns} 个工序节点，单节点最多 ${summary.largest} 张`);
+  }
+
+  const document = render(boards, dateStr(), server, days);
+  validate(document, BOARDS.length);
+  const outDir = argv.out || process.cwd();
+  const filePath = path.resolve(outDir, `生产节点看板${timestamp()}.html`);
+  if (fs.existsSync(filePath)) {
+    throw new Error(`输出文件已存在：${filePath}`);
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, document, 'utf8');
+  const counts = boards.map((board) => {
+    const summary = boardSummary(board.columns, board.unconfigured);
+    return `${board.title} ${summary.orders} 张`;
+  });
+  return {
+    filePaths: [filePath],
+    summary: `生产节点看板已生成：${counts.join('、')}（近 ${days} 天）`,
+  };
+}
+
+module.exports = { generate };