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

package/reports/materialTransit.js

@@ -0,0 +1,593 @@
+// 物料在途状态报表：三个工作表（采购在途 / 已入库未发料 / 物料缺口提醒）。
+// 数据来自用料中心物料明细视图（进行中的用料行 + 生产中/待生产的生产单）。
+// 「物料缺口提醒」对辅料按主面料采购入库数折算：
+//   单品预裁数 = min over 面料( floor( 面料已入库 × 该单品下单数 / 分配总量 ÷ 单件用量(含损耗) ) )
+//   预计总用量(面料采购) = Σ 预裁数 × 单件用量(含损耗、含缩水)
+//   预估差额 = 预计总用量(面料采购) - 基础已采购
+// 逐单调生产单详情取 BOM 与下单数（接口限流，请求间隔至少 2.1 秒），
+// 款式图来自详情或按单号查生产单列表。
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../cli/api');
+const { dateStr, shiftDate, timestamp, fetchAll, createThrottle } = require('./util');
+const { createWorkbook, saveWorkbook, embedImage } = require('./excel');
+const { downloadImages } = require('./image');
+
+const SHEETS = {
+  purchase: '采购在途',
+  stored: '已入库未发料',
+  gap: '物料缺口提醒',
+};
+// 用料状态：0 进行中（报表固定口径，与用料中心页面默认一致）
+const USE_STATE_PROCESSING = 0;
+// 物料类型名：面料。判定「主面料」用（类型名缺失时按类型值 1=面料）
+const FABRIC_TYPE_NAME = '面料';
+const FABRIC_MATERIAL_TYPE = 1;
+// 换算结果保留的小数位（与接口数据同精度）
+const ROUND_PLACES = 4;
+// 逐单请求详情/列表的节流间隔（毫秒）
+const DETAIL_THROTTLE_MS = 2100;
+
+// 三个工作表的列定义（列名、字段、类型），与原脚本的表头顺序一致
+const COLUMNS_PURCHASE = [
+  { header: '图片', field: 'imgUrl', kind: 'image' },
+  { header: '物料名称', field: 'name', kind: 'text' },
+  { header: '物料货号', field: 'sn', kind: 'text' },
+  { header: '颜色', field: 'colorName', kind: 'text' },
+  { header: '规格', field: 'spec', kind: 'text' },
+  { header: '类型', field: 'smTypeName', kind: 'text' },
+  { header: '生产单号', field: 'ordersSnDisplay', kind: 'text' },
+  { header: '款式图', field: 'goodsImgUrl', kind: 'image' },
+  { header: '物料色号', field: 'supplierColor', kind: 'text' },
+  { header: '采购数', field: 'purchaseNumber', kind: 'number' },
+  { header: '采购单位', field: 'purchaseUnitName', kind: 'text' },
+];
+const COLUMNS_STORED = [
+  { header: '生产单号', field: 'ordersSnDisplay', kind: 'text' },
+  { header: '款式图', field: 'goodsImgUrl', kind: 'image' },
+  { header: '预计总用量(下单数)', field: 'orderRequirementNumber', kind: 'number' },
+  { header: '发料数', field: 'issueInNumber', kind: 'number' },
+  { header: '物料货号', field: 'sn', kind: 'text' },
+  { header: '规格', field: 'spec', kind: 'text' },
+  { header: '类型', field: 'smTypeName', kind: 'text' },
+  { header: '物料色号', field: 'supplierColor', kind: 'text' },
+  { header: '采购数', field: 'purchaseNumber', kind: 'number' },
+  { header: '采购已入库', field: 'purchaseInNumber', kind: 'number' },
+  { header: '采购单位', field: 'purchaseUnitName', kind: 'text' },
+  { header: '基础已入库', field: 'baseInNumber', kind: 'number' },
+  { header: '基础单位', field: 'baseUnitName', kind: 'text' },
+];
+const COLUMNS_GAP = [
+  { header: '生产单号', field: 'ordersSnDisplay', kind: 'text' },
+  { header: '款式图', field: 'goodsImgUrl', kind: 'image' },
+  { header: '物料货号', field: 'sn', kind: 'text' },
+  { header: '颜色', field: 'colorName', kind: 'text' },
+  { header: '物料色号', field: 'supplierColor', kind: 'text' },
+  { header: '预计总用量(下单数)', field: 'orderRequirementNumber', kind: 'number' },
+  { header: '预计总用量(面料采购)', field: 'requirementByFabricPurchase', kind: 'number' },
+  { header: '预估差额', field: 'shortfallByFabricPurchase', kind: 'number' },
+  { header: '采购数', field: 'purchaseNumber', kind: 'number' },
+  { header: '采购已入库', field: 'purchaseInNumber', kind: 'number' },
+  { header: '采购单位', field: 'purchaseUnitName', kind: 'text' },
+  { header: '基础已采购', field: 'basePurchaseNumber', kind: 'number' },
+  { header: '基础已入库', field: 'baseInNumber', kind: 'number' },
+  { header: '基础单位', field: 'baseUnitName', kind: 'text' },
+];
+
+const BORDER = {
+  top: { style: 'thin', color: { argb: 'FFCCCCCC' } },
+  left: { style: 'thin', color: { argb: 'FFCCCCCC' } },
+  bottom: { style: 'thin', color: { argb: 'FFCCCCCC' } },
+  right: { style: 'thin', color: { argb: 'FFCCCCCC' } },
+};
+// 表头底色：浅蓝（与原脚本一致）
+const HEADER_FILL = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE8F1FB' } };
+// 嵌图行的统一行高（约 92 像素），有图无图都用同一高度，图片底部对齐
+const IMAGE_ROW_HEIGHT = 69;
+// 图片显示尺寸（像素）：宽 60 高 80，接近原脚本 64x88 的图片框
+const IMAGE_SIZE = { width: 60, height: 80 };
+
+/** 文本归一化：空值返回空字符串 */
+function text(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+/** 参与运算的数值：缺失或非法按 0 处理 */
+function amountOf(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+/** 四舍五入（远离零）保留 places 位小数 */
+function roundHalfUp(value, places) {
+  const factor = 10 ** places;
+  const magnitude = Math.abs(value) * factor;
+  const rounded = Math.round(magnitude + Number.EPSILON * magnitude);
+  const result = (value < 0 ? -rounded : rounded) / factor;
+  return Object.is(result, -0) ? 0 : result;
+}
+
+/** 换算结果保留 4 位小数 */
+function round4(value) {
+  return roundHalfUp(value, ROUND_PLACES);
+}
+
+/** 除法：与后端 BigDecimalUtil.div 一致，HALF_UP 保留 2 位；分母为 0 或缺失返回 0 */
+function divide(numerator, denominator) {
+  const divisor = Number(denominator);
+  if (!Number.isFinite(divisor) || divisor === 0) {
+    return 0;
+  }
+  return roundHalfUp(amountOf(numerator) / divisor, 2);
+}
+
+/** 数量列取值：数值写数字，无法转换按原文返回 */
+function numeric(value) {
+  if (value === null || value === undefined || value === '') {
+    return '';
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return text(value);
+  }
+  return parsed;
+}
+
+/** 采购已入库 = 采购数 - 采购待入库数（采购单位口径） */
+function purchaseInNumber(row) {
+  return round4(amountOf(row.purchaseNumber) - amountOf(row.purchaseWinNumber));
+}
+
+/** 基础已入库 = 采购已入库 × 转换系数 */
+function baseInNumberOf(row) {
+  return round4(purchaseInNumber(row) * amountOf(row.convertRate || 1));
+}
+
+/** 基础已采购 = 采购数 × 转换系数 */
+function basePurchaseNumberOf(row) {
+  return round4(amountOf(row.purchaseNumber) * amountOf(row.convertRate || 1));
+}
+
+/** 生产单号：ordersSn 优先，缺失时用 produceOrdersSn */
+function ordersSnOf(row) {
+  return text(row.ordersSn) || text(row.produceOrdersSn);
+}
+
+/**
+ * 用料中心行是否面料：类型名优先（smTypeName == 面料），
+ * 类型名缺失时按物料类型值 1 判断。
+ */
+function rowIsFabric(row) {
+  const name = text(row.smTypeName);
+  if (name) {
+    return name === FABRIC_TYPE_NAME;
+  }
+  if (row.materialType != null && row.materialType !== '') {
+    return amountOf(row.materialType) === FABRIC_MATERIAL_TYPE;
+  }
+  return false;
+}
+
+/**
+ * BOM 行是否面料。BOM 行本身没有类型字段，用生产单详情 materialList 里
+ * 同物料单品的 materialTypeName / materialType 判断。
+ */
+function bomIsFabric(bomRow, materialTypeIndex) {
+  const info = materialTypeIndex.get(String(bomRow.materialSkuId));
+  if (info) {
+    if (info.name) {
+      return info.name === FABRIC_TYPE_NAME;
+    }
+    if (info.type != null) {
+      return amountOf(info.type) === FABRIC_MATERIAL_TYPE;
+    }
+  }
+  return false;
+}
+
+/** 单件用量（含损耗率，不含缩水率）：number × (1 + 损耗率/100) */
+function perUseWithLoss(bomRow) {
+  return amountOf(bomRow.number) * (1 + amountOf(bomRow.materialLossRate) / 100);
+}
+
+/** 单件用量（含损耗率与缩水率）：× (1+损耗率/100) ÷ (1-缩水率/100)；分母为 0 返回 0 */
+function perUseWithLossAndShrink(bomRow) {
+  const divisor = 1 - amountOf(bomRow.shrinkRate) / 100;
+  if (divisor === 0) {
+    return 0;
+  }
+  return perUseWithLoss(bomRow) / divisor;
+}
+
+/**
+ * 把一张生产单详情整理成缺口计算用的索引：
+ * quantities：商品单品 id → 下单数（整数，小数截断）；
+ * materials：(商品单品 id, 物料单品 id) → BOM 行，同键保留第一条。
+ */
+function bomIndexOf(detail) {
+  const quantities = new Map();
+  for (const goods of (detail && detail.orderGoods) || []) {
+    if (goods == null || goods.goodsSkuId == null) {
+      continue;
+    }
+    quantities.set(String(goods.goodsSkuId), Math.trunc(amountOf(goods.number)));
+  }
+  const materials = new Map();
+  for (const bom of (detail && detail.bomList) || []) {
+    if (bom == null || bom.goodsSkuId == null || bom.materialSkuId == null) {
+      continue;
+    }
+    const key = `${bom.goodsSkuId}|${bom.materialSkuId}`;
+    if (!materials.has(key)) {
+      materials.set(key, bom);
+    }
+  }
+  return { quantities, materials };
+}
+
+/** (生产单号, 物料单品id) → 面料采购已入库数（采购单位口径） */
+function fabricInNumbers(rows) {
+  const result = new Map();
+  for (const row of rows) {
+    if (!rowIsFabric(row)) {
+      continue;
+    }
+    const sn = ordersSnOf(row);
+    const skuId = text(row.materialSkuId);
+    if (sn && skuId) {
+      result.set(`${sn}|${skuId}`, purchaseInNumber(row));
+    }
+  }
+  return result;
+}
+
+/**
+ * 每个商品单品的「预裁数」：该单品用到的每个面料单品各算一个可裁数后取最小。
+ * 可裁数 = floor( 面料已入库 × 该单品下单数 ÷ 分配总量 ÷ 单件用量(含损耗) )，
+ * 中间除法按 2 位小数四舍五入（与后端 getPreCutNumber 一致）。
+ * 面料已入库为 0 时按 0 参与；面料行不在本批用料数据里时跳过该面料。
+ */
+function preCutNumbers(sn, orderBom, fabricIn, materialTypeIndex) {
+  const { quantities, materials } = orderBom;
+  // 每个面料单品分到的商品单品集合与下单数合计
+  const fabricSkus = new Map();
+  for (const [key, bomRow] of materials) {
+    if (!bomIsFabric(bomRow, materialTypeIndex) || perUseWithLoss(bomRow) <= 0) {
+      continue;
+    }
+    const [, materialSkuId] = key.split('|');
+    if (!fabricSkus.has(materialSkuId)) {
+      fabricSkus.set(materialSkuId, new Set());
+    }
+    fabricSkus.get(materialSkuId).add(key);
+  }
+  const fabricTotal = new Map();
+  for (const [materialSkuId, keys] of fabricSkus) {
+    let total = 0;
+    for (const key of keys) {
+      const [goodsSkuId] = key.split('|');
+      total += quantities.get(goodsSkuId) || 0;
+    }
+    fabricTotal.set(materialSkuId, total);
+  }
+
+  const result = new Map();
+  for (const [key, bomRow] of materials) {
+    if (!bomIsFabric(bomRow, materialTypeIndex)) {
+      continue;
+    }
+    const [goodsSkuId, materialSkuId] = key.split('|');
+    const perUse = perUseWithLoss(bomRow);
+    const total = fabricTotal.get(materialSkuId) || 0;
+    if (perUse <= 0 || total === 0) {
+      continue;
+    }
+    const inNumber = fabricIn.get(`${sn}|${materialSkuId}`);
+    if (inNumber === undefined) {
+      continue;
+    }
+    const allocated = divide(inNumber * (quantities.get(goodsSkuId) || 0), total);
+    const cut = Math.floor(divide(allocated, perUse));
+    const current = result.get(goodsSkuId);
+    result.set(goodsSkuId, current === undefined ? cut : Math.min(current, cut));
+  }
+  return result;
+}
+
+/**
+ * 预计总用量(面料采购)：该物料在各商品单品上的 Σ(预裁数 × 单件用量含损耗缩水)。
+ */
+function requirementByFabricPurchase(row, preCut, orderBom) {
+  const materialSkuId = text(row.materialSkuId);
+  let total = 0;
+  for (const [key, bomRow] of orderBom.materials) {
+    const [, bomMaterialSkuId] = key.split('|');
+    if (bomMaterialSkuId !== materialSkuId) {
+      continue;
+    }
+    const [goodsSkuId] = key.split('|');
+    const cut = preCut.get(goodsSkuId) || 0;
+    if (cut <= 0) {
+      continue;
+    }
+    total += cut * perUseWithLossAndShrink(bomRow);
+  }
+  return round4(total);
+}
+
+/** 单元格值：数量列写数字，图片列留空（图片单独嵌入） */
+function cellValue(row, column) {
+  const value = row[column.field];
+  if (column.kind === 'image') {
+    return '';
+  }
+  if (column.kind === 'number') {
+    return numeric(value);
+  }
+  return text(value);
+}
+
+/** 列宽：图片 10、数量 15、文本按标题长度（与原脚本一致） */
+function columnWidth(column) {
+  if (column.kind === 'image') {
+    return 10;
+  }
+  if (column.kind === 'number') {
+    return 15;
+  }
+  return Math.max(12, Math.min(24, column.header.length * 3 + 4));
+}
+
+/** 写一个工作表：单层表头 + 数据行 + 嵌图 + 自动筛选 + 冻结首行 */
+function buildSheet(workbook, sheetName, columns, rows, images) {
+  const sheet = workbook.addWorksheet(sheetName, {
+    views: [{ state: 'frozen', ySplit: 1 }],
+    pageSetup: { orientation: 'landscape', fitToPage: true, fitToWidth: 1, fitToHeight: 0 },
+  });
+  const headerRow = sheet.addRow(columns.map((column) => column.header));
+  headerRow.height = 24;
+  headerRow.eachCell((cell) => {
+    cell.font = { bold: true };
+    cell.fill = HEADER_FILL;
+    cell.border = BORDER;
+    cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
+  });
+  const imageCols = columns
+    .map((column, index) => (column.kind === 'image' ? index + 1 : 0))
+    .filter(Boolean);
+  rows.forEach((row, index) => {
+    const rowNumber = index + 2;
+    const added = sheet.addRow(columns.map((column) => cellValue(row, column)));
+    added.height = IMAGE_ROW_HEIGHT;
+    added.eachCell((cell, colNumber) => {
+      const kind = columns[colNumber - 1].kind;
+      cell.border = BORDER;
+      cell.alignment = {
+        vertical: 'middle',
+        horizontal: kind === 'text' ? 'left' : kind === 'number' ? 'right' : 'center',
+        wrapText: kind === 'text',
+      };
+    });
+    for (const col of imageCols) {
+      const url = text(row[columns[col - 1].field]);
+      if (url && images.has(url)) {
+        embedImage(workbook, sheet, images.get(url), rowNumber, col, IMAGE_SIZE);
+      }
+    }
+  });
+  columns.forEach((column, index) => {
+    sheet.getColumn(index + 1).width = columnWidth(column);
+  });
+  if (rows.length) {
+    const lastColLetter = sheet.getColumn(columns.length).letter;
+    sheet.autoFilter = `A1:${lastColLetter}${rows.length + 1}`;
+  }
+  return sheet;
+}
+
+/**
+ * 生成物料在途状态报表 Excel。
+ * argv.days：业务日期回看天数，默认 90（结束日今天，起始日往前 days-1 天）；
+ * argv.from/to：直接指定日期区间，覆盖 days；argv.out：输出目录。
+ */
+async function generate(argv = {}) {
+  const days = Math.max(Number(argv.days) > 0 ? Number(argv.days) : 90, 1);
+  const to = argv.to || dateStr();
+  const from = argv.from || shiftDate(-(days - 1), new Date(`${to}T00:00:00`));
+  if (from > to) {
+    throw new Error('起始日期不能晚于结束日期');
+  }
+
+  const outDir = argv.out || process.cwd();
+  const filePath = path.resolve(outDir, `物料在途状态报表${timestamp()}.xlsx`);
+  if (fs.existsSync(filePath)) {
+    throw new Error(`输出文件已存在：${filePath}；如需替换请先删除旧文件或更换输出目录`);
+  }
+
+  // 企业配置：produceBatchSnEnable 决定生产单号列显示批次号还是生产单号；失败按未开启处理
+  let useBatchSn = false;
+  try {
+    const config = await call('GET', '/api/agent/v1/company-config');
+    useBatchSn = config && config.produceBatchSnEnable === true;
+  } catch (e) {
+    // 配置接口失败不中断导出
+  }
+
+  // 用料中心物料明细：进行中的用料行 + 生产中/待生产的生产单（spoState 固定 2,4）
+  const { list: rows } = await fetchAll(
+    (page, limit) => call('GET', '/api/agent/v1/material-requirement/list', {
+      from,
+      to,
+      spoState: '2,4',
+      useState: USE_STATE_PROCESSING,
+      page,
+      limit,
+    })
+  );
+
+  const isAccessory = (row) => !rowIsFabric(row);
+  // 三个 sheet 的行筛选（与原脚本一致）
+  const purchaseRows = rows.filter((row) => amountOf(row.purchaseNumber) !== 0);
+  const storedRows = rows.filter(
+    (row) => row.useState === USE_STATE_PROCESSING
+      && purchaseInNumber(row) > 0
+      && amountOf(row.issueInNumber) === 0
+  );
+  if (!purchaseRows.length && !storedRows.length) {
+    throw new Error('没有符合条件的物料在途数据');
+  }
+
+  // 物料缺口提醒：先对「进行中且有辅料行」的生产单逐单取详情（含 BOM 与下单数）
+  const throttle = createThrottle(DETAIL_THROTTLE_MS);
+  const candidateSns = [...new Set(
+    rows.filter((row) => row.useState === USE_STATE_PROCESSING && isAccessory(row))
+      .map((row) => ordersSnOf(row))
+      .filter(Boolean)
+  )].sort();
+  const details = new Map();
+  const bomFailed = [];
+  for (const sn of candidateSns) {
+    try {
+      const detail = await throttle(() => call('GET', '/api/agent/v1/produce/detail', { sn }));
+      if (detail) {
+        details.set(sn, detail);
+      }
+    } catch (e) {
+      bomFailed.push(sn);
+    }
+  }
+
+  // 缺口计算：先整理每张单的 BOM 索引与物料类型索引
+  const bomIndexes = new Map();
+  const materialTypeIndexes = new Map();
+  for (const [sn, detail] of details) {
+    bomIndexes.set(sn, bomIndexOf(detail));
+    const typeIndex = new Map();
+    for (const material of detail.materialList || []) {
+      if (material && material.materialSkuId != null) {
+        typeIndex.set(String(material.materialSkuId), { name: text(material.materialTypeName), type: material.materialType });
+      }
+    }
+    materialTypeIndexes.set(sn, typeIndex);
+  }
+  const fabricIn = fabricInNumbers(rows);
+  for (const row of rows) {
+    row.basePurchaseNumber = basePurchaseNumberOf(row);
+    const sn = ordersSnOf(row);
+    const orderBom = bomIndexes.get(sn);
+    if (!orderBom || !isAccessory(row)) {
+      // 没有 BOM（详情读取失败）或面料行：两列留空而不是填 0，避免被当成「无缺口」
+      row.requirementByFabricPurchase = '';
+      row.shortfallByFabricPurchase = '';
+    } else {
+      const preCut = preCutNumbers(sn, orderBom, fabricIn, materialTypeIndexes.get(sn));
+      row.requirementByFabricPurchase = requirementByFabricPurchase(row, preCut, orderBom);
+      row.shortfallByFabricPurchase = round4(
+        amountOf(row.requirementByFabricPurchase) - amountOf(basePurchaseNumberOf(row))
+      );
+    }
+  }
+  const gapRows = rows.filter((row) => {
+    if (row.useState !== USE_STATE_PROCESSING || !isAccessory(row)) {
+      return false;
+    }
+    const required = Number(row.requirementByFabricPurchase);
+    const shortfall = Number(row.shortfallByFabricPurchase);
+    return Number.isFinite(required) && required > 0 && Number.isFinite(shortfall) && shortfall >= 0;
+  });
+  const gapSkipped = rows.filter(
+    (row) => row.useState === USE_STATE_PROCESSING
+      && isAccessory(row)
+      && !(Number(row.requirementByFabricPurchase) > 0)
+  ).length;
+
+  // 款式图：详情已有的单直接用；其余单按单号查生产单列表补图
+  const goodsImgBySn = new Map();
+  for (const [sn, detail] of details) {
+    goodsImgBySn.set(sn, text(detail.goodsImgUrl));
+  }
+  const wantedSns = [...new Set(
+    [...purchaseRows, ...storedRows, ...gapRows].map((row) => ordersSnOf(row)).filter(Boolean)
+  )];
+  for (const sn of wantedSns) {
+    if (goodsImgBySn.has(sn)) {
+      continue;
+    }
+    try {
+      // 只按单号关键词查询，不带业务日期：款式图所属生产单的业务日期可能在本报表区间之外
+      const data = await throttle(() => call('GET', '/api/agent/v1/produce/list', { searchKey: sn }));
+      const matched = (data && data.list ? data.list : []).find((item) => text(item.ordersSn) === sn);
+      goodsImgBySn.set(sn, matched ? text(matched.goodsImgUrl) : '');
+    } catch (e) {
+      goodsImgBySn.set(sn, '');
+    }
+  }
+  for (const row of rows) {
+    row.goodsImgUrl = goodsImgBySn.get(ordersSnOf(row)) || '';
+  }
+
+  // 行排序与展示字段整理（规格、单号显示、换算列）
+  const sortRows = (list) => list.sort((a, b) => {
+    const left = [ordersSnOf(a), text(a.sn), text(a.supplierColor)];
+    const right = [ordersSnOf(b), text(b.sn), text(b.supplierColor)];
+    for (let i = 0; i < 3; i += 1) {
+      if (left[i] !== right[i]) {
+        return left[i] < right[i] ? -1 : 1;
+      }
+    }
+    return 0;
+  });
+  const transformRow = (row) => {
+    const properties = Array.isArray(row.skuProperties) ? row.skuProperties : [];
+    const spec = properties.map((item) => text(item.propertyValue)).join('-');
+    const batchSn = text(row.produceBatchSn);
+    return {
+      ...row,
+      spec: spec || '-',
+      ordersSnDisplay: useBatchSn && batchSn ? batchSn : ordersSnOf(row),
+      purchaseInNumber: purchaseInNumber(row),
+      baseInNumber: baseInNumberOf(row),
+    };
+  };
+  const sheetPurchase = sortRows(purchaseRows).map(transformRow);
+  const sheetStored = sortRows(storedRows).map(transformRow);
+  const sheetGap = sortRows(gapRows).map(transformRow);
+
+  // 批量下载全部图片（物料图 + 款式图）
+  const urls = new Set();
+  for (const row of [...sheetPurchase, ...sheetStored, ...sheetGap]) {
+    for (const column of [...COLUMNS_PURCHASE, ...COLUMNS_STORED, ...COLUMNS_GAP]) {
+      if (column.kind === 'image') {
+        const url = text(row[column.field]);
+        if (url) {
+          urls.add(url);
+        }
+      }
+    }
+  }
+  const images = await downloadImages([...urls]);
+
+  const workbook = createWorkbook();
+  buildSheet(workbook, SHEETS.purchase, COLUMNS_PURCHASE, sheetPurchase, images);
+  buildSheet(workbook, SHEETS.stored, COLUMNS_STORED, sheetStored, images);
+  buildSheet(workbook, SHEETS.gap, COLUMNS_GAP, sheetGap, images);
+
+  await saveWorkbook(workbook, filePath);
+
+  const notes = [];
+  if (gapSkipped) {
+    notes.push(`${gapSkipped} 行辅料的「预计总用量(面料采购)」为 0 或无法计算（整单面料尚未入库、面料行不在本批数据或 BOM 读取失败），未纳入缺口提醒`);
+  }
+  if (bomFailed.length) {
+    notes.push(`${bomFailed.length} 张生产单的详情读取失败（${bomFailed.slice(0, 5).join('、')}${bomFailed.length > 5 ? ' 等' : ''}）`);
+  }
+  return {
+    filePaths: [filePath],
+    summary: `物料在途状态报表已生成：业务日期 ${from} ~ ${to}，用料中心明细 ${rows.length} 行；` +
+      `「采购在途」${sheetPurchase.length} 行、「已入库未发料」${sheetStored.length} 行、「物料缺口提醒」${sheetGap.length} 行，` +
+      `嵌图 ${images.size} 张，单号显示${useBatchSn ? '生产批次号优先' : '生产单号'}` +
+      (notes.length ? `；${notes.join('；')}` : ''),
+  };
+}
+
+module.exports = { generate };