@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/daily-report-core.mjs

@@ -0,0 +1,517 @@
+/**
+ * daily-report-core.mjs —— 店铺日报的**共用取数 + 聚合 + 口径**实现（L1 执行内核）。
+ *
+ * ## 为什么有它（2026-10-12，「日报口径透明化 + 只读对账」批）
+ * 客户在平台概览看到的「销售量」与卡片上的「订单数」对不上（现场：10-11 一店 595 vs 602）。
+ * 要回答"为什么有出入"，就必须能**逐候选口径**重算同一窗口 —— 而那必须是**同一份**实现，
+ * 不是第二份（"复制一份口径逻辑"必然在下一次口径调整时漂移，届时两边各自"正确"）。
+ * 因此把 **窗口计算 + fetchOrders + aggregateOrders + 候选口径/命中判定** 抽到本文件：
+ *   · `scripts/daily-report.mjs`（日报 CLI）—— 生产取数 + 卡片渲染；
+ *   · `scripts/daily-report-reconcile.mjs`（只读对账 CLI）—— 逐候选重算 + 漂移对照；
+ * 两个 CLI 都 import 本文件，**没有任何第二份口径**。`daily-report.mjs` 的对外导出
+ * （`aggregateOrders` / `apiGet` / `localDateStr` / `startOfLocalDayUTC` / `tzOffsetMs` /
+ * `localHour`）**逐字转出**本文件，既有单测与调用方一字不改。
+ *
+ * ## 本文件为什么**不含平台域名/业务词**
+ * `node scripts/vertical-lint.mjs` 的 engine-words 档（`verticals/_engine-words.json`）
+ * 只拦**新增**业务词、且明令 ⛔ 不抬基线 ⇒ 引擎面新文件里出现平台域名即判红（实测过）。
+ * 所以 API 基址**不硬编码**：由调用方注入（日报 CLI 用自己那份历史常量 / `ML_API_BASE`），
+ * 或由 `ML_API_BASE` 环境变量给出（`apiGet`/`apiToken` 的兜底）。对账 CLI 另从**快照里记录的
+ * `apiBase`**（抓取时刻的事实）取，见 `daily-report-reconcile.mjs`。
+ *
+ * ## 纪律
+ *   · **纯 L1**：只 import `node:` 内建，零宿主模块（`scripts/tests/kernel-purity.test.mjs` 扫内容）；
+ *   · 本文件里**零写盘**（写盘属调用方：日报 CLI 落快照、对账 CLI 默认完全不写）；
+ *   · 所有函数纯函数或纯读（`fetchOrders`/`apiGet` 是只读 GET）。
+ */
+
+// ── 依赖：只有 node 内建（L1 ⇒ ⛔ 不得 import 宿主模块）──────────
+import { readFileSync, existsSync } from 'node:fs'
+
+// ── 纯工具：env 文件解析（两个 CLI 共用同一份；⛔ 不要各写一个）────
+/** 读 `K=V` 形态的 env 文件（缺文件 ⇒ 空对象；`#` 注释与空行跳过；值两侧空白去掉）。 */
+export function loadEnvFile(path) {
+  const out = {}
+  if (!existsSync(path)) return out
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    const t = line.trim()
+    if (!t || t.startsWith('#')) continue
+    const eq = t.indexOf('=')
+    if (eq > 0) out[t.slice(0, eq).trim()] = t.slice(eq + 1).trim()
+  }
+  return out
+}
+
+// ── 站点 → 本地时区（IANA，自动处理夏令时）与货币 ─────────────
+export const SITE_TZ = {
+  MLM: 'America/Mexico_City',
+  MLB: 'America/Sao_Paulo',
+  MLA: 'America/Argentina/Buenos_Aires',
+  MLC: 'America/Santiago',
+  MCO: 'America/Bogota',
+  MPE: 'America/Lima',
+  MLU: 'America/Montevideo',
+  MLV: 'America/Caracas',
+}
+export const SITE_CURRENCY = {
+  MLM: 'MXN', MLB: 'BRL', MLA: 'ARS', MLC: 'CLP',
+  MCO: 'COP', MPE: 'PEN', MLU: 'UYU', MLV: 'USD',
+}
+export const fallbackSite = (site) => (SITE_TZ[site] ? site : 'MLM')
+
+/** API 基址：显式传入优先，其次 `ML_API_BASE`（排障旋钮/离线夹具）。两者都没有 ⇒ 抛（绝不猜域名）。 */
+export function resolveApiBase(explicit) {
+  const base = explicit || process.env.ML_API_BASE
+  if (!base) throw new Error('缺少 API 基址：请传 base 或设 ML_API_BASE（引擎侧不硬编码平台域名）')
+  return base
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+// ── 时区工具（逐字搬自 daily-report.mjs；行为不得变化）──────────
+// 某时区的「本地日期 YYYY-MM-DD」字符串
+export function localDateStr(tz, date) {
+  return new Intl.DateTimeFormat('en-CA', {
+    timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit',
+  }).format(date)
+}
+
+// 某时区在指定时刻的 UTC 偏移（毫秒），如 墨西哥 -6h → -21600000
+export function tzOffsetMs(tz, date) {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz, timeZoneName: 'longOffset',
+    }).formatToParts(date)
+    const name = (parts.find((p) => p.type === 'timeZoneName') || {}).value || ''
+    const m = /GMT([+-])(\d{2}):(\d{2})/.exec(name)
+    if (!m) return 0
+    const sign = m[1] === '-' ? -1 : 1
+    return sign * (Number(m[2]) * 60 + Number(m[3])) * 60000
+  } catch {
+    return 0
+  }
+}
+
+// 某时区「本地某日 00:00」对应的 UTC 毫秒
+export function startOfLocalDayUTC(tz, date) {
+  const [y, m, d] = localDateStr(tz, date).split('-').map(Number)
+  return Date.UTC(y, m - 1, d) - tzOffsetMs(tz, date)
+}
+
+// 某时区的本地小时（0-23）
+export function localHour(tz, date) {
+  const parts = new Intl.DateTimeFormat('en-GB', {
+    timeZone: tz, hour: '2-digit', hour12: false,
+  }).formatToParts(date)
+  return Number((parts.find((p) => p.type === 'hour') || {}).value || 0)
+}
+
+// ── 抓取时刻 / 窗口的「人读 + 机读」两种表示（快照新增字段用）──────
+const pad2 = (n) => String(n).padStart(2, '0')
+
+/** 站点本地 `MM-DD HH:mm`（如 `10-12 14:05`）。绝不返回 `undefined`：取不到就返回 `null`。 */
+export function localStamp(tz, date) {
+  const d = date instanceof Date ? date : new Date(date)
+  if (!Number.isFinite(d.getTime())) return null
+  try {
+    const parts = new Intl.DateTimeFormat('en-GB', {
+      timeZone: tz, month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
+    }).formatToParts(d)
+    const get = (t) => (parts.find((p) => p.type === t) || {}).value
+    const mo = get('month'), da = get('day'), ho = get('hour'), mi = get('minute')
+    if (!mo || !da || !ho || !mi) return null
+    return `${mo}-${da} ${ho}:${mi}`
+  } catch {
+    return null
+  }
+}
+
+/** 站点本地 ISO8601 **带偏移**（如 `2026-10-12T14:05:00.000-06:00`）。取不到 ⇒ `null`。 */
+export function isoWithOffset(tz, date) {
+  const d = date instanceof Date ? date : new Date(date)
+  if (!Number.isFinite(d.getTime())) return null
+  const off = tzOffsetMs(tz, d)
+  const shifted = new Date(d.getTime() + off)
+  const s = `${shifted.getUTCFullYear()}-${pad2(shifted.getUTCMonth() + 1)}-${pad2(shifted.getUTCDate())}`
+    + `T${pad2(shifted.getUTCHours())}:${pad2(shifted.getUTCMinutes())}:${pad2(shifted.getUTCSeconds())}`
+    + `.${String(shifted.getUTCMilliseconds()).padStart(3, '0')}`
+  const sign = off < 0 ? '-' : '+'
+  const abs = Math.abs(off)
+  return `${s}${sign}${pad2(Math.floor(abs / 3600000))}:${pad2(Math.floor((abs % 3600000) / 60000))}`
+}
+
+/**
+ * 一次日报的**窗口 + 抓取时刻**（快照新增字段的唯一来源；两个 CLI 共用）。
+ *
+ * 口径（与改动前的 `collectStore` **逐字等价**）：
+ *   · `reportStart` = 报告日（站点本地）00:00；`todayStart` = 今天（站点本地）00:00；
+ *   · 报告窗口 = `[reportStart, todayStart)` —— **站点本地自然日**，天然含夏令时切换；
+ *   · `weekStart` = `reportStart - winDays`（`winDays = max(1, SALES_WINDOW_DAYS - 1)`，缺省 6）；
+ *   · `prevStart` = `reportStart - (winDays + 7)`。
+ */
+export function reportWindows(site, reportDate, now, opts = {}) {
+  const siteCode = fallbackSite(site)
+  const tz = SITE_TZ[siteCode]
+  const salesWindowDays = opts.salesWindowDays != null && opts.salesWindowDays !== ''
+    ? Number(opts.salesWindowDays) : 7
+  const winDays = Math.max(1, (Number.isFinite(salesWindowDays) ? salesWindowDays : 7) - 1)
+  const todayStart = startOfLocalDayUTC(tz, now)
+  const reportStart = startOfLocalDayUTC(tz, reportDate)
+  const weekStart = startOfLocalDayUTC(tz, new Date(reportDate.getTime() - winDays * 86400000))
+  const prevStart = startOfLocalDayUTC(tz, new Date(reportDate.getTime() - (winDays + 7) * 86400000))
+  return {
+    site: siteCode,
+    tz,
+    winDays,
+    weekStart,
+    reportStart,
+    todayStart,
+    prevStart,
+    windows: { weekStartMs: weekStart, reportStartMs: reportStart, todayStartMs: todayStart },
+  }
+}
+
+/** 报告窗口的**自描述**（存进快照：换台机器/换个人也能一眼看懂这段数字覆盖哪段时间）。 */
+export function windowInfo(site, reportStart, todayStart) {
+  const tz = SITE_TZ[fallbackSite(site)]
+  return {
+    tz,
+    from: new Date(reportStart).toISOString(),
+    to: new Date(todayStart).toISOString(),
+    fromLocal: `${localDateStr(tz, new Date(reportStart))} 00:00`,
+    toLocal: `${localDateStr(tz, new Date(todayStart))} 00:00`,
+  }
+}
+
+/** 快照新增的「抓取时刻」字段（站点本地时区语义）。 */
+export function capturedAtInfo(site, now = new Date()) {
+  const tz = SITE_TZ[fallbackSite(site)]
+  return { capturedAt: isoWithOffset(tz, now), capturedAtLocal: localStamp(tz, now), capturedTz: tz }
+}
+
+// ── 店铺授权表：稳定 key + 匹配（两个 CLI 共用同一份，别写第二份）──
+/** 快照/幂等标记的文件名 key：以 user_id 稳定命名（不按下标 —— 多时区店铺触发时刻不同，下标会漂移）。 */
+export const storeKey = (store) => `store-${String(store.user_id ?? store.name)}`
+
+/** `--store` 匹配：名称**子串**或 user_id **全等**（与日报 CLI 的历史行为逐字一致）。 */
+export function matchStores(stores, queries) {
+  const q = (queries || []).map((x) => String(x).trim()).filter(Boolean)
+  if (!q.length) return stores || []
+  return (stores || []).filter((x) => q.some((t) => String(x.name).includes(t) || String(x.user_id) === t))
+}
+
+// ── 订单聚合：近7日 + 昨日，按 SKU ─────────────────────────
+// orders: MELI /orders/search results；itemById: 商品信息 map
+// windows: {weekStartMs, reportStartMs, todayStartMs}
+export function aggregateOrders(orders, itemById, windows, site) {
+  const skus = new Map()
+  // 2026-09-27（用户口径）：日报显示 **SKU**（替换西语标题——中国同事看不懂西语），且**不读 lip 表**。
+  // SKU 来源：`order_items[].item.seller_sku`（实测 3 店 × 200 单 = 600 行 100% 有值，含变体），
+  // 因此**不需要任何额外接口调用**；一个 listing 有多个变体 SKU 时，取**卖得最多**的那个。
+  const ensure = (id) => {
+    if (!skus.has(id)) {
+      skus.set(id, {
+        id, title: (itemById[id] && itemById[id].title) || `商品 ${id}`,
+        price: (itemById[id] && itemById[id].price) ?? null,
+        avail: (itemById[id] && itemById[id].available_quantity) ?? null,
+        sold: (itemById[id] && itemById[id].sold_quantity) ?? null,
+        units7: 0, gmv7: 0, unitsY: 0, gmvY: 0,
+        skuUnits: new Map(),   // seller_sku → 近7日件数（用于挑主 SKU）
+        sku: '',
+      })
+    }
+    return skus.get(id)
+  }
+  const summary = { orders: 0, gmv: 0, cancelled: 0, units: 0, avg: null, fees: 0, coupons: 0, orders7: 0 }
+  const daily = new Map()                 // 站点本地日期 → {orders, gmv}（第 2 批：每日趋势）
+  const buyers = new Set()                // 近 7 日买家（第 2 批：新客占比）
+  for (const o of orders || []) {
+    const created = Date.parse(o.date_created || '')
+    if (!created) continue
+    if (o.status === 'cancelled') {
+      if (created >= windows.reportStartMs && created < windows.todayStartMs) summary.cancelled++
+      continue
+    }
+    // 2026 实测：有效订单状态为 paid（旧文档的 confirmed 已不再出现）；
+    // 排除未付款的 payment_required，其余状态（paid/confirmed/shipped/delivered）都算有效订单
+    if (o.status === 'payment_required') continue
+    const inY = created >= windows.reportStartMs && created < windows.todayStartMs
+    const in7 = created >= windows.weekStartMs && created < windows.todayStartMs
+    const bid = (o.buyer && o.buyer.id) || null
+    if (bid) buyers.add(String(bid))
+    if (inY) {
+      summary.orders++
+      summary.gmv += Number(o.total_amount || 0)
+      summary.units += (o.order_items || []).reduce((a, i) => a + Number(i.quantity || 0), 0)
+      // 平台费用与优惠券（都在订单响应里 ⇒ 零额外请求）
+      for (const oi of o.order_items || []) summary.fees += Number(oi.sale_fee || 0)
+      for (const pay of o.payments || []) summary.coupons += Number(pay.coupon_amount || 0)
+    }
+    if (in7) {                                   // 趋势要 7 个点 ⇒ 按近 7 日分桶（不是只桶昨日）
+      summary.orders7++
+      const dk = localDateStr(SITE_TZ[fallbackSite(site)] || 'America/Mexico_City', new Date(created))
+      const bucket = daily.get(dk) || { date: dk, orders: 0, gmv: 0 }
+      bucket.orders++
+      bucket.gmv += Number(o.total_amount || 0)
+      daily.set(dk, bucket)
+    }
+    if (!in7) continue
+    for (const oi of o.order_items || []) {
+      const id = String((oi.item && oi.item.id) || '')
+      if (!id) continue
+      const sku = ensure(id)
+      const qty = Number(oi.quantity || 0)
+      const amt = qty * Number(oi.unit_price || 0)
+      const code = String((oi.item && oi.item.seller_sku) || '').trim()
+      if (code) sku.skuUnits.set(code, (sku.skuUnits.get(code) || 0) + qty)
+      if (inY) { sku.unitsY += qty; sku.gmvY += amt }
+      sku.units7 += qty
+      sku.gmv7 += amt
+    }
+  }
+  summary.avg = summary.orders ? summary.gmv / summary.orders : null
+  for (const s of skus.values()) {
+    let best = '', bestN = -1
+    for (const [code, n] of s.skuUnits) if (n > bestN) { best = code; bestN = n }   // 并列时保留先出现的（Map 保序）
+    s.sku = best
+    delete s.skuUnits
+  }
+  return { summary, skus: [...skus.values()], daily: [...daily.values()].sort((a, b) => (a.date < b.date ? -1 : 1)), buyers }
+}
+
+// ── 「为什么对不上」：候选口径逐项重算（纯函数，只读）──────────────
+// 现场结论（2026-10-12 实测）：**没有一个候选等于平台的 602** ⇒ 差异不是口径而是时点/未知。
+// 所以这里把**所有能算的候选**都算出来并排显示，而不是猜一个。
+export const CANDIDATE_DESC = {
+  orders: '我方口径：窗口内、date_created 命中、排除 cancelled 与 payment_required 的订单笔数',
+  paidApproved: '候选：窗口内有效订单中，payments[] 里至少一笔 status=approved',
+  withShipping: '候选：窗口内有效订单中带发货信息（shipping.id/mode/status 任一存在）',
+  allCreated: '候选：窗口内全部创建的订单**含取消**（= 有效订单 + 取消单；仍排除 payment_required）',
+  paymentRequired: '候选：窗口内 status=payment_required（未付款）的订单数',
+  uniqueBuyers: '候选：窗口内有效订单的**去重买家**数（buyer.id）',
+  units: '候选：窗口内有效订单 Σ order_items[].quantity（= 卡片「已售件数」）',
+  cancelled: '候选：窗口内 status=cancelled 的订单数（卡片「取消」）',
+  gmv: '候选：窗口内有效订单 Σ total_amount（= 卡片「销售额」，可能带小数）',
+  avg: '候选：我方客单价（gmv / orders，四舍五入到整数）',
+}
+
+/** 窗口内命中（按 `date_created`；与 `aggregateOrders` 用同一判据）。 */
+export const inWindow = (o, fromMs, toMs) => {
+  const t = Date.parse((o && o.date_created) || '')
+  return !!t && t >= fromMs && t < toMs
+}
+
+const hasShippingInfo = (o) => !!(o && o.shipping && (o.shipping.id || o.shipping.mode || o.shipping.status))
+const hasApprovedPayment = (o) => ((o && o.payments) || []).some((p) => p && p.status === 'approved')
+const unitsOf = (list) => list.reduce((a, o) => a + (o.order_items || []).reduce((x, i) => x + Number(i.quantity || 0), 0), 0)
+
+/**
+ * 逐候选口径（**纯函数**）：给定订单集与窗口 ⇒ 我方口径 + 各候选值。
+ * `orders` 需要覆盖**整个窗口**（含取消/未付款），调用方取数时已含。
+ */
+export function candidateMetrics(orders, windows, { tz = 'America/Mexico_City' } = {}) {
+  const from = windows.reportStartMs
+  const to = windows.todayStartMs
+  const win = (orders || []).filter((o) => inWindow(o, from, to))
+  const cancelled = win.filter((o) => o.status === 'cancelled')
+  const paymentRequired = win.filter((o) => o.status === 'payment_required')
+  const valid = win.filter((o) => o.status !== 'cancelled' && o.status !== 'payment_required')
+  const gmv = Math.round(valid.reduce((a, o) => a + Number(o.total_amount || 0), 0) * 100) / 100   // 金额到分（浮点累加会带噪声）
+  const units = unitsOf(valid)
+  const buyers = new Set()
+  for (const o of valid) if (o.buyer && o.buyer.id != null) buyers.add(String(o.buyer.id))
+  const values = {
+    orders: valid.length,
+    paidApproved: valid.filter(hasApprovedPayment).length,
+    withShipping: valid.filter(hasShippingInfo).length,
+    allCreated: valid.length + cancelled.length,
+    paymentRequired: paymentRequired.length,
+    uniqueBuyers: buyers.size,
+    units,
+    cancelled: cancelled.length,
+    gmv,
+    avg: valid.length ? Math.round(gmv / valid.length) : null,
+  }
+  const candidates = Object.keys(CANDIDATE_DESC).map((key) => ({
+    key, label: key, value: values[key], desc: CANDIDATE_DESC[key],
+  }))
+  return {
+    values,
+    candidates,
+    summary: { orders: values.orders, units: values.units, gmv, cancelled: cancelled.length, avg: values.avg },
+    window: { from, to, tz, fromLocal: localDateStr(tz, new Date(from)), toLocal: localDateStr(tz, new Date(to)) },
+    counts: { window: win.length, valid: valid.length, cancelled: cancelled.length, paymentRequired: paymentRequired.length },
+  }
+}
+
+/** 窗口平移敏感度：把窗口整体平移 N 小时，重算「我方口径」的订单数。 */
+export function windowShiftSensitivity(orders, windows, shiftsHours = [-3, -2, -1, 1, 2, 3]) {
+  const base = { from: windows.reportStartMs, to: windows.todayStartMs }
+  const at = (h) => {
+    const from = base.from + h * 3600000
+    const to = base.to + h * 3600000
+    return (orders || []).filter((o) => inWindow(o, from, to)
+      && o.status !== 'cancelled' && o.status !== 'payment_required').length
+  }
+  return { base: at(0), shifts: shiftsHours.map((h) => ({ hours: h, orders: at(h) })) }
+}
+
+/** `--platform-kpi "订单数量=602,已售件数=640"`（也接受 JSON `{"订单数量":602}`）⇒ `[{label,value}]`。 */
+export function parsePlatformKpi(spec) {
+  if (spec == null || spec === '') return []
+  const text = String(spec).trim()
+  if (!text) return []
+  const out = []
+  if (text.startsWith('{')) {
+    const obj = JSON.parse(text)
+    for (const [label, value] of Object.entries(obj || {})) {
+      const n = Number(value)
+      if (Number.isFinite(n)) out.push({ label: String(label), value: n })
+    }
+    return out
+  }
+  for (const part of text.split(',')) {
+    const seg = part.trim()
+    if (!seg) continue
+    const i = seg.lastIndexOf('=') >= 0 ? seg.lastIndexOf('=') : seg.indexOf(':')
+    if (i < 0) throw new Error(`--platform-kpi 需要「名称=数值」形式（实得 ${JSON.stringify(seg)}）`)
+    const label = seg.slice(0, i).trim()
+    const raw = seg.slice(i + 1).trim().replace(/[,_\s]/g, '')
+    const n = Number(raw)
+    if (!label || !Number.isFinite(n)) throw new Error(`--platform-kpi 的「${seg}」解析不出数值`)
+    out.push({ label, value: n })
+  }
+  return out
+}
+
+/**
+ * 命中判据：把每个平台 KPI 的数值与**全部候选值**比对。
+ * 返回 `{ hits: [{label, value, matched:[candidateKey…]}], misses: [{label,value}] }`。
+ * ⛔ 不"就近匹配"、不四舍五入 —— 对不上就是对不上（正是本次事故的结论）。
+ */
+export function matchCandidates(metrics, kpis) {
+  const cands = (metrics && metrics.candidates) || []
+  const hits = []
+  const misses = []
+  for (const k of kpis || []) {
+    const matched = cands.filter((c) => Number(c.value) === Number(k.value)).map((c) => c.key)
+    if (matched.length) hits.push({ ...k, matched })
+    else misses.push({ ...k })
+  }
+  return { hits, misses, hitAll: misses.length === 0 && hits.length > 0 }
+}
+
+// ── 只读 HTTP（429 退避重试；base 由调用方注入）──────────────
+/**
+ * 平台 GET。**429（local_rate_limited）自动退避重试**：
+ * 2026-09-27 实测——短时间密集跑几轮后会连续 429，而日报此前一次失败就整店放弃
+ * （"全部店铺采集失败，不推送"）⇒ 客户当天收不到日报。限流是**瞬时**的，退避即恢复。
+ */
+export async function apiGet(path, token, opts = {}) {
+  const base = resolveApiBase(opts.base)
+  const retries = opts.retries != null ? opts.retries : Number(process.env.ML_HTTP_RETRIES || 3)
+  // 退避序列可覆盖（测试用 ML_HTTP_BACKOFF_MS=20,30 跑得快；默认 5s/15s/30s）
+  const wait = String(process.env.ML_HTTP_BACKOFF_MS || '5000,15000,30000').split(',').map((x) => Number(x.trim())).filter((x) => x >= 0)
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } })
+    const body = await res.json().catch(() => ({}))
+    if (res.ok) return body
+    const short = String(path.split('?')[0])
+    const msg = `API ${short} 失败 HTTP ${res.status}: ${JSON.stringify(body).slice(0, 200)}`
+    const limited = res.status === 429 || /local_rate_limited/i.test(msg)
+    if (!limited || attempt >= retries) throw new Error(msg)
+    const ms = wait[Math.min(attempt, wait.length - 1)]
+    console.error(`[daily-report] ⏳ 触发限流（429）⇒ ${Math.round(ms / 1000)}s 后重试（第 ${attempt + 1}/${retries} 次）：${short}`)
+    await sleep(ms)
+  }
+}
+
+/** 拉窗口内订单（分页 + 节流）。只读。 */
+export async function fetchOrders(token, sellerId, fromISO, toISO, opts = {}) {
+  const all = []
+  let offset = 0
+  for (;;) {
+    const p = new URLSearchParams({
+      seller: String(sellerId),
+      'order.date_created.from': fromISO,
+      'order.date_created.to': toISO,
+      limit: '50',
+      offset: String(offset),
+    })
+    const d = await apiGet(`/orders/search?${p}`, token, { base: opts.base })
+    all.push(...(d.results || []))
+    const total = (d.paging && d.paging.total) || all.length
+    if (all.length >= total || all.length >= 5000 || !(d.results || []).length) break
+    offset += 50
+    await sleep(Number(process.env.ML_PAGE_GAP_MS || 60))   // 翻页节流：降低被限流概率
+  }
+  return all
+}
+
+// ── OAuth token（刷新 + 轮换回写交给调用方）──────────────────
+async function apiToken(form, opts = {}) {
+  const base = resolveApiBase(opts.base)
+  const res = await fetch(`${base}/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(form).toString(),
+  })
+  const body = await res.json().catch(() => ({}))
+  if (!res.ok || !body.access_token) {
+    throw new Error(`token 刷新失败 HTTP ${res.status}: ${JSON.stringify(body).slice(0, 200)}`)
+  }
+  return body
+}
+
+/** access_token 剩余有效期（毫秒）；缺字段 ⇒ `null`（调用方按"需要刷新"处理）。 */
+export function tokenLeftMs(store, now = Date.now()) {
+  if (!store || !store.access_token || !store.access_expires_at) return null
+  const t = new Date(store.access_expires_at).getTime()
+  return Number.isFinite(t) ? t - now : null
+}
+
+/**
+ * token 复用 + 轮换刷新。
+ *
+ * ⚠️ **refresh_token 是轮换制**：刷新成功后**必须**把新的 refresh_token 原子写回凭据文件，
+ * 否则下次仍用已作废的旧 token 刷新 ⇒ 撞 429（2026-09-04/05 连续两日断供的根因）。
+ * 写回**不在本函数里**（本文件零写盘）：由调用方通过 `opts.onRotate(store)` 承担，且调用方
+ * 必须显式开启（日报 CLI 恒写回；对账 CLI 只在 `--allow-token-refresh` 分支才写回）。
+ */
+export async function refreshStoreToken(env, store, opts = {}) {
+  const appId = env.ML_APP_ID || process.env.ML_APP_ID
+  const appSecret = env.ML_APP_SECRET || process.env.ML_APP_SECRET
+  if (!appId || !appSecret) throw new Error('缺少 ML_APP_ID / ML_APP_SECRET（daily-report.env）')
+  // token 复用：access_token 剩余有效期 > 15min 直接用，不无谓刷新（grant 限流保护）
+  const left = tokenLeftMs(store)
+  if (left != null && left > 15 * 60 * 1000) return store.access_token
+  if (opts.allowRefresh === false) {
+    throw new Error(`access_token 不可用（剩余 ${left == null ? '未知' : Math.round(left / 1000) + 's'}）⇒ 未开启刷新`)
+  }
+  const tok = await apiToken({
+    grant_type: 'refresh_token',
+    client_id: appId,
+    client_secret: appSecret,
+    refresh_token: store.refresh_token,
+  }, { base: opts.base })
+  store.access_token = tok.access_token
+  store.access_expires_at = new Date(Date.now() + (tok.expires_in || 21600) * 1000).toISOString()
+  if (tok.refresh_token) store.refresh_token = tok.refresh_token
+  if (opts.onRotate) opts.onRotate(store)   // 轮换后的新 token 立即落盘（原子写），防旧 token 复用触发 429
+  return tok.access_token
+}
+
+// ── 卡片上的「数据截至 + 口径」两行（老快照优雅降级 ⇒ 返回空数组）──
+export const CALIBER_LINE = '**口径**：订单数＝订单笔数（不含取消/未付款）｜已售件数＝件数｜平台可事后变更历史订单状态 ⇒ 与平台概览可能相差个位数'
+
+/**
+ * 概览段追加的两行。**只有拿得到抓取时刻时才追加**（老快照/无字段 ⇒ 返回 `[]`，
+ * ⛔ 绝不打印 `undefined`、也绝不猜一个时刻）。
+ */
+export function captureNoteLines(r, tz) {
+  if (!r) return []
+  let local = r.capturedAtLocal || null
+  if (!local && r.capturedAt) local = localStamp(tz, new Date(r.capturedAt))
+  if (!local) return []
+  return [`**数据截至**：${local}（${tz}）`, CALIBER_LINE]
+}

package/engine/scripts/lib/dep-declaration.mjs

@@ -0,0 +1,81 @@
+/**
+ * 子包"漏声明"分类（**唯一真源**，纯函数，可离线测试）。
+ *
+ * 由来（2026-09-28 升级前审查）：`dsh-preflight.mjs` 的漏声明检测用**目录名**
+ * （`dsh-client-ui-sidebar`）去比**包名**（`@deepseek-ai/dsh-client-ui-sidebar`）⇒ 一个都匹配不上
+ * ⇒ 把 0.1.7-rc.2 的 **52 个 UI 子包全报成"未被主包声明"**。全是噪音的告警等于没有告警：
+ * 真正的孤儿（`dsh-client-ui-primitives` / `dsh-client-ui-slots`，前者正是 rc.8 断链事故的包名）
+ * 会被淹在 52 行里没人看。
+ *
+ * 正确分类（三级）：
+ *   declared    —— 被声明方（dsh / dsh-web-app / …）在 dependencies/peer/optional 里声明 ⇒ 正常；
+ *   transitive  —— 没被声明方声明，但**别的包依赖它** ⇒ 传递依赖，也正常（npm 会装、解析得到）；
+ *   orphan      —— 既没被声明、也没有任何包依赖 ⇒ **真可疑**（磁盘上有、没人引用），才值得告警。
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 读取一个 scope 目录（`.../node_modules/@deepseek-ai`）下所有包的 package.json。 */
+export function readScope(scopeDir) {
+  const out = new Map() // 包名 → package.json
+  if (!existsSync(scopeDir)) return out
+  for (const dir of readdirSync(scopeDir)) {
+    const pj = join(scopeDir, dir, 'package.json')
+    if (!existsSync(pj)) continue
+    try {
+      const j = JSON.parse(readFileSync(pj, 'utf8'))
+      if (j.name) out.set(j.name, j)
+    } catch { /* 坏 package.json 跳过 */ }
+  }
+  return out
+}
+
+/**
+ * 分类子包。
+ * @param {object} o
+ * @param {Map<string, object>} o.packages  readScope 的结果
+ * @param {string[]} [o.declarers] 声明方包名
+ * @param {(name: string) => boolean} [o.interest] 只关心哪些子包（默认全部）
+ * @returns {{ declared: string[], transitive: string[], orphan: string[], declaredBy: Map<string,string[]> }}
+ */
+export function classifySubpackages({ packages, declarers = ['@deepseek-ai/dsh', '@deepseek-ai/dsh-web-app'], interest = () => true }) {
+  const DEP_KEYS = ['dependencies', 'peerDependencies', 'optionalDependencies']
+  const declaredBy = new Map()
+  for (const d of declarers) {
+    const pkg = packages.get(d)
+    if (!pkg) continue
+    for (const key of DEP_KEYS) {
+      for (const dep of Object.keys(pkg[key] || {})) {
+        if (!declaredBy.has(dep)) declaredBy.set(dep, [])
+        declaredBy.get(dep).push(d)
+      }
+    }
+  }
+  // 谁依赖了谁（用于判"传递依赖"）
+  const dependedBy = new Map()
+  for (const [name, pkg] of packages) {
+    for (const key of DEP_KEYS) {
+      for (const dep of Object.keys(pkg[key] || {})) {
+        if (!dependedBy.has(dep)) dependedBy.set(dep, [])
+        dependedBy.get(dep).push(name)
+      }
+    }
+  }
+
+  const declared = []
+  const transitive = []
+  const orphan = []
+  for (const name of packages.keys()) {
+    if (!interest(name)) continue
+    if (declaredBy.has(name)) { declared.push(name); continue }
+    const users = (dependedBy.get(name) || []).filter((u) => u !== name)
+    if (users.length) transitive.push(name)
+    else orphan.push(name)
+  }
+  return {
+    declared: declared.sort(),
+    transitive: transitive.sort(),
+    orphan: orphan.sort(),
+    declaredBy,
+  }
+}