@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/daily-report-reconcile.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * daily-report-reconcile.mjs —— 「为什么和平台概览差几个数」的**只读**对账工具（2026-10-12）。
+ *
+ * ## 它回答什么
+ * 客户在平台概览看到「销售量 602」，卡片上写「订单数 595」⇒ 问"为什么有出入"。本工具用
+ * **与日报同一条**取数/聚合实现（`lib/daily-report-core.mjs`，⛔ 不复制第二份口径）把同一窗口
+ * 逐候选重算一遍，并排给出：
+ *   ① 我方口径（订单/件数/销售额/取消/客单价）；② 候选口径对照表（仅付款已批准 / 含发货信息 /
+ *   含取消（全部创建）/ 未付款数 / 唯一买家数 / 件数 …）；③ 窗口平移敏感度（±1h/±2h/±3h）；
+ *   ④ 与快照的漂移（【报告时 vs 现在】—— 「平台会事后改历史订单状态」的直接证据）；
+ *   ⑤ 给了 `--platform-kpi` ⇒ 命中哪个候选 / 「无候选命中 ⇒ 差异不是口径而是时点或平台未知口径」。
+ *
+ * ## 用法
+ *   node scripts/daily-report-reconcile.mjs --store <名或 uid> --date YYYY-MM-DD \
+ *        [--platform-kpi "订单数量=602,已售件数=640"] [--json] \
+ *        [--api-base <url>] [--env <path>] [--allow-token-refresh]
+ *   · `--date` **支持任意历史日**（窗口 = 该日在站点本地时区的自然日，与当天日报给客户的窗口一致）；
+ *   · `--platform-kpi` 也接受 JSON：`--platform-kpi '{"订单数量":602}'`；
+ *   · `--json` 只把结构化结果打到 stdout（日志一律 stderr）；`--help` 纯读即退。
+ *
+ * ## 退出码
+ *   0 = 有候选命中，或（没给 `--platform-kpi` 时）漂移对照已给出 ⇒ 差异有解释；
+ *   2 = **无候选命中**（给了 KPI 却谁都不等于它 ⇒ 差异是时点/平台未知口径，可判红，别硬掰口径）；
+ *   1 = 用法错/店铺匹配不到/取数失败；3 = 凭据不可用（未开启刷新）。
+ *
+ * ## 只读纪律（本文件的红线）
+ *   · ⛔ 不写任何客户表、⛔ 不写快照（读快照只为对照"报告时"）；
+ *   · token：优先用凭据文件里**仍有效**的 `access_token`（剩余 > 15min）；
+ *     确实需要 refresh 时**必须**把轮换后的 `refresh_token` **原子写回**（tmp + rename，
+ *     保持原文件权限）—— 否则下次日报会因旧 token 撞 429（2026-09-04/05 断供的根因）；
+ *     该写回**必须显式开开关**：`--allow-token-refresh`；默认只读失败退出并给下一步提示；
+ *   · 唯一会写盘的路径 = `persistStoreAtomic()`，且只在 `--allow-token-refresh` 分支被调用。
+ *
+ * ## API 基址从哪来（引擎侧不硬编码平台域名）
+ * `--api-base` → `ML_API_BASE` → **快照里记录的 `apiBase`**（抓取时刻的事实）→ 同店任一快照的
+ * `apiBase` → 报错。`vertical-lint` 的 engine-words 档只拦新增业务词且 ⛔ 不抬基线，所以
+ * 引擎面新文件里不能出现平台域名；快照带 `apiBase` 正好也是"数据来源可追溯"该有的样子。
+ */
+import { readFileSync, writeFileSync, renameSync, existsSync, statSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import {
+  SITE_TZ, SITE_CURRENCY, fallbackSite,
+  reportWindows, aggregateOrders, candidateMetrics, windowShiftSensitivity,
+  parsePlatformKpi, matchCandidates, localStamp, isoWithOffset,
+  loadEnvFile, matchStores, storeKey, tokenLeftMs, refreshStoreToken, fetchOrders,
+} from './lib/daily-report-core.mjs'
+
+const argv = process.argv.slice(2)
+const has = (f) => argv.includes(f)
+const valOf = (f) => {
+  const i = argv.indexOf(f)
+  return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : null
+}
+
+const USAGE = `日报口径只读对账（解释"为什么和平台差几个数"）
+
+用法:
+  node scripts/daily-report-reconcile.mjs --store <名或 uid> --date YYYY-MM-DD [选项]
+
+选项:
+  --store <名或 uid>      必填；名称子串或 uid 全等（与日报 --store 同一份匹配判据）
+  --date YYYY-MM-DD       必填；支持任意历史日（窗口 = 该日站点本地自然日）
+  --platform-kpi <spec>   "订单数量=602,已售件数=640" 或 JSON {"订单数量":602}
+  --json                  只输出结构化 JSON（stdout），日志走 stderr
+  --api-base <url>        API 基址（缺省取 ML_API_BASE，再取快照记录的 apiBase）
+  --env <path>            凭据 env 文件（缺省 <数据目录>/daily-report.env）
+  --allow-token-refresh   允许刷新 access_token，并**原子写回**轮换后的 refresh_token
+  --help                  打印本用法即退（纯读，不读凭据、不联网）
+
+退出码: 0 有命中/漂移已解释 ｜ 2 无候选命中 ｜ 1 用法或取数失败 ｜ 3 凭据不可用（未开启刷新）
+`
+
+if (has('-h') || has('--help')) {
+  console.log(USAGE.trimEnd())
+  process.exit(0)
+}
+
+function die(msg, code = 1) {
+  console.error(`✗ ${msg}`)
+  process.exit(code)
+}
+
+const STORE_ARG = valOf('--store')
+const DATE_ARG = valOf('--date')
+if (!STORE_ARG || !DATE_ARG) {
+  console.error(USAGE.trimEnd())
+  die('缺少 --store 或 --date（用法见上）', 1)
+}
+if (!/^\d{4}-\d{2}-\d{2}$/.test(DATE_ARG)) die(`--date 需要 YYYY-MM-DD（实得 ${DATE_ARG}）`, 1)
+
+const FLAG_JSON = has('--json')
+const FLAG_ALLOW_REFRESH = has('--allow-token-refresh')
+const ARG_API_BASE = valOf('--api-base')
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+const ENV_PATH = valOf('--env') || join(DATA_DIR, 'daily-report.env')
+const STORES_PATH = process.env.ML_API_STORES_JSON || join(DATA_DIR, 'ml-api-stores.json')
+const CACHE_DIR = join(DATA_DIR, 'daily-report-cache')
+const snapshotPath = (date, store) => join(CACHE_DIR, `${date}-${storeKey(store)}.json`)
+
+function readJson(path, label) {
+  try { return JSON.parse(readFileSync(path, 'utf8')) } catch (e) {
+    die(`读不到${label} ${path}：${e.message}`, 1)
+  }
+}
+
+// ── 只读：先定位店铺与快照 ────────────────────────────────
+if (!existsSync(STORES_PATH)) die(`未找到店铺授权文件 ${STORES_PATH}（先在该店跑一次初始化/授权）`, 1)
+const allStores = (readJson(STORES_PATH, '店铺授权文件').stores) || []
+const matched = matchStores(allStores, [STORE_ARG])
+if (matched.length !== 1) {
+  die(matched.length
+    ? `--store ${STORE_ARG} 匹配到 ${matched.length} 家（${matched.map((x) => x.name).join('、')}）⇒ 请再具体一点`
+    : `--store ${STORE_ARG} 没匹配到店铺｜可用：${allStores.map((x) => x.name).join(' / ') || '（无）'}`, 1)
+}
+const store = matched[0]
+const site = fallbackSite(store.site)
+const tz = SITE_TZ[site]
+
+const now = new Date()
+const reportDate = new Date(`${DATE_ARG}T12:00:00Z`)
+// 对账窗口 = 该日**站点本地自然日** [D 00:00, D+1 00:00) —— 与当天日报给客户的窗口逐字同一个
+// （日报的窗口是 [报告日 00:00, 今天 00:00)，而报告日 = 昨天 ⇒ 两者等价）。跨任意历史日都对。
+const W = reportWindows(store.site, reportDate, new Date(reportDate.getTime() + 86400000),
+  { salesWindowDays: (loadEnvFile(ENV_PATH).SALES_WINDOW_DAYS ?? process.env.SALES_WINDOW_DAYS) })
+const windows = { weekStartMs: W.weekStart, reportStartMs: W.reportStart, todayStartMs: W.todayStart }
+const env = { ...loadEnvFile(ENV_PATH), ...process.env }
+
+const snapshotFile = snapshotPath(DATE_ARG, store)
+const snapshot = existsSync(snapshotFile) ? readJson(snapshotFile, '日报快照') : null
+
+// ── API 基址：显式 → env → 快照记录 → 同店任一快照 → 报错 ──────────
+function apiBaseFromCache() {
+  try {
+    for (const f of readdirSync(CACHE_DIR)) {
+      if (!f.endsWith(`-${storeKey(store)}.json`)) continue
+      try {
+        const d = JSON.parse(readFileSync(join(CACHE_DIR, f), 'utf8'))
+        if (d && d.apiBase) return { base: d.apiBase, from: `同店快照 ${join(CACHE_DIR, f)}` }
+      } catch { /* 坏快照跳过 */ }
+    }
+  } catch { /* 缓存目录不存在 */ }
+  return null
+}
+function resolveBase() {
+  if (ARG_API_BASE) return { base: ARG_API_BASE, from: '--api-base' }
+  if (process.env.ML_API_BASE) return { base: process.env.ML_API_BASE, from: 'ML_API_BASE' }
+  if (snapshot && snapshot.apiBase) return { base: snapshot.apiBase, from: `快照 ${snapshotFile}` }
+  const c = apiBaseFromCache()
+  if (c) return c
+  return die('拿不到 API 基址：请给 --api-base 或设 ML_API_BASE，或让该店至少有一份带 apiBase 的日报快照', 1)
+}
+
+/**
+ * 唯一会写盘的路径：把轮换后的 token **原子写回**凭据文件（tmp + rename，保持原权限）。
+ * 只在 `--allow-token-refresh` 分支被调用（见下方 `collect()`）。
+ */
+function persistStoreAtomic(rotated) {
+  const doc = JSON.parse(readFileSync(STORES_PATH, 'utf8'))
+  const list = doc.stores || []
+  const i = list.findIndex((x) => String(x.user_id) === String(rotated.user_id))
+  if (i < 0) { console.error(`⚠️ 写回：授权文件里找不到 uid=${rotated.user_id}，跳过（未写盘）`); return null }
+  list[i] = {
+    ...list[i],
+    access_token: rotated.access_token,
+    access_expires_at: rotated.access_expires_at,
+    refresh_token: rotated.refresh_token,
+  }
+  const tmp = `${STORES_PATH}.tmp`
+  let mode = 0o600
+  try { mode = statSync(STORES_PATH).mode & 0o777 } catch { /* 兜底 600 */ }
+  writeFileSync(tmp, JSON.stringify({ stores: list }, null, 2) + '\n', { mode })
+  renameSync(tmp, STORES_PATH)
+  return tmp
+}
+
+// ── 取数（共用实现）────────────────────────────────────────
+async function collect() {
+  const { base, from } = resolveBase()
+  const left = tokenLeftMs(store)
+  const fresh = left != null && left > 15 * 60 * 1000
+  if (!fresh && !FLAG_ALLOW_REFRESH) {
+    die(`凭据不可用（access_token 剩余 ${left == null ? '未知' : Math.round(left / 1000) + 's'}，需 > 900s）`
+      + '\n  ⇒ 本工具**默认只读**：不刷新、不写凭据文件。'
+      + '\n  ⇒ 要么先跑一次日报（它会刷新并原子写回），要么显式 --allow-token-refresh（会原子写回轮换后的 refresh_token）。', 3)
+  }
+  const token = await refreshStoreToken(env, store, {
+    base, allowRefresh: FLAG_ALLOW_REFRESH, onRotate: persistStoreAtomic,
+  })
+  const orders = await fetchOrders(token, store.user_id,
+    new Date(windows.reportStartMs).toISOString(), new Date(windows.todayStartMs).toISOString(), { base })
+  return { orders, base, from, refreshed: !fresh }
+}
+
+// ── 输出 ───────────────────────────────────────────────────
+const num = (n) => (n == null ? '—' : Number(n).toLocaleString('en-US'))
+const money = (code, n) => (n == null ? '—' : `${code} ${Number(n).toLocaleString('en-US', { maximumFractionDigits: 2 })}`)
+/** 中文/ASCII 混排的定宽：中文按 2 列计（表格对齐用；对齐只为好读，不参与判据）。 */
+const widthOf = (s) => [...String(s)].reduce((a, c) => a + (/[\u4e00-\u9fff\uff00-\uffef]/.test(c) ? 2 : 1), 0)
+const padTo = (s, w) => s + ' '.repeat(Math.max(0, w - widthOf(s)))
+
+async function main() {
+  const { orders, base, from, refreshed } = await collect()
+  const m = candidateMetrics(orders, windows, { tz })
+  const shift = windowShiftSensitivity(orders, windows)
+  const kpis = parsePlatformKpi(valOf('--platform-kpi'))
+  const verdict = matchCandidates(m, kpis)
+  const code = kpis.length && verdict.misses.length ? 2 : 0
+
+  // ── 漂移：【报告时（快照） vs 现在】 ──────────────────────
+  const snap = snapshot && snapshot.summary
+    ? { orders: snapshot.summary.orders, units: snapshot.summary.units, cancelled: snapshot.summary.cancelled, gmv: snapshot.summary.gmv }
+    : null
+  const nowM = { orders: m.summary.orders, units: m.summary.units, cancelled: m.summary.cancelled, gmv: m.summary.gmv }
+  const drift = snap ? {
+    orders: { was: snap.orders, now: nowM.orders, delta: nowM.orders - snap.orders },
+    units: { was: snap.units, now: nowM.units, delta: nowM.units - snap.units },
+    cancelled: { was: snap.cancelled, now: nowM.cancelled, delta: nowM.cancelled - snap.cancelled },
+  } : null
+  const capturedLocal = (snapshot && (snapshot.capturedAtLocal
+    || (snapshot.capturedAt ? localStamp(tz, new Date(snapshot.capturedAt)) : null))) || null
+  const win = {
+    tz,
+    fromLocal: `${DATE_ARG} 00:00`,
+    toLocal: `${m.window.toLocal} 00:00`,
+    from: new Date(windows.reportStartMs).toISOString(),
+    to: new Date(windows.todayStartMs).toISOString(),
+  }
+
+  if (FLAG_JSON) {
+    console.log(JSON.stringify({
+      store: { name: store.name, site, user_id: String(store.user_id) },
+      date: DATE_ARG,
+      window: win,
+      capturedAt: snapshot ? (snapshot.capturedAt || null) : null,
+      capturedAtLocal: capturedLocal,
+      snapshotFile: snapshot ? snapshotFile : null,
+      apiBase: base,
+      apiBaseFrom: from,
+      tokenRefreshed: refreshed,
+      fetchedOrders: orders.length,
+      reportAt: snap,
+      now: nowM,
+      drift,
+      candidates: m.candidates,
+      values: m.values,
+      counts: m.counts,
+      shift,
+      platformKpi: kpis,
+      verdict,
+      exitCode: code,
+    }, null, 2))
+    process.exit(code)
+  }
+
+  const L = []
+  L.push(`📊 **日报口径对账** · ${store.name}（${site}）· ${DATE_ARG}`)
+  L.push(`抓取时刻（快照记录）：${capturedLocal ? `${capturedLocal}（${tz}）` : '未记录（老快照 ⇒ 回答不了"当时那一刻"，只能给"现在"）'}`)
+  L.push(`窗口：[${win.fromLocal} → ${win.toLocal}]（${tz}）｜UTC ${win.from} → ${win.to}`)
+  L.push(`本次取数：${isoWithOffset(tz, now)}（重拉 ${orders.length} 笔原始订单；API 基址来源：${from}${refreshed ? '；已刷新并原子写回凭据' : ''}）`)
+  L.push('')
+  L.push('【1】我方口径（同一窗口、站点本地自然日）')
+  L.push(`订单数 ${num(m.summary.orders)} ｜ 已售件数 ${num(m.summary.units)} ｜ 销售额 ${money(SITE_CURRENCY[site] || 'USD', m.summary.gmv)}`
+    + ` ｜ 取消 ${num(m.summary.cancelled)} ｜ 客单价 ${num(m.summary.avg != null ? Math.round(m.summary.avg) : null)}`)
+  L.push(`（窗口内原始订单 ${num(m.counts.window)} 笔 = 有效 ${num(m.counts.valid)} + 取消 ${num(m.counts.cancelled)} + 未付款 ${num(m.counts.paymentRequired)}）`)
+  L.push('')
+  L.push('【2】候选口径对照表（同一窗口，逐候选重算）')
+  const w0 = Math.max(...m.candidates.map((c) => widthOf(c.key))) + 2
+  for (const c of m.candidates) L.push(`  ${padTo(c.key, w0)}${num(c.value)}   ${c.desc}`)
+  L.push('')
+  L.push('【3】窗口平移敏感度（我方口径的订单数；看"边界时刻"能差多少）')
+  const shifts = [...shift.shifts.filter((s) => s.hours < 0), { hours: 0, orders: shift.base },
+    ...shift.shifts.filter((s) => s.hours > 0)]
+  L.push('  ' + shifts.map((s) => `${s.hours === 0 ? '基准' : (s.hours > 0 ? '+' : '') + s.hours + 'h'} ${num(s.orders)}`).join(' ｜ '))
+  L.push('')
+  L.push('【4】与快照的漂移（【报告时 vs 现在】—— 平台会**事后变更**历史订单状态的直接证据）')
+  if (!drift) {
+    L.push(`  无快照（${snapshotFile} 不存在）⇒ 只能给"现在"，无从对照"报告时"`)
+  } else {
+    for (const [k, label] of [['orders', '订单数'], ['units', '已售件数'], ['cancelled', '取消']]) {
+      const d = drift[k]
+      L.push(`  ${padTo(label, 10)}${num(d.was)} → ${num(d.now)}（${d.delta > 0 ? '+' : ''}${num(d.delta)}）`)
+    }
+    L.push('  ⚠️ 平台侧同一指标也在滚动更新 ⇒ **跨时点比较必然可能差个位数**（不是口径错，是快照时点不同）')
+  }
+  L.push('')
+  L.push('【5】平台 KPI 判定')
+  if (!kpis.length) {
+    L.push('  （未给 --platform-kpi ⇒ 只给上面的事实，不下判定）')
+  } else {
+    for (const h of verdict.hits) L.push(`  ${h.label} = ${num(h.value)} ⇒ ✅ 命中候选：${h.matched.join('、')}`)
+    for (const mi of verdict.misses) L.push(`  ${mi.label} = ${num(mi.value)} ⇒ ❌ 无候选命中（一个候选都不等于它）`)
+    L.push(verdict.misses.length
+      ? '  ⇒ **差异不是口径，而是时点（快照 vs 现在）或平台侧另有口径（平台概览标签未知）**'
+      : '  ⇒ 差异可由候选口径解释（见上命中项）')
+  }
+  L.push('')
+  L.push(`结论：${verdict.misses.length
+    ? '对不上不是"算错"，是**时点 / 平台口径**差异 —— 请与客户核对"同一时刻 + 同一标签"再比。'
+    : (drift ? '差异已解释（见【4】漂移与【5】命中项）。' : '已给出同一窗口的逐候选口径；未给平台 KPI ⇒ 不下判定。')}`)
+  console.log(L.join('\n'))
+  return code
+}
+
+if (isDirectRun(import.meta.url)) {
+  main().then((c) => process.exit(c)).catch((err) => {
+    // 采集失败（限流/网络/JSON）：只给错误摘要，⛔ 绝不 fallback 到推送，⛔ 不写任何文件
+    die(`取数失败：${err.message}`, 1)
+  })
+}