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

package/reports/supplierBalance.js

@@ -0,0 +1,671 @@
+// 供应商对账报表：每个供应商导出一个 Excel 对账单文件，内容是对账界面的
+// 11 表结构：1 张汇总表 + 最多 10 类明细表（外发工序加工、委外加工入库、
+// 次品返厂、返修关联加工厂、物料采购、物料采购入库、物料采购退货、
+// 收款付款、优惠金额、应收应付记账）。
+// 数据流：GET /api/agent/v1/supplier/list 分页取供应商，
+// 再逐供应商 GET /api/agent/v1/supplier/balance-record 取 11 表数据。
+// 生成逻辑从原 Python 报表脚本 export_supplier_reconciliation.py 移植，
+// 表结构、列名、合计行、文件名与原脚本一致。与原脚本的差异：
+// 1. 对账状态由 admin 的文字字段 recordStateStr 改为数字 recordState
+//    （1-未对账 2-已对账），本模块转换为文字显示。
+// 2. 外发明细的「完成」列在原脚本读 recover_ 前缀键；agent 接口的发出与
+//    回收共用一行结构，因此完成列直接读同名字段。
+// 3. agent DTO 不提供委外加工入库、次品返厂两表的创建时间列，输出为空。
+// 4. 无供应商欠款数据权限时本期欠款、期末欠款可能为空，按 0 显示。
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../cli/api');
+const { dateStr, createThrottle, fetchAll } = require('./util');
+const { createWorkbook, saveWorkbook } = require('./excel');
+
+/** 服务器对同一 AI Key 每分钟限 30 次请求，两次请求间隔至少 2100 毫秒 */
+const REQUEST_INTERVAL_MS = 2100;
+/** 供应商列表分页大小（服务端单页上限 100） */
+const PAGE_LIMIT = 100;
+/** 金额列的货币格式（与原脚本 numFmt 164 一致） */
+const CURRENCY_FORMAT = '[$¥-804]#,##0.00;[Red]-[$¥-804]#,##0.00';
+
+/** 表头底色（浅蓝，与原脚本一致） */
+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);
+}
+
+/** 取第一个非空值（null、undefined、空字符串视为空） */
+function first(...values) {
+  const found = values.find((v) => v !== null && v !== undefined && v !== '');
+  return found === undefined ? '' : found;
+}
+
+/** 对账状态数字转文字：1-未对账 2-已对账，其余为空 */
+function recordStateText(value) {
+  return ({ 1: '未对账', 2: '已对账' })[value] ?? '';
+}
+
+/** 毫秒时间戳或日期字符串转「yyyy-MM-dd HH:mm:ss」，解析失败返回原始文字 */
+function formatDateTime(value) {
+  if (value === null || value === undefined || value === '') {
+    return '';
+  }
+  let date = null;
+  if (typeof value === 'number') {
+    date = new Date(value);
+  } else {
+    const s = String(value).trim();
+    // 纯数字字符串按毫秒时间戳处理（Java Timestamp 的常见序列化形式）
+    if (/^\d+(\.\d+)?$/.test(s)) {
+      date = new Date(Number(s));
+    } else if (/^\d{4}-\d{2}-\d{2}/.test(s)) {
+      date = new Date(s);
+    }
+    if (!date || Number.isNaN(date.getTime())) {
+      return s;
+    }
+  }
+  if (Number.isNaN(date.getTime())) {
+    return text(value);
+  }
+  const pad = (v) => String(v).padStart(2, '0');
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+  );
+}
+
+/**
+ * 列定义辅助函数。
+ * textCol：普通文本列；amount：数值列（sum 参与合计行，currency 显示货币格式）。
+ * 需要特殊取值的列通过 get 函数提供。
+ */
+function textCol(key, header, get) {
+  return { key, header, get };
+}
+
+function amount(key, header, { sum = false, currency = false } = {}) {
+  return { key, header, sum, currency, numeric: true };
+}
+
+/** 优惠金额列取绝对值（原脚本对 优惠金额明细 的 needAmount 取 abs） */
+function absAmount(key, header, { sum = false, currency = false } = {}) {
+  return {
+    key,
+    header,
+    sum,
+    currency,
+    numeric: true,
+    get: (row) => {
+      const v = row[key];
+      if (v === null || v === undefined || v === '') {
+        return '';
+      }
+      return Math.abs(Number(v));
+    },
+  };
+}
+
+/** 记账明细的生产单/商品列：多个生产批次时从 produceBatchSnList 逐个拼接 */
+function batchJoin(field, fallbackKey) {
+  return (row) => {
+    if (Array.isArray(row.produceBatchSnList)) {
+      return row.produceBatchSnList
+        .map((item) => (item && typeof item === 'object' ? text(item[field]) : ''))
+        .join('、');
+    }
+    return fallbackKey ? text(row[fallbackKey]) : '';
+  };
+}
+
+// ---------- 各明细表的列定义（列名与列序对照原脚本 constants） ----------
+
+/** 外发工序加工明细：发出列与完成列共用 agent 的同名字段（见文件头说明第 2 点） */
+const OUTWARD = [
+  textCol('date', '日期'),
+  textCol('businessSn', '生产单/批次号'),
+  textCol('goodsSn', '款式'),
+  textCol('categoryName', '一级分类'),
+  textCol('colorName', '颜色'),
+  textCol('sizeName', '尺码'),
+  textCol('processNames', '工序'),
+  textCol('outWardRemark', '外发备注'),
+  textCol('recoverRemark', '回收备注'),
+  amount('outWardNumber', '发出数', { sum: true }),
+  amount('recoverNumber', '已收回数', { sum: true }),
+  amount('repairDeductNumber', '返修扣减', { sum: true }),
+  textCol('date', '完成日期'),
+  textCol('businessSn', '完成生产单/批次号'),
+  textCol('goodsSn', '完成款式'),
+  textCol('categoryName', '完成一级分类'),
+  textCol('colorName', '完成颜色'),
+  textCol('sizeName', '完成尺码'),
+  textCol('processNames', '完成工序'),
+  textCol('businessKey', '完成单号'),
+  textCol('businessItemDesc', '完成类型'),
+  amount('recoverNumber', '完成数量', { sum: true }),
+  amount('price', '单价', { currency: true }),
+  amount('needAmount', '应付金额', { sum: true, currency: true }),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('recordRemark', '备注'),
+];
+
+/** 委外加工入库明细、成品采购入库明细（创建时间列 agent 不提供，输出为空） */
+const PROCESS = [
+  textCol('date', '日期'),
+  textCol('businessSn', '入库单'),
+  textCol('produceOrdersSn', '生产单/批次号'),
+  textCol('goodsSn', '款式'),
+  textCol('categoryName', '一级分类'),
+  textCol('colorName', '颜色'),
+  textCol('sizeName', '尺码'),
+  amount('number', '入库数', { sum: true }),
+  textCol('storehouseName', '入库仓库'),
+  textCol('businessRemark', '成品入库单备注'),
+  textCol('remark', '入库单备注'),
+  amount('price', '单价', { currency: true }),
+  amount('needAmount', '应付金额', { sum: true, currency: true }),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('recordRemark', '备注'),
+  textCol('createTime', '创建时间', () => ''),
+  textCol('handlerName', '创建人'),
+];
+
+/** 次品返厂明细（创建时间列 agent 不提供，输出为空） */
+const REWORK = [
+  textCol('date', '日期'),
+  textCol('ordersSn', '次品返厂单'),
+  textCol('goodsStoreInOrdersSn', '入库单'),
+  textCol('produceOrdersSn', '生产单/批次号'),
+  textCol('goodsSn', '款式'),
+  textCol('categoryName', '一级分类'),
+  textCol('colorName', '颜色'),
+  textCol('sizeName', '尺码'),
+  amount('price', '单价', { currency: true }),
+  textCol('businessRemark', '成品入库单备注'),
+  textCol('remark', '返厂单备注'),
+  textCol('illustrate', '说明'),
+  amount('number', '数量', { sum: true }),
+  amount('needAmount', '应付金额', { sum: true, currency: true }),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('recordRemark', '备注'),
+  textCol('createTime', '创建时间', () => ''),
+  textCol('handlerName', '创建人'),
+];
+
+/** 返修关联加工厂明细 */
+const REPAIR = [
+  textCol('date', '日期'),
+  textCol('ordersSn', '质检单'),
+  textCol('produceOrdersSn', '生产单/批次号'),
+  textCol('goodsSn', '款式'),
+  textCol('colorName', '颜色'),
+  textCol('sizeName', '尺码'),
+  amount('price', '单价', { currency: true }),
+  textCol('businessRemark', '质检单备注'),
+  amount('number', '数量', { sum: true }),
+  amount('needAmount', '应付金额', { sum: true, currency: true }),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('remark', '备注'),
+  textCol('createTime', '创建时间', (row) => formatDateTime(row.createTime)),
+  textCol('handlerName', '创建人'),
+];
+
+/** 物料采购明细、物料采购入库明细共用列定义 */
+const PURCHASE = [
+  textCol('date', '日期'),
+  textCol('businessSn', '采购单/采购入库单'),
+  textCol('materialName', '物料'),
+  textCol('materialSn', '货号'),
+  textCol('colorName', '颜色'),
+  textCol('propertyValueNameStr', '规格'),
+  textCol('produceOrdersSn', '生产单/批次号'),
+  textCol('supplierSn', '供应商单号'),
+  textCol('goodsSn', '款式'),
+  amount('purchasePrice', '采购单价', { currency: true }),
+  amount('purchaseRealPrice', '抹零后采购单价', { currency: true }),
+  amount('purchaseNumber', '基础采购数', { sum: true }),
+  textCol('purchaseUnitName', '采购单位'),
+  amount('needAmount', '应付金额', { sum: true, currency: true }),
+  textCol('expectTime', '采购预计到料日期', (row) => formatDateTime(row.expectTime)),
+  textCol('convertRate', '转换系数'),
+  amount('basePrice', '基础单价', { currency: true }),
+  amount('price', '抹零后基础单价', { currency: true }),
+  amount('number', '基础入库数', { sum: true }),
+  textCol('baseUnitName', '基础单位'),
+  textCol('remark', '采购单备注'),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('recordRemark', '备注'),
+  textCol('createTime', '创建时间', (row) => formatDateTime(row.createTime)),
+];
+
+/** 物料采购退货出库明细 */
+const REFUND = [
+  textCol('date', '日期'),
+  textCol('businessSn', '退货出库单'),
+  textCol('materialName', '物料'),
+  textCol('materialSn', '货号'),
+  textCol('colorName', '颜色'),
+  textCol('propertyValueNameStr', '规格'),
+  amount('purchaseRefundPrice', '单价', { currency: true }),
+  textCol('purchaseStoreOutNumber', '出库数'),
+  textCol('purchaseRefundUnitName', '退货单位'),
+  amount('needAmount', '应收金额', { sum: true, currency: true }),
+  textCol('convertRate', '转换系数'),
+  amount('price', '基础单价', { currency: true }),
+  amount('number', '基础出库数', { sum: true }),
+  textCol('baseUnitName', '基础单位'),
+  textCol('remark', '退货单备注'),
+  textCol('materialStoreOutRemark', '出库单备注'),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('recordRemark', '备注'),
+];
+
+/** 收款、付款明细 */
+const PAY = [
+  textCol('date', '日期'),
+  textCol('businessItem', '业务类型'),
+  textCol('businessSn', '单号'),
+  amount('realAmount', '付款金额', { sum: true, currency: true }),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('remark', '备注'),
+  textCol('businessRemark', '单据备注'),
+];
+
+/** 优惠金额明细（needAmount 取绝对值） */
+const DISCOUNT = [
+  textCol('date', '日期'),
+  textCol('businessItem', '业务类型'),
+  textCol('businessSn', '单号'),
+  absAmount('needAmount', '优惠金额', { sum: true, currency: true }),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('remark', '备注'),
+  textCol('businessRemark', '单据备注'),
+];
+
+/** 应收记账、应付记账明细 */
+const ACCOUNT = [
+  textCol('date', '日期'),
+  textCol('businessItem', '业务类型'),
+  textCol('accountItemName', '账目类型'),
+  textCol('businessSn', '单号'),
+  textCol('produceOrdersSn', '生产单', batchJoin('ordersSn', 'produceOrdersKey')),
+  textCol('goodsName', '商品', batchJoin('goodsName', '')),
+  textCol('goodsSn', '货号', batchJoin('goodsSn', '')),
+  amount('needAmount', '应付金额', { sum: true, currency: true }),
+  textCol('payWayStr', '付款方式'),
+  textCol('payerName', '代付人'),
+  textCol('feeReimbursementOrdersSn', '报销单'),
+  textCol('feeReimbursementOrderState', '报销单状态'),
+  textCol('statementStateStr', '结算情况'),
+  textCol('recordState', '对账状态', (row) => recordStateText(row.recordState)),
+  textCol('handlerName', '创建人'),
+  textCol('remark', '备注'),
+];
+
+// ---------- Excel 生成 ----------
+
+/** 取一列在某行上的显示值：数值列返回 number，空值返回空字符串 */
+function cellValue(column, row) {
+  if (column.get) {
+    return column.get(row);
+  }
+  const v = row[column.key];
+  if (column.numeric) {
+    if (v === null || v === undefined || v === '') {
+      return '';
+    }
+    return Number(v);
+  }
+  return text(v);
+}
+
+/** 表头行样式：加粗、浅蓝底、细边框、居中换行 */
+function styleHeaderRow(row, height = 22) {
+  row.height = height;
+  row.eachCell({ includeEmpty: true }, (cell) => {
+    cell.font = { bold: true };
+    cell.fill = HEADER_FILL;
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+  });
+}
+
+/** 写一张明细表：表头 + 数据行 + 合计行（数量列保留 4 位、金额列保留 2 位） */
+function addDetailSheet(workbook, name, columns, rows) {
+  const sheet = workbook.addWorksheet(name, { views: [{ state: 'frozen', ySplit: 1 }] });
+  styleHeaderRow(sheet.addRow(columns.map((c) => c.header)));
+
+  const sums = columns.map(() => 0);
+  for (const row of rows) {
+    const values = columns.map((column, i) => {
+      const value = cellValue(column, row);
+      if (column.sum && typeof value === 'number') {
+        sums[i] += value;
+      }
+      return value;
+    });
+    const added = sheet.addRow(values);
+    added.height = 20;
+    added.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+      cell.border = BORDER;
+      cell.alignment = CENTER;
+      if (columns[colNumber - 1].currency) {
+        cell.numFmt = CURRENCY_FORMAT;
+      }
+    });
+  }
+
+  // 合计行：第一列固定「合计」，参与合计的列输出累计值
+  const totalValues = columns.map((column, i) => {
+    if (i === 0) {
+      return '合计';
+    }
+    if (column.sum) {
+      const digits = column.currency ? 2 : 4;
+      return Math.round(sums[i] * 10 ** digits) / 10 ** digits;
+    }
+    return '';
+  });
+  const totalRow = sheet.addRow(totalValues);
+  totalRow.height = 20;
+  totalRow.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+    cell.font = { bold: true };
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+    if (columns[colNumber - 1].currency) {
+      cell.numFmt = CURRENCY_FORMAT;
+    }
+  });
+
+  columns.forEach((column, i) => {
+    sheet.getColumn(i + 1).width = 14;
+  });
+  return sheet;
+}
+
+/** 汇总表：供应商与对账周期、五个金额汇总、按类型应付金额 */
+function addSummarySheet(workbook, data, supplierName, start, end) {
+  const sheet = workbook.addWorksheet('汇总', { views: [{ state: 'frozen', ySplit: 1 }] });
+  const share = data.shareSum || {};
+  const keys = [
+    ['initDebtAmount', '期初欠款'],
+    ['needAmount', '本期应付金额'],
+    ['realAmount', '本期实付金额'],
+    ['debtAmount', '本期欠款'],
+    ['endDebtAmount', '期末欠款'],
+  ];
+
+  // 第 1 行：供应商名称与对账周期
+  const infoRow = sheet.getRow(1);
+  infoRow.getCell(1).value = '供应商：';
+  infoRow.getCell(2).value = supplierName;
+  infoRow.getCell(4).value = '对账周期：';
+  infoRow.getCell(5).value = `${start}至${end}`;
+  infoRow.height = 20;
+  for (const col of [1, 4]) {
+    const cell = infoRow.getCell(col);
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+  }
+  for (const col of [2, 5]) {
+    const cell = infoRow.getCell(col);
+    cell.font = { bold: true };
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+  }
+
+  // 第 3~4 行：五个金额汇总（无欠款权限时按 0 显示）
+  const headerRow = sheet.getRow(3);
+  keys.forEach(([key, header], i) => {
+    headerRow.getCell(i + 1).value = header;
+  });
+  styleHeaderRow(headerRow);
+  const valueRow = sheet.getRow(4);
+  keys.forEach(([key], i) => {
+    const v = share[key];
+    const number = v === null || v === undefined || v === '' ? 0 : Number(v);
+    valueRow.getCell(i + 1).value = Number.isFinite(number) ? number : 0;
+  });
+  valueRow.height = 20;
+  valueRow.eachCell({ includeEmpty: true }, (cell) => {
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+    cell.numFmt = CURRENCY_FORMAT;
+  });
+
+  // 第 6 行起：按业务类型的应付金额
+  const typeHeader = sheet.getRow(6);
+  typeHeader.getCell(1).value = '类型';
+  typeHeader.getCell(2).value = '应付金额';
+  styleHeaderRow(typeHeader);
+  (data.lstType || []).forEach((typeRow, index) => {
+    const row = sheet.getRow(7 + index);
+    row.getCell(1).value = text(typeRow.typeName);
+    const amount = typeRow.needAmount === null || typeRow.needAmount === undefined || typeRow.needAmount === ''
+      ? 0
+      : Number(typeRow.needAmount);
+    row.getCell(2).value = Number.isFinite(amount) ? amount : 0;
+    row.height = 20;
+    row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+      cell.border = BORDER;
+      cell.alignment = CENTER;
+      if (colNumber === 2) {
+        cell.numFmt = CURRENCY_FORMAT;
+      }
+    });
+  });
+
+  for (let i = 1; i <= 5; i += 1) {
+    sheet.getColumn(i).width = 28;
+  }
+  return sheet;
+}
+
+/** 组装一个供应商的全部工作表：汇总表必有，明细表只在实际有数据时保留 */
+function buildSheets(workbook, data, supplierName, start, end) {
+  addSummarySheet(workbook, data, supplierName, start, end);
+  const configs = [
+    ['外发工序加工明细', OUTWARD, [...(data.lstOutWard || []), ...(data.lstOutWardRecover || [])]],
+    ['委外加工入库明细、成品采购入库明细', PROCESS, data.lstProcess || []],
+    ['次品返厂明细', REWORK, data.lstRework || []],
+    ['返修关联加工厂明细', REPAIR, data.lstRepairDeduction || []],
+    ['物料采购明细', PURCHASE, data.lstPurchaseOrderDetail || []],
+    ['物料采购入库明细', PURCHASE, data.lstPurchaseDetail || []],
+    ['物料采购退货出库明细', REFUND, data.lstRefundDetail || []],
+    ['收款、付款明细', PAY, (data.lstPay || []).filter((row) => row.accountItemId !== 5)],
+    ['优惠金额明细', DISCOUNT, (data.lstPay || []).filter((row) => row.accountItemId === 5)],
+    ['应收记账、应付记账明细', ACCOUNT, data.lstSupplierAccount || []],
+  ];
+  let sheetCount = 1;
+  for (const [sheetName, columns, rows] of configs) {
+    if (rows.length) {
+      addDetailSheet(workbook, sheetName, columns, rows);
+      sheetCount += 1;
+    }
+  }
+  return sheetCount;
+}
+
+// ---------- 查询与参数 ----------
+
+/** 分页取供应商列表（可选按名称过滤，服务端为模糊匹配） */
+async function fetchSuppliers(throttle, supplierName) {
+  const { list } = await fetchAll(
+    (page, limit) => throttle(() => call('GET', '/api/agent/v1/supplier/list', {
+      supplierName: supplierName || undefined,
+      page,
+      limit,
+    })),
+    { limit: PAGE_LIMIT },
+  );
+  return list;
+}
+
+/** 供应商行取 id 与名称（agent 字段为 id/supplierName） */
+function chooseSuppliers(suppliers, argv) {
+  const idOf = (row) => first(row.supplierId, row.id);
+  const nameOf = (row) => row.supplierName || row.name || '未命名供应商';
+  if (argv.supplierId !== undefined && argv.supplierId !== null && argv.supplierId !== '') {
+    const wanted = String(argv.supplierId);
+    const found = suppliers.find((row) => String(idOf(row)) === wanted);
+    return [{ id: argv.supplierId, name: found ? nameOf(found) : wanted }];
+  }
+  if (argv.supplier) {
+    if (suppliers.length !== 1) {
+      throw new Error(`名称“${argv.supplier}”匹配到 ${suppliers.length} 个供应商；请改用更精确的名称或供应商 id`);
+    }
+    return [{ id: idOf(suppliers[0]), name: nameOf(suppliers[0]) }];
+  }
+  return suppliers
+    .filter((row) => idOf(row) !== '')
+    .map((row) => ({ id: idOf(row), name: nameOf(row) }));
+}
+
+/** 解析并校验日期字符串，返回当日零点的 Date */
+function parseDay(value, label) {
+  const s = String(value || '');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+    throw new Error(`${label}日期格式应为 yyyy-MM-dd：${s}`);
+  }
+  const date = new Date(`${s}T00:00:00`);
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`${label}日期无效：${s}`);
+  }
+  return date;
+}
+
+/** 取一个月前的同一天（目标月天数不足时取当月最后一天） */
+function monthBack(date) {
+  const year = date.getMonth() > 0 ? date.getFullYear() : date.getFullYear() - 1;
+  const month = date.getMonth() > 0 ? date.getMonth() - 1 : 11;
+  const lastDay = new Date(year, month + 1, 0).getDate();
+  return new Date(year, month, Math.min(date.getDate(), lastDay));
+}
+
+/**
+ * 确定对账周期。优先使用显式传入的 from/to（必须同时提供）；
+ * 未提供时按 period 取默认区间（recent-month 近一个自然月到当天，
+ * last-month 上个自然月，current-month 本月 1 日到当天）。
+ * 区间必须有效且不超过 365 天（与原脚本一致）。
+ */
+function resolveRange(argv) {
+  let start;
+  let end;
+  if (argv.from !== undefined || argv.to !== undefined) {
+    if (!argv.from || !argv.to) {
+      throw new Error('自定义对账周期必须同时提供 from 与 to（格式 yyyy-MM-dd）');
+    }
+    start = parseDay(argv.from, '开始');
+    end = parseDay(argv.to, '结束');
+  } else {
+    const period = argv.period || 'recent-month';
+    const today = new Date();
+    if (period === 'recent-month') {
+      start = monthBack(today);
+      end = today;
+    } else if (period === 'last-month') {
+      end = new Date(today.getFullYear(), today.getMonth(), 0);
+      start = new Date(end.getFullYear(), end.getMonth(), 1);
+    } else if (period === 'current-month') {
+      start = new Date(today.getFullYear(), today.getMonth(), 1);
+      end = today;
+    } else {
+      throw new Error(`不支持的对账周期：${period}`);
+    }
+  }
+  if (end < start) {
+    throw new Error('对账周期结束日期不能早于开始日期');
+  }
+  if ((end - start) / 86400000 > 365) {
+    throw new Error('对账周期不能超过 366 天');
+  }
+  return { start: dateStr(start), end: dateStr(end) };
+}
+
+/** 文件名安全处理：替换非法字符、去掉首尾空白与点号（与原脚本 safe_filename 一致） */
+function safeFilename(value) {
+  const cleaned = String(value ?? '')
+    .replace(/[\\/:*?"<>|\x00-\x1f]+/g, '_')
+    .trim()
+    .replace(/^[.\s]+|[.\s]+$/g, '');
+  return cleaned || '未命名供应商';
+}
+
+// ---------- 报表入口 ----------
+
+/**
+ * 生成供应商对账 Excel。
+ * argv：{ supplier 供应商名称（可选，不传导出全部）,
+ *         supplierId 供应商 id（可选，优先于名称）,
+ *         from/to 对账起止日期（可选，默认近一个自然月）,
+ *         period 默认周期（可选）, out 输出目录 }。
+ * 每个供应商一个文件，文件已存在时报错，不覆盖。
+ */
+async function generate(argv = {}) {
+  const throttle = createThrottle(REQUEST_INTERVAL_MS);
+  const { start, end } = resolveRange(argv);
+
+  // 指定 id 时不按名称过滤，保证能从全量列表解析出名称
+  const hasId = argv.supplierId !== undefined && argv.supplierId !== null && argv.supplierId !== '';
+  const suppliers = await fetchSuppliers(throttle, hasId ? undefined : argv.supplier);
+  const chosen = chooseSuppliers(suppliers, argv);
+  if (!chosen.length) {
+    throw new Error('没有可导出的供应商');
+  }
+
+  const outDir = argv.out ? path.resolve(String(argv.out)) : process.cwd();
+  const filePaths = [];
+  let totalSheets = 0;
+  let summaryOnlyCount = 0;
+  for (let i = 0; i < chosen.length; i += 1) {
+    const { id, name } = chosen[i];
+    const data = (await throttle(() => call('GET', '/api/agent/v1/supplier/balance-record', {
+      supplierId: id,
+      from: start,
+      to: end,
+    }))) || {};
+    const workbook = createWorkbook();
+    const sheetCount = buildSheets(workbook, data, name, start, end);
+    if (sheetCount === 1) {
+      summaryOnlyCount += 1;
+    }
+    totalSheets += sheetCount;
+
+    const filePath = path.resolve(
+      outDir,
+      `供应商对账_${safeFilename(name)}_${start.replace(/-/g, '')}至${end.replace(/-/g, '')}.xlsx`,
+    );
+    if (fs.existsSync(filePath)) {
+      throw new Error(`输出文件已存在：${filePath}；如需替换请先删除旧文件`);
+    }
+    await saveWorkbook(workbook, filePath);
+    filePaths.push(filePath);
+    if ((i + 1) % 10 === 0) {
+      process.stdout.write(`供应商对账进度：已导出 ${i + 1}/${chosen.length} 个供应商\n`);
+    }
+  }
+
+  let summary = `供应商对账导出完成：供应商 ${filePaths.length} 个（对账周期 ${start} 至 ${end}），共保留 ${totalSheets} 张工作表（汇总及非空明细）`;
+  if (summaryOnlyCount) {
+    summary += `；其中 ${summaryOnlyCount} 个供应商只有汇总表（明细无数据）`;
+  }
+  summary += `；输出目录：${outDir}`;
+  return { filePaths, summary };
+}
+
+module.exports = { generate };