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

package/reports/goodsSize.js

@@ -0,0 +1,440 @@
+// 商品尺寸信息报表：每个商品生成一个 Excel 文件（工作表「尺寸指示」），
+// 默认部位纵向、尺码横向；传 transpose 时转置为尺码纵向、部位横向。
+// 同时导出洗前与洗后尺寸；部位图片下载后嵌入「图片」列（转置布局不嵌图）。
+// 数据流：GET /api/agent/v1/goods/rich-list 分页取商品列表，
+// 再逐商品 GET /api/agent/v1/goods/full-detail 取尺码轴、部位尺寸表与部位图片地址。
+// 列名、尺码轴构建规则、文件名与原 Python 报表脚本 export_goods_measurements.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 MAX_IMAGES_PER_PART = 3;
+const MAX_IMAGES_PER_GOODS = 120;
+/** 部位图片的显示尺寸（像素），多张图嵌在同一单元格内 */
+const PART_IMAGE_SIZE = { width: 64, height: 64 };
+
+/** 表头底色：基础列浅蓝、洗前列浅绿、洗后列浅紫（与原脚本一致） */
+const FILL_BASE = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFD9EAF7' } };
+const FILL_BEFORE = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE2F0D9' } };
+const FILL_AFTER = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE4DFEC' } };
+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 '';
+}
+
+/** 生成不含非法字符、不与已用名称冲突的文件名主体 */
+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-小数」时取数值列（洗前 length / 洗后
+ * lengthAfterWash），否则优先取分数文字列、缺失时回退数值列。
+ */
+function sizeValue(row, display, after) {
+  const numKey = after ? 'lengthAfterWash' : 'length';
+  const strKey = after ? 'lengthStrAfterWash' : 'lengthStr';
+  if (String(display) === '1') {
+    const value = row[numKey];
+    if (value === null || value === undefined || value === '' || typeof value === 'boolean') {
+      return '';
+    }
+    return value;
+  }
+  return firstValue(row[strKey], row[numKey]);
+}
+
+/**
+ * 把列表行与详情整理成报表数据结构：
+ * - 尺码轴按启用 SKU 的尺码名首次出现排序、按尺码 id 去重；
+ *   部位尺寸数据里出现而轴中没有的尺码名追加为兜底列。
+ * - 每个部位的尺寸值按「尺码 id（无 id 时用尺码名)」索引，分洗前/洗后两组。
+ */
+function normalizeGoods(summary, detail) {
+  const display = firstValue(detail.sizeLenDisplay, '');
+  const sizes = [];
+  const seenIds = new Set();
+  const seenNames = new Set();
+  for (const sku of detail.goodsSkuList || []) {
+    if (sku.isDisable) {
+      continue;
+    }
+    const name = text(sku.sizeName);
+    if (!name || seenNames.has(name)) {
+      continue;
+    }
+    const key = sku.sizeId !== null && sku.sizeId !== undefined ? String(sku.sizeId) : name;
+    if (seenIds.has(key)) {
+      continue;
+    }
+    seenNames.add(name);
+    seenIds.add(key);
+    sizes.push({ id: sku.sizeId, name, key });
+  }
+  const parts = [];
+  for (const raw of detail.goodsPartList || []) {
+    const values = new Map();
+    for (const item of raw.sizeLengths || []) {
+      const name = text(item.sizeName);
+      const key = item.sizeId !== null && item.sizeId !== undefined ? String(item.sizeId) : name;
+      // 无 SKU 但有尺寸数据时补充尺码列，避免尺寸值没有列可展示
+      if (name && !seenNames.has(name) && !seenIds.has(key)) {
+        seenNames.add(name);
+        seenIds.add(key);
+        sizes.push({ id: item.sizeId, name, key });
+      }
+      values.set(key, { before: sizeValue(item, display, false), after: sizeValue(item, display, true) });
+    }
+    // 小数显示时误差范围优先数值列，分数显示时优先文字列
+    const errorRange = String(display) === '1'
+      ? firstValue(raw.errorRange, raw.errorRangeStr)
+      : firstValue(raw.errorRangeStr, raw.errorRange);
+    parts.push({
+      name: text(raw.name),
+      measureMethod: text(raw.measureMethod),
+      errorRange: text(errorRange),
+      sample: text(firstValue(raw.sampleLengthStr, raw.sampleLength)),
+      grading: text(raw.gradingDifference),
+      gradingAfter: text(raw.gradingDifferenceAfterWash),
+      attachments: raw.attachmentUrls || [],
+      values,
+    });
+  }
+  return {
+    id: firstValue(detail.id, summary.id),
+    goodsName: text(firstValue(detail.name, summary.name)),
+    goodsSn: text(firstValue(detail.goodsSn, summary.goodsSn)),
+    sampleSize: text(detail.partLenSampleSizeName),
+    sizes,
+    parts,
+  };
+}
+
+/** 下载各部位图片：每部位最多 3 张、每商品最多 120 张，失败记录到导出说明 */
+async function downloadPartImages(item) {
+  const imagesByPart = new Map();
+  const failures = [];
+  let count = 0;
+  for (let index = 0; index < item.parts.length; index += 1) {
+    const part = item.parts[index];
+    const images = [];
+    for (const url of part.attachments.slice(0, MAX_IMAGES_PER_PART)) {
+      if (count >= MAX_IMAGES_PER_GOODS) {
+        break;
+      }
+      const image = await downloadImage(text(url));
+      if (image) {
+        images.push(image);
+        count += 1;
+      } else {
+        failures.push({ part: part.name || String(index + 1), url: text(url) });
+      }
+    }
+    imagesByPart.set(index, images);
+  }
+  return { imagesByPart, failures };
+}
+
+/** 图片下载失败地址脱敏：去掉 query 与 fragment，避免暴露签名参数 */
+function sanitizeUrl(url) {
+  if (!url) {
+    return '';
+  }
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch (e) {
+    return '';
+  }
+}
+
+/** 表头单元格样式：按列底色加粗居中 */
+function styleHeaderCell(cell, fill) {
+  cell.border = THIN_BORDER;
+  cell.fill = fill;
+  cell.font = { bold: true };
+  cell.alignment = { vertical: 'middle', horizontal: 'center', wrapText: true };
+}
+
+/** 数据单元格样式：细边框、垂直居中、自动换行（与原脚本数据样式一致，不水平居中） */
+function styleDataCell(cell) {
+  cell.border = THIN_BORDER;
+  cell.alignment = { vertical: 'middle', wrapText: true };
+}
+
+/** 尺寸值取用：部位 values 里按尺码 key 查洗前/洗后值，缺失返回空 */
+function valueOf(part, size, after) {
+  const entry = part.values.get(size.key);
+  if (!entry) {
+    return '';
+  }
+  return after ? entry.after : entry.before;
+}
+
+/** 写「部位纵向、尺码横向」布局：一行表头 + 每部位一行数据 */
+function writePartVertical(workbook, item, partImages) {
+  const sheet = workbook.addWorksheet('尺寸指示', { views: [{ state: 'frozen', ySplit: 1 }] });
+  const sampleTitle = `打样尺寸（${item.sampleSize || '样衣'}）`;
+  const headers = ['部位', '测量方法', '图片', '误差范围（+-）', sampleTitle, '洗前尺寸：档差'];
+  for (const size of item.sizes) {
+    headers.push(`洗前尺寸：${size.name}`);
+  }
+  headers.push('洗后尺寸：档差');
+  for (const size of item.sizes) {
+    headers.push(`洗后尺寸：${size.name}`);
+  }
+  // 表头配色：基础 5 列蓝，洗前档差列加洗前尺码列浅绿，洗后档差列加洗后尺码列浅紫
+  const headerRow = sheet.getRow(1);
+  headerRow.values = headers;
+  headerRow.height = 28;
+  headerRow.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+    styleHeaderCell(cell, colNumber <= 5 ? FILL_BASE : colNumber <= 6 + item.sizes.length ? FILL_BEFORE : FILL_AFTER);
+  });
+
+  item.parts.forEach((part, index) => {
+    const row = sheet.getRow(index + 2);
+    const values = [
+      part.name,
+      part.measureMethod,
+      '',
+      part.errorRange,
+      part.sample,
+      part.grading,
+      ...item.sizes.map((size) => valueOf(part, size, false)),
+      part.gradingAfter,
+      ...item.sizes.map((size) => valueOf(part, size, true)),
+    ];
+    row.values = values;
+    row.height = 54;
+    row.eachCell({ includeEmpty: true }, styleDataCell);
+    // 部位图片全部嵌在该行的图片列（第 3 列），多张图按原脚本叠放
+    for (const image of partImages.get(index) || []) {
+      embedImage(workbook, sheet, image, index + 2, 3, PART_IMAGE_SIZE);
+    }
+  });
+
+  headers.forEach((_, i) => {
+    sheet.getColumn(i + 1).width = i === 2 ? 16 : 22;
+  });
+  return sheet;
+}
+
+/**
+ * 写「尺码纵向、部位横向」布局（transpose）：表头为各部位列，
+ * 行依次为每个尺码的洗前尺寸、每个尺码的洗后尺寸、测量方法、误差范围、打样尺寸。
+ * 该布局不嵌部位图片。
+ */
+function writeSizeVertical(workbook, item) {
+  const sheet = workbook.addWorksheet('尺寸指示', { views: [{ state: 'frozen', ySplit: 1 }] });
+  const top = ['部位', ...item.parts.map((p, i) => p.name || `部位${i + 1}`)];
+  const headerRow = sheet.getRow(1);
+  headerRow.values = top;
+  headerRow.height = 28;
+  headerRow.eachCell({ includeEmpty: true }, (cell) => styleHeaderCell(cell, FILL_BASE));
+
+  const rows = [];
+  const rowFills = [];
+  for (const size of item.sizes) {
+    rows.push([`洗前尺寸${size.name}`, ...item.parts.map((p) => valueOf(p, size, false))]);
+    rowFills.push(FILL_BEFORE);
+  }
+  for (const size of item.sizes) {
+    rows.push([`洗后尺寸${size.name}`, ...item.parts.map((p) => valueOf(p, size, true))]);
+    rowFills.push(FILL_AFTER);
+  }
+  rows.push(['测量方法', ...item.parts.map((p) => p.measureMethod)]);
+  rowFills.push(FILL_BASE);
+  rows.push(['误差范围（+-）', ...item.parts.map((p) => p.errorRange)]);
+  rowFills.push(FILL_BASE);
+  rows.push([`打样尺寸（${item.sampleSize || '样衣'}）`, ...item.parts.map((p) => p.sample)]);
+  rowFills.push(FILL_BASE);
+
+  rows.forEach((values, index) => {
+    const row = sheet.getRow(index + 2);
+    row.values = values;
+    row.height = 24;
+    row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+      // 第一列是字段名，按所在行分组着色；其余列为数据
+      if (colNumber === 1) {
+        styleHeaderCell(cell, rowFills[index]);
+      } else {
+        styleDataCell(cell);
+      }
+    });
+  });
+
+  top.forEach((_, i) => {
+    sheet.getColumn(i + 1).width = i === 0 ? 20 : 22;
+  });
+  return sheet;
+}
+
+/** 图片下载失败时补一张「导出说明」工作表，记录失败部位与脱敏地址 */
+function writeNotesSheet(workbook, failures) {
+  if (!failures.length) {
+    return;
+  }
+  const sheet = workbook.addWorksheet('导出说明');
+  const headers = ['类型', '部位', '说明', '地址（脱敏）'];
+  const headerRow = sheet.getRow(1);
+  headerRow.values = headers;
+  headerRow.height = 28;
+  headerRow.eachCell({ includeEmpty: true }, (cell) => styleHeaderCell(cell, FILL_BASE));
+  failures.forEach((failure, index) => {
+    const row = sheet.getRow(index + 2);
+    row.values = ['图片下载失败', failure.part, '下载失败或格式校验未通过', sanitizeUrl(failure.url)];
+    row.height = 22;
+    row.eachCell({ includeEmpty: true }, styleDataCell);
+  });
+  headers.forEach((_, i) => {
+    sheet.getColumn(i + 1).width = i === 0 ? 14 : 26;
+  });
+}
+
+/** 创建输出目录；同名目录已存在时追加序号，避免覆盖既有报表 */
+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, item, used) {
+  const base = `${safeComponent(item.goodsName, '商品')}（${safeComponent(item.goodsSn, '无货号')}）`;
+  let name = `${base}.xlsx`;
+  if (used.has(name.toLowerCase())) {
+    name = `${base}_${item.id}.xlsx`;
+  }
+  let seq = 2;
+  while (used.has(name.toLowerCase())) {
+    name = `${base}_${item.id}_${seq}.xlsx`;
+    seq += 1;
+  }
+  used.add(name.toLowerCase());
+  return path.join(directory, name);
+}
+
+/**
+ * 报表入口：分页取商品列表（可选按款号过滤），逐商品取详情生成尺寸表。
+ * 没有尺寸部位数据的商品不生成文件；单个商品详情失败会跳过并继续。
+ * argv：{ sn 款号（可选）, limit 最多导出商品数（默认 100）,
+ * transpose 转置为尺码纵向, out 输出目录 }。
+ */
+async function generate(argv = {}) {
+  const limit = Number(argv.limit) > 0 ? Number(argv.limit) : 100;
+  const transpose = argv.transpose === true;
+  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, `商品尺寸信息${transpose ? '尺码纵向' : ''}${timestamp()}`);
+  const used = new Set();
+  const filePaths = [];
+  let detailFailed = 0;
+  let skippedExisting = 0;
+  for (let i = 0; i < selected.length; i += 1) {
+    const summary = selected[i];
+    let detail;
+    try {
+      detail = await throttle(() => call('GET', '/api/agent/v1/goods/full-detail', { id: summary.id }));
+    } catch (e) {
+      // 单个商品详情失败不中断其它商品
+      detailFailed += 1;
+      process.stdout.write(`商品 ${text(summary.goodsSn) || summary.id} 详情获取失败：${e.message}\n`);
+      continue;
+    }
+    const item = normalizeGoods(summary, detail);
+    if (!item.parts.length) {
+      continue;
+    }
+    const filePath = planFile(directory, item, used);
+    if (fs.existsSync(filePath)) {
+      skippedExisting += 1;
+      continue;
+    }
+    const workbook = createWorkbook();
+    if (transpose) {
+      writeSizeVertical(workbook, item);
+    } else {
+      const { imagesByPart, failures } = await downloadPartImages(item);
+      writePartVertical(workbook, item, imagesByPart);
+      writeNotesSheet(workbook, failures);
+    }
+    await saveWorkbook(workbook, filePath);
+    filePaths.push(filePath);
+    if ((i + 1) % 10 === 0) {
+      process.stdout.write(`已处理 ${i + 1}/${selected.length} 个商品\n`);
+    }
+  }
+  if (!filePaths.length) {
+    throw new Error('没有成功生成文件，未发布空目录');
+  }
+
+  let summaryText = `商品尺寸信息导出完成：商品 ${filePaths.length} 个`;
+  if (detailFailed) {
+    summaryText += `，详情获取失败 ${detailFailed} 个`;
+  }
+  if (skippedExisting) {
+    summaryText += `，跳过已存在文件 ${skippedExisting} 个`;
+  }
+  summaryText += `，报表目录：${directory}`;
+  return { filePaths, summary: summaryText };
+}
+
+module.exports = { generate };

