cardbuddy 0.19.3 → 0.21.0

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

@@ -80,6 +80,9 @@ const COVER_FETCH_TIMEOUT_MS = Number(process.env.CARDBUDDY_COVER_TIMEOUT_MS ||
 // FinMall 交易请求超时。IDC10001/IDC10012 偶发挂起（后端不响应），同样没有任何默认超时，
 // 一张卡挂住就会拖垮整批同步——所以和预览图一样，内层 abort + 外层 race 双重设防。
 const FINMALL_POST_TIMEOUT_MS = Number(process.env.CARDBUDDY_POST_TIMEOUT_MS || 30000);
+// 卡片预览图上传（IDC10014.do）超时。与切图上传同款设防：内层 AbortController +
+// 外层 Promise.race 兜住 page.evaluate 自身不返回（evaluate 无默认超时）。
+const PREVIEW_UPLOAD_TIMEOUT_MS = Number(process.env.CARDBUDDY_PREVIEW_UPLOAD_TIMEOUT_MS || 30000);
 
 function withTimeout(promise, ms, label) {
   let timer;
@@ -92,9 +95,10 @@ function withTimeout(promise, ms, label) {
 }
 
 // 服务端判定会话/权限失效并应「重新进入」的特征集合。命中后由 finmallPostWithHeal
-// 自动清 session 重登再试一次——覆盖会话超时（BLEC0006）、token 失效，以及
-// 本次遇到的「您当前角色菜单权限发生变化，请重新进入」这类权限态异常。
-const SESSION_INVALID_RE = /BLEC0006|会话超时|会话过期|登录超时|未登录|登录失效|登录已失效|请重新登录|invalid token|token|角色菜单权限发生变化|权限发生变化|重新进入|请重新进入/i;
+// 自动清 session 重登再试一次——覆盖会话超时（BLEC0006）、token 失效、
+// 「您当前角色菜单权限发生变化，请重新进入」这类权限态异常，以及前端页面会话键丢失
+// （localStorage._sessionId 为空，如后台 Chrome 被清理/重启后）：本地凭证仍在即可自愈。
+const SESSION_INVALID_RE = /BLEC0006|会话超时|会话过期|登录超时|未登录|登录失效|登录已失效|请重新登录|invalid token|token|角色菜单权限发生变化|权限发生变化|重新进入|请重新进入|缺少会话凭据/i;
 
 /**
  * 带自愈的 FinMall 接口调用：正常请求，若命中会话/权限失效特征则清 session 重登后重试一次。
@@ -124,6 +128,7 @@ async function finmallPostWithHeal(page, urlPath, requestBody, transCode = urlPa
  *
  * @param {object} opts
  * @param {string} [opts.cardCode]     仅同步该英文卡 id（用列表接口 searchValue 定位）
+ * @param {string[]} [opts.cardCodes]  仅同步这些英文卡 id（集合筛选；与 cardCode 互斥，cardCode 优先）
  * @param {number} [opts.startPage=1]
  * @param {number} [opts.startIndex=0]
  * @param {number} [opts.pageSize=24]
@@ -132,7 +137,11 @@ async function finmallPostWithHeal(page, urlPath, requestBody, transCode = urlPa
  * @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}>}
+ * @param {(p: {done:number,total:number|null,currentId:string,currentTitle:string}) => void} [opts.onProgress]
+ *                                     每张卡处理完毕后的进度回调（失败也回调），供前端进度条消费
+ * @param {() => boolean} [opts.shouldCancel] 取消探针：返回 true 时在下一条卡片前中止，
+ *                                     已落盘的卡片保留，summary 标记 cancelled
+ * @returns {Promise<{success:boolean, synced:Array, failed:Array, duplicates:Array, cancelled?:boolean}>}
  */
 export async function syncCards(opts = {}) {
   // 非注入形态（纯 CLI）用 cwd 作为项目根，跨「仓库内 / 消费者工程」一致；server 中间件始终注入绝对 outRoot。
@@ -152,6 +161,19 @@ export async function syncCards(opts = {}) {
   const workspaceId = opts.workspaceId || finmallConfig.workspaceId;
   // 单卡筛选：传 cardCode 时仅同步该卡
   const cardCodeFilter = opts.cardCode || '';
+  // 集合筛选：cardCodes 非空时仅同步集合内卡片（与单卡筛选互斥，单卡优先）。
+  // 入口处已做格式校验，这里再按 normalizeCard 同源正则兜底，非法项静默剔除。
+  const cardCodeSet =
+    !cardCodeFilter && Array.isArray(opts.cardCodes) && opts.cardCodes.length
+      ? new Set(
+          opts.cardCodes.filter((c) => typeof c === 'string' && /^[A-Za-z0-9_-]+$/.test(c))
+        )
+      : null;
+  // 进度回调与取消探针（前端「查看全部 → 下载选中/全部下载」的进度弹窗消费）
+  const onProgress = typeof opts.onProgress === 'function' ? opts.onProgress : null;
+  const shouldCancel = typeof opts.shouldCancel === 'function' ? opts.shouldCancel : () => false;
+  // 预期总张数：单卡=1；集合=集合大小；全量=0（未知，边拉边算）
+  const expectedTotal = cardCodeFilter ? 1 : cardCodeSet ? cardCodeSet.size : 0;
 
   // 自动确保后台 FinMall 会话：未启动/缺失则拉起无界面 Chrome 并登录，无需手动触发。
   const session = await ensureFinMallSession();
@@ -170,14 +192,17 @@ export async function syncCards(opts = {}) {
     const totalPages = Number(firstList.totalPages || Math.ceil(Number(firstList.totalNums || 0) / pageSize) || startPage);
 
   let done = false;
+  let cancelled = false;
   const allCards = [];
-  for (let pageNo = startPage; pageNo <= totalPages && !done; pageNo++) {
+  for (let pageNo = startPage; pageNo <= totalPages && !done && !cancelled; 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++) {
+      for (let index = begin; index < cards.length && !done && !cancelled; index++) {
         if (summary.synced.length + summary.failed.length >= maxCards) break;
+        // 取消探针：用户点「取消」后在下一条卡片前退出（已落盘的卡片保留）
+        if (shouldCancel()) { cancelled = true; break; }
         // normalizeCard 会对非法 code 抛错；单条异常不应中断整批同步。
         let card;
         try {
@@ -189,6 +214,8 @@ export async function syncCards(opts = {}) {
           continue;
         }
         if (cardCodeFilter && card.id !== cardCodeFilter) continue;
+        // 集合筛选：不在勾选集合内的卡片跳过（仍进 allCards 供缓存整体刷新）
+        if (cardCodeSet && !cardCodeSet.has(card.id)) 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, importMeta });
@@ -203,12 +230,30 @@ export async function syncCards(opts = {}) {
           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 });
         }
+        // 进度回调：失败也回调（done 计数含失败），前端据此更新「已完成 X / 全部 Y」
+        if (onProgress) {
+          try {
+            onProgress({
+              done: summary.synced.length + summary.failed.length,
+              total: expectedTotal || null,
+              currentId: card.id,
+              currentTitle: card.title || '',
+            });
+          } catch { /* 前端回调异常不阻断同步 */ }
+        }
         if (cardCodeFilter) done = true;
       }
       if (summary.synced.length + summary.failed.length >= maxCards) break;
     }
+    // 取消：已落盘的卡片保留，summary 显式标记，由调用方（dev server 任务）转成用户提示
+    if (cancelled) {
+      summary.cancelled = true;
+      summary.success = false;
+      log.warn('同步已被用户取消', { done: summary.synced.length + summary.failed.length });
+    }
     // 全量同步（无 cardCode 过滤）时整体刷新卡片列表缓存，供推送前「存在性闸门」使用；
-    // 单卡同步只增量合并，不整体替换，避免清空其余卡片。缓存未就绪则跳过（不影响同步）。
+    // 单卡同步只增量合并，不整体替换，避免清空其余卡片。集合筛选（cardCodes）会翻遍
+    // 全部分页，allCards 即完整列表，整体刷新同样准确。缓存未就绪则跳过（不影响同步）。
     try {
       const cache = await getCardListCache();
       if (cache) cache.refreshCardList(allCards, { full: !cardCodeFilter });
@@ -222,6 +267,66 @@ export async function syncCards(opts = {}) {
   return summary;
 }
 
+/**
+ * 拉取远端完整卡片列表（IDC10001 分页全量），供编辑器「查看全部」网格浏览。
+ * 只读、不落盘；与 syncCards 共用同一后台 FinMall 会话（ensureFinMallSession 自动保活）。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.pageSize=50]    列表分页大小
+ * @param {number} [opts.maxPages=400]   分页上限保护（50×400=2 万张，防服务端异常死循环）
+ * @param {string} [opts.appId]
+ * @param {string} [opts.workspaceId]
+ * @returns {Promise<Array<{id:string,title:string,cardId:string|number,coverUrl:string}>>}
+ *   id=英文卡 code（本地目录名同源）；coverUrl 为 FinMall 图片库绝对地址（可能为空串）
+ */
+export async function listRemoteCards(opts = {}) {
+  const appId = opts.appId || finmallConfig.appId;
+  const workspaceId = opts.workspaceId || finmallConfig.workspaceId;
+  const pageSize = Number(opts.pageSize || 50);
+  const maxPages = Number(opts.maxPages || 400);
+
+  // 自动确保后台 FinMall 会话：未启动/缺失则拉起无界面 Chrome 并登录，无需手动触发。
+  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();
+
+    const out = [];
+    const seen = new Set();
+    let pageNo = 1;
+    let totalPages = 1;
+    do {
+      const list = await fetchCardList(page, { pageNo, pageSize, appId, workspaceId });
+      totalPages = Number(list.totalPages || Math.ceil(Number(list.totalNums || 0) / pageSize) || 1);
+      for (const raw of list.cardList || []) {
+        // 非法 code（normalizeCard 抛错）的单条跳过，不阻断整表拉取
+        let card;
+        try {
+          card = normalizeCard(raw);
+        } catch {
+          continue;
+        }
+        if (seen.has(card.id)) continue;
+        seen.add(card.id);
+        out.push({
+          id: card.id,
+          title: card.title || '',
+          cardId: card.cardId,
+          coverUrl: card.coverUrl || '',
+        });
+      }
+      pageNo += 1;
+    } while (pageNo <= totalPages && pageNo <= maxPages);
+    return out;
+  } finally {
+    // 仅断开连接，不关闭后台 Chrome（与 syncCards 一致，供后续同步/推送复用会话）
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+
 /**
  * 把一张卡片的最新 schema 写回 FinMall（线上编辑器「保存」接口 IDC10010.do）。
  * 与 syncCards 共用同一套已登录浏览器会话与带自愈的 finmallPost，
@@ -315,6 +420,175 @@ export async function saveCardToRemote(schema, { skeletonScreen = '', verify = t
   }
 }
 
+/**
+ * 在已认证页面上下文内以 multipart/form-data 上传卡片预览图（IDC10014.do）。
+ *
+ * 请求形态取自线上编辑器抓包（`/ubomp-web/IDC10014.do`），与切图上传（CC0000.do）的差异：
+ *   - 表单字段是 `cardId`（纯文本数字 cardId）+ `file`（二进制，filename 固定 `<cardId>.png`，
+ *     抓包里 Content-Type 为 application/octet-stream —— Blob 不带 type 时浏览器就是这个值，
+ *     这里照抄抓包，不做「更正确」的覆盖）；
+ *   - `sassAppId` / `sassWorkspaceId` 走**表单字段**（CC0000.do 是查询串）；
+ *   - 没有 `fileName` 纯文本字段；
+ *   - 鉴权头只有 `token`。
+ *
+ * token 仅在页面上下文内读取并直接用于请求，不回传 Node 侧、不打印、不落盘（与 finmallPost 同纪律）。
+ *
+ * @returns {Promise<string>} 原始响应文本（交由 parsePreviewUploadResponse 解析）
+ */
+async function postPreviewUpload(page, { cardId, fileName, base64, appId, workspaceId }) {
+  return withTimeout(
+    page.evaluate(
+      async ({ cardId, fileName, base64, appId, workspaceId, timeoutMs }) => {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeoutMs);
+        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 binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+        const form = new FormData();
+        form.append('cardId', cardId);
+        // 抓包里该 part 的 Content-Type 是 application/octet-stream，filename 为 <cardId>.png
+        form.append('file', new Blob([bytes]), fileName);
+        form.append('sassAppId', String(appId));
+        form.append('sassWorkspaceId', String(workspaceId));
+        const response = await fetch(new URL('/ubomp-web/IDC10014.do', location.origin).href, {
+          method: 'POST',
+          headers: { token: sessionToken, Accept: '*/*' },
+          credentials: 'include',
+          body: form,
+          signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+        return text;
+      },
+      { cardId, fileName, base64, appId, workspaceId, timeoutMs: PREVIEW_UPLOAD_TIMEOUT_MS },
+    ),
+    PREVIEW_UPLOAD_TIMEOUT_MS + 2000,
+    `上传卡片预览图 ${fileName}`,
+  );
+}
+
+/**
+ * 解析 IDC10014.do 响应（导出仅为单测可直接断言；正常路径走 uploadCardPreview）。
+ *
+ * 该接口的响应体形态没有可比对的既有文档，故按 FinMall 交易接口的通用信封
+ * （`{header:{errorCode,errorMsg}, body:{...}}`）做**宽松**判定：
+ *   - 空响应体 → 视为成功（HTTP 2xx 已由调用方保证，接口可能不返回业务体）；
+ *   - 非 JSON 非空 → 直接报错（多半是网关 HTML 错误页，不能当成功）；
+ *   - errorCode 存在且非 '0' → 抛错（BLEC0006 等会话失效特征会被 uploadCardPreview 捕获并重登重试）；
+ *   - 成功时尽力从 body 里捞预览图地址（字段名依 ubomp 同类接口习惯多键兜底），
+ *     捞不到不影响「上传成功」的结论。
+ *
+ * @param {string} text 原始响应文本
+ * @param {string} cardId 请求用的数字型 cardId（用于回显校验 / 日志）
+ * @returns {{ ok: boolean, url: string, cardId: string }}
+ */
+export function parsePreviewUploadResponse(text, cardId) {
+  const raw = String(text == null ? '' : text).trim();
+  if (!raw) return { ok: true, url: '', cardId: String(cardId == null ? '' : cardId) };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`预览图上传响应不是 JSON：${raw.slice(0, 300)}`);
+  }
+  const header = (parsed && parsed.header) || {};
+  const body = (parsed && parsed.body) || {};
+  // header 与 body 各自可能带 errorCode：**逐个**看，不能用 `a || b` 短路——
+  // header.errorCode='0' 是真值，会把 body 里的业务错误（如 PEO000003）整段盖掉。
+  const codes = [header.errorCode, body.errorCode].filter((c) => c != null && String(c).trim() !== '');
+  const bad = codes.find((c) => String(c) !== '0');
+  if (bad != null) {
+    throw new Error(
+      `FinMall 预览图上传失败 [errorCode=${bad}] ${header.errorMsg || body.errorMsg || ''} | ${raw.slice(0, 300)}`,
+    );
+  }
+  // 地址字段多键兜底：接口未回地址属正常（上传即生效），所以这里只做尽力提取。
+  const url =
+    body.picUrl || body.previewUrl || body.imageUrl || body.filePath || body.url ||
+    parsed.picUrl || '';
+  return {
+    ok: true,
+    url: typeof url === 'string' ? url : '',
+    cardId: String(body.cardId || cardId || ''),
+  };
+}
+
+/**
+ * 上传卡片预览图到远端（IDC10014.do）。供「推送」成功后由 server/core/cardSave.js 调用：
+ * 本地无头渲染出透明底 PNG → 交给已登录的 FinMall 后台会话上传，卡片列表缩略图随之更新。
+ *
+ * 与 saveCardToRemote 的会话纪律一致：saveCardToRemote 末尾会 disconnect，故本函数自行
+ * ensureFinMallSession 重新取一次连接（Chrome 已常驻时这一步是廉价的 attach）。
+ * 会话/权限失效命中 SESSION_INVALID_RE 时自动清 session 重登并重试一次。
+ *
+ * @param {{ cardId: string|number, pngBase64: string, appId?: string, workspaceId?: string }} opts
+ * @returns {Promise<{ ok: true, url: string, cardId: string, bytes: number }>}
+ */
+export async function uploadCardPreview({ cardId, pngBase64, appId, workspaceId } = {}) {
+  const id = String(cardId == null ? '' : cardId).trim();
+  if (!/^\d+$/.test(id)) {
+    throw new Error(`上传卡片预览图需要数字型 cardId（IDC10014.do 主键），收到：${JSON.stringify(cardId)}`);
+  }
+  const base64 = String(pngBase64 == null ? '' : pngBase64);
+  if (!base64) throw new Error('上传卡片预览图缺少 PNG 内容（pngBase64 为空）。');
+  const appIdv = appId || finmallConfig.appId;
+  const workspaceIdv = workspaceId || finmallConfig.workspaceId;
+  const fileName = `${id}.png`;
+
+  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();
+
+    const payload = { cardId: id, fileName, base64, appId: appIdv, workspaceId: workspaceIdv };
+    let parsed;
+    try {
+      parsed = parsePreviewUploadResponse(await postPreviewUpload(page, payload), id);
+    } catch (error) {
+      if (SESSION_INVALID_RE.test(String(error && error.message))) {
+        log.warn('会话/权限失效，自动重新登录后重试预览图上传', {
+          cardId: id,
+          reason: String(error && error.message).slice(0, 40),
+        });
+        await relogin(page);
+        parsed = parsePreviewUploadResponse(await postPreviewUpload(page, payload), id);
+      } else {
+        throw error;
+      }
+    }
+    log.ok('卡片预览图已上传', { cardId: id, fileName, url: parsed.url || '(接口未回地址)' });
+    return { ...parsed, bytes: Math.round((base64.length * 3) / 4) };
+  } finally {
+    try { await browser.disconnect() } catch { /* 后台 Chrome 常驻，仅断开连接 */ }
+  }
+}
+
 /**
  * 远端预览：复刻 ubomp-h5-sub PreviewPopover.vue 的 onPopoverShow 全链路。
  *  1) prepreview：先把当前编辑的卡片保存到远端（IDC10010.do，对齐 ubomp 的 prepreview 钩子）
@@ -418,11 +692,40 @@ export async function previewCardRemote(schema, { skeletonScreen = '', publish =
 }
 
 /**
- * 远端发布：取当前卡片远端最大版本号 +1，发布上线为新版本。
+ * FinMall 版本号格式：8 位「年份 + 4 位序号」，如 20260025。
+ * 该格式的最小值约 20200001，故任何 < 10000000 的纯数字都不符合格式
+ * （含旧实现首发时误写出的 1 / 2 / 3…）。
+ */
+const MIN_YEAR_SEQ_VERSION = 10000000;
+
+/**
+ * 由远端最大版本号推导「下一个待发布版本号」。
+ *   - 远端从未发布（maxVersion 为 null / 空 / '0'）→ `${当前年份}0001`，而不是裸 '1'；
+ *   - 已是「年份+4 位序号」→ 数值 +1。注意这里**不按年份重置**：跨年后沿用上一年的序号递增
+ *     （如 20250028 → 20250029），保证版本号单调递增，避免回退到比线上更小的值；
+ *   - 历史遗留的旧格式小版本（旧 bug 写出的 '1' 等）→ 视同首发，规范化为 `${当前年份}0001`，
+ *     数值上 20260001 > 2，不会造成版本回退，可自愈已受该 bug 影响的卡片。
+ * @param {string|number|null|undefined} maxVersion IDC10004 返回的 maxVersion
+ * @returns {string} 8 位版本号
+ * @example nextPublishVersion(null) // '20260001'
+ * @example nextPublishVersion('20260025') // '20260026'
+ * @example nextPublishVersion('1') // '20260001'
+ */
+export function nextPublishVersion(maxVersion) {
+  const raw = String(maxVersion == null ? '' : maxVersion).trim();
+  const num = Number(raw);
+  const valid = /^\d+$/.test(raw) && Number.isFinite(num) && num >= MIN_YEAR_SEQ_VERSION;
+  if (!valid) return `${new Date().getFullYear()}0001`;
+  return String(num + 1);
+}
+
+/**
+ * 远端发布：取当前卡片远端最大版本号，推导下一个版本号并发布上线。
  * 链路（对齐 ubomp 发布流程，仅两步）：
  *   1) IDC10004.do 取当前卡片最大版本号 maxVersion；
- *   2) IDC10016.do 以 maxVersion+1 作为新版本号发布（发布的是远端「当前已保存」的卡片内容——
+ *   2) IDC10016.do 以 nextPublishVersion(maxVersion) 作为新版本号发布（发布的是远端「当前已保存」的卡片内容——
  *      故发布前应先用「推送当前卡」把本地内容保存到远端，否则会发布陈旧内容）。
+ *      版本号格式为 8 位「年份 + 4 位序号」：远端从未发布时取 `${当前年份}0001`（不是裸 1）。
  * 会话由 ensureFinMallSession 自动保证；与 saveCardToRemote / syncCards / previewCardRemote
  * 共用同一套已登录后台 Chrome，命中会话/权限失效（BLEC0006 等）时自动清 session 重登重试一次。
  *
@@ -452,8 +755,7 @@ export async function publishCard(schema) {
       'IDC10004.do',
     )
     const maxVersion = String(maxResp && maxResp.maxVersion != null ? maxResp.maxVersion : '0')
-    const maxNum = Number(maxVersion)
-    const nextVersion = String(Number.isFinite(maxNum) ? maxNum + 1 : 1)
+    const nextVersion = nextPublishVersion(maxVersion)
     log.info('发布前取最大版本', { cardId, maxVersion, nextVersion })
 
     // 2) 以 maxVersion+1 发布（发布类型/平台等参数对齐 ubomp 发布弹窗的默认值）
@@ -518,6 +820,335 @@ export async function fetchCardLatestVersion(cardId) {
   }
 }
 
+/**
+ * 取远端「发布版本记录」分页列表：IDC10004.do 的 versionList（新→旧，最多一页 pageSize 条）。
+ * 供调试面板「导入信息」tab 的「发布版本记录」弹框渲染（版本号 / 平台 / 状态 / 发布时间）。
+ * 只读；与 fetchCardLatestVersion / fetchCardHistory 共用同一后台 FinMall 会话
+ * （ensureFinMallSession + finmallPostWithHeal，命中会话失效自动清 session 重登重试一次）。
+ *
+ * 响应体（逆向 innermanage 前端 inner_flamePublish 页面）：
+ *   body.versionList[] = { versionId, version, platformStatus（JSON 字符串，如 '["iOS","Android"]'）,
+ *                           publishStatus, createTime }
+ *   body.maxVersion / pageNo / pageSize / totalNums / totalPages
+ *
+ * publishStatus 枚举（逆向页面 statusEnum，见 34.*.js：{ UNPUB:'0', PUB:'1', FINISH:'2', STOP:'3' }；
+ * 页面渲染仅对 0/1 出标签「未发布 / 发布中」，2/3 依枚举名与「停止发布」动作（publishStatus:'3'）释义）：
+ *   0=未发布  1=发布中  2=已完成  3=已停止
+ *
+ * @param {string|number} cardId
+ * @param {{ pageNo?: number, pageSize?: number }} [opts]
+ * @returns {Promise<{ list: Array<object>, maxVersion: string, totalNums: number, totalPages: number }>}
+ */
+export async function fetchCardPublishVersions(cardId, { pageNo = 1, pageSize = 10 } = {}) {
+  if (cardId == null) {
+    throw new Error('缺少 cardId，无法查询发布版本记录（IDC10004.do 需要 cardId）。');
+  }
+  const appId = finmallConfig.appId;
+  const workspaceId = finmallConfig.workspaceId;
+  const id = String(cardId);
+  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();
+    const resp = await finmallPostWithHeal(
+      page,
+      `/ubomp-web/IDC10004.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+      {
+        channel: '',
+        pageNo,
+        pageSize,
+        publishStatus: '',
+        version: '',
+        cardId: id,
+        sassAppId: appId,
+        sassWorkspaceId: workspaceId,
+      },
+      'IDC10004.do',
+    );
+    const rawList = Array.isArray(resp && resp.versionList) ? resp.versionList : [];
+    const list = rawList.map((raw) => {
+      let platforms = [];
+      try {
+        const parsed = JSON.parse(raw.platformStatus || '[]');
+        if (Array.isArray(parsed)) platforms = parsed.map((p) => String(p));
+      } catch {
+        /* platformStatus 损坏时按空平台处理，不阻断列表 */
+      }
+      const status = String(raw.publishStatus == null ? '' : raw.publishStatus);
+      return {
+        versionId: String(raw.versionId == null ? '' : raw.versionId),
+        version: String(raw.version == null ? '' : raw.version),
+        platforms,
+        platformStr: platforms.join('、'),
+        publishStatus: status,
+        publishTime: String(raw.createTime == null ? '' : raw.createTime),
+      };
+    });
+    log.info('查询远端发布版本记录', {
+      cardId: id,
+      pageNo,
+      count: list.length,
+      totalNums: resp && resp.totalNums,
+    });
+    return {
+      list,
+      maxVersion: String(resp && resp.maxVersion != null ? resp.maxVersion : ''),
+      totalNums: Number(resp && resp.totalNums != null ? resp.totalNums : list.length) || list.length,
+      totalPages: Number(resp && resp.totalPages != null ? resp.totalPages : 1) || 1,
+    };
+  } finally {
+    try { await browser.disconnect(); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * 取远端「卡片历史版本时间线」：IDC10013 按 cardId 分页返回 schemaValueList（新→旧）。
+ * 供编辑器「卡片历史记录」tab 渲染 git 式时间线。只读；与 fetchCardLatestVersion 共用
+ * 同一后台 FinMall 会话（ensureFinMallSession + finmallPostWithHeal）。
+ *
+ * schema 全量（每条数 KB~上百 KB）不跨端透传：服务端就地解析为轻量摘要 + 相邻版本 diff
+ * 标签，响应体积与 schema 大小解耦，UI 拿到的就是可直接渲染的字段。
+ *
+ * @param {string|number} cardId
+ * @param {{ pageNo?: number, pageSize?: number }} [opts]
+ * @returns {Promise<{ list: Array<object>, totalNums: number, totalPages: number }>}
+ */
+// —— 版本 schema 进程内缓存（(cardId, versionId) → schema）——
+// IDC10013 单页 100 条实测 ~6.5MB / 4.2s，而「加载此版本」只需要其中一条。
+// fetchCardHistory（时间线列表）本来就会解析页内全部 schema 算 diff，顺手按
+// (cardId, versionId) 缓存；fetchCardVersionSchema 命中缓存时零网络请求，
+// 把点击到加载的等待从 ~7s 降到毫秒级。未命中仍走原分页翻找兜底。
+const SCHEMA_CACHE_TTL_MS = Number(process.env.FINMALL_SCHEMA_CACHE_TTL_MS || 300000)
+const SCHEMA_CACHE_MAX = 500
+const _versionSchemaCache = new Map() // `${cardId}::${versionId}` → { schema, createTime, at }
+
+function cacheVersionSchema(cardId, versionId, schema, createTime) {
+  const key = `${cardId}::${versionId}`
+  _versionSchemaCache.set(key, { schema, createTime: createTime || '', at: Date.now() })
+  if (_versionSchemaCache.size > SCHEMA_CACHE_MAX) {
+    // 惰性容量控制：淘汰最早写入的一批（Map 保序）
+    let excess = _versionSchemaCache.size - SCHEMA_CACHE_MAX
+    for (const k of _versionSchemaCache.keys()) {
+      _versionSchemaCache.delete(k)
+      if (--excess <= 0) break
+    }
+  }
+}
+
+function getCachedVersionSchema(cardId, versionId) {
+  const key = `${cardId}::${versionId}`
+  const hit = _versionSchemaCache.get(key)
+  if (!hit) return null
+  if (Date.now() - hit.at > SCHEMA_CACHE_TTL_MS) {
+    _versionSchemaCache.delete(key)
+    return null
+  }
+  return hit
+}
+
+export async function fetchCardHistory(cardId, { pageNo = 1, pageSize = 30 } = {}) {
+  if (cardId == null) {
+    throw new Error('缺少 cardId，无法查询远端历史（IDC10013.do 需要 cardId）。')
+  }
+  const appId = finmallConfig.appId
+  const workspaceId = finmallConfig.workspaceId
+  const id = String(cardId)
+  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()
+    const resp = await finmallPostWithHeal(
+      page,
+      `/ubomp-web/IDC10013.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`,
+      { cardId: id, pageNo, pageSize, sassAppId: appId, sassWorkspaceId: workspaceId },
+      'IDC10013.do',
+    )
+    const rawList = Array.isArray(resp && resp.schemaValueList) ? resp.schemaValueList : []
+    // 顺带填充版本 schema 缓存：供「加载此版本」零网络命中（同进程内，list 已解析过一份）
+    for (const raw of rawList) {
+      try {
+        const parsed = typeof raw.schema === 'string' ? JSON.parse(raw.schema) : raw.schema
+        if (parsed && typeof parsed === 'object') {
+          cacheVersionSchema(id, String(raw.id != null ? raw.id : ''), parsed, raw.createTime)
+        }
+      } catch {
+        /* 单条 schema 损坏不阻断时间线，缓存自然跳过 */
+      }
+    }
+    // 接口顺序即新→旧，时间线按此顺序直接渲染（最新在上，同 git log）
+    const list = rawList.map((raw) => summarizeHistoryItem(raw))
+    // 相邻 diff：第 i 条相对第 i+1 条（更旧的一个版本）算变更标签
+    for (let i = 0; i < list.length; i += 1) {
+      const older = list[i + 1]
+      list[i].tags = diffHistoryTags(list[i].summary, older ? older.summary : null)
+    }
+    log.info('查询远端卡片历史', { cardId: id, pageNo, count: list.length, totalNums: resp && resp.totalNums })
+    return {
+      list,
+      totalNums: Number(resp && resp.totalNums != null ? resp.totalNums : list.length) || list.length,
+      totalPages: Number(resp && resp.totalPages != null ? resp.totalPages : 1) || 1,
+    }
+  } finally {
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+
+/**
+ * 按版本记录 id 取该历史版本的完整 schema（「加载此版本到编辑器」的数据源）。
+ * IDC10013 没有「按 id 单查」能力，只能分页翻找：pageSize 100 逐页扫到 totalPages，命中即返回。
+ * schema 为原始 JSON（顶层 version/pageId/name/desc + view.components 组件树），与 syncCard 落盘同构。
+ *
+ * @param {string|number} cardId
+ * @param {string|number} versionId 历史记录 id（IDC10013 schemaValueList[].id）
+ * @returns {Promise<{ schema: object, record: { id: string, createTime: string } }>}
+ */
+export async function fetchCardVersionSchema(cardId, versionId) {
+  if (cardId == null) {
+    throw new Error('缺少 cardId，无法查询远端历史版本（IDC10013.do 需要 cardId）。')
+  }
+  const want = String(versionId == null ? '' : versionId)
+  if (!want) {
+    throw new Error('缺少版本记录 id，无法定位远端历史版本。')
+  }
+  const id = String(cardId)
+  // 缓存优先：时间线列表（fetchCardHistory）已按 (cardId, versionId) 填充过页内 schema，
+  // 命中即零网络请求返回（毫秒级）；未命中才走下面的分页翻找。
+  const cached = getCachedVersionSchema(id, want)
+  if (cached) {
+    log.info('命中版本 schema 缓存（零网络）', { cardId: id, versionId: want })
+    return { schema: cached.schema, record: { id: want, createTime: cached.createTime || '' } }
+  }
+  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 页面，请先运行 finmall-session-navigator 登录。')
+    await page.bringToFront()
+    const url = `/ubomp-web/IDC10013.do?sassAppId=${appId}&sassWorkspaceId=${workspaceId}`
+    let pageNo = 1
+    let totalPages = 1
+    do {
+      const resp = await finmallPostWithHeal(
+        page,
+        url,
+        { cardId: id, pageNo, pageSize: 100, sassAppId: appId, sassWorkspaceId: workspaceId },
+        'IDC10013.do',
+      )
+      const rawList = Array.isArray(resp && resp.schemaValueList) ? resp.schemaValueList : []
+      const hit = rawList.find((raw) => String(raw && raw.id != null ? raw.id : '') === want)
+      if (hit) {
+        const schema = typeof hit.schema === 'string' ? JSON.parse(hit.schema) : hit.schema
+        if (!schema || typeof schema !== 'object') {
+          throw new Error(`远端版本记录 #${want} 的 schema 为空或损坏，无法加载。`)
+        }
+        log.info('定位远端历史版本', { cardId: id, versionId: want, pageNo })
+        return {
+          schema,
+          record: {
+            id: String(hit.id != null ? hit.id : ''),
+            createTime: hit.createTime || '',
+          },
+        }
+      }
+      totalPages = Number(resp && resp.totalPages != null ? resp.totalPages : 1) || 1
+      pageNo += 1
+    } while (pageNo <= totalPages)
+    throw new Error(`远端历史中找不到版本记录 #${want}（cardId=${id}，共 ${totalPages} 页）。`)
+  } finally {
+    try { await browser.disconnect() } catch { /* ignore */ }
+  }
+}
+function summarizeHistoryItem(raw) {
+  let name = ''
+  let desc = ''
+  let version = ''
+  let platform = ''
+  let width = ''
+  let components = []
+  try {
+    const schema = typeof raw.schema === 'string' ? JSON.parse(raw.schema) : raw.schema || {}
+    name = schema.name || ''
+    desc = schema.desc || ''
+    version = schema.version || ''
+    platform = schema.platform || ''
+    width = (schema.view && schema.view.width) || ''
+    // 组件树挂在 view.components 下（schema 顶层只有 version/pageId/name/desc/platform/dictionary/view）
+    components = (schema.view && Array.isArray(schema.view.components)) ? schema.view.components : []
+  } catch {
+    /* 单条 schema 损坏不阻断时间线渲染，摘要退化为空 */
+  }
+  return {
+    id: String(raw.id != null ? raw.id : ''),
+    createTime: raw.createTime || '',
+    updateTime: raw.updateTime || '',
+    bizChannel: raw.bizChannel || '',
+    // @filestore/x → /minio/x（同源相对路径，经 8787 assetProxy 回源；与 adapter.js 约定一致）
+    screenshotPath: filestorePathToLocal(raw.screenshotUrl),
+    // compKeys / eventCount 仅服务端相邻 diff 消费，体积恒定（数十字节/条）
+    summary: {
+      name,
+      desc,
+      version,
+      platform,
+      width,
+      componentCount: components.length,
+      compKeys: components.map(compKey),
+      eventCount: countEvents(components),
+    },
+  }
+}
+
+/** 组件 diff 标识：componentId::className（同卡内 componentId 稳定，跨版本可比） */
+function compKey(c) {
+  return `${c && c.componentId != null ? c.componentId : ''}::${c && c.className != null ? c.className : ''}`
+}
+
+/** 交互事件总数：各组 eventactions 条目数之和（事件代码增删的粗粒度信号） */
+function countEvents(comps) {
+  return comps.reduce((n, c) => n + (Array.isArray(c && c.eventactions) ? c.eventactions.length : 0), 0)
+}
+
+/** @filestore/ 前缀切为同源 /minio/ 相对路径；已是绝对地址则原样返回 */
+function filestorePathToLocal(value) {
+  if (!value || typeof value !== 'string') return ''
+  if (value.startsWith('http://') || value.startsWith('https://')) return value
+  if (value.startsWith('@filestore/')) return '/minio/' + value.slice('@filestore/'.length)
+  if (value.startsWith('/')) return value
+  return filestoreToUrl(value)
+}
+
+/**
+ * 相邻版本 diff 摘要：相对更旧版本算变更标签（组件增减 / 交互事件变化 / 重命名 /
+ * 描述变更 / 画布宽度变化 / 结构未变）。tags 为字符串数组，前端直接渲染徽标。
+ */
+function diffHistoryTags(cur, older) {
+  if (!older) return ['初始版本']
+  const curIds = new Set(cur.compKeys)
+  const oldIds = new Set(older.compKeys)
+  let added = 0
+  let removed = 0
+  for (const k of curIds) if (!oldIds.has(k)) added += 1
+  for (const k of oldIds) if (!curIds.has(k)) removed += 1
+  const tags = []
+  if (added > 0) tags.push(`新增 ${added} 个组件`)
+  if (removed > 0) tags.push(`移除 ${removed} 个组件`)
+  if (cur.eventCount !== older.eventCount) tags.push(`交互事件 ${older.eventCount} → ${cur.eventCount}`)
+  if (cur.name !== older.name) tags.push('重命名')
+  if (cur.desc !== older.desc) tags.push('描述变更')
+  if (cur.width !== older.width) tags.push(`画布宽度 ${older.width} → ${cur.width}`)
+  if (tags.length === 0) tags.push('结构未变')
+  return tags
+}
+
 // —— 保存落库校验辅助 ——
 
 /** 稳定序列化：对象键排序、带 id/key/className/name 的数组元素按该键排序，避免服务端字段重排导致指纹误判。 */
@@ -632,15 +1263,17 @@ async function fetchCardSchema(page, card, { appId, workspaceId }) {
 /** 清空过期会话并以保存的凭据重新登录（复用导航器的登录逻辑，全程在页面上下文内完成）。 */
 async function relogin(page) {
   await clearTimeoutPrompts(page);
-  await page
-    .evaluate(() => {
+  await withTimeout(
+    page.evaluate(() => {
       try {
         localStorage.clear();
       } catch {
         /* ignore */
       }
-    })
-    .catch(() => {});
+    }),
+    FINMALL_POST_TIMEOUT_MS,
+    'page.evaluate(localStorage.clear)',
+  ).catch(() => {});
   await page.reload({ waitUntil: "domcontentloaded", timeout: 15000 }).catch(() => {});
   await sleep(1500);
   const credentials = await loadCredentials();
@@ -955,6 +1588,7 @@ async function findExistingCover(cardDir, id) {
 async function writeImportSidecar(cardDir, { appId, workspaceId, card, files, importMeta }) {
   try {
     const mod = importMeta || (await import(pathToFileURL(path.resolve(workspace, 'server', 'core', 'cardImportMeta.js')).href));
+    const raw = card.raw || {};
     const meta = mod.buildImportMeta({
       baseUrl: finmallConfig.baseUrl,
       appId,
@@ -963,6 +1597,14 @@ async function writeImportSidecar(cardDir, { appId, workspaceId, card, files, im
       cardCode: card.id,
       cardName: card.title,
       files,
+      // 远端列表元数据原样快照：导入包（cards.json）的 picUrl / cardClassId / applyScene
+      // 只能从这里取真值，本地无处可推。缺了它导出侧只能伪造或留空，而留空会让
+      // 导入侧按空串推封面文件名、退化成卡目录路径并抛异常（2026-10-22 事故）。
+      remote: {
+        picUrl: typeof raw.picUrl === 'string' ? raw.picUrl : '',
+        cardClassId: raw.cardClassId == null ? '' : String(raw.cardClassId),
+        applyScene: raw.applyScene == null ? '' : String(raw.applyScene),
+      },
     });
     mod.writeImportMeta(cardDir, meta);
   } catch (e) {