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

package/reports/leakCheck.js

@@ -0,0 +1,694 @@
+// 漏料检测日报：每个生产单导出一个「物料数据」Excel，内容为生产单详情页
+// 物料 BOM 表的完整内置列（75 列），默认隐藏 0 用量行。
+// 预计总用量公式：下单数 × 单件用量 × (1 + 损耗率%) ÷ (1 - 缩水率%)，
+// 逐行保留 4 位小数后再分组累加；分组键为 物料id + 物料单品id。
+// 数据流：GET /api/agent/v1/produce/list 取近 N 天第一页 100 张生产单，
+// 逐单 GET /api/agent/v1/produce/detail 取物料行 materialList、BOM 映射行
+// bomList 与颜色尺码明细 orderGoods，
+// 再按 20 单一批 GET /api/agent/v1/produce/material-data 取占用与缺料数据
+// （按 materialSkuId 合并进物料行）。
+// 生成逻辑从原 Python 报表脚本 export_produce_material_daily.py 移植，
+// 列名、列序、公式与文件名规则保持一致。与原脚本的差异与缺口：
+// 1. 原脚本按更新时间倒序取第一页 100 单；agent 列表接口排序固定为
+//    生产状态序（草稿、待生产、生产中、生产完成、撤销），因此改为按业务
+//    日期近 N 天（默认 30 天，可用 days 参数调整）取第一页 100 单。
+// 2. 物料图片列嵌入图片：物料单品首图优先，无则用物料主图（与后端行级
+//    展示图的取图顺序一致），下载失败时跳过该行图片，不中断生成。
+// 3. 地址列只输出详细地址；省市区名称需要行政区划 id 映射数据，本 CLI 不带
+//    该数据，因此省市区段留空。
+// 4. 物料备注列留空：生产单物料行的来源数据没有该字段（原脚本读
+//    materialRemark 与 materialSkuDTO.remark，在这个接口里同样取不到值）。
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../cli/api');
+const { timestamp, shiftDate, createThrottle } = require('./util');
+const { createWorkbook, saveWorkbook, embedImage } = require('./excel');
+const { downloadImages } = require('./image');
+
+/** 服务器对同一 AI Key 每分钟限 30 次请求，两次请求间隔至少 2100 毫秒 */
+const REQUEST_INTERVAL_MS = 2100;
+/** 列表单页大小（服务端单页上限 100，同时是默认处理的生产单数上限） */
+const PAGE_LIMIT = 100;
+/** 物料占用接口一次最多查询的生产单数 */
+const OCCUPATION_BATCH = 20;
+/** 取单的业务日期窗口天数（原脚本无日期窗口，按更新时间取最近 100 单） */
+const DEFAULT_DAYS = 30;
+const SHEET_NAME = '物料数据';
+
+/** 表头底色（浅蓝，与原脚本一致） */
+const HEADER_FILL = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9EAF7' } };
+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 CENTER = { vertical: 'middle', horizontal: 'center', wrapText: true };
+const LEFT = { vertical: 'middle', horizontal: 'left', wrapText: true };
+
+/** 首列物料图片的嵌入尺寸（像素），与数据行高约 40 像素匹配 */
+const IMAGE_SIZE = { width: 38, height: 38 };
+
+/** 75 个内置列的字段与列名（顺序对照页面 MaterialBom 内置列清单） */
+const COLUMNS = [
+  ['materialImgUrl', '图片'],
+  ['materialName', '物料名称'],
+  ['materialSn', '物料货号'],
+  ['useState', '用料状态'],
+  ['inventoryEstimate', '库存预估'],
+  ['isComplete', '齐料状态'],
+  ['issueState', '发料状态'],
+  ['supplierName', '供应商'],
+  ['supplierAddressText', '地址'],
+  ['supplierCellPhone', '联系电话'],
+  ['materialType', '类型'],
+  ['fabricType', '面料属性'],
+  ['materialColor', '物料颜色'],
+  ['matSpec', '物料规格'],
+  ['purchaseUserItems', '采购员'],
+  ['bomSupplierColor', '色号'],
+  ['materialSkuSupplierColor', '物料色号'],
+  ['materialFabricWidth', '幅宽(cm)'],
+  ['materialGramWeight', '克重(g/㎡)'],
+  ['materialQunce', '安数'],
+  ['shrinkRates', '缩水率(%)'],
+  ['materialLossRates', '损耗率(%)'],
+  ['materialComposition', '成分'],
+  ['materialPart', '使用部位'],
+  ['materialPostProcess', '后处理'],
+  ['price', '基础单价'],
+  ['avgGoodsNumber', '单件用量'],
+  ['avgGoodsIncludingLossNumber', '含损耗单件用量'],
+  ['avgProduceNumber', '生产单件用量'],
+  ['materialUnit', '基础单位'],
+  ['number', '预计总用量(下单数)'],
+  ['predictNumber', '预计总用量(裁床数)'],
+  ['cost', '物料成本'],
+  ['convertRate', '转换系数'],
+  ['predictPurchaseNumber', '预计采购数'],
+  ['purchasePrice', '采购单价'],
+  ['purchaseUnitName', '采购单位'],
+  ['predictWeight', '预计净重（kg）'],
+  ['materialNetWeight', '净重（kg）'],
+  ['predictPower', '预计匹数'],
+  ['materialMeterOutput', '出米数'],
+  ['materialAvailableNumber', '可用库存'],
+  ['factoryMaterialAvailableNumber', '加工厂可用库存'],
+  ['factoryMaterialStoredNumber', '加工厂当前库存'],
+  ['purchaseNumber', '采购数'],
+  ['purchaseWinNumber', '采购待入库数'],
+  ['issueNumber', '发料数'],
+  ['issuedPreCutNumber', '发料预裁数'],
+  ['waitIssueNumber', '待发数'],
+  ['ableIssueNumber', '可发数'],
+  ['issueWoutNumber', '发料待出库数'],
+  ['issueWinNumber', '发料待入库数'],
+  ['transferNumber', '调拨数'],
+  ['transferWoutNumber', '调拨待出库'],
+  ['transferWinNumber', '调拨待入库'],
+  ['pickNumber', '已领料'],
+  ['pickedPreCutNumber', '领料预裁数'],
+  ['pickOutNumber', '领料已出库'],
+  ['pickWoutNumber', '领料待出库'],
+  ['pickRefundNumber', '已退料'],
+  ['pickRefundInNumber', '退料已入库'],
+  ['pickRefundWinNumber', '退料待入库'],
+  ['practicalNumber', '实用量'],
+  ['cuttingLoss', '裁床等损耗'],
+  ['lackPickNumber', '本单缺料'],
+  ['surplusPickNumber', '本单余料'],
+  ['recoveryNumber', '回料数'],
+  ['recoveryWoutNumber', '回料待出库数'],
+  ['recoveryWinNumber', '回料待入库数'],
+  ['remark', '备注'],
+  ['occupationNumber', '本单临时占用'],
+  ['otherOccupationNumber', '其他单占用'],
+  ['planPurchaseNumber', '建议采购'],
+  ['materialRemark', '物料备注'],
+  ['materialCategoryName', '物料分类'],
+];
+
+// ---------- 数值与文本辅助 ----------
+
+/** 空值转空字符串，其余转去空白字符串 */
+function text(value) {
+  return value === null || value === undefined ? '' : String(value).trim();
+}
+
+/** 取第一个非空值（null、undefined、空字符串视为空） */
+function first(...values) {
+  const found = values.find((v) => v !== null && v !== undefined && v !== '');
+  return found === undefined ? '' : found;
+}
+
+/** 数值容错：空值与无法解析的值返回 0 */
+function dec(value) {
+  if (value === null || value === undefined || value === '' || typeof value === 'boolean') {
+    return 0;
+  }
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+/** 保留指定小数位（四舍五入） */
+function roundPlaces(value, places = 4) {
+  return Math.round(value * 10 ** places) / 10 ** places;
+}
+
+function round4(value) {
+  return roundPlaces(value, 4);
+}
+
+/** 单位换算行：列表第一行，无则空对象 */
+function unitConvert(row) {
+  const list = row.materialSkuUnitConvertList;
+  return Array.isArray(list) && list.length && list[0] && typeof list[0] === 'object' ? list[0] : {};
+}
+
+/** 地址文本：agent 详情只提供详细地址（省市区 id 无名称映射数据） */
+function addressText(row) {
+  return text(row.supplierAddress);
+}
+
+/** 行级展示图地址：物料单品首图优先，无则用物料主图 */
+function rowImageUrl(row) {
+  return text(first(row.materialSkuImgUrl, row.materialImgUrl));
+}
+
+/** 枚举字段转文字 */
+const STATE_TEXT = {
+  useState: { 0: '进行中', 1: '已结束' },
+  isComplete: { 0: '未齐', 1: '齐料' },
+  issueState: { 0: '空', 1: '发料中', 2: '无需发料', 3: '发料结束' },
+  fabricType: { 1: '针织', 2: '梭织' },
+};
+
+function stateText(field, raw) {
+  if (raw === null || raw === undefined || raw === '') {
+    return '';
+  }
+  const map = STATE_TEXT[field];
+  if (map) {
+    return map[raw] ?? map[String(raw)] ?? text(raw);
+  }
+  return text(raw);
+}
+
+/**
+ * 按页面默认口径动态计算的列（纯 HTTP 无法取得用户偏好，固定采用
+ * 详情页默认：裁床数口径 + 按单占用库存）。返回 null 表示该列不走动态逻辑。
+ */
+function displayDynamic(row, field) {
+  const isFabric = text(row.materialTypeName) === '面料';
+  const useCutBed = true;
+  if (field === 'predictPurchaseNumber') {
+    const rate = dec(row.convertRate);
+    return rate ? roundPlaces(dec(row.number) / rate) : '-';
+  }
+  if (field === 'occupationNumber' || field === 'otherOccupationNumber'
+    || field === 'planPurchaseNumber' || field === 'inventoryEstimate') {
+    if (isFabric && useCutBed) {
+      return '-';
+    }
+    if (field === 'occupationNumber') {
+      return roundPlaces(Math.max(dec(row.occupationByCutBedNumber), 0));
+    }
+    if (field === 'otherOccupationNumber') {
+      return roundPlaces(Math.max(dec(row.otherOccupationCutBedNumber), 0));
+    }
+    const plan = Math.max(dec(row.planPurchaseCutBedNumber), 0);
+    if (field === 'inventoryEstimate') {
+      return plan > 0 ? '缺' : '足';
+    }
+    return roundPlaces(plan);
+  }
+  return null;
+}
+
+/** 单个列的显示值 */
+function columnValue(row, field) {
+  const dynamic = displayDynamic(row, field);
+  if (dynamic !== null) {
+    return dynamic;
+  }
+  switch (field) {
+    case 'useState':
+    case 'isComplete':
+    case 'issueState':
+    case 'fabricType':
+      return stateText(field, row[field]);
+    case 'materialColor':
+      return first(row.materialColor, row.materialColorName, row.colorName);
+    case 'matSpec':
+      return first(row.matSpec, row.materialSkuPropertyText, row.spec);
+    case 'supplierCellPhone':
+      return first(row.supplierCellPhone, row.supplierCellphone);
+    case 'materialPart':
+      return first(row.materialPart, row.materialParts);
+    case 'materialPostProcess':
+      return first(row.materialPostProcess, row.materialPostProcesses);
+    case 'purchaseUnitName':
+      return first(row.purchaseUnitName, unitConvert(row).purchaseUnitName);
+    case 'convertRate':
+      return first(row.convertRate, unitConvert(row).convertRate);
+    case 'purchasePrice':
+      return first(row.purchasePrice, unitConvert(row).purchasePrice);
+    case 'supplierAddressText':
+      return addressText(row);
+    case 'materialName':
+      return first(row.materialName, row.name);
+    case 'materialSn':
+      return first(row.materialSn, row.sn);
+    case 'materialImgUrl':
+      return '';
+    case 'purchaseUserItems':
+      return text(row.purchaseUserNames);
+    case 'materialType':
+      return first(row.materialTypeName, row.materialType);
+    case 'materialUnit':
+      return first(row.materialUnitName, row.materialUnit, row.unitName);
+    case 'shrinkRates':
+      return first(row.shrinkRates, row.shrinkRate);
+    case 'materialLossRates':
+      return first(row.materialLossRates, row.materialLossRate);
+    default: {
+      const value = row[field];
+      return value === undefined || value === null ? '' : value;
+    }
+  }
+}
+
+// ---------- 数据组装 ----------
+
+/**
+ * 把物料占用数据按 materialSkuId 合并进生产单物料行。
+ * 复制原脚本的使用状态与 8 个缺料/占用字段；可用库存、采购待入库数、
+ * 已领料数、实际用量这四列详情物料行本身已提供（与原脚本同源），因此
+ * 仅在详情值为空时用占用接口的值回退（对应 DTO 的 pickedNumber 与
+ * actualUseNumber）。
+ */
+function mergeOccupation(detail, occupations) {
+  const bySku = new Map();
+  for (const item of occupations || []) {
+    if (item && typeof item === 'object') {
+      bySku.set(String(item.materialSkuId), item);
+    }
+  }
+  for (const item of detail.materialList || []) {
+    const extra = bySku.get(String(item.materialSkuId));
+    if (!extra) {
+      continue;
+    }
+    item.useState = extra.state;
+    const copyFields = [
+      'lackNumberByOrderNumber', 'lackNumberByCutBedNumber',
+      'occupationByOrderNumber', 'occupationByCutBedNumber',
+      'otherOccupationOrderNumber', 'otherOccupationCutBedNumber',
+      'planPurchaseOrderNumber', 'planPurchaseCutBedNumber',
+    ];
+    for (const field of copyFields) {
+      if (extra[field] !== null && extra[field] !== undefined) {
+        item[field] = extra[field];
+      }
+    }
+    const isEmpty = (v) => v === null || v === undefined || v === '';
+    if (isEmpty(item.materialAvailableNumber) && extra.materialAvailableNumber != null) {
+      item.materialAvailableNumber = extra.materialAvailableNumber;
+    }
+    if (isEmpty(item.purchaseWinNumber) && extra.purchaseWinNumber != null) {
+      item.purchaseWinNumber = extra.purchaseWinNumber;
+    }
+    if (isEmpty(item.pickNumber) && extra.pickedNumber != null) {
+      item.pickNumber = extra.pickedNumber;
+    }
+    if (isEmpty(item.practicalNumber) && extra.actualUseNumber != null) {
+      item.practicalNumber = extra.actualUseNumber;
+    }
+  }
+}
+
+/**
+ * 由生产单详情组装报表行：
+ * 1. BOM 映射行合并物料行同名字段（物料行空值不覆盖）；
+ * 2. 按 物料id+物料单品id 分组，逐行计算预计用量后累加；
+ * 3. 齐料状态为空时推断：面料按采购数、辅料按发料已入库数。
+ */
+function buildRows(detail) {
+  const materialList = detail.materialList || [];
+  const mappings = detail.bomList || [];
+
+  const materialIndex = new Map();
+  for (const item of materialList) {
+    if (item && typeof item === 'object') {
+      materialIndex.set(`${item.materialId}\u0001${item.materialSkuId}`, item);
+    }
+  }
+
+  // 颜色尺码明细的单品下单数：goodsSkuId → number
+  const quantities = new Map();
+  for (const goods of detail.orderGoods || []) {
+    const key = goods.goodsSkuId;
+    if (key !== null && key !== undefined && key !== '') {
+      quantities.set(String(key), dec(goods.number));
+    }
+  }
+
+  const intermediate = [];
+  for (const raw of mappings) {
+    if (!raw || typeof raw !== 'object') {
+      continue;
+    }
+    const source = materialIndex.get(`${raw.materialId}\u0001${raw.materialSkuId}`) || {};
+    const row = { ...raw };
+    for (const [key, value] of Object.entries(source)) {
+      if (value !== null && value !== undefined && value !== '') {
+        row[key] = value;
+      }
+    }
+    row.materialId = raw.materialId;
+    row.materialSkuId = raw.materialSkuId;
+    row._number = dec(raw.number);
+    row.goodsSkuId = raw.goodsSkuId !== null && raw.goodsSkuId !== undefined && raw.goodsSkuId !== ''
+      ? String(raw.goodsSkuId)
+      : '';
+    row.proNumber = quantities.has(row.goodsSkuId) ? quantities.get(row.goodsSkuId) : 0;
+    intermediate.push(row);
+  }
+  // 旧单没有 BOM 映射行时，直接用物料行输出，保持详情可见数据
+  if (!intermediate.length) {
+    for (const item of materialList) {
+      if (!item || typeof item !== 'object') {
+        continue;
+      }
+      intermediate.push({ ...item, _number: dec(item.number), proNumber: 0, goodsSkuId: '' });
+    }
+  }
+
+  const groups = new Map();
+  for (const row of intermediate) {
+    const key = `${row.materialId}\u0001${row.materialSkuId}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = {
+        row: { ...row },
+        number: 0,
+        numberSum: 0,
+        including: 0,
+        sku: new Set(),
+        produce: 0,
+        produceSku: new Set(),
+      };
+      groups.set(key, group);
+    }
+    const pn = row.proNumber;
+    const unit = row._number;
+    const loss = dec(row.materialLossRate);
+    const shrink = dec(row.shrinkRate);
+    const divisor = 1 - shrink / 100;
+    const expected = divisor === 0 ? 0 : round4((pn * unit * (1 + loss / 100)) / divisor);
+    const including = divisor === 0 ? 0 : (unit * (1 + loss / 100)) / divisor;
+    group.number += expected;
+    group.numberSum += unit;
+    group.including += including;
+    if (unit && row.goodsSkuId) {
+      group.sku.add(row.goodsSkuId);
+    }
+    if (unit && pn && !group.produceSku.has(row.goodsSkuId)) {
+      group.produceSku.add(row.goodsSkuId);
+      group.produce += pn;
+    }
+  }
+
+  const result = [];
+  for (const group of groups.values()) {
+    const row = group.row;
+    row.number = round4(group.number);
+    row.cost = round4(group.number * dec(row.price));
+    const convert = unitConvert(row);
+    for (const field of ['convertRate', 'purchasePrice', 'purchaseUnitName']) {
+      if ((row[field] === null || row[field] === undefined || row[field] === '')
+        && convert[field] !== null && convert[field] !== undefined) {
+        row[field] = convert[field];
+      }
+    }
+    row.supplierAddressText = addressText(row);
+    const count = group.sku.size;
+    row.avgGoodsNumber = round4(count ? group.numberSum / count : 0);
+    row.avgGoodsIncludingLossNumber = round4(count ? group.including / count : 0);
+    row.avgProduceNumber = round4(group.produce ? group.number / group.produce : 0);
+    if (row.isComplete === null || row.isComplete === undefined || row.isComplete === '') {
+      row.isComplete = text(row.materialTypeName) === '面料'
+        ? (dec(row.purchaseNumber) >= group.number ? 1 : 0)
+        : (dec(row.issueInNumber) >= dec(row.predictNumber) ? 1 : 0);
+    }
+    row.lackPickNumber = first(row.lackNumberByOrderNumber, row.lackPickNumber);
+    row.occupationNumber = first(row.occupationByOrderNumber, row.occupationNumber);
+    row.otherOccupationNumber = first(row.otherOccupationOrderNumber, row.otherOccupationNumber);
+    row.planPurchaseNumber = first(row.planPurchaseOrderNumber, row.planPurchaseNumber);
+    result.push(row);
+  }
+  return result;
+}
+
+/** 过滤显示行：剔除按采购员隐藏的行；默认再剔除 0 用量行 */
+function displayRows(detail, includeZero) {
+  return buildRows(detail).filter((row) => !row.isHideByPurchaseUser && (includeZero || dec(row.number) !== 0));
+}
+
+// ---------- Excel 生成 ----------
+
+/** 表头/标签样式：加粗、浅蓝底、细边框、居中换行 */
+function styleHeaderCells(row, height) {
+  row.height = height;
+  row.eachCell({ includeEmpty: true }, (cell) => {
+    cell.font = { bold: true };
+    cell.fill = HEADER_FILL;
+    cell.border = BORDER;
+    cell.alignment = CENTER;
+  });
+}
+
+/** 生产单信息键值对样式：奇数位是标签（表头样式），偶数位是值（细边框左对齐） */
+function styleInfoRow(row, count) {
+  row.height = 24;
+  for (let col = 1; col <= count; col += 1) {
+    const cell = row.getCell(col);
+    cell.border = BORDER;
+    if (col % 2 === 1) {
+      cell.font = { bold: true };
+      cell.fill = HEADER_FILL;
+      cell.alignment = CENTER;
+    } else {
+      cell.alignment = LEFT;
+    }
+  }
+}
+
+/**
+ * 写一个生产单的工作表：标题行、信息行、表头行（第 4 行）与数据行。
+ * images 是 地址 → 图片对象 的 Map，数据行首列按行嵌入对应图片。
+ */
+function addOrderSheet(workbook, order, rows, images) {
+  const count = COLUMNS.length;
+  const sheet = workbook.addWorksheet(SHEET_NAME, { views: [{ state: 'frozen', ySplit: 4 }] });
+
+  // 第 1 行：整行合并的表标题
+  const titleRow = sheet.getRow(1);
+  titleRow.getCell(1).value = '生产单物料数据';
+  titleRow.height = 30;
+  titleRow.eachCell({ includeEmpty: true }, (cell) => {
+    cell.font = { bold: true, size: 11 };
+    cell.fill = HEADER_FILL;
+    cell.border = BORDER;
+    cell.alignment = LEFT;
+  });
+  sheet.mergeCells(1, 1, 1, count);
+
+  // 第 2 行：生产批次号、商品名、商品货号、生产单状态、导出时间
+  const infoPairs = [
+    ['生产批次号', first(order.produceBatchSn, order.ordersSn)],
+    ['商品名', order.goodsName],
+    ['商品货号', order.goodsSn],
+    ['生产单状态', order.stateName],
+    ['导出时间', formatNow()],
+  ];
+  const infoRow = sheet.getRow(2);
+  infoPairs.forEach(([label, value], i) => {
+    infoRow.getCell(i * 2 + 1).value = label;
+    infoRow.getCell(i * 2 + 2).value = value;
+  });
+  styleInfoRow(infoRow, count);
+
+  // 第 4 行：列表头
+  const headerRow = sheet.getRow(4);
+  COLUMNS.forEach(([, header], i) => {
+    headerRow.getCell(i + 1).value = header;
+  });
+  styleHeaderCells(headerRow, 32);
+
+  // 第 5 行起：物料数据行；首列有图片时嵌入图片（单元格本身留空）
+  rows.forEach((row, index) => {
+    const dataRow = sheet.getRow(5 + index);
+    COLUMNS.forEach(([field], i) => {
+      dataRow.getCell(i + 1).value = columnValue(row, field);
+    });
+    dataRow.height = 30;
+    dataRow.eachCell({ includeEmpty: true }, (cell) => {
+      cell.border = BORDER;
+      cell.alignment = LEFT;
+    });
+    const image = images ? images.get(rowImageUrl(row)) : null;
+    if (image) {
+      embedImage(workbook, sheet, image, 5 + index, 1, IMAGE_SIZE);
+    }
+  });
+
+  // 列宽：前三列 18，其余 14
+  for (let i = 1; i <= count; i += 1) {
+    sheet.getColumn(i).width = i < 4 ? 18 : 14;
+  }
+  return sheet;
+}
+
+/** 当前时间 yyyy-MM-dd HH:mm:ss */
+function formatNow() {
+  const pad = (v) => String(v).padStart(2, '0');
+  const now = new Date();
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} `
+    + `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+}
+
+/** 文件名组成部分安全处理：全角归一、替换非法字符、截断 100 字符 */
+function safeComponent(value, fallback) {
+  let v = String(value ?? '').normalize('NFKC').trim();
+  v = v.replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').replace(/[.\s]+$/, '');
+  if (!v) {
+    v = fallback;
+  }
+  if (/^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i.test(v)) {
+    v = `_${v}`;
+  }
+  return v.slice(0, 100).replace(/[.\s]+$/, '') || fallback;
+}
+
+/** 单个生产单的文件名：批次号（商品名）.xlsx，重名追加序号 */
+function planFile(directory, order, used) {
+  const base = `${safeComponent(first(order.produceBatchSn, order.ordersSn), '无批次号')}`
+    + `（${safeComponent(order.goodsName, '无商品名')}）`;
+  let name = `${base}.xlsx`;
+  let suffix = 2;
+  while (used.has(name.toLowerCase())) {
+    name = `${base}_${suffix}.xlsx`;
+    suffix += 1;
+  }
+  used.add(name.toLowerCase());
+  return path.join(directory, name);
+}
+
+// ---------- 报表入口 ----------
+
+/**
+ * 生成漏料检测日报。
+ * argv：{ limit 最多处理的生产单数（默认 100）,
+ *         includeZero 是否包含 0 用量行（默认隐藏）,
+ *         days 取单的业务日期窗口天数（默认 30）, out 输出目录 }。
+ * 输出目录名固定为 漏料检测日报+时间戳，已存在时报错；单个文件不覆盖。
+ */
+async function generate(argv = {}) {
+  const limit = Number(argv.limit) > 0 ? Number(argv.limit) : PAGE_LIMIT;
+  const includeZero = argv.includeZero === true || argv.includeZero === 'true';
+  const days = Number(argv.days) > 0 ? Number(argv.days) : DEFAULT_DAYS;
+  const outDir = argv.out ? path.resolve(String(argv.out)) : process.cwd();
+  const throttle = createThrottle(REQUEST_INTERVAL_MS);
+
+  // 后端对业务日期结束时间用严格小于比较，因此结束日期传明天才能包含今天
+  const from = shiftDate(-(days - 1));
+  const to = shiftDate(1);
+  const page = await throttle(() => call('GET', '/api/agent/v1/produce/list', {
+    from,
+    to,
+    page: 1,
+    limit: PAGE_LIMIT,
+  }));
+  const orders = (page && page.list ? page.list : []).slice(0, limit);
+  if (!orders.length) {
+    throw new Error('没有符合条件的生产单');
+  }
+
+  // 逐单取详情：物料行与 BOM 映射行只在详情接口返回
+  const details = [];
+  let failedCount = 0;
+  for (let i = 0; i < orders.length; i += 1) {
+    const sn = text(orders[i].ordersSn);
+    if (!sn) {
+      failedCount += 1;
+      continue;
+    }
+    try {
+      details.push(await throttle(() => call('GET', '/api/agent/v1/produce/detail', { sn })));
+    } catch (e) {
+      failedCount += 1;
+    }
+    if ((i + 1) % 10 === 0) {
+      process.stdout.write(`漏料检测日报进度：已取生产单详情 ${i + 1}/${orders.length}\n`);
+    }
+  }
+  if (!details.length) {
+    throw new Error('没有成功取得生产单详情');
+  }
+
+  // 物料占用数据按 20 单一批查询，按生产单号分组
+  const occupationsBySn = new Map();
+  for (let i = 0; i < details.length; i += OCCUPATION_BATCH) {
+    const batch = details
+      .slice(i, i + OCCUPATION_BATCH)
+      .map((detail) => text(detail.ordersSn))
+      .filter(Boolean);
+    if (!batch.length) {
+      continue;
+    }
+    const rows = (await throttle(() => call('GET', '/api/agent/v1/produce/material-data', {
+      sns: batch.join(','),
+    }))) || [];
+    for (const row of rows) {
+      const sn = text(row.produceOrdersSn);
+      if (!sn) {
+        continue;
+      }
+      if (!occupationsBySn.has(sn)) {
+        occupationsBySn.set(sn, []);
+      }
+      occupationsBySn.get(sn).push(row);
+    }
+  }
+
+  const directory = path.resolve(outDir, `漏料检测日报${timestamp()}`);
+  if (fs.existsSync(directory)) {
+    throw new Error(`输出目录已存在：${directory}`);
+  }
+  fs.mkdirSync(directory, { recursive: true });
+
+  const used = new Set();
+  const filePaths = [];
+  for (const detail of details) {
+    mergeOccupation(detail, occupationsBySn.get(text(detail.ordersSn)));
+    const rows = displayRows(detail, includeZero);
+    // 批量下载本单行的展示图（地址去重，失败自动跳过）
+    const urls = rows.map(rowImageUrl).filter(Boolean);
+    const images = urls.length ? await downloadImages(urls) : new Map();
+    const workbook = createWorkbook();
+    addOrderSheet(workbook, detail, rows, images);
+    const filePath = planFile(directory, detail, used);
+    await saveWorkbook(workbook, filePath);
+    filePaths.push(filePath);
+  }
+
+  let summary = `漏料检测日报导出完成：生产单 ${filePaths.length} 个，文件 ${filePaths.length} 个，`
+    + `${includeZero ? '包含' : '不包含'} 0 用量行；报表目录：${directory}`;
+  if (failedCount) {
+    summary += `；${failedCount} 张生产单详情获取失败已跳过`;
+  }
+  return { filePaths, summary };
+}
+
+module.exports = { generate };