cardbuddy 0.9.1 → 0.11.0

package/dist/vendored/skills/finmall-card-sync/scripts/api_batch_sync.mjs

@@ -0,0 +1,900 @@
+import { mkdir, stat, writeFile, readFile, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { finmallConfig } from '../../shared/finmall-config.mjs';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const skillDir = path.resolve(scriptDir, '..');
+// skill now lives under <repo-root>/skills/<name>: repo root is two levels up from skillDir
+const workspace = path.resolve(skillDir, '..', '..');
+// 与 finmall_login.mjs 保持一致的解析方式：用裸标识符让 Node 从项目根 node_modules 解析
+// playwright。原硬编码路径指向 .workbuddy/skills/finmall-session-navigator/scripts/node_modules
+// （该 node_modules 是已失效的断链符号链接），导致「Cannot find module」报错。
+const { chromium } = await import('playwright');
+
+// 统一日志美化（容错：缺 server/core/logger 时回退极简实现，保证 demo / 老项目不崩）。
+// 实时项目与 build 后的 dist/server-core 均含该模块；demo 等缺少 server/ 目录的场景走 fallback。
+let log;
+try {
+  ({ log } = await import('../../../server/core/logger.js'));
+} catch {
+  const w = (m, ...a) => console.log(`[card] ${m}`, ...a);
+  log = {
+    info: w,
+    ok: w,
+    warn: (m, ...a) => console.warn(`[card] ${m}`, ...a),
+    error: (m, ...a) => console.error(`[card] ${m}`, ...a),
+    box: () => {},
+    rule: () => {},
+  };
+}
+
+// 后台会话管理：点击预览「同步远程数据」时自动拉起/复用无界面 Chrome 并登录，
+// 无需手动运行 finmall-session-navigator。
+import { ensureFinMallSession } from "../../finmall-session-navigator/scripts/session-manager.mjs";
+import {
+  performLogin,
+  clearTimeoutPrompts,
+  waitForAuthenticatedPage,
+  loadCredentials,
+} from "../../finmall-session-navigator/scripts/finmall_login.mjs";
+
+// 代理处理：本机设了 HTTP_PROXY，但 Chrome 远程调试端口在 127.0.0.1，需把
+// localhost 排除在代理外，否则 connectOverCDP 会经代理拿到 502 / ECONNREFUSED。
+// 仅影响 Node 侧 CDP 连接；浏览器内访问 finmall.com 仍走代理。
+for (const key of ["NO_PROXY", "no_proxy"]) {
+  const cur = process.env[key];
+  const extra = "127.0.0.1,localhost";
+  process.env[key] = cur && cur.length ? `${cur},${extra}` : extra;
+}
+
+// 卡片列表缓存（推送前存在性校验用）：与 server 共享同一 dev server 进程内单例。
+// 仅在 5180 经中间件触发同步时本进程即 server 进程，缓存写入/读取天然一致；
+// 独立 CLI 运行时不写 server 缓存（无推送发生在该进程），故惰性加载、失败静默降级。
+let _cardListCache = null;
+async function getCardListCache() {
+  if (_cardListCache) return _cardListCache;
+  try {
+    const cachePath = path.resolve(workspace, 'server', 'core', 'cardListCache.js');
+    _cardListCache = await import(pathToFileURL(cachePath).href);
+  } catch (e) {
+    _cardListCache = null;
+    log.warn('卡片列表缓存模块加载失败（存在性校验将跳过）', { error: e && e.message });
+  }
+  return _cardListCache;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// 预览图下载超时闸门。实测：Filestore 对不存在的对象（典型如空白卡的 picUrl）不会返回
+// 404，而是直接挂起不响应；page.evaluate 本身没有默认超时，裸 fetch 会把整次同步永久拖死。
+// 内部用 AbortController 掐断请求，外部再包一层 Promise.race 兜住 evaluate 自身不返回的情况。
+const COVER_FETCH_TIMEOUT_MS = Number(process.env.CARDBUDDY_COVER_TIMEOUT_MS || 15000);
+// FinMall 交易请求超时。IDC10001/IDC10012 偶发挂起（后端不响应），同样没有任何默认超时，
+// 一张卡挂住就会拖垮整批同步——所以和预览图一样，内层 abort + 外层 race 双重设防。
+const FINMALL_POST_TIMEOUT_MS = Number(process.env.CARDBUDDY_POST_TIMEOUT_MS || 30000);
+
+function withTimeout(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label}超时（>${ms}ms），已放弃`)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+// 服务端判定会话/权限失效并应「重新进入」的特征集合。命中后由 finmallPostWithHeal
+// 自动清 session 重登再试一次——覆盖会话超时（BLEC0006）、token 失效，以及
+// 本次遇到的「您当前角色菜单权限发生变化，请重新进入」这类权限态异常。
+const SESSION_INVALID_RE = /BLEC0006|会话超时|会话过期|登录超时|未登录|登录失效|登录已失效|请重新登录|invalid token|token|角色菜单权限发生变化|权限发生变化|重新进入|请重新进入/i;
+
+/**
+ * 带自愈的 FinMall 接口调用：正常请求，若命中会话/权限失效特征则清 session 重登后重试一次。
+ * 列表（IDC10001）与 schema（IDC10012）共用，确保任意一步出现权限态异常都能自动恢复。
+ */
+async function finmallPostWithHeal(page, urlPath, requestBody, transCode = urlPath) {
+  try {
+    return await finmallPost(page, urlPath, requestBody, transCode);
+  } catch (error) {
+    if (SESSION_INVALID_RE.test(error.message)) {
+      log.warn('会话/权限失效，自动重新登录后重试', { url: urlPath, reason: error.message.slice(0, 40) });
+      await relogin(page);
+      return await finmallPost(page, urlPath, requestBody, transCode);
+    }
+    throw error;
+  }
+}
+
+/**
+ * 从已认证的 FinMall 浏览器会话同步卡片到 src/cards。
+ * 既可由 CLI 直接运行（api_batch_sync.mjs），也可被 Vite 中间件 import 后供预览「同步远程数据」按钮调用。
+ *
+ * 会话由 ensureFinMallSession 自动保证：若后台无界面 Chrome（专用端口）未启动或会话缺失，
+ * 会自动拉起并登录；完成后只 disconnect 不关闭进程，便于复用。
+ * 若服务端会话/权限失效（IDC10012 返回 BLEC0006 或「角色菜单权限发生变化」等），
+ * finmallPostWithHeal 会自动清 session 重登再重试。
+ *
+ * @param {object} opts
+ * @param {string} [opts.cardCode]     仅同步该英文卡 id（用列表接口 searchValue 定位）
+ * @param {number} [opts.startPage=1]
+ * @param {number} [opts.startIndex=0]
+ * @param {number} [opts.pageSize=24]
+ * @param {number} [opts.maxCards]     最多同步张数（不传=全部）
+ * @param {string} [opts.appId]
+ * @param {string} [opts.workspaceId]
+ * @param {string} [opts.cdpUrl]       已废弃：会话现在由 ensureFinMallSession 在专用后台端口自动管理
+ * @param {string} [opts.outRoot]      输出根目录（默认 workspace/src/cards）
+ * @returns {Promise<{success:boolean, synced:Array, failed:Array, duplicates:Array}>}
+ */
+export async function syncCards(opts = {}) {
+  const outRoot = path.resolve(opts.outRoot || path.join(workspace, 'src', 'cards'));
+  const startPage = Number(opts.startPage || 1);
+  const startIndex = Number(opts.startIndex || 0);
+  const pageSize = Number(opts.pageSize || 24);
+  const maxCards = opts.maxCards != null ? Number(opts.maxCards) : Infinity;
+  const appId = opts.appId || finmallConfig.appId;
+  const workspaceId = opts.workspaceId || finmallConfig.workspaceId;
+  // 单卡筛选：传 cardCode 时仅同步该卡
+  const cardCodeFilter = opts.cardCode || '';
+
+  // 自动确保后台 FinMall 会话：未启动/缺失则拉起无界面 Chrome 并登录，无需手动触发。
+  const session = await ensureFinMallSession();
+  const browser = session.browser;
+  const summary = { success: true, synced: [], failed: [], duplicates: [] };
+  // 重复 schema 检测：记录每张卡 schema 的 MD5，若不同 code 命中相同 schema 说明抓取仍串卡。
+  const schemaHashes = new Map();
+
+  try {
+    const context = browser.contexts()[0];
+    const page = context?.pages().find((p) => p.url().includes('finmall.com')) || context?.pages()[0];
+    if (!page) throw new Error('未能在后台 Chrome 中找到 FinMall 页面，请检查凭据或重新触发同步。');
+    await page.bringToFront();
+
+    const firstList = await fetchCardList(page, { pageNo: startPage, pageSize, appId, workspaceId, searchValue: cardCodeFilter });
+    const totalPages = Number(firstList.totalPages || Math.ceil(Number(firstList.totalNums || 0) / pageSize) || startPage);
+
+  let done = false;
+  const allCards = [];
+  for (let pageNo = startPage; pageNo <= totalPages && !done; pageNo++) {
+    const list = pageNo === startPage ? firstList : await fetchCardList(page, { pageNo, pageSize, appId, workspaceId, searchValue: cardCodeFilter });
+    const cards = list.cardList || [];
+    for (const c of cards) allCards.push(c);
+    const begin = pageNo === startPage ? startIndex : 0;
+      for (let index = begin; index < cards.length && !done; index++) {
+        if (summary.synced.length + summary.failed.length >= maxCards) break;
+        // normalizeCard 会对非法 code 抛错；单条异常不应中断整批同步。
+        let card;
+        try {
+          card = normalizeCard(cards[index]);
+        } catch (error) {
+          summary.success = false;
+          summary.failed.push({ page: pageNo, index, id: cards[index]?.code || '(unknown)', title: cards[index]?.cardName || '', error: error.message });
+          log.error('抓取失败', { page: pageNo, index, id: cards[index]?.code || '(unknown)', error: error.message });
+          continue;
+        }
+        if (cardCodeFilter && card.id !== cardCodeFilter) continue;
+        log.info('同步中', { page: `${pageNo}/${totalPages}`, index, id: card.id, title: card.title });
+        try {
+          const files = await syncCard(page, card, { outRoot, appId, workspaceId, summary, schemaHashes });
+          // 空白卡不算失败，但要在结果里显式标记，避免与「抓到完整 schema」混为一谈。
+          summary.synced.push({
+            page: pageNo, index, id: card.id, title: card.title, files,
+            blank: !!files.blank,
+            keptLocal: !!files.keptLocal,
+          });
+        } catch (error) {
+          summary.success = false;
+          summary.failed.push({ page: pageNo, index, id: card.id, title: card.title, error: error.message });
+          log.error('同步失败', { id: card.id, title: card.title, error: error.message });
+        }
+        if (cardCodeFilter) done = true;
+      }
+      if (summary.synced.length + summary.failed.length >= maxCards) break;
+    }
+    // 全量同步（无 cardCode 过滤）时整体刷新卡片列表缓存，供推送前「存在性闸门」使用；
+    // 单卡同步只增量合并，不整体替换，避免清空其余卡片。缓存未就绪则跳过（不影响同步）。
+    try {
+      const cache = await getCardListCache();
+      if (cache) cache.refreshCardList(allCards, { full: !cardCodeFilter });
+    } catch (e) {
+      log.warn('刷新卡片列表缓存失败（不影响同步）', { error: e && e.message });
+    }
+  } finally {
+    // 仅断开连接，不关闭用户自己启动的 Chrome（connectOverCDP 连的是外部浏览器）
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+  return summary;
+}
+
+/**
+ * 把一张卡片的最新 schema 写回 FinMall（线上编辑器「保存」接口 IDC10010.do）。
+ * 与 syncCards 共用同一套已登录浏览器会话与带自愈的 finmallPost，
+ * 确保任意一步会话/权限失效都能自动重登重试。
+ *
+ * 入参 schema 即本地 src/cards/<id>/schema.json 的完整内容（含 pageId / dictionary / view …）。
+ * 关键映射（来自线上编辑器抓包）：
+ *   - body.cardId   = 数字型 schema.pageId（非英文 code）
+ *   - body.schemaValue = 整张 schema 的 JSON 字符串（非对象）
+ *   - body.skeletonScreen = 骨架屏 SVG（仅用于编辑器列表缩略图，可传空串）
+ *
+ * 保存成功后默认立刻读回（IDC10012.do）做落库校验——FinMall 网关有
+ * 「errorCode=0 但 body 空/未落库」的静默空返回先例，不校验无法判断真实生效。
+ *
+ * @param {object} schema  完整卡片 schema（含 pageId）
+ * @param {{ skeletonScreen?: string, verify?: boolean }} [opts]
+ * @returns {Promise<{ response: object, verified: object }>}
+ *   verified = { ok, cardIdMatched, fingerprintMatched, diff, readBackError }
+ */
+export async function saveCardToRemote(schema, { skeletonScreen = '', verify = true } = {}) {
+  if (!schema || !schema.pageId) {
+    throw new Error('schema 缺少 pageId，无法确定要保存的卡片（IDC10010.do 需要数字型 cardId）。')
+  }
+  const appId = finmallConfig.appId
+  const workspaceId = finmallConfig.workspaceId
+  const session = await ensureFinMallSession()
+  const browser = session.browser
+  try {
+    const context = browser.contexts()[0]
+    const page = context?.pages().find((p) => p.url().includes('finmall.com')) || context?.pages()[0]
+    if (!page) throw new Error('未能在后台 Chrome 中找到 FinMall 页面，请检查凭据或重新触发同步。')
+    await page.bringToFront()
+
+    // 保护远端列表缩略图：本地未提供骨架屏时，先读回远端已有的 skeletonScreen 复用，
+    // 避免把缩略图刷成空白（仅影响列表显示，不影响卡片内容）。
+    let sk = skeletonScreen && String(skeletonScreen).trim() ? skeletonScreen : ''
+    if (!sk) {
+      try {
+        const pre = await finmallPostWithHeal(page, '/ubomp-web/IDC10012.do', {
+          cardId: String(schema.pageId),
+          sassAppId: appId,
+          sassWorkspaceId: workspaceId,
+        }, 'IDC10012.do')
+        if (pre && pre.skeletonScreen && String(pre.skeletonScreen).trim()) sk = pre.skeletonScreen
+      } catch { /* 读不到就退化成最小合法 SVG */ }
+    }
+    if (!sk) sk = '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="400"></svg>'
+
+    // finmallPost 会把 requestBody 放进 payload.body，并自己生成 payload.header；
+    // 因此这里只传「内层 body」（与读接口 fetchCardSchema 保持一致），切勿再包一层 {header, body}。
+    // 关键：IDC10010.do 需要 sassAppId/sassWorkspaceId（与读接口一致），缺失会返回 PEO000003。
+    const innerBody = {
+      cardId: String(schema.pageId),
+      skeletonScreen: sk,
+      schemaValue: JSON.stringify(schema),
+      sassAppId: appId,
+      sassWorkspaceId: workspaceId,
+    }
+    const urlPath = `/ubomp-web/IDC10010.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`
+    log.info('保存卡片', { pageId: schema.pageId, name: schema.name || '' })
+    const response = await finmallPostWithHeal(page, urlPath, innerBody, 'IDC10010.do')
+
+    // 落库校验：保存后立刻读回，确认内容真的写进去了（而非静默空返回）。
+    const verified = { ok: false, cardIdMatched: false, fingerprintMatched: false, diff: null, readBackError: null }
+    if (verify) {
+      try {
+        const readBody = await finmallPostWithHeal(page, '/ubomp-web/IDC10012.do', {
+          cardId: String(schema.pageId),
+          sassAppId: appId,
+          sassWorkspaceId: workspaceId,
+        }, 'IDC10012.do')
+        verified.cardIdMatched = String(readBody.cardId) === String(schema.pageId)
+        const remoteSchema = readBody.schemaValue ? JSON.parse(readBody.schemaValue) : null
+        if (!remoteSchema) {
+          verified.readBackError = '远端读回无 schemaValue（疑似静默空返回）'
+        } else {
+          const localFp = createHash('md5').update(stableStringify(schema)).digest('hex')
+          const remoteFp = createHash('md5').update(stableStringify(remoteSchema)).digest('hex')
+          verified.fingerprintMatched = localFp === remoteFp
+          if (!verified.fingerprintMatched) verified.diff = schemaDiff(schema, remoteSchema)
+        }
+        verified.ok = verified.cardIdMatched && verified.fingerprintMatched
+      } catch (e) {
+        verified.readBackError = String(e && e.message)
+        verified.ok = false
+      }
+    }
+    return { response, verified }
+  } finally {
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+
+/**
+ * 远端预览：复刻 ubomp-h5-sub PreviewPopover.vue 的 onPopoverShow 全链路。
+ *  1) prepreview：先把当前编辑的卡片保存到远端（IDC10010.do，对齐 ubomp 的 prepreview 钩子）
+ *  2) queryCardDetail：读卡片详情取 code（IDC10015.do）
+ *  3) submitForm：发布预览测试版（IDC10020.do）
+ *  4) doNotify：消息通知已连接的真机（IDC10021.do）
+ * 前端据返回的 cardCode 生成 scheme 二维码：
+ *   app://previewCard?cardId=<id>&cardCode=<code>&cardVersion=00000000&socket=<wss>
+ *
+ * 会话由 ensureFinMallSession 自动保证；与「保存到远端」共用同一套已登录后台 Chrome。
+ * 注意：saveCardToRemote 内部会自行 ensure+disconnect，故本函数先调用它（自带会话），
+ * 之后再重新 ensure 一次拿干净会话处理后续三个接口，避免复用已被 disconnect 的 page。
+ *
+ * @param {object} schema  当前卡片 schema（需含 pageId）
+ * @param {{skeletonScreen?:string, publish?:boolean, notify?:boolean}} [opts]
+ * @returns {Promise<{cardCode:string, version:string, steps:object}>}
+ */
+export async function previewCardRemote(schema, { skeletonScreen = '', publish = true, notify = true } = {}) {
+  if (!schema || !schema.pageId) {
+    throw new Error('schema 缺少 pageId，无法确定要预览的卡片（IDC10020.do 需要 cardId）。')
+  }
+  const appId = finmallConfig.appId
+  const workspaceId = finmallConfig.workspaceId
+  const cardId = String(schema.pageId)
+  const result = { cardCode: '', version: '00000000', steps: {} }
+
+  // 1) 先保存当前卡片（对齐 ubomp 的 prepreview 钩子：预览前先把编辑器内容落库）。
+  //    saveCardToRemote 自行管理会话、末尾 disconnect，失败不阻断后续预览流程。
+  try {
+    await saveCardToRemote(schema, { skeletonScreen, verify: false })
+    result.steps.saved = true
+  } catch (e) {
+    result.steps.saved = false
+    result.savedError = String(e && e.message)
+  }
+
+  // 后续三个接口使用一次干净的会话
+  const session = await ensureFinMallSession()
+  const browser = session.browser
+  try {
+    const context = browser.contexts()[0]
+    const page = context?.pages().find((p) => p.url().includes('finmall.com')) || context?.pages()[0]
+    if (!page) throw new Error('未能在后台 Chrome 中找到 FinMall 页面，请先运行 finmall-session-navigator 登录。')
+    await page.bringToFront()
+
+    // 2) 取卡片 code（对齐 ubomp queryCardDetail → IDC10015.do 的 code 字段）
+    try {
+      const detail = await finmallPostWithHeal(
+        page,
+        `/ubomp-web/IDC10015.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+        { cardId, sassAppId: appId, sassWorkspaceId: workspaceId },
+        'IDC10015.do'
+      )
+      result.cardCode = (detail && detail.code) || ''
+    } catch (e) {
+      result.codeError = String(e && e.message)
+    }
+
+    // 3) 发布预览测试版（对齐 ubomp submitForm → IDC10020.do）
+    if (publish) {
+      try {
+        await finmallPostWithHeal(
+          page,
+          `/ubomp-web/IDC10020.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+          {
+            cardId,
+            version: '00000000',
+            platformStatus: JSON.stringify(['iOS', 'Android', 'HarmonyOS']),
+            sassAppId: appId,
+            sassWorkspaceId: workspaceId,
+          },
+          'IDC10020.do'
+        )
+        result.steps.published = true
+      } catch (e) {
+        result.steps.published = false
+        result.publishError = String(e && e.message)
+      }
+    }
+
+    // 4) 消息通知（对齐 ubomp doNotify → IDC10021.do）
+    if (notify) {
+      try {
+        await finmallPostWithHeal(
+          page,
+          `/ubomp-web/IDC10021.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+          { agentId: cardId, sassAppId: appId, sassWorkspaceId: workspaceId },
+          'IDC10021.do'
+        )
+        result.steps.notified = true
+      } catch (e) {
+        result.steps.notified = false
+        result.notifyError = String(e && e.message)
+      }
+    }
+
+    return result
+  } finally {
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+
+// —— 保存落库校验辅助 ——
+
+/** 稳定序列化：对象键排序、带 id/key/className/name 的数组元素按该键排序，避免服务端字段重排导致指纹误判。 */
+function stableStringify(v) {
+  if (Array.isArray(v)) {
+    const arr = v.map(stableStringify)
+    if (v.length && v[0] && typeof v[0] === 'object') {
+      const keyOf = (o) => (o.id != null ? o.id : o.key != null ? o.key : o.className != null ? o.className : o.name != null ? o.name : null)
+      if (keyOf(v[0]) != null) arr.sort()
+    }
+    return '[' + arr.join(',') + ']'
+  }
+  if (v && typeof v === 'object') {
+    const keys = Object.keys(v).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(v[k])).join(',') + '}'
+  }
+  return JSON.stringify(v)
+}
+
+/** 把本地 schema 与远端读回的 schema 做关键字段 diff（顶层标量 + inputParams.defaultValue + view 指纹）。 */
+function schemaDiff(local, remote) {
+  const out = []
+  for (const k of ['version', 'pageId', 'name', 'desc', 'platform']) {
+    if (String(local[k] ?? '') !== String(remote[k] ?? '')) {
+      out.push(`顶层.${k}: 本地=${JSON.stringify(local[k])} 远端=${JSON.stringify(remote[k])}`)
+    }
+  }
+  const lp = (local.dictionary && local.dictionary.inputParams) || []
+  const rp = (remote.dictionary && remote.dictionary.inputParams) || []
+  const rmap = {}
+  for (const p of rp) rmap[p.key || p.name] = p
+  for (const p of lp) {
+    const key = p.key || p.name
+    const r = rmap[key]
+    if (!r) { out.push(`inputParams 远端缺失项: ${key}`); continue }
+    if (String(p.defaultValue ?? '') !== String(r.defaultValue ?? '')) {
+      out.push(`inputParams[${key}].defaultValue: 本地=${JSON.stringify(p.defaultValue)} 远端=${JSON.stringify(r.defaultValue)}`)
+    }
+  }
+  const lv = createHash('md5').update(stableStringify(local.view)).digest('hex')
+  const rv = createHash('md5').update(stableStringify(remote.view)).digest('hex')
+  if (lv !== rv) out.push('view 结构不一致（指纹不同）')
+  return out
+}
+
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) continue;
+    const eq = arg.indexOf('=');
+    if (eq >= 0) parsed[arg.slice(2, eq)] = arg.slice(eq + 1);
+    else parsed[arg.slice(2)] = argv[i + 1]?.startsWith('--') ? true : argv[++i] ?? true;
+  }
+  return parsed;
+}
+
+async function fetchCardList(page, { pageNo, pageSize, appId, workspaceId, searchValue = '' }) {
+  const body = await finmallPostWithHeal(page, `/ubomp-web/IDC10001.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`, {
+    channel: '',
+    applyScene: '1',
+    pageNo,
+    pageSize,
+    searchValue,
+    cardClassId: '',
+    sassAppId: appId,
+    sassWorkspaceId: workspaceId,
+  });
+  return body;
+}
+
+/**
+ * 拉取远端 schema。返回 `null` 表示「空白卡」——该卡片在 FinMall 侧从未保存过
+ * schema（新建后未编辑），IDC10012.do 会返回 errorCode=0 但 body 无 schemaValue。
+ * 这是合法状态而非主键错误，调用方须走「空白卡落盘」分支，不要当成同步失败。
+ */
+async function fetchCardSchema(page, card, { appId, workspaceId }) {
+  // IDC10012.do 只接受数字型 `cardId` 作为主键（实测：传 cardCode 会返回
+  // errorCode=0「交易成功」，但 body 里根本没有 schemaValue —— 是静默空返回，
+  // 极易被误判成抓取成功）。cardId 由 IDC10001.do 列表逐条给出，页面卡与其
+  // dialog 变体的 cardId 本就不同（如 activityLevel=10000840 / activityLevelDialog=10000841），
+  // 因此按 cardId 抓取不会串卡；此前的串卡来自已废弃的编辑器 DOM 抓取路径。
+  if (!card.cardId) throw new Error(`列表未返回 cardId，无法抓取 ${card.id} 的 schema。`);
+  const body = await finmallPostWithHeal(page, '/ubomp-web/IDC10012.do', {
+    cardId: card.cardId,
+    sassAppId: appId,
+    sassWorkspaceId: workspaceId,
+  }, 'IDC10012.do');
+  // 响应体整体缺失（而非缺 schemaValue）时同样按空白卡处理：绝不把整批同步拖成失败。
+  if (!body || typeof body !== 'object') {
+    log.warn('远端响应体为空，按空白卡处理', { id: card.id, cardId: card.cardId });
+    return null;
+  }
+  // 防串卡：服务端会回显 cardId，与请求不一致说明拿到了别的卡片，宁可失败也不写盘。
+  if (body.cardId && String(body.cardId) !== String(card.cardId)) {
+    throw new Error(`${card.id} 响应 cardId=${body.cardId} 与请求 cardId=${card.cardId} 不一致，已中止以防串卡。`);
+  }
+  if (!body.schemaValue) {
+    log.warn('远端无 schemaValue，判定为空白卡', { id: card.id, cardId: card.cardId });
+    return null;
+  }
+  return JSON.parse(body.schemaValue);
+}
+
+/**
+ * 取 schema（已在 finmallPostWithHeal 内带会话/权限失效自愈）。
+ * IDC10012.do 只接受数字型 `cardId` 作为主键，命中 SESSION_INVALID_RE 特征时
+ * finmallPostWithHeal 会自动清 session 重登再试一次，覆盖会话超时与权限态异常。
+ */
+
+/** 清空过期会话并以保存的凭据重新登录（复用导航器的登录逻辑，全程在页面上下文内完成）。 */
+async function relogin(page) {
+  await clearTimeoutPrompts(page);
+  await page
+    .evaluate(() => {
+      try {
+        localStorage.clear();
+      } catch {
+        /* ignore */
+      }
+    })
+    .catch(() => {});
+  await page.reload({ waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
+  await sleep(1500);
+  const credentials = await loadCredentials();
+  const result = await performLogin(page, credentials);
+  if (!result.sessionCreated) {
+    throw new Error(
+      "自动重新登录失败：" +
+        (result.businessFailure ? "登录接口返回业务失败" : `HTTP ${result?.status || "失败"}`),
+    );
+  }
+  await page.reload({ waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
+  await sleep(1500);
+  await clearTimeoutPrompts(page);
+  await waitForAuthenticatedPage(page, 20000);
+}
+
+async function finmallPost(page, urlPath, requestBody, transCode = urlPath) {
+  return withTimeout(
+    page.evaluate(async ({ urlPath, requestBody, transCode, timeoutMs }) => {
+      const controller = new AbortController();
+      setTimeout(() => controller.abort(), timeoutMs);
+      // FinMall 不用 Cookie 鉴权（document.cookie 恒为空），会话凭据存在 localStorage
+      // 的 `_sessionId` 中，由前端以 `token` 请求头透传。缺这个头时 IDC10001.do（不鉴权）
+      // 仍能返回，但 IDC10012.do 会返回 BLEC0006「会话超时」——这正是此前抓取失败的根因。
+      // 该值仅在页面上下文内读取并直接用于请求，不回传 Node 侧、不打印、不落盘。
+      const readSessionToken = () => {
+        try {
+          const raw = localStorage.getItem('_sessionId');
+          if (!raw) return '';
+          let value = JSON.parse(raw);
+          if (value && typeof value === 'object' && 'value' in value) value = value.value;
+          if (typeof value === 'string' && value.startsWith('"')) {
+            try { value = JSON.parse(value); } catch { /* 保留原字符串 */ }
+          }
+          return typeof value === 'string' ? value : '';
+        } catch {
+          return '';
+        }
+      };
+      const sessionToken = readSessionToken();
+      if (!sessionToken) {
+        throw new Error('页面缺少会话凭据（localStorage._sessionId 为空），请先运行 finmall-session-navigator 登录。');
+      }
+      const url = new URL(urlPath, location.origin).href;
+      const payload = {
+        header: {
+          version: '1.0.0',
+          commType: '',
+          transCode,
+          srcIP: '',
+          channelType: '',
+          channelNo: '',
+          srcSystemId: '',
+          srcSystemDevId: '',
+          charset: 'json',
+          respFormat: 'UTF-8',
+          reqNo: '',
+          securityFlag: '',
+          macCode: '',
+          macValue: '',
+          requestTime: Date.now(),
+          transTime: Date.now(),
+          globalFlowNo: '',
+        },
+        body: requestBody,
+      };
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json;charset=UTF-8', token: sessionToken },
+        credentials: 'include',
+        signal: controller.signal,
+        body: JSON.stringify(payload),
+      });
+      const text = await response.text();
+      if (!response.ok) throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+      const parsed = JSON.parse(text);
+      const errorCode = parsed.header?.errorCode || parsed.body?.errorCode;
+      if (errorCode && errorCode !== '0') {
+        // 把 errorCode 与响应体片段一并抛出，便于排查（如 cardId 不存在 / 无权限 / 入参结构不符）。
+        const detail = JSON.stringify(parsed).slice(0, 600);
+        throw new Error(`FinMall 交易失败 [errorCode=${errorCode}] ${parsed.header?.errorMsg || parsed.body?.errorMsg || ''} | ${detail}`);
+      }
+      return parsed.body;
+  }, { urlPath, requestBody, transCode, timeoutMs: FINMALL_POST_TIMEOUT_MS }),
+    FINMALL_POST_TIMEOUT_MS + 2000,
+    `FinMall 请求 ${transCode}`
+  );
+}
+
+function normalizeCard(raw) {
+  const id = raw.code;
+  if (!id || !/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`Unsafe card code: ${id}`);
+  return {
+    id,
+    title: raw.cardName || '',
+    cardId: raw.cardId,
+    coverUrl: filestoreToUrl(raw.picUrl),
+    raw,
+  };
+}
+
+function filestoreToUrl(value) {
+  return finmallConfig.filestoreUrl(value);
+}
+
+async function syncCard(page, card, { outRoot, appId, workspaceId, summary, schemaHashes }) {
+  const cardDir = path.join(outRoot, card.id);
+  await mkdir(cardDir, { recursive: true });
+  const schema = await fetchCardSchema(page, card, { appId, workspaceId });
+  // 空白卡（远端从未保存过 schema）：合法状态，走专门的落盘分支，不再整批失败。
+  if (!schema) {
+    return syncBlankCard(page, card, { cardDir, appId, workspaceId });
+  }
+  // 推送前一致性闸门（基于实测不变量：IDC10001 列表 cardId ≡ schema 内 pageId）。
+  // 若二者不等，说明抓取的 schema 与该实例错位（串卡 / 模板错挂），落盘后推送会按错 pageId 打错卡。
+  // 直接抛错由调用方记入 failed 并中止本卡落盘，避免错位 pageId 进入本地与远端。
+  if (card.cardId != null && String(schema.pageId) !== String(card.cardId)) {
+    throw new Error(`${card.id} pageId 错位：列表 cardId=${card.cardId} ≠ schema.pageId=${schema.pageId}，疑似串卡，已拒绝落盘`);
+  }
+  const coverPath = await saveCover(page, card, cardDir);
+  // 注意：schema 内部的 pageId 一律以「远端拉取」的为准，原样落盘，不做覆盖。
+  // 远端返回的 pageId 是 FinMall 编辑器维护的权威页面/模板 ID，落盘后随 schema 一并保留，
+  // 供保存（IDC10010）/预览（IDC10015/10020/10021）链路按此主键打到线上。
+  // 重复 schema 检测：若不同 code 抓到了字节完全相同的 schema，说明仍串卡，
+  // 记录到 duplicates 并把整体结果标为失败，便于重抓时立即发现而非事后排查。
+  const schemaHash = createHash('md5').update(JSON.stringify(schema)).digest('hex');
+  const dupOf = schemaHashes.get(schemaHash);
+  if (dupOf && dupOf !== card.id) {
+    summary.duplicates.push({ id: card.id, dupOf, hash: schemaHash.slice(0, 8) });
+    summary.success = false;
+    log.warn('检测到重复 schema（疑似串卡）', { id: card.id, dupOf, hash: schemaHash.slice(0, 8) });
+  }
+  schemaHashes.set(schemaHash, card.id);
+  const schemaPath = path.join(cardDir, 'schema.json');
+  await writeFile(schemaPath, JSON.stringify(schema, null, 2), 'utf8');
+  const dataPath = path.join(cardDir, 'data.json');
+  await writeFile(dataPath, JSON.stringify(buildDataFromSchema(schema), null, 2), 'utf8');
+  const [cover, schemaInfo, data] = await Promise.all([
+    stat(coverPath), stat(schemaPath), stat(dataPath),
+  ]);
+  await writeImportSidecar(cardDir, {
+    appId,
+    workspaceId,
+    card,
+    files: { schema: schemaInfo.size, data: data.size, cover: cover.size },
+  });
+  return { cover: cover.size, schema: schemaInfo.size, data: data.size };
+}
+
+/**
+ * 空白卡落盘：远端从未保存过 schema（IDC10012 无 schemaValue），但卡片实例真实存在。
+ * 规则（用户确认）：
+ *   1) 本地已有同名卡片 → 以本地 schema.json / data.json 为准，远端空白绝不覆盖；
+ *   2) 本地已有同名预览图 → 跳过下载；否则照常同步；
+ *   3) pageId 必须与远端列表返回的 cardId 一致（保存 IDC10010 / 预览 10015·10020·10021
+ *      全链路按这个数字主键定位线上卡片，错位会打到别的卡上）。
+ * 本地无任何卡片时，落一份最小合法空白 schema，保证目录可被编辑器/预览正常加载。
+ */
+async function syncBlankCard(page, card, { cardDir, appId, workspaceId }) {
+  const schemaPath = path.join(cardDir, 'schema.json');
+  const dataPath = path.join(cardDir, 'data.json');
+  const localSchema = await readJsonIfValid(schemaPath);
+  const localData = await readJsonIfValid(dataPath);
+  const keptLocal = !!localSchema;
+
+  // 本地有实体卡片：保留本地内容；否则建最小空白骨架。
+  const schema = localSchema || buildBlankSchema(card);
+  const data = localData || (keptLocal ? buildDataFromSchema(schema) : {});
+
+  // pageId 对齐远端 cardId：只改这一个字段，其余本地内容原样保留。
+  const pageIdRewritten = String(schema.pageId ?? '') !== String(card.cardId);
+  if (pageIdRewritten) schema.pageId = String(card.cardId);
+
+  if (!keptLocal || pageIdRewritten) {
+    await writeFile(schemaPath, JSON.stringify(schema, null, 2), 'utf8');
+  }
+  if (!localData) {
+    await writeFile(dataPath, JSON.stringify(data, null, 2), 'utf8');
+  }
+
+  // 预览图：本地已有同名图则跳过，否则下载（无可用图源时静默跳过，不算失败）。
+  let coverPath = await findExistingCover(cardDir, card.id);
+  let coverSkipped = !!coverPath;
+  let coverError = '';
+  if (!coverPath && card.coverUrl) {
+    try {
+      coverPath = await saveCover(page, card, cardDir);
+    } catch (e) {
+      coverError = String(e && e.message);
+      log.warn('空白卡预览图同步失败（不影响卡片落盘）', { id: card.id, error: coverError });
+    }
+  }
+
+  const [schemaInfo, dataInfo] = await Promise.all([stat(schemaPath), stat(dataPath)]);
+  const coverInfo = coverPath ? await stat(coverPath).catch(() => null) : null;
+  await writeImportSidecar(cardDir, {
+    appId,
+    workspaceId,
+    card,
+    files: { schema: schemaInfo.size, data: dataInfo.size, cover: coverInfo ? coverInfo.size : 0 },
+  });
+
+  return {
+    cover: coverInfo ? coverInfo.size : 0,
+    schema: schemaInfo.size,
+    data: dataInfo.size,
+    blank: true,
+    keptLocal,
+    pageIdRewritten,
+    coverSkipped,
+    coverError,
+  };
+}
+
+/** 最小合法空白 schema：满足 validate_schema.py 的顶层必填（version/pageId/name/dictionary/view）。 */
+function buildBlankSchema(card) {
+  return {
+    version: '1.0.0',
+    pageId: String(card.cardId),
+    name: card.title || card.id,
+    desc: '',
+    platform: 'mobile',
+    dictionary: { dictionaryList: [], inputParams: [], mocks: [] },
+    view: {
+      width: '375',
+      className: 'Root',
+      style: { properties: [] },
+      properties: [],
+      eventactions: [],
+      components: [],
+    },
+  };
+}
+
+/** 读本地 JSON；文件不存在或解析失败返回 null（不抛，交给调用方决定降级策略）。 */
+async function readJsonIfValid(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+
+/** 找本地已有的同名预览图（<cardId>.<ext>）；没有返回 null。 */
+async function findExistingCover(cardDir, id) {
+  let entries = [];
+  try {
+    entries = await readdir(cardDir);
+  } catch {
+    return null;
+  }
+  for (const name of entries) {
+    const ext = path.extname(name).toLowerCase();
+    if (IMAGE_EXTS.has(ext) && path.basename(name, ext) === id) return path.join(cardDir, name);
+  }
+  return null;
+}
+
+/**
+ * 导入来源可追溯（Phase E）：把这张卡从哪来 / 何时导入 / 落盘在哪写进侧车 .import-meta.json。
+ * 侧车独立于 schema.json/data.json，绝不污染 DSL 产品数据；找不到 server 模块时静默跳过。
+ * 空白卡同样写侧车——pageId 已对齐远端 cardId，属于合法的远端来源卡，允许后续推送。
+ */
+async function writeImportSidecar(cardDir, { appId, workspaceId, card, files }) {
+  try {
+    const metaPath = path.resolve(workspace, 'server', 'core', 'cardImportMeta.js');
+    const { writeImportMeta, buildImportMeta } = await import(pathToFileURL(metaPath).href);
+    const meta = buildImportMeta({
+      baseUrl: finmallConfig.baseUrl,
+      appId,
+      workspaceId,
+      cardId: card.cardId,
+      cardCode: card.id,
+      cardName: card.title,
+      files,
+    });
+    writeImportMeta(cardDir, meta);
+  } catch (e) {
+    log.warn('写导入元数据侧车失败（不影响卡片落盘）', { error: e && e.message });
+  }
+}
+
+async function saveCover(page, card, cardDir) {
+  if (!card.coverUrl) throw new Error(`No cover url for ${card.id}.`);
+  const ext = imageExt(card.coverUrl);
+  const coverPath = path.join(cardDir, `${card.id}${ext}`);
+  const base64 = await withTimeout(
+    page.evaluate(async ({ src, timeoutMs }) => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(src, { credentials: 'include', signal: controller.signal });
+        if (!response.ok) throw new Error(`cover fetch failed ${response.status}`);
+        const buffer = await response.arrayBuffer();
+        let binary = '';
+        const bytes = new Uint8Array(buffer);
+        for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+        return btoa(binary);
+      } finally {
+        clearTimeout(timer);
+      }
+    }, { src: card.coverUrl, timeoutMs: COVER_FETCH_TIMEOUT_MS }),
+    COVER_FETCH_TIMEOUT_MS + 2000,
+    '预览图下载'
+  );
+  await writeFile(coverPath, Buffer.from(base64, 'base64'));
+  return coverPath;
+}
+
+function imageExt(url) {
+  try {
+    const ext = path.extname(decodeURIComponent(new URL(url).pathname)).toLowerCase();
+    return ext && ext.length <= 8 ? ext : '.png';
+  } catch {
+    return '.png';
+  }
+}
+
+function buildDataFromSchema(schema) {
+  const data = {};
+  for (const param of schema.dictionary?.inputParams || []) {
+    const fallback = parseDescFallback(param);
+    const defaultValue = param.defaultValue;
+    const emptyObject = defaultValue && typeof defaultValue === 'object' && !Array.isArray(defaultValue) && Object.keys(defaultValue).length === 0;
+    data[param.key] = clone(fallback !== undefined && (defaultValue === undefined || defaultValue === '' || emptyObject) ? fallback : defaultValue);
+  }
+  return data;
+}
+
+function parseDescFallback(param) {
+  if (!param.desc || typeof param.desc !== 'string') return undefined;
+  const text = param.desc.trim();
+  if (!text.startsWith('{')) return undefined;
+  try {
+    const parsed = JSON.parse(text);
+    return Object.prototype.hasOwnProperty.call(parsed, param.key) ? parsed[param.key] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+// 仅当作为脚本直接运行时执行 CLI 逻辑（被 Vite 中间件 import 时不触发）
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const args = parseArgs(process.argv.slice(2));
+  const summary = await syncCards(args);
+  const blanks = summary.synced.filter((s) => s.blank);
+  log.box({
+    title: '同步结果',
+    level: summary.success ? 'ok' : 'warn',
+    lines: [
+      `请求：${args.cardCode || '(全部)'}`,
+      `已同步：${summary.synced.length} 张`,
+      `失败：${summary.failed.length} 张`,
+      `空白卡片：${blanks.length} 张`,
+      `重复 schema：${summary.duplicates.length} 项`,
+      ...(blanks.length
+        ? [`空白明细：${blanks.map((b) => `${b.id}${b.keptLocal ? '(保留本地)' : '(新建空白)'}`).join('、')}`]
+        : []),
+      ...(summary.failed.length
+        ? [`失败明细：${summary.failed.map((f) => f.id || '(unknown)').join('、')}`]
+        : []),
+    ],
+  });
+  if (summary.failed.length) process.exitCode = 1;
+}