package/reports/image.js

@@ -0,0 +1,216 @@
+// 报表嵌图公共模块：下载商品图、物料图等到内存，供 Excel 嵌入。
+// 图片地址以 CDN 为主（不需要认证）。下载前统一转换为缩略地址，下载后做
+// 大小与格式校验，任何一步失败都返回 null，报表跳过该图，不中断整体生成。
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { sleep } = require('./util');
+
+/** 单张图片大小上限 5MB（与原报表脚本一致） */
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+/** 图片宽高上限与总像素上限（与原报表脚本一致，防御异常超大图） */
+const MAX_DIMENSION = 8192;
+const MAX_PIXELS = 20_000_000;
+/** 用查询参数承载缩略样式的 CDN 域名 */
+const CDN_QUERY_HOSTS = new Set(['is-scm.cdn.qinsilk.com', 'is-scm-dev.cdn.qinsilk.com']);
+
+/** 每张图片的缓存目录（按服务器域名隔离，进程结束后由系统临时目录策略清理） */
+function cacheDir() {
+  const dir = path.join(os.tmpdir(), 'scm-agent-images');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * 把接口返回的图片地址转换为缩略下载地址（约 200px，Excel 嵌图 60-80px 足够）。
+ * 规则与原报表脚本一致：
+ * - qinsilk 域名下 http 图片升级为 https；
+ * - 地址已带查询参数、已带 @! 处理后缀或是 gif，说明已处理过，原样返回；
+ * - is-scm*.cdn 域名用查询参数 x-image-process=style/pic200wh；
+ * - 其他 qinsilk 域名在路径末尾追加 @!pic200wh；
+ * - 其他域名原样返回（不掌握其图片服务能力，不做处理）。
+ * 无法解析的地址返回 null。
+ */
+function toThumbUrl(rawUrl, baseUrl) {
+  const text = String(rawUrl || '').trim();
+  if (!text) {
+    return null;
+  }
+  let url;
+  try {
+    url = new URL(text);
+  } catch (e) {
+    if (!baseUrl) {
+      return null;
+    }
+    try {
+      url = new URL(text, baseUrl.endsWith('/') ? baseUrl : baseUrl + '/');
+    } catch (e2) {
+      return null;
+    }
+  }
+  const host = (url.hostname || '').toLowerCase();
+  if (url.protocol === 'http:' && host.endsWith('.qinsilk.com')) {
+    url.protocol = 'https:';
+  }
+  let decodedPath = url.pathname;
+  try {
+    decodedPath = decodeURIComponent(url.pathname).toLowerCase();
+  } catch (e) {
+    decodedPath = url.pathname.toLowerCase();
+  }
+  if (url.search || url.pathname.includes('@!') || decodedPath.endsWith('.gif')) {
+    return url.href;
+  }
+  if (CDN_QUERY_HOSTS.has(host)) {
+    url.search = 'x-image-process=style/pic200wh';
+    return url.href;
+  }
+  if (host === 'qinsilk.com' || host.endsWith('.qinsilk.com')) {
+    return url.origin + url.pathname + '@!pic200wh';
+  }
+  return url.href;
+}
+
+/** 下载后的内存缓存（键为接口返回的原始地址），同一份报表内重复图片只下载一次 */
+const memory = new Map();
+
+/**
+ * 下载图片并返回 { buffer, extension }；地址非法、下载失败或校验不通过返回 null。
+ * 重试一次后放弃，保证网络波动不会让整份报表失败。
+ */
+async function downloadImage(url, { baseUrl } = {}) {
+  if (!url) {
+    return null;
+  }
+  if (memory.has(url)) {
+    return memory.get(url);
+  }
+  const result = await downloadWithRetry(toThumbUrl(url, baseUrl));
+  memory.set(url, result);
+  return result;
+}
+
+async function downloadWithRetry(thumbUrl) {
+  if (!thumbUrl) {
+    return null;
+  }
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const response = await fetch(thumbUrl, { redirect: 'follow' });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      const declaredLength = Number(response.headers.get('content-length') || 0);
+      if (declaredLength > MAX_IMAGE_BYTES) {
+        return null;
+      }
+      const buffer = Buffer.from(await response.arrayBuffer());
+      const extension = validateImage(buffer);
+      if (!extension) {
+        return null;
+      }
+      return { buffer, extension };
+    } catch (e) {
+      if (attempt === 1) {
+        return null;
+      }
+      await sleep(500);
+    }
+  }
+  return null;
+}
+
+/** 读 PNG 头部的宽高（IHDR 固定偏移 16/20） */
+function pngSize(buffer) {
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
+
+/**
+ * 按 JPEG 段结构定位 SOF 段读取宽高。
+ * 0xC4/0xC8/0xCC 不是尺寸段必须排除；0xFF 填充与 0xD0-0xD7 独立标记无长度字段直接跳过。
+ */
+function jpegSize(buffer) {
+  let index = 2;
+  while (index < buffer.length - 1) {
+    if (buffer[index] !== 0xff) {
+      index += 1;
+      continue;
+    }
+    const marker = buffer[index + 1];
+    if (marker === 0xff || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      index += 2;
+      continue;
+    }
+    if (marker === 0xd9 || index + 4 > buffer.length) {
+      return null;
+    }
+    const isSizeMarker = (marker >= 0xc0 && marker < 0xc4) || (marker >= 0xc5 && marker < 0xc8)
+      || (marker >= 0xc9 && marker < 0xcc) || (marker >= 0xcd && marker < 0xd0);
+    if (isSizeMarker) {
+      if (index + 9 > buffer.length) {
+        return null;
+      }
+      return { width: buffer.readUInt16BE(index + 7), height: buffer.readUInt16BE(index + 5) };
+    }
+    index += 2 + buffer.readUInt16BE(index + 2);
+  }
+  return null;
+}
+
+/**
+ * 校验图片内容并返回扩展名（png / jpg），不合格返回 null：
+ * 只接受 PNG 与 JPEG；超过 5MB、宽高超过 8192、总像素超过 2000 万的都拒绝。
+ * 校验以内容魔数为准（URL 后缀可能不准确）。
+ */
+function validateImage(buffer) {
+  if (!buffer || !buffer.length || buffer.length > MAX_IMAGE_BYTES) {
+    return null;
+  }
+  let size = null;
+  let extension = null;
+  if (buffer.length >= 24 && buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+    size = pngSize(buffer);
+    extension = 'png';
+  } else if (buffer.length > 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    size = jpegSize(buffer);
+    extension = 'jpg';
+  } else {
+    return null;
+  }
+  if (!size || !size.width || !size.height) {
+    return null;
+  }
+  if (size.width > MAX_DIMENSION || size.height > MAX_DIMENSION || size.width * size.height > MAX_PIXELS) {
+    return null;
+  }
+  return extension;
+}
+
+/**
+ * 下载一批图片（地址去重、剔除空值），返回 原始地址 → { buffer, extension } 的 Map。
+ * 并发 4 个，避免图片较多时压满连接。
+ */
+async function downloadImages(urls, { onProgress, baseUrl } = {}) {
+  const unique = [...new Set((urls || []).filter(Boolean))];
+  const map = new Map();
+  let done = 0;
+  const queue = [...unique];
+  async function worker() {
+    while (queue.length) {
+      const url = queue.shift();
+      const image = await downloadImage(url, { baseUrl });
+      if (image) {
+        map.set(url, image);
+      }
+      done += 1;
+      if (onProgress) {
+        onProgress(done, unique.length);
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, unique.length) }, worker));
+  return map;
+}
+
+module.exports = { downloadImage, downloadImages, toThumbUrl, validateImage };