@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/ml-oauth-setup.mjs

@@ -0,0 +1,550 @@
+#!/usr/bin/env node
+/**
+ * ml-oauth-setup.mjs — 美客多官方 API OAuth 授权向导（Argent on DSH · 日报数据源）
+ *
+ * 一次性配置：把卖家的每个店铺账号授权给卖家自己的开发者应用，
+ * 生成 ~/.dsh/argent/ml-api-stores.json（每店 user_id + refresh_token + access_token）。
+ *
+ * 前置：
+ *   1. 卖家在 https://developers.mercadolibre.com 创建应用，拿到 App ID / Secret；
+ *   2. 把 ML_APP_ID / ML_APP_SECRET 写入 ~/.dsh/argent/daily-report.env
+ *      （模板由 init-ml.sh 生成，见 docs/daily-report.md）。
+ *
+ * 用法:
+ *   node ml-oauth-setup.mjs                    # 交互引导：逐店授权（推荐）
+ *   node ml-oauth-setup.mjs --redirect-uri <url>  # 覆盖回调地址（默认 https://example.com/callback）
+ *   node ml-oauth-setup.mjs --https            # 本地回环 https 回调（老场景/特殊站点；自签证书）
+ *   node ml-oauth-setup.mjs --list             # 列出已授权店铺
+ *   # 非交互（**异步授权**推荐：客户在飞书把回调 URL 发回来，一条命令落库）
+ *   node ml-oauth-setup.mjs --store 1店主账号 --site MLM --code '<回调URL或纯code>'
+ *     · 自动用 ml-store-ids.json 交叉校验授权账号是不是这家店（不符则**拒绝落库**）
+ *     · --expect-uid <id> 显式指定期望 uid；--force 跳过校验（危险）
+ *   node ml-oauth-setup.mjs --remove <名称>    # 移除店铺授权
+ *   node ml-oauth-setup.mjs --refresh-all      # 校验并刷新全部 access token
+ *   node ml-oauth-setup.mjs --env <路径>       # 指定 daily-report.env 路径
+ *
+ * 数据: ~/.dsh/argent/ml-api-stores.json（chmod 600，update 不覆盖）
+ * 说明: access_token 6 小时有效；daily-report.mjs 每次运行自动用 refresh_token
+ *       换新（refresh_token 轮换，回写本文件）。refresh_token 有效期约 6 个月，
+ *       过期后需重新授权（重跑本向导 --remove + 重新添加，或直接重跑交互流程）。
+ */
+
+import { createServer } from 'node:http'
+import { createServer as createHttpsServer } from 'node:https'
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import readline from 'node:readline'
+import { dirname } from 'node:path'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const API_BASE = process.env.ML_API_BASE || 'https://api.mercadolibre.com'
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+// 授权域名按站点取国家域名：CloudFront WAF（2026）对通用域名 auth.mercadolibre.com 拦截
+// redirect_uri 指向 127.0.0.1/localhost（SSRF 防护），而站点国家域名（如 .com.mx）放行 localhost。
+// 已实测：MLM 用 auth.mercadolibre.com.mx + https://localhost:8080/callback 通过（302）。
+// 其他站点域名实测被拦（403），后续逐个站点验证后更新此表。
+const AUTH_HOSTS = {
+  MLM: 'auth.mercadolibre.com.mx',
+  MLB: 'auth.mercadolibre.com.br',
+  MLA: 'auth.mercadolibre.com.ar',
+  MLC: 'auth.mercadolibre.cl',
+  MCO: 'auth.mercadolibre.com.co',
+  MPE: 'auth.mercadolibre.com.pe',
+  MLU: 'auth.mercadolibre.com.uy',
+}
+
+const SITE_CHOICES = [
+  ['MLM', '墨西哥'],
+  ['MLB', '巴西'],
+  ['MLA', '阿根廷'],
+  ['MLC', '智利'],
+  ['MCO', '哥伦比亚'],
+  ['MPE', '秘鲁'],
+  ['MLU', '乌拉圭'],
+]
+
+// ── 参数 ───────────────────────────────────────────────────
+const args = process.argv.slice(2)
+const argVal = (name) => {
+  const i = args.indexOf(name)
+  return i >= 0 && args[i + 1] ? args[i + 1] : null
+}
+// 数据目录：内核三级链（唯一判据；原为硬编码 ~/.dsh/argent）
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+const ENV_PATH = argVal('--env') || join(DATA_DIR, 'daily-report.env')
+const STORES_PATH = process.env.ML_API_STORES_JSON || join(DATA_DIR, 'ml-api-stores.json')
+// 回调端口：美客多对 redirect_uri 精确匹配 → 必须固定端口（默认 8080），
+// 卖家在开发者应用里注册 http(s)://127.0.0.1:8080/callback。--redirect-port 覆盖；--port 0 随机（仅测试）
+// TLS：美客多新门户强制 Redirect URI 以 https:// 开头（2026 起）→ --https 开启自签证书回调
+const REDIRECT_PORT = args.includes('--port') ? Number(argVal('--port')) : Number(argVal('--redirect-port') || 8080)
+const USE_TLS = args.includes('--https')
+const FLAG_LIST = args.includes('--list')
+const FLAG_REMOVE = args.includes('--remove')
+const FLAG_REFRESH = args.includes('--refresh-all')
+const FLAG_CODE = args.includes('--code')            // 非交互一键授权（值可为空 ⇒ 报错而不是掉进交互）
+
+// ── 小工具 ─────────────────────────────────────────────────
+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
+}
+
+function loadStores() {
+  if (!existsSync(STORES_PATH)) return { stores: [] }
+  try {
+    return JSON.parse(readFileSync(STORES_PATH, 'utf8'))
+  } catch (err) {
+    console.error(`⚠️  ml-api-stores.json 解析失败（${err.message}），按空表处理`)
+    return { stores: [] }
+  }
+}
+
+function saveStores(data) {
+  mkdirSync(DATA_DIR, { recursive: true })
+  writeFileSync(STORES_PATH, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
+  try { chmodSync(STORES_PATH, 0o600) } catch { /* 平台差异忽略 */ }
+}
+
+// 非交互 stdin（管道 /dev/null）下的健壮处理：
+//  - readableEnded 快速路径：EOF 已发生后新建 readline 接口收不到已过去的 close 事件，直接返回默认值
+//  - close 监听兜底：本次读取恰好遇到 EOF 时用默认值继续（EOF 时 question 回调可能永不触发）
+// ASK_EOF 供调用方在非交互下退出交互循环（如「继续授权?」默认 Y 会死循环）
+let ASK_EOF = false
+// 非 TTY（管道/重定向）下 readline 的语义坑：**没有待答 question 时到达的行直接丢弃**
+// ⇒ `printf '店名\n站点\n回调URL\n' | node …` 只会答上前一两问，粘贴那步拿到空、静默 `成功授权 0 家`。
+// 所以非 TTY 时先把 stdin 读成行队列，再按顺序分发（并把消费到的行回显到日志里，便于复盘）。
+let _piped = null
+async function loadPipedLines() {
+  if (_piped) return _piped
+  if (process.stdin.isTTY) { _piped = null; return null }
+  const chunks = []
+  for await (const c of process.stdin) chunks.push(c)
+  _piped = Buffer.concat(chunks).toString('utf8').split('\n').map((l) => l.replace(/\r$/, ''))
+  while (_piped.length && _piped[_piped.length - 1] === '') _piped.pop()
+  return _piped
+}
+// ⚠️ 必须**全程共用一个** readline 接口（2026-09-24 事故）：
+// 每次 ask() 新建接口时，Node 已经把 stdin 的一整块读进第一个接口的缓冲，
+// 接口一 close，缓冲里**后面几行就丢了** ⇒ 表现为「店铺名/站点答上了，粘贴回调 URL 那一步却是空」
+// ⇒ 静默 `成功授权 0 家店铺`（授权码还被白烧掉）。共享一个接口后，排队输入按顺序发给各个 prompt。
+let _rl = null
+function getRl() {
+  if (!_rl) {
+    _rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    _rl.on('close', () => { ASK_EOF = true })
+  }
+  return _rl
+}
+function ask(question, def = '') {
+  if (_piped) {                                   // 非 TTY：从行队列里取（确定性）
+    const prompt = def ? `${question} [${def}]: ` : `${question}: `
+    process.stdout.write(prompt)
+    if (!_piped.length) { ASK_EOF = true; process.stdout.write('\n'); return Promise.resolve(def) }
+    const line = _piped.shift()
+    process.stdout.write(`${line}\n`)
+    return Promise.resolve(line.trim() || def)
+  }
+  if (ASK_EOF || process.stdin.readableEnded) { ASK_EOF = true; return Promise.resolve(def) }
+  const rl = getRl()
+  return new Promise((resolve) => {
+    let answered = false
+    const onClose = () => done('', true)
+    const done = (ans, eof = false) => {
+      if (answered) return
+      answered = true
+      if (eof) ASK_EOF = true
+      rl.removeListener('close', onClose)
+      resolve(String(ans == null ? '' : ans).trim() || def)
+    }
+    rl.once('close', onClose)
+    rl.question(def ? `${question} [${def}]: ` : `${question}: `, (ans) => done(ans))
+  })
+}
+
+async function apiToken(form) {
+  const res = await fetch(`${API_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, 300)}`)
+  }
+  return body
+}
+
+async function apiGet(path, token) {
+  const res = await fetch(`${API_BASE}${path}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  })
+  const body = await res.json().catch(() => ({}))
+  if (!res.ok) throw new Error(`API ${path} 失败 HTTP ${res.status}: ${JSON.stringify(body).slice(0, 300)}`)
+  return body
+}
+
+async function exchangeCode(appId, appSecret, redirectUri, code) {
+  return apiToken({
+    grant_type: 'authorization_code',
+    client_id: appId,
+    client_secret: appSecret,
+    code,
+    redirect_uri: redirectUri,
+  })
+}
+
+async function refreshAccess(appId, appSecret, refreshToken) {
+  return apiToken({
+    grant_type: 'refresh_token',
+    client_id: appId,
+    client_secret: appSecret,
+    refresh_token: refreshToken,
+  })
+}
+
+// ── TLS 自签证书（--https 模式）────────────────────────────
+// 证书缓存在 ~/.dsh/argent/ml-oauth-cert/，不存在时用 openssl 生成（macOS/Linux 自带）
+function ensureTlsCert() {
+  const dir = join(DATA_DIR, 'ml-oauth-cert')
+  const keyPath = join(dir, 'key.pem')
+  const certPath = join(dir, 'cert.pem')
+  if (!existsSync(keyPath) || !existsSync(certPath)) {
+    mkdirSync(dir, { recursive: true })
+    execFileSync('openssl', [
+      'req', '-x509', '-newkey', 'rsa:2048',
+      '-keyout', keyPath, '-out', certPath,
+      '-days', '365', '-nodes',
+      '-subj', '/CN=localhost',
+      '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1',
+    ], { stdio: 'ignore' })
+  }
+  return { key: readFileSync(keyPath), cert: readFileSync(certPath) }
+}
+
+// ── 授权码解析（模块级：交互与非交互共用）──────────────────
+function extractCode(input) {
+  const t = String(input || '').trim()
+  if (!t) return ''
+  try {
+    const u = new URL(t)
+    // 是 URL：必须有 code，否则无效（避免把 example.com 这种地址当 code 发出去）
+    return u.searchParams.get('code') || ''
+  } catch { /* 不是 URL，当纯 code 值处理 */ }
+  return t
+}
+
+// ── 授权账号 ↔ 店铺 交叉校验（防串店）──────────────────────
+// ml-store-ids.json 是「店铺 → ML 卖家 user_id」的唯一真源（键 = 国家-店号）。
+// 从任意店铺名里取 `<N>店`，再按「墨西哥-<N>店」查表 —— 与发票链路同一口径。
+function expectedUidForStore(name) {
+  const m = String(name || '').match(/(\d+)店/)
+  if (!m) return null
+  const country = /巴西/.test(name) ? '巴西' : '墨西哥'
+  try {
+    const table = JSON.parse(readFileSync(join(SCRIPT_DIR, 'ml-store-ids.json'), 'utf8'))
+    const uid = (table.stores || {})[`${country}-${m[1]}店`]
+    return uid ? String(uid) : null
+  } catch { return null }
+}
+
+function verifyUid(name, uid, expectUidArg) {
+  const expected = expectUidArg ? String(expectUidArg) : expectedUidForStore(name)
+  if (!expected) return { ok: true, expected: null, why: '（表里没有这家店的期望 uid ⇒ 跳过校验）' }
+  if (String(uid) === expected) return { ok: true, expected, why: '与 ml-store-ids.json 一致' }
+  return { ok: false, expected, why: `授权账号 uid=${uid} ≠ 期望 ${expected}（**可能是子账号/别的店窗口**）` }
+}
+
+// ── 落库（交互与非交互共用；同 user_id 视为重复授权 ⇒ 覆盖）──
+function persistStore(name, site, tok, me) {
+  const stores = loadStores()
+  const idx = stores.stores.findIndex((s) => String(s.user_id) === String(tok.user_id))
+  const entry = {
+    name,
+    site,
+    user_id: tok.user_id,
+    nickname: (me && me.nickname) || '',
+    refresh_token: tok.refresh_token,
+    access_token: tok.access_token,
+    access_expires_at: new Date(Date.now() + (tok.expires_in || 21600) * 1000).toISOString(),
+    added_at: new Date().toISOString(),
+  }
+  if (idx >= 0) { stores.stores[idx] = entry; saveStores(stores); return { updated: true, entry } }
+  stores.stores.push(entry); saveStores(stores); return { updated: false, entry }
+}
+
+// ── 非交互一键授权（异步授权：客户把回调 URL 发回来 → 一条命令落库）──
+async function authorizeOnce() {
+  const env = loadEnvFile(ENV_PATH)
+  const appId = env.ML_APP_ID || process.env.ML_APP_ID
+  const appSecret = env.ML_APP_SECRET || process.env.ML_APP_SECRET
+  const name = argVal('--store')
+  const site = (argVal('--site') || 'MLM').toUpperCase()
+  const rawCode = argVal('--code')
+  const code = extractCode(rawCode)
+  if (!name) { console.error('✗ 非交互模式必须给 --store <店铺名>（如 --store 1店主账号）'); return 1 }
+  if (!appId || !appSecret) { console.error(`✗ 缺少应用凭据（${ENV_PATH} 里的 ML_APP_ID / ML_APP_SECRET）`); return 1 }
+  if (!code) {
+    console.error('✗ --code 为空或里面没有 code= 参数。请粘贴**整段回调 URL**（如 https://example.com/callback?code=TG-…）')
+    return 1
+  }
+  const redirectUri = argVal('--redirect-uri') || 'https://example.com/callback'
+  try {
+    const tok = await exchangeCode(appId, appSecret, redirectUri, code)
+    const me = await apiGet('/users/me', tok.access_token)
+    const chk = verifyUid(name, tok.user_id, argVal('--expect-uid'))
+    console.log(`  授权账号：${me.nickname || '（无昵称）'}  uid=${tok.user_id}  site=${me.site_id || site}`)
+    console.log(`  店铺校验：${chk.ok ? '✅' : '❌'} ${chk.why}`)
+    if (!chk.ok && !args.includes('--force')) {
+      console.error('✗ **拒绝落库**：授权账号与店铺不匹配（授权码已消耗，请在正确的店铺窗口重新授权）')
+      return 1
+    }
+    const r = persistStore(name, site, tok, me)
+    console.log(`✅ ${r.updated ? '已更新' : '已新增'}授权：${name}（${r.entry.nickname || r.entry.user_id}）→ ${STORES_PATH}`)
+    console.log(`   下一步：node scripts/daily-report.mjs --force（或等约次日推送）`)
+    return 0
+  } catch (err) {
+    console.error(`✗ 授权失败：${err.message}`)
+    console.error('  常见原因：授权码已过期/已被使用（约 10 分钟有效，且只能用一次）⇒ 让客户重新点一次链接，把新的回调 URL 发来')
+    return 1
+  }
+}
+
+// ── 交互授权（本地回调）────────────────────────────────────
+// 返回 { server, port, waitCode }：waitCode 是 Promise<code>（失败 reject）
+// port 固定（美客多 redirect_uri 精确匹配）；端口被占用时抛错提示换端口
+function startCallbackServer(port) {
+  return new Promise((resolve, reject) => {
+    const handler = (req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1')
+      if (url.pathname !== '/callback') {
+        res.writeHead(404); res.end(); return
+      }
+      const code = url.searchParams.get('code')
+      const error = url.searchParams.get('error')
+      const desc = url.searchParams.get('error_description') || ''
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      if (code) {
+        res.end('<html><body><h3>✅ 授权成功，可以关闭此页面了</h3></body></html>')
+        server.close()
+        waitResolve(code)
+      } else {
+        res.end(`<html><body><h3>❌ 授权失败：${error} ${desc}</h3></body></html>`)
+        server.close()
+        waitReject(new Error(`授权失败：${error} ${desc}`))
+      }
+    }
+    const server = USE_TLS ? createHttpsServer(ensureTlsCert(), handler) : createServer(handler)
+    server.on('error', (err) => {
+      reject(new Error(err.code === 'EADDRINUSE'
+        ? `回调端口 ${port} 被占用——换一个端口（--redirect-port <n>），并同步修改开发者应用里注册的 Redirect URI`
+        : `回调服务启动失败：${err.message}`))
+    })
+    let waitResolve, waitReject
+    const waitCode = new Promise((res, rej) => { waitResolve = res; waitReject = rej })
+    server.listen(port, '127.0.0.1', () => {
+      resolve({ server, port: server.address().port, waitCode })
+    })
+  })
+}
+
+async function addStoreInteractive(env) {
+  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) {
+    console.error('✗ 缺少 ML_APP_ID / ML_APP_SECRET（写入 daily-report.env 或环境变量）')
+    return false
+  }
+  const name = await ask('店铺名称（用于日报展示）', '墨西哥站')
+  console.log('可选站点：' + SITE_CHOICES.map(([c, n]) => `${c}=${n}`).join('  '))
+  const site = (await ask('站点代码', 'MLM')).toUpperCase()
+  if (!SITE_CHOICES.some(([c]) => c === site)) {
+    console.log(`⚠️  未知站点 ${site}，仍可继续（时区按站点代码匹配，未知则用 America/Mexico_City）`)
+  }
+
+  // Redirect URI：默认 https://example.com/callback（2026 新门户表单只认真实域名，
+  // localhost/127.0.0.1 均被拒；example.com 为 IANA 保留域名，可作占位回调地址）。
+  // 授权后浏览器跳到该地址（内容无关），从地址栏复制整段 URL 粘贴回来即可。
+  // 正式环境可换问述自有域名：--redirect-uri https://whyshu.com/ml-oauth-callback（需应用注册一致）
+  const redirectUri = argVal('--redirect-uri') || 'https://example.com/callback'
+  // 本地回环回调（老场景/特殊站点）：起本地回调服务器自动收 code
+  const isLocalCallback = /^(127\.0\.0\.1|localhost|\[::1\])/.test(new URL(redirectUri).hostname)
+  // 授权域名：站点国家域名（CloudFront WAF 对通用域名 + 本地回环 redirect_uri 拦 403）
+  const authBase = `https://${AUTH_HOSTS[site] || 'auth.mercadolibre.com'}/authorization`
+  console.log('\n步骤：')
+  console.log(`  0. 确认卖家开发者应用里注册的 Redirect URI 为：${redirectUri}`)
+  console.log('     （developers.mercadolibre.com → 应用 → Redirect URI；美客多要求与授权请求精确匹配）')
+  console.log(`  1. 打开下面链接（用【${name}】店铺的紫鸟浏览器打开，确保已登录该店账号）`)
+  console.log(`  2. 在授权页点击「Autorizar / 允许」`)
+  if (isLocalCallback) {
+    console.log('  3. 本机回调自动完成授权（约 5 分钟内）\n')
+    if (USE_TLS) {
+      console.log(`     ⚠️ 自签证书：浏览器首次访问 ${redirectUri} 会提示证书不受信任，`)
+      console.log('        点「高级/Avanzado → 继续前往/Continuar」即可（仅本地回环，一次性操作）')
+    }
+  } else {
+    console.log('  3. 授权后浏览器会跳到注册的回调地址（如 example.com，内容无关）')
+    console.log('  4. 复制地址栏整段 URL（含 code=…），粘贴回本终端，回车完成授权\n')
+  }
+
+  let server = null
+  let waitCode = null
+  if (isLocalCallback) {
+    ;({ server, waitCode } = await startCallbackServer(REDIRECT_PORT))
+  }
+  const authUrl = `${authBase}?response_type=code&client_id=${encodeURIComponent(appId)}&redirect_uri=${encodeURIComponent(redirectUri)}`
+  console.log(`  授权链接：\n  ${authUrl}\n`)
+
+  let code = null
+  if (isLocalCallback) {
+    try {
+      code = await Promise.race([
+        waitCode,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('等待授权超时（5 分钟）')), 300000)),
+      ])
+    } catch (err) {
+      console.log(`\n⚠️  ${err.message}`)
+      code = extractCode(await ask('请把浏览器地址栏里 code= 后面的值粘贴到这里（或留空取消）', ''))
+      if (!code) { server.close(); return false }
+    }
+  } else {
+    code = extractCode(await ask('授权完成后，请把浏览器地址栏整段 URL（含 code=…）粘贴到这里（或留空取消）', ''))
+    if (!code) return false
+  }
+
+  try {
+    const tok = await exchangeCode(appId, appSecret, redirectUri, code)
+    const me = await apiGet('/users/me', tok.access_token)
+    const chk = verifyUid(name, tok.user_id, argVal('--expect-uid'))
+    console.log(`  店铺校验：${chk.ok ? '✅' : '❌'} ${chk.why}`)
+    if (!chk.ok && !args.includes('--force')) {
+      console.error('✗ 拒绝落库：授权账号与店铺不匹配（请在正确的店铺窗口重新授权）')
+      return false
+    }
+    const r = persistStore(name, site, tok, me)
+    console.log(`✅ ${r.updated ? '已更新' : '已新增'}授权：${name}（${me.nickname || tok.user_id}）`)
+    return true
+  } catch (err) {
+    console.error(`✗ 授权失败：${err.message}`)
+    return false
+  }
+}
+
+// ── --list ─────────────────────────────────────────────────
+function listStores() {
+  const { stores } = loadStores()
+  if (!stores.length) {
+    console.log('（暂无已授权店铺 —— 运行 node ml-oauth-setup.mjs 开始授权）')
+    return
+  }
+  console.log(`已授权店铺（${stores.length}）：`)
+  for (const s of stores) {
+    const exp = s.access_expires_at ? new Date(s.access_expires_at).toISOString().slice(0, 16).replace('T', ' ') : '?'
+    console.log(`  · ${s.name}（${s.site}）user_id=${s.user_id} ${s.nickname ? '『' + s.nickname + '』' : ''} access 有效期至 ${exp}`)
+  }
+}
+
+// ── --remove ───────────────────────────────────────────────
+function removeStore(target) {
+  const stores = loadStores()
+  const before = stores.stores.length
+  stores.stores = stores.stores.filter((s) => s.name !== target && String(s.user_id) !== target)
+  if (stores.stores.length === before) {
+    console.log(`✗ 未找到店铺：${target}（可用 --list 查看）`)
+    return 1
+  }
+  saveStores(stores)
+  console.log(`✅ 已移除授权：${target}`)
+  return 0
+}
+
+// ── --refresh-all ──────────────────────────────────────────
+async function refreshAll(env) {
+  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) {
+    console.error('✗ 缺少 ML_APP_ID / ML_APP_SECRET')
+    return 1
+  }
+  const stores = loadStores()
+  if (!stores.stores.length) { console.log('（暂无已授权店铺）'); return 0 }
+  let fail = 0
+  for (const s of stores.stores) {
+    try {
+      const tok = await refreshAccess(appId, appSecret, s.refresh_token)
+      s.access_token = tok.access_token
+      s.access_expires_at = new Date(Date.now() + (tok.expires_in || 21600) * 1000).toISOString()
+      if (tok.refresh_token) s.refresh_token = tok.refresh_token
+      const me = await apiGet('/users/me', tok.access_token)
+      s.nickname = me.nickname || s.nickname
+      console.log(`✅ ${s.name}（${s.site}）token 已刷新（${me.nickname || s.user_id}）`)
+    } catch (err) {
+      fail++
+      console.error(`✗ ${s.name} 刷新失败：${err.message}`)
+    }
+  }
+  saveStores(stores)
+  console.log(fail ? `完成，${fail} 家店铺失败（refresh_token 可能已过期，请重新授权）` : '全部刷新成功')
+  return fail ? 1 : 0
+}
+
+// 导出给回归测试（纯函数：不联网、不写文件）
+export { extractCode, expectedUidForStore, verifyUid }
+
+// ── main ───────────────────────────────────────────────────
+async function main() {
+  const env = loadEnvFile(ENV_PATH)
+  await loadPipedLines()
+  if (FLAG_CODE) return authorizeOnce()
+  if (FLAG_LIST) { listStores(); return 0 }
+  if (FLAG_REMOVE) return removeStore(argVal('--remove'))
+  if (FLAG_REFRESH) return refreshAll(env)
+
+  console.log('╔══════════════════════════════════════════════╗')
+  console.log('║  美客多官方 API 授权向导（日报数据源）        ║')
+  console.log('╚══════════════════════════════════════════════╝')
+  console.log(`  应用凭据来源：${ENV_PATH}${existsSync(ENV_PATH) ? '' : '（文件不存在，请先运行 init-ml.sh 生成模板）'}`)
+  console.log(`  授权数据：${STORES_PATH}\n`)
+
+  if (!env.ML_APP_ID && !process.env.ML_APP_ID) {
+    console.log('✗ 未找到 ML_APP_ID —— 请先运行 init-ml.sh（日报设置段）生成 daily-report.env 并填入应用凭据')
+    return 1
+  }
+
+  // 展示已有授权
+  const existing = loadStores()
+  if (existing.stores.length) {
+    console.log('当前已授权店铺：')
+    existing.stores.forEach((s, i) => console.log(`  ${i + 1}. ${s.name}（${s.site}）user_id=${s.user_id}`))
+  }
+
+  console.log('\n开始逐店授权（每店：输入名称 → 用该店紫鸟浏览器打开链接 → 授权）\n')
+  let ok = 0
+  while (true) {
+    const done = await addStoreInteractive(env)
+    if (done) ok++
+    const more = await ask('继续授权下一家店铺? [Y/n] ')
+    if (ASK_EOF || (more.toLowerCase() !== 'y' && more !== '')) break
+  }
+  console.log(`\n完成：成功授权 ${ok} 家店铺。现在可以运行 node daily-report.mjs --force 测试推送。`)
+  return 0
+}
+
+// 仅直接执行时跑主流程（import 单测时不触发）
+const isMain = isDirectRun(import.meta.url)
+if (isMain) {
+  main().then((code) => process.exit(code)).catch((err) => {
+    console.error(`✗ 异常：${err.message}`)
+    process.exit(1)
+  })
+}

package/engine/scripts/ml-store-ids.json

@@ -0,0 +1,26 @@
+{
+  "_doc": "ML（美客多）店铺 → 卖家 user_id 的**唯一真源**（2026-09-19 用户亲口提供，运营口径）。",
+  "_why": [
+    "此前同一个概念散落三处、键格式还各不相同，结果鑫中航发票的 PO Number 静默退化成**紫鸟 store_id**（浏览器店铺 ID，不是 ML 卖家 ID），6 张发票写错都没人发现：",
+    "  ① scripts/wenyao-template-map.json#storeIds   键='1店'（文鳐用，值本来就对）",
+    "  ② ~/.dsh/argent/invoice-mapping.json#storeId 键='1店-子账号'（旧管线用，lip 改造后完整店铺名匹配不上 ⇒ 失效）",
+    "  ③ ~/.dsh/argent/lip-po-mapping.json          键=lip 完整店铺名（**该文件从未创建** ⇒ 回退到紫鸟 ID）",
+    "现统一到本文件：键一律用 **'<N>店'**（与 wenyao-template-map 同口径），解析时从任意店铺名（'墨西哥-2店-子账号' / '2店-主账号' / '墨西哥-6店'）里取 '<N>店'。"
+  ],
+  "_scope": [
+    "**主账号/子账号共用同一个 ML user_id**（2026-09-19 用户确认）⇒ 按『店』给一条即可，不要再按账号拆。",
+    "『4店』运营标注为**跨境店**（同一 ML ID）。"
+  ],
+  "_verifiedBy": "~/.dsh/argent/ml-api-stores.json 里 3店主账号 user_id=2216458475，与本表 3店 完全一致（官方 ML API 交叉验证）",
+  "_unknown": [
+    "巴西-1店：lip 表 5 行，运营未提供 ML ID ⇒ 解析必须返回空串（响亮失败），绝不许回退成紫鸟 ID 或串到墨西哥的 ID。"
+  ],
+  "stores": {
+    "墨西哥-1店": "2443747608",
+    "墨西哥-2店": "2475636269",
+    "墨西哥-3店": "2216458475",
+    "墨西哥-4店": "3126660693",
+    "墨西哥-6店": "3354492092"
+  },
+  "_keyNote": "键 = **国家-店号**（'墨西哥-2店'）而不是裸 '2店'：2026-09-19 自测发现裸键会让 '**巴西**-1店' 命中 '1店' 并返回**墨西哥**-1店的 ID —— 与本次要修的 bug 同类（跨国家静默串号）。lip 表里确有 5 行『巴西-1店』，且运营尚未提供其 ML ID ⇒ 必须解析失败、不得猜。"
+}