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

package/reports/goodsBom.js

@@ -0,0 +1,648 @@
+// BOM 商品信息报表：每个商品生成一个 Excel 文件，文件内分三段：
+// 1. 商品横向信息一行（44 列）；2. 默认只读物料清单 BOM——30 个固定列加
+//    按颜色/尺码动态展开的列组，每组三列「物料规格/用量/含损耗用量」；
+// 3. 物料单品明细（23 列，按 materialSkuId 聚合后的单件用量口径）。
+// 数据流：GET /api/agent/v1/goods/rich-list 分页取商品列表，
+// 再逐商品 GET /api/agent/v1/goods/full-detail 取 BOM 行与档案字段，
+// 商品主图与物料图下载后嵌入 A 列。列名、列序、合并规则、文件名与
+// 原 Python 报表脚本 export_goods_bom.py 一致。
+const fs = require('fs');
+const path = require('path');
+const { call } = require('../cli/api');
+const { timestamp, createThrottle, fetchAll } = require('./util');
+const { downloadImage } = require('./image');
+const { createWorkbook, saveWorkbook, embedImage } = require('./excel');
+
+/** 列表分页大小（服务端单页上限 100） */
+const PAGE_LIMIT = 100;
+/** 逐商品详情请求的最小间隔毫秒数（服务端按 Key 每分钟限流约 30 次） */
+const REQUEST_INTERVAL_MS = 2100;
+/** 每张图片嵌入的显示尺寸（像素） */
+const MAIN_IMAGE_SIZE = { width: 90, height: 90 };
+const BOM_IMAGE_SIZE = { width: 38, height: 38 };
+const DETAIL_IMAGE_SIZE = { width: 34, height: 34 };
+
+const SHEET_NAME = '商品信息';
+const PRODUCT_HEADERS = ['图片', '商品名称', '商品货号', '颜色', '尺码', '分类', '标签', 'BOM完成状态', 'BOM锁定状态', '委外加工费', '封样状态', '打版师', '当前库存', '待入库', '待出库', '可用库存', '生产中', 'IE核价', '成本价', '吊牌价', '建议零售价', '批发价', '零售价', '物料', '客户', '开发日期', '品牌', '设计款号', '供应商货号', '设计师', '跟单员', '年份', '季节', '克重(g/㎡)', '成分', '性别', '波段', '商品条码', '状态', '备注', '创建人', '创建时间', '最后更新人', '更新时间'];
+const BOM_FIXED_HEADERS = ['图片', '物料名称', '物料货号', '供应商', '供应商货号', '地址', '联系电话', '类型', '面料属性', '基础单位', '基础单价', '转换系数', '采购单位', '采购单价', '采购员', '出米数(m/kg)', '纸筒(kg)', '空差(kg)', '净重(kg)', '幅宽(cm)', '克重(g/㎡)', '安数', '损耗率(%)', '缩水率(%)', '采购损耗(%)', '成分', '使用部位', '后处理', '物料备注', '物料分类'];
+/** 物料单品明细列顺序（与商品编辑页 material-sku-bom.vue 默认列一致） */
+const MATERIAL_SKU_HEADERS = ['图片', '物料名称', '物料货号', '供应商', '供应商货号', '地址', '联系电话', '类型', '物料分类', '物料颜色', '物料规格', '采购员', '色号', '物料色号', '成衣颜色', '基础单价', '单件用量', '含损耗单件用量', '基础单位', '转换系数', '采购单位', '采购单价', '物料备注'];
+const BOM_FIXED_WIDTHS = [18, 20, 16, 18, 16, 18, 18, 14, 14, 12, 12, 12, 12, 12, 16, 12, 12, 12, 12, 12, 12, 10, 12, 12, 12, 16, 16, 16, 16, 16];
+const PRODUCT_WIDTHS = [18, 20, 16, 18, 16, 14, 14, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 12, 18, 14, 14, 14, 14, 14, 14, 14, 12, 12, 12, 16, 10, 12, 16, 12, 16, 18, 16, 18];
+
+/** 表头底色（浅蓝，与原脚本一致） */
+const HEADER_FILL = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9EAF7' } };
+const THIN_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' } },
+};
+
+/** 空值转空字符串，其余转去空白字符串 */
+function text(value) {
+  return value === null || value === undefined ? '' : String(value).trim();
+}
+
+/** 取第一个非空值（null、undefined、空字符串视为空），保留原始类型 */
+function firstValue(...values) {
+  for (const value of values) {
+    if (value !== null && value !== undefined && value !== '') {
+      return value;
+    }
+  }
+  return '';
+}
+
+/** 数值转 number（写入 Excel 数值单元格），无法解析返回空字符串 */
+function numeric(value) {
+  if (value === null || value === undefined || value === '' || typeof value === 'boolean') {
+    return '';
+  }
+  const n = Number(value);
+  return Number.isFinite(n) ? n : '';
+}
+
+function pad2(n) {
+  return String(n).padStart(2, '0');
+}
+
+/** 时间戳毫秒或日期字符串转「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);
+  }
+  return (
+    `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())} ` +
+    `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`
+  );
+}
+
+/** 日期部分 yyyy-MM-dd */
+function formatDate(value) {
+  return formatDateTime(value).slice(0, 10);
+}
+
+/** 枚举 1/0 转展示文字 */
+function stateText(value, yes, no) {
+  return value === 1 ? yes : no;
+}
+
+function sexText(value) {
+  return ({ 0: '通款', 1: '男款', 2: '女款', 3: '童装' })[value] ?? text(value);
+}
+
+function fabricText(value) {
+  return ({ 1: '针织', 2: '梭织' })[value] ?? '-';
+}
+
+function bomFinishText(value) {
+  return ({ 1: '完成', 0: '待完成', 2: '' })[value] ?? '';
+}
+
+/** 生成不与已用名称冲突、不含非法字符的文件名主体 */
+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;
+}
+
+/**
+ * 含损耗用量：用量 × (1 + 损耗率%) ÷ (1 - 缩水率%)，四舍五入保留 4 位小数。
+ * 缩水率等于 100 时分母为零，返回空字符串（与原脚本一致）。
+ */
+function lossQuantity(number, loss, shrink) {
+  const amount = numeric(number);
+  if (amount === '') {
+    return '';
+  }
+  const l = numeric(loss) === '' ? 0 : Number(loss);
+  const s = numeric(shrink) === '' ? 0 : Number(shrink);
+  if (100 - s === 0) {
+    return '';
+  }
+  return Math.round((amount * (1 + l / 100) / (1 - s / 100)) * 10000) / 10000;
+}
+
+/** 把 BOM 行（full-detail 的 BomRow）整理成报表需要的聚合基础结构 */
+function bomRecord(row) {
+  return {
+    key: text(row.materialSkuId),
+    materialSkuId: text(row.materialSkuId),
+    goodsSkuId: text(row.goodsSkuId),
+    hidden: row.hidden === true,
+    goodsColor: text(row.goodsColorName),
+    goodsSize: text(row.goodsSizeName),
+    colorId: row.goodsColorId,
+    sizeId: row.goodsSizeId,
+    number: numeric(row.number),
+    loss: numeric(row.materialLossRate),
+    shrink: numeric(row.shrinkRate),
+    property: text(row.propertyText),
+    raw: row,
+  };
+}
+
+/** 颜色/尺码轴：详情的颜色轴、尺码轴在前，BOM 行里出现而轴中没有的追加到末尾 */
+function axisOf(detail, records) {
+  const colors = [];
+  const sizes = [];
+  for (const c of detail.goodsColors || []) {
+    if (text(c.colorName)) {
+      colors.push([text(c.colorName), c.colorId]);
+    }
+  }
+  for (const s of detail.goodsSizes || []) {
+    if (text(s.sizeName)) {
+      sizes.push([text(s.sizeName), s.sizeId]);
+    }
+  }
+  for (const r of records) {
+    if (!colors.some(([n, id]) => n === r.goodsColor && id === r.colorId)) {
+      colors.push([r.goodsColor, r.colorId]);
+    }
+    if (!sizes.some(([n, id]) => n === r.goodsSize && id === r.sizeId)) {
+      sizes.push([r.goodsSize, r.sizeId]);
+    }
+  }
+  return {
+    colors: colors.filter(([n]) => n),
+    sizes: sizes.filter(([n]) => n),
+  };
+}
+
+/**
+ * 物料单品分组：按 materialSkuId 聚合全部未隐藏 BOM 行。
+ * 单件用量 = 该物料全部 BOM 行用量合计 ÷ 覆盖的单品数（按 goodsSkuId 去重），
+ * 含损耗单件用量同理对含损耗用量合计后平均；合计为零时显示「-」。
+ */
+function materialSkuGroups(records) {
+  const groups = [];
+  const index = new Map();
+  for (const record of records) {
+    if (record.hidden) {
+      continue;
+    }
+    let group = index.get(record.materialSkuId);
+    if (!group) {
+      group = { first: record, records: [], skuKeys: [], colors: [] };
+      index.set(record.materialSkuId, group);
+      groups.push(group);
+    }
+    group.records.push(record);
+    const key = record.goodsSkuId || `${record.goodsColor}-${record.goodsSize}`;
+    if (!group.skuKeys.includes(key)) {
+      group.skuKeys.push(key);
+    }
+    if (record.goodsColor && !group.colors.includes(record.goodsColor)) {
+      group.colors.push(record.goodsColor);
+    }
+  }
+  for (const group of groups) {
+    let total = 0;
+    let lossTotal = 0;
+    for (const r of group.records) {
+      total += Number(r.number) || 0;
+      const loss = lossQuantity(r.number, r.loss, r.shrink);
+      lossTotal += loss === '' ? 0 : loss;
+    }
+    const count = Math.max(1, group.skuKeys.length);
+    const divide = (v) => Math.round((v / count) * 10000) / 10000;
+    group.unitNumber = total ? divide(total) : '-';
+    group.unitLoss = lossTotal ? divide(lossTotal) : '-';
+  }
+  return groups;
+}
+
+/** BOM 固定 30 列的值（取分组第一行） */
+function fixedBomValues(record) {
+  const row = record.raw;
+  return [
+    '',
+    text(row.materialName),
+    text(row.materialSn),
+    text(row.supplierName),
+    text(row.supplierSn),
+    text(row.supplierAddress),
+    text(row.supplierCellPhone),
+    text(row.materialTypeName),
+    fabricText(row.materialFabricType),
+    text(row.materialUnitName),
+    numeric(row.price),
+    numeric(row.convertRate),
+    text(row.purchaseUnitName),
+    numeric(row.purchasePrice),
+    text(row.purchaseUserNames),
+    numeric(row.materialMeterOutput),
+    numeric(row.materialPaperBucket),
+    numeric(row.materialEmptyGap),
+    numeric(row.materialNetWeight),
+    numeric(row.materialFabricWidth),
+    numeric(row.materialGramWeight),
+    numeric(row.materialQunce),
+    numeric(row.materialLossRate),
+    numeric(row.shrinkRate),
+    numeric(row.purchaseLossRate),
+    text(row.materialComposition),
+    text(row.materialPart),
+    text(row.materialPostProcess),
+    text(row.materialRemark),
+    text(row.materialCategoryName),
+  ];
+}
+
+/** 物料单品明细 23 列的值。物料色号一列后端 DTO 暂无对应字段，输出为空 */
+function materialSkuValues(group) {
+  const row = group.first.raw;
+  const colors = group.colors.join('、') || '-';
+  return [
+    '',
+    text(row.materialName),
+    text(row.materialSn),
+    text(row.supplierName),
+    text(row.supplierSn),
+    text(row.supplierAddress),
+    text(row.supplierCellPhone),
+    text(row.materialTypeName),
+    text(row.materialCategoryName),
+    text(row.materialColorName),
+    group.first.property || '-',
+    text(row.purchaseUserNames),
+    text(row.bomSupplierColor),
+    '',
+    colors,
+    numeric(row.price),
+    group.unitNumber,
+    group.unitLoss,
+    text(row.materialUnitName),
+    numeric(row.convertRate),
+    text(row.purchaseUnitName),
+    numeric(row.purchasePrice),
+    text(row.materialRemark),
+  ];
+}
+
+/** 商品横向信息 44 列（详情字段优先，列表行字段回退） */
+function productValues(summary, detail) {
+  const colors = (detail.goodsColors || []).map((c) => text(c.colorName)).filter(Boolean);
+  const sizes = (detail.goodsSizes || []).map((s) => text(s.sizeName)).filter(Boolean);
+  const materialText = (summary.materialNames || []).join('、');
+  return [
+    '',
+    text(firstValue(detail.name, summary.name)),
+    text(firstValue(detail.goodsSn, summary.goodsSn)),
+    colors.join(',') || (summary.colorNames || []).join(','),
+    sizes.join(',') || (summary.sizeNames || []).join(','),
+    text(firstValue(detail.categoryName, summary.categoryName)),
+    (summary.tagNames || []).join('、'),
+    bomFinishText(firstValue(detail.bomFinish, summary.bomFinish)),
+    stateText(firstValue(detail.bomState, summary.bomState), '已锁定', '未锁定'),
+    (summary.externalProcessingFees || []).join('；'),
+    stateText(firstValue(detail.isSealedSample, summary.isSealedSample), '封样', '未封样'),
+    text(firstValue(detail.patternMakerName, summary.patternMakerName)),
+    numeric(firstValue(detail.storedNumber, summary.storedNumber)),
+    numeric(firstValue(detail.winNumber, summary.winNumber)),
+    numeric(firstValue(detail.woutNumber, summary.woutNumber)),
+    numeric(firstValue(detail.availableNumber, summary.availableNumber)),
+    numeric(firstValue(detail.produceNumber, summary.produceNumber)),
+    numeric(firstValue(detail.iePrice, summary.iePrice)),
+    numeric(firstValue(detail.costPrice, summary.costPrice)),
+    numeric(firstValue(detail.tagPrice, summary.tagPrice)),
+    numeric(firstValue(detail.retailPriceFactory, summary.retailPriceFactory)),
+    numeric(firstValue(detail.tradePrice, summary.tradePrice)),
+    numeric(firstValue(detail.retailPriceArea, summary.retailPriceArea)),
+    materialText,
+    text(firstValue(detail.clientName, summary.clientName)),
+    formatDate(firstValue(detail.devTime, summary.devTime)),
+    text(firstValue(detail.brandName, summary.brandName)),
+    text(firstValue(detail.designSn, summary.designSn)),
+    text(firstValue(detail.supplierSn, summary.supplierSn)),
+    text(firstValue(detail.designerName, summary.designerName)),
+    text(firstValue(detail.followerName, summary.followerName)),
+    text(firstValue(detail.year, summary.year)),
+    text(firstValue(detail.seasonName, summary.seasonName)),
+    numeric(firstValue(detail.gramWeight, summary.gramWeight)),
+    text(firstValue(detail.composition, summary.composition)),
+    sexText(firstValue(detail.sex, summary.sex)),
+    text(firstValue(detail.rangesName, summary.rangesName)),
+    text(firstValue(detail.barCode, summary.barCode)),
+    stateText(firstValue(detail.isOnSale, summary.isOnSale), '启用', '停用'),
+    text(firstValue(detail.remark, summary.remark)),
+    text(firstValue(detail.handlerName, summary.handlerName)),
+    formatDateTime(firstValue(detail.createTime, summary.createTime)),
+    text(firstValue(detail.lastHandlerName, summary.lastHandlerName)),
+    formatDateTime(firstValue(detail.updateTime, summary.updateTime)),
+  ];
+}
+
+/** 显式行号写一行值（values 数组第 0 位对应第 1 列） */
+function setRow(sheet, rowNumber, values) {
+  const row = sheet.getRow(rowNumber);
+  row.values = values;
+  return row;
+}
+
+/** 表头样式：加粗、浅蓝底、细边框、居中换行 */
+function styleHeaderRow(row, height) {
+  row.height = height;
+  row.eachCell({ includeEmpty: true }, (cell) => {
+    cell.border = THIN_BORDER;
+    cell.fill = HEADER_FILL;
+    cell.font = { bold: true };
+    cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
+  });
+}
+
+/** 数据行样式：细边框；leftCols 里的列左对齐，其余居中 */
+function styleDataRow(row, height, leftCols) {
+  row.height = height;
+  const left = new Set(leftCols);
+  row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+    cell.border = THIN_BORDER;
+    cell.alignment = { vertical: 'middle', horizontal: left.has(colNumber) ? 'left' : 'center', wrapText: true };
+  });
+}
+
+/** 创建输出目录；同名目录已存在时追加序号，避免覆盖既有报表 */
+function makeDirectory(parent, baseName) {
+  let dir = path.join(parent, baseName);
+  let seq = 2;
+  while (fs.existsSync(dir)) {
+    dir = path.join(parent, `${baseName}-${seq}`);
+    seq += 1;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * 单个商品文件名：`商品名称（货号）.xlsx`；同一批内重名先追加商品 id，
+ * 仍冲突再追加自增序号（与原脚本 file_plan 一致）。
+ */
+function planFile(directory, goods, used) {
+  const base = `${safeComponent(goods.name, '商品')}（${safeComponent(goods.goodsSn, '无货号')}）`;
+  let name = `${base}.xlsx`;
+  if (used.has(name.toLowerCase())) {
+    name = `${base}_${goods.id}.xlsx`;
+  }
+  let seq = 2;
+  while (used.has(name.toLowerCase())) {
+    name = `${base}_${goods.id}_${seq}.xlsx`;
+    seq += 1;
+  }
+  used.add(name.toLowerCase());
+  return path.join(directory, name);
+}
+
+/** 下载商品主图与各物料图（按 materialSkuId 去重），失败自动跳过 */
+async function downloadGoodsImages(detail, summary, records) {
+  const firstImg = (detail.goodsImgList || []).map((i) => text(i.url)).find(Boolean);
+  const mainImage = await downloadImage(text(firstValue(detail.goodsImgUrl, summary.goodsImgUrl)) || firstImg);
+  const materialImages = new Map();
+  for (const record of records) {
+    if (record.materialSkuId && !materialImages.has(record.materialSkuId)) {
+      materialImages.set(record.materialSkuId, await downloadImage(text(record.raw.materialImgUrl)));
+    }
+  }
+  return { mainImage, materialImages };
+}
+
+/**
+ * 生成单个商品的 Excel：商品信息行 + 三层表头的 BOM 区 + 物料单品明细区。
+ * BOM 行按 materialSkuId 分组，每组一行；颜色×尺码单元格的用量是该组内
+ * 相同（颜色,尺码) 行的用量合计，含损耗用量按合计后的值重新计算。
+ */
+async function writeGoodsFile(filePath, summary, detail) {
+  const records = (detail.goodsMaterialList || []).map(bomRecord);
+  const { colors, sizes } = axisOf(detail, records);
+  const dynamicCount = colors.length * sizes.length;
+  const fixedCount = BOM_FIXED_HEADERS.length;
+  const bomTotal = fixedCount + dynamicCount * 3;
+  const sheetTotal = Math.max(PRODUCT_HEADERS.length, bomTotal);
+  const pad = (values) => [...values, ...new Array(Math.max(0, sheetTotal - values.length)).fill('')];
+
+  const { mainImage, materialImages } = await downloadGoodsImages(detail, summary, records);
+
+  const workbook = createWorkbook();
+  const sheet = workbook.addWorksheet(SHEET_NAME, { views: [{ state: 'frozen', ySplit: 7 }] });
+
+  // 第 1 行表头、第 2 行商品信息（第 3 行留空，与原脚本行结构一致）
+  styleHeaderRow(setRow(sheet, 1, pad(PRODUCT_HEADERS)), 30);
+  styleDataRow(setRow(sheet, 2, pad(productValues(summary, detail))), 75, [1, 2, 3, 4, 5, 7, 10, 24, 40, 41, 43]);
+  if (mainImage) {
+    embedImage(workbook, sheet, mainImage, 2, 1, MAIN_IMAGE_SIZE);
+  }
+
+  // 第 4 行「物料清单BOM」整行合并
+  const bomTitle = pad(['物料清单BOM']);
+  styleHeaderRow(setRow(sheet, 4, bomTitle), 24);
+  sheet.mergeCells(4, 1, 4, sheetTotal);
+
+  // 第 5~7 行三层表头：固定列纵向合并三行；颜色在第 5 行跨该颜色全部列，
+  // 尺码在第 6 行跨 3 列，第 7 行固定为「物料规格/用量/含损耗用量」。
+  const top = new Array(sheetTotal).fill('');
+  const middle = new Array(sheetTotal).fill('');
+  const bottom = new Array(sheetTotal).fill('');
+  BOM_FIXED_HEADERS.forEach((h, i) => {
+    top[i] = h;
+  });
+  let col = fixedCount;
+  for (const [colorName] of colors) {
+    top[col] = colorName;
+    col += sizes.length * 3;
+  }
+  col = fixedCount;
+  for (const [sizeName] of sizes) {
+    middle[col] = sizeName;
+    col += 3;
+  }
+  col = fixedCount;
+  for (let i = 0; i < dynamicCount; i += 1) {
+    bottom[col] = '物料规格';
+    bottom[col + 1] = '用量';
+    bottom[col + 2] = '含损耗用量';
+    col += 3;
+  }
+  styleHeaderRow(setRow(sheet, 5, top), 28);
+  styleHeaderRow(setRow(sheet, 6, middle), 28);
+  styleHeaderRow(setRow(sheet, 7, bottom), 28);
+  for (let c = 1; c <= fixedCount; c += 1) {
+    sheet.mergeCells(5, c, 7, c);
+  }
+  col = fixedCount + 1;
+  for (const [colorName] of colors) {
+    sheet.mergeCells(5, col, 5, col + sizes.length * 3 - 1);
+    for (const [sizeName] of sizes) {
+      sheet.mergeCells(6, col, 6, col + 2);
+      col += 3;
+    }
+  }
+
+  // BOM 数据行：按 materialSkuId 分组（插入顺序），一组一行
+  const grouped = [];
+  const groupIndex = new Map();
+  for (const record of records) {
+    let list = groupIndex.get(record.key);
+    if (!list) {
+      list = [];
+      groupIndex.set(record.key, list);
+      grouped.push(list);
+    }
+    list.push(record);
+  }
+  let rowNo = 8;
+  for (const list of grouped) {
+    const values = [...fixedBomValues(list[0])];
+    // 相同（颜色,尺码）的多行合并用量；损耗率/缩水率/规格取第一个非空值
+    const pivot = new Map();
+    for (const r of list) {
+      const k = `${r.goodsColor}\u0000${r.goodsSize}`;
+      const old = pivot.get(k) || { number: 0, loss: '', shrink: '', property: '' };
+      old.number += Number(r.number) || 0;
+      if (r.loss !== '') {
+        old.loss = r.loss;
+      }
+      if (r.shrink !== '') {
+        old.shrink = r.shrink;
+      }
+      if (!old.property) {
+        old.property = r.property;
+      }
+      pivot.set(k, old);
+    }
+    for (const [colorName] of colors) {
+      for (const [sizeName] of sizes) {
+        const p = pivot.get(`${colorName}\u0000${sizeName}`);
+        if (p) {
+          values.push(p.property, numeric(p.number), lossQuantity(p.number, p.loss, p.shrink));
+        } else {
+          values.push('-', '', '');
+        }
+      }
+    }
+    styleDataRow(setRow(sheet, rowNo, pad(values)), 32, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 15, 26, 27, 28, 29, 30]);
+    const image = materialImages.get(list[0].materialSkuId);
+    if (image) {
+      embedImage(workbook, sheet, image, rowNo, 1, BOM_IMAGE_SIZE);
+    }
+    rowNo += 1;
+  }
+
+  // 物料单品明细区：标题整行合并 + 表头 + 聚合行
+  styleHeaderRow(setRow(sheet, rowNo, pad(['物料单品明细'])), 24);
+  sheet.mergeCells(rowNo, 1, rowNo, sheetTotal);
+  const detailHeaderRow = rowNo + 1;
+  styleHeaderRow(setRow(sheet, detailHeaderRow, pad(MATERIAL_SKU_HEADERS)), 28);
+  rowNo = detailHeaderRow + 1;
+  for (const group of materialSkuGroups(records)) {
+    styleDataRow(setRow(sheet, rowNo, pad(materialSkuValues(group))), 28, [1, 2, 3, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 23]);
+    const image = materialImages.get(group.first.materialSkuId);
+    if (image) {
+      embedImage(workbook, sheet, image, rowNo, 1, DETAIL_IMAGE_SIZE);
+    }
+    rowNo += 1;
+  }
+
+  // 列宽：BOM 固定列宽 + 每个动态列组 [14,12,14]；超出部分沿用商品信息区列宽
+  const widths = [...BOM_FIXED_WIDTHS];
+  for (let i = 0; i < dynamicCount; i += 1) {
+    widths.push(14, 12, 14);
+  }
+  for (let i = widths.length; i < sheetTotal; i += 1) {
+    widths.push(PRODUCT_WIDTHS[i] || 14);
+  }
+  widths.forEach((w, i) => {
+    sheet.getColumn(i + 1).width = w;
+  });
+
+  await saveWorkbook(workbook, filePath);
+  return { bomRows: grouped.length };
+}
+
+/**
+ * 报表入口：分页取商品列表（可选按款号过滤），逐商品取详情并生成文件。
+ * argv：{ sn 款号（可选）, limit 最多导出商品数（默认 100）, out 输出目录 }。
+ */
+async function generate(argv = {}) {
+  const limit = Number(argv.limit) > 0 ? Number(argv.limit) : 100;
+  const outDir = argv.out ? path.resolve(String(argv.out)) : process.cwd();
+  const sn = text(argv.sn);
+  const throttle = createThrottle(REQUEST_INTERVAL_MS);
+
+  const { list } = await fetchAll(
+    (page) => throttle(() => call('GET', '/api/agent/v1/goods/rich-list', {
+      sn: sn || undefined,
+      isOnSale: 1,
+      skuIsDisable: 0,
+      page,
+      limit: PAGE_LIMIT,
+    })),
+    { limit: PAGE_LIMIT, maxPages: Math.max(1, Math.ceil(limit / PAGE_LIMIT)) }
+  );
+  const selected = list.slice(0, limit);
+  if (!selected.length) {
+    throw new Error('没有符合条件的商品');
+  }
+
+  const directory = makeDirectory(outDir, `bom商品信息${timestamp()}`);
+  const used = new Set();
+  const filePaths = [];
+  let noBomCount = 0;
+  let skippedExisting = 0;
+  for (let i = 0; i < selected.length; i += 1) {
+    const summary = selected[i];
+    const detail = await throttle(() => call('GET', '/api/agent/v1/goods/full-detail', { id: summary.id }));
+    const goods = {
+      id: summary.id,
+      name: text(firstValue(detail.name, summary.name)),
+      goodsSn: text(firstValue(detail.goodsSn, summary.goodsSn)),
+    };
+    const filePath = planFile(directory, goods, used);
+    if (fs.existsSync(filePath)) {
+      skippedExisting += 1;
+      continue;
+    }
+    const meta = await writeGoodsFile(filePath, summary, detail);
+    filePaths.push(filePath);
+    if (!meta.bomRows) {
+      noBomCount += 1;
+    }
+    if ((i + 1) % 10 === 0) {
+      process.stdout.write(`已处理 ${i + 1}/${selected.length} 个商品\n`);
+    }
+  }
+
+  let summaryText = `BOM 商品信息导出完成：商品 ${filePaths.length} 个，无BOM商品 ${noBomCount} 个` +
+    (skippedExisting ? `，跳过已存在文件 ${skippedExisting} 个` : '') +
+    `，报表目录：${directory}`;
+  if (sn && !selected.some((g) => text(g.goodsSn) === sn)) {
+    summaryText += `；未匹配货号：${sn}`;
+  }
+  return { filePaths, summary: summaryText };
+}
+
+module.exports = { generate };