cardbuddy 0.20.0 → 0.21.0

package/dist/vendored/server/core/cardImportMeta.js

@@ -26,8 +26,9 @@ export const META_SCHEMA_VERSION = 1
  * @param {string} o.cardCode   英文卡 id（目录名）
  * @param {string} [o.cardName] 卡片标题
  * @param {object} [o.files]    { schema, data, cover } 字节数
+ * @param {object} [o.remote]   远端列表元数据快照（picUrl / cardClassId / applyScene）
  */
-export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode, cardName, files }) {
+export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode, cardName, files, remote }) {
   return {
     schemaVersion: META_SCHEMA_VERSION,
     source: 'IDC10012',
@@ -39,6 +40,10 @@ export function buildImportMeta({ baseUrl, appId, workspaceId, cardId, cardCode,
     cardCode: cardCode || '',
     cardName: cardName || '',
     files: files || null,
+    // 远端卡片列表（IDC10001）才有、本地 DSL 产品数据不持久化的元数据：picUrl / cardClassId / applyScene。
+    // 导出包必须带上**真值**：导入侧（ImportCardAction.java:61-64）无条件按 cardPO.picUrl 末段
+    // 推文件名去读卡目录根的封面，picUrl 为空会退化成目录路径、直接抛异常。真值只在同步时可获得。
+    remote: remote || null,
     syncedAt: new Date().toISOString(),
     tool: 'finmall-card-sync',
     dirty: false, // 本地编辑后偏离导入镜像为 true（重置为导入镜像后回 false）

package/dist/vendored/server/core/cardPublishVersions.js

@@ -0,0 +1,91 @@
+import { pathToFileURL } from 'node:url'
+import { findCardDir } from './cardSidecar.js'
+import { readImportMeta } from './cardImportMeta.js'
+import { log } from './logger.js'
+import { resolveSkillPathOrProject } from './skillPaths.js'
+
+const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
+
+/**
+ * 调试面板「导入信息」tab「发布版本记录」弹框的远端数据源（只读）：
+ * GET /__card-publish-versions/:cardCode?pageNo=&pageSize=
+ *
+ * 语义：经 .import-meta.json 侧车里的 cardId 调 IDC10004，取该卡发布版本记录分页（新→旧），
+ * 每条含版本号 / 平台（iOS·Android·HarmonyOS 子集）/ 发布状态 / 发布时间。
+ * 触发时机由前端控制（打开弹框 / 滚动到底懒加载下一页），不自动轮询——与「编辑记录」tab
+ * 的懒加载策略一致，避免每次加载卡片都拉起后台 Chrome。
+ *
+ * 安全闸（与 /__card-history / /__card-version 同源）：仅「已同步导入卡」（有
+ * .import-meta.json 侧车且含 cardId）可查；本地自建卡 / 未同步卡返回 409 local_card_no_source。
+ *
+ * @param {{ root: string }} opts
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createCardPublishVersionsMiddleware({ root }) {
+  return function cardPublishVersionsMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const m = pathname.match(/^\/__card-publish-versions\/([^/]+)$/)
+    if (!m) return next()
+    if ((req.method || 'GET').toUpperCase() !== 'GET') return next()
+
+    const id = decodeURIComponent(m[1])
+    const dir = findCardDir(root, { code: id })
+    const meta = dir ? readImportMeta(dir) : null
+    if (!meta || !meta.cardId) {
+      res.statusCode = 409
+      res.setHeader('Content-Type', 'application/json')
+      return res.end(
+        JSON.stringify({
+          ok: false,
+          error: 'local_card_no_source',
+          message: '该卡片为本地自建、无远端同步来源（缺少 .import-meta.json 侧车），无法查看发布版本记录。',
+        }),
+      )
+    }
+
+    const qs = new URL(req.url || '/', 'http://localhost').searchParams
+    const pageNo = Math.max(1, parseInt(qs.get('pageNo') || '1', 10) || 1)
+    const pageSize = Math.min(100, Math.max(1, parseInt(qs.get('pageSize') || '10', 10) || 10))
+
+    ;(async () => {
+      try {
+        const skillPath = resolveSkillPathOrProject(root, SYNC_SCRIPT_REL)
+        const { fetchCardPublishVersions } = await import(pathToFileURL(skillPath).href)
+        const r = await fetchCardPublishVersions(meta.cardId, { pageNo, pageSize })
+        log.ok('查询远端发布版本记录', {
+          cardCode: id,
+          cardId: String(meta.cardId),
+          pageNo,
+          count: r.list.length,
+        })
+        res.statusCode = 200
+        res.setHeader('Content-Type', 'application/json')
+        res.setHeader('Cache-Control', 'no-store')
+        res.end(
+          JSON.stringify({
+            ok: true,
+            cardId: String(meta.cardId),
+            cardCode: id,
+            list: r.list,
+            maxVersion: r.maxVersion,
+            totalNums: r.totalNums,
+            totalPages: r.totalPages,
+          }),
+        )
+      } catch (e) {
+        // 区分「凭据缺失」与「真正的查询错误」：前者让前端提示登录，而非裸抛 ENOENT。
+        const isNoCred =
+          e && /credentials\.json|credentials 不存在|NO_CREDENTIALS/.test(String(e && e.message))
+        res.statusCode = isNoCred ? 200 : 500
+        res.setHeader('Content-Type', 'application/json')
+        res.end(
+          JSON.stringify(
+            isNoCred
+              ? { error: 'need_credentials', needCredentials: true, message: String(e && e.message) }
+              : { error: 'publish versions failed', message: String(e && e.message) },
+          ),
+        )
+      }
+    })()
+  }
+}

package/dist/vendored/server/core/cardSave.js

@@ -9,17 +9,115 @@ import { checkPushAllowed } from './cardListCache.js'
 import { assertRemoteSource, findCardDir } from './cardSidecar.js'
 import { log } from './logger.js'
 import { resolveSkillPathOrProject } from './skillPaths.js'
+import { generateCardCover } from './screenshot.js'
+import { serialize } from './browser.js'
 
 /** 远端保存脚本相对 skills/ 的路径（与「同步」共用 finmall-card-sync） */
 const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
 
+/**
+ * 推送成功后「截图 + 上传为远端预览图」的整段预算。
+ *
+ * 为什么要预算：这一步串了无头渲染（首次拉起 Chrome 可达数秒）与一次跨网 HTTPS 上传，
+ * 两步各有 30s 级超时。不设总闸的话，最坏情况会把 /__save 的响应拖到 1 分钟以上——
+ * 用户看到的是「点了推送一直在转圈」，而卡片内容其实早就写成功了。到点即放弃并
+ * 在响应里带 preview.error 说明，不影响推送本身的成功结论。
+ */
+const PUSH_PREVIEW_TIMEOUT_MS = Number(process.env.CARDBUDDY_PUSH_PREVIEW_TIMEOUT_MS || 45000)
+
+/**
+ * 推送成功后自动更新远端预览图的总开关（默认开）。
+ * 需要临时关闭时设 `CARDBUDDY_PUSH_PREVIEW=0`（例如远端图片库维护中，避免每条推送都多等一次失败）。
+ */
+const PUSH_PREVIEW_ENABLED = process.env.CARDBUDDY_PUSH_PREVIEW !== '0'
+
+/** 带总时限的 Promise 竞速（超时不取消底层任务，只放弃等待） */
+function withDeadline(promise, ms, label) {
+  let timer
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label}超时（>${ms}ms），已放弃`)), ms)
+    }),
+  ]).finally(() => clearTimeout(timer))
+}
+
+/**
+ * 推送成功后把「当前卡片」截图上传为远端预览图（IDC10014.do）。
+ *
+ * 为什么放在服务端而不是前端：①截图走本地无头渲染（screenshot.js 单例 Chrome），
+ * 与「预览图」按钮同一条链路，产出透明底、与卡片实际渲染尺寸 1:1 的 PNG；
+ * ②上传必须带 FinMall token，只有已登录的后台会话拿得到，前端不接触凭据。
+ *
+ * 三条纪律：
+ *   - **best-effort**：任何失败都返回结构化结果，绝不向上抛——预览图是推送的附加产物，
+ *     不能让它把「卡片已保存到远端」这个既成事实变成一次报错；
+ *   - **不写本地预览图**：只上传，不覆盖 src/cards/<id>/<id>.png。写盘会触发 watcher 的
+ *     cards-changed，而截图 + 上传耗时可能超出前端 2.5s 的自保存抑制窗口，会误弹
+ *     「卡片已在编辑器外被修改」——本地封面仍由「预览图」按钮显式生成（单一触发点）；
+ *   - **渲染基于磁盘态**：调用方（前端「推送」）需先确保未保存编辑已落盘，否则截到的是
+ *     上一版布局（见 App.vue saveToRemote 的前置 saveCard）。
+ *
+ * @param {object} opts
+ * @param {string} opts.cardCode        卡片目录名（= 英文卡 id，截图入口用它定位卡片）
+ * @param {string|number} opts.cardId   数字型远端 cardId（= schema.pageId，IDC10014.do 主键）
+ * @param {number} [opts.width]         卡片设计宽度（缺省 375，取自 schema.view.width）
+ * @param {unknown[]} [opts.components] 卡片组件数组（用于识别空白卡：空数组时不截图）
+ * @param {(p: {cardId: string, pngBase64: string}) => Promise<object>} opts.upload
+ *                                      上传实现（注入 skill 的 uploadCardPreview）
+ * @param {(id: string, o?: object) => Promise<object>} [opts.shoot]
+ *                                      截图实现（默认 generateCardCover；单测可注入）
+ * @returns {Promise<{ ok: boolean, width?: number|null, height?: number|null, bytes?: number, url?: string, error?: string, message?: string }>}
+ */
+export async function uploadPreviewAfterPush({
+  cardCode,
+  cardId,
+  width,
+  components,
+  upload,
+  shoot = generateCardCover,
+} = {}) {
+  if (!cardCode) return { ok: false, error: 'no_card_code', message: '未定位到卡片目录，跳过预览图上传' }
+  if (!cardId) return { ok: false, error: 'no_card_id', message: '缺少数字型 cardId，跳过预览图上传' }
+  if (typeof upload !== 'function') {
+    return { ok: false, error: 'upload_unavailable', message: '当前 skill 未提供 uploadCardPreview，跳过预览图上传' }
+  }
+  // 空白卡（组件数组为空）：无头渲染只会得到一张纯透明图，传上去等于把列表缩略图刷没。
+  // 与 /__card-image 的 422 判定同源（那里同样按「数组存在且为空」认定空白卡）。
+  if (Array.isArray(components) && !components.length) {
+    return { ok: false, error: 'empty-card', message: '空白卡（无组件）没有可预览内容，跳过预览图上传' }
+  }
+
+  // 与 /__card-image、/__screenshot 共用同一浏览器单例 + 串行队列，避免同时渲多张打爆内存
+  const shot = await serialize(() => shoot(cardCode, { width: Number(width) > 0 ? Number(width) : 375 }))
+  if (!shot || shot.tooBusy) {
+    return { ok: false, error: 'too-busy', message: '截图队列已满，跳过预览图上传' }
+  }
+  if (!shot.buffer) {
+    return { ok: false, error: shot.error || 'screenshot-failed', message: shot.message || '截图失败' }
+  }
+
+  const uploaded = await upload({ cardId: String(cardId), pngBase64: shot.buffer.toString('base64') })
+  return {
+    ok: true,
+    width: shot.width,
+    height: shot.height,
+    bytes: shot.buffer.length,
+    url: (uploaded && uploaded.url) || '',
+  }
+}
+
 /**
  * 远端保存（写回 FinMall）服务端处理。
  * 前端「保存」按钮把当前预览的 schema（含实时数据绑定）POST 过来，
  * 本中间件校验 pageId 后，经已登录浏览器中转调用 IDC10010.do 写回远端，
  * 与「同步」共用 finmall-card-sync 的 saveCardToRemote（带会话自愈）。
+ *
+ * @param {{ root: string, previewAfterPush?: typeof uploadPreviewAfterPush }} opts
+ *   - previewAfterPush：推送成功后的「截图 + 上传预览图」实现，默认即上面的
+ *     uploadPreviewAfterPush；单测注入替身以便在无 Chrome / 无 FinMall 会话的环境断言接线。
  */
-export function createSaveMiddleware({ root }) {
+export function createSaveMiddleware({ root, previewAfterPush = uploadPreviewAfterPush }) {
   return async function saveMiddleware(req, res, next) {
     const pathname = decodeURIComponent((req.url || '').split('?')[0])
     const method = (req.method || 'GET').toUpperCase()
@@ -102,17 +200,18 @@ export function createSaveMiddleware({ root }) {
           pathToFileURL(resolveSkillPathOrProject(root || process.cwd(), SYNC_SCRIPT_REL)).href
         )
         const { response, verified } = await mod.saveCardToRemote(schema, { skeletonScreen })
+        // 卡片目录反查只做一次：既供导出元数据落盘，也供随后的预览图截图定位（目录名 = 英文卡 id）。
+        const cardDir = root ? findCardDir(root, { code, pageId: schema.pageId }) : null
         // 导出可追溯（Phase E）：把远端保存的读回校验结果写进导入元数据侧车。
         // 注意：目录按 cardCode 命名，必须按 pageId 反查到正确的 src/cards/<cardCode>/。
         if (root) {
           try {
-            const dir = findCardDir(root, { pageId: schema.pageId })
-            if (dir) {
-              await recordExport(dir, verified)
+            if (cardDir) {
+              await recordExport(cardDir, verified)
               // 推送成功即与远端对齐：清除「偏离导入镜像」标记（来源 tab 据此提示）。
               // 注：本地磁盘（含编辑）仍可能 ≠ 当初导入镜像，此处语义转为「已与远端同步」，
               // 符合用户预期——推送到远端后不应再被标为「偏离」。
-              await markDirty(dir, false)
+              await markDirty(cardDir, false)
             } else console.warn(`[__save] 未找到 pageId=${schema.pageId} 对应的本地卡片目录，跳过导出元数据`)
           } catch (e) {
             log.warn('写导出元数据失败（不影响保存结果）', { error: e && e.message })
@@ -126,9 +225,47 @@ export function createSaveMiddleware({ root }) {
         if (!verified.fingerprintMatched && verified.diff && verified.diff.length) {
           log.warn('指纹不匹配（落库内容与本地不一致）', { diff: verified.diff.slice(0, 3) })
         }
+
+        // 推送成功后自动更新远端预览图：本地无头渲染当前卡片 → IDC10014.do 上传。
+        // 全程 best-effort：失败只记日志 + 在响应里带 preview.error，推送本身的成功结论不受影响。
+        let preview = null
+        if (PUSH_PREVIEW_ENABLED) {
+          try {
+            preview = await withDeadline(
+              previewAfterPush({
+                cardCode: cardDir ? path.basename(cardDir) : '',
+                cardId: String(schema.pageId),
+                width: Number((schema.view && schema.view.width) || 0),
+                components: schema.view && schema.view.components,
+                upload: typeof mod.uploadCardPreview === 'function' ? mod.uploadCardPreview : null,
+              }),
+              PUSH_PREVIEW_TIMEOUT_MS,
+              '推送后预览图上传',
+            )
+          } catch (e) {
+            preview = { ok: false, error: 'preview_failed', message: String(e && e.message) }
+          }
+          if (preview && preview.ok) {
+            log.ok('推送后预览图已更新', {
+              cardId: String(schema.pageId),
+              width: preview.width,
+              height: preview.height,
+              bytes: preview.bytes,
+            })
+          } else {
+            log.warn('推送成功但预览图未更新（不影响卡片内容）', {
+              cardId: String(schema.pageId),
+              error: (preview && preview.error) || 'unknown',
+              message: (preview && preview.message) || '',
+            })
+          }
+        }
+
         res.statusCode = 200
         res.setHeader('Content-Type', 'application/json')
-        return res.end(JSON.stringify({ ok: true, code, cardId: String(schema.pageId), response, verified }))
+        return res.end(
+          JSON.stringify({ ok: true, code, cardId: String(schema.pageId), response, verified, preview }),
+        )
       } catch (e) {
         log.error('远端保存失败', e)
         res.statusCode = 502

package/dist/vendored/server/core/cardSync.js

@@ -13,6 +13,19 @@ const SYNC_SCRIPT_REL = 'finmall-card-sync/scripts/api_batch_sync.mjs'
 /** 卡片 id 合法形态（与 normalizeCard / 新建卡同源正则） */
 const CARD_CODE_RE = /^[A-Za-z0-9_-]+$/
 
+/**
+ * 同步任务硬超时（看门狗）。
+ *
+ * 为什么必须有：同步中间件是单飞制（`activeSyncJob()` 未终态时，之后每次 POST /__sync 都拿
+ * 409「已有同步任务正在进行」）。而同步链路上游仍有「await 一个永不 settle 的 Promise」的
+ * 可能（page.evaluate 无默认超时、页面内 fetch 挂起、CDP 连接半死等）——一旦某个任务挂在
+ * 这种 await 上，`finally { job.finished = true }` 永远不执行，单飞锁被永久占用，
+ * 用户侧表现就是「点了远端同步、服务端再也不响应」。
+ * 看门狗到点把任务判超时收尾（置 cancelRequested 让 syncCards 在下一张卡片前退出、
+ * 直接标 finished 释放锁），保证任何单次同步都不会无限期占用服务。
+ */
+const SYNC_JOB_TIMEOUT_MS = Number(process.env.CARDBUDDY_SYNC_JOB_TIMEOUT_MS || 10 * 60 * 1000)
+
 /**
  * 同步任务表（进程内单例）。
  * 任务制模型：POST /__sync 立即返回 jobId，syncCards 在后台跑；
@@ -249,12 +262,37 @@ export function createSyncMiddleware({ root }) {
         id: `sj-${Date.now().toString(36)}-${syncJobSeq}`,
         createdAt: Date.now(),
         cancelRequested: false,
+        timedOut: false,
         finished: false,
         progress: { done: 0, total: cardCode ? 1 : cardCodes ? cardCodes.length : 0, currentId: '', currentTitle: '' },
         result: null,
       }
       rememberSyncJob(job)
 
+      // 看门狗：硬超时兜底。同步链路里仍有「await 一个永不 settle 的 Promise」的可能
+      // （page.evaluate 无默认超时 / 页面内 fetch 挂起 / CDP 半死），一旦挂住，下面 IIFE 的
+      // finally 永远不执行 → 单飞锁被永久占用 → 之后每次同步都 409，用户侧就是「服务端僵死」。
+      // 到点后代它收尾：置 cancelRequested 让 syncCards 在下一张卡片前退出，并直接标 finished
+      // 释放锁；后台任务若稍后真的返回，也以看门狗的结论为准（不再回滚成「成功」误导用户）。
+      const watchdog = setTimeout(() => {
+        if (job.finished) return
+        job.timedOut = true
+        job.cancelRequested = true
+        job.finished = true
+        job.result = {
+          success: false,
+          timedOut: true,
+          error: `同步任务超过 ${Math.round(SYNC_JOB_TIMEOUT_MS / 1000)} 秒未完成，已自动收尾（上游无响应）。请重试，或检查 FinMall 登录态 / 网络。`,
+        }
+        log.error('远端同步看门狗触发：任务超时，已代其收尾并释放同步锁', {
+          jobId: job.id,
+          timeoutMs: SYNC_JOB_TIMEOUT_MS,
+          done: job.progress.done,
+          currentId: job.progress.currentId,
+        })
+      }, SYNC_JOB_TIMEOUT_MS)
+      if (typeof watchdog.unref === 'function') watchdog.unref()
+
       // 后台跑同步：请求立即返回，前端轮询 progress
       ;(async () => {
         try {
@@ -281,12 +319,15 @@ export function createSyncMiddleware({ root }) {
             },
             shouldCancel: () => job.cancelRequested,
           })
-          job.result = {
-            success: !!summary.success,
-            cancelled: !!summary.cancelled,
-            synced: summary.synced || [],
-            failed: summary.failed || [],
-            duplicates: summary.duplicates || [],
+          // 看门狗已代收尾时不回滚结论：用户当时已经收到「超时」结论，迟到的成功会造成错觉
+          if (!job.timedOut) {
+            job.result = {
+              success: !!summary.success,
+              cancelled: !!summary.cancelled,
+              synced: summary.synced || [],
+              failed: summary.failed || [],
+              duplicates: summary.duplicates || [],
+            }
           }
           logSyncSummary(summary, cardCode ? cardCode : cardCodes ? `勾选 ${cardCodes.length} 张` : '(全部)')
         } catch (e) {
@@ -297,6 +338,7 @@ export function createSyncMiddleware({ root }) {
             log.error('远端同步失败', e)
           }
         } finally {
+          clearTimeout(watchdog)
           job.finished = true
         }
       })()

package/dist/vendored/server/core/index.js

@@ -14,8 +14,10 @@ import { createSyncMiddleware, createPreviewMiddleware, createLoginCredentialsMi
 import { createPublishMiddleware } from './cardPublish.js'
 import { createCardVersionMiddleware } from './cardVersion.js'
 import { createCardHistoryMiddleware } from './cardHistoryRemote.js'
+import { createCardPublishVersionsMiddleware } from './cardPublishVersions.js'
 import { createSliceUploadMiddleware } from './sliceUpload.js'
 import { createCardFilesMiddleware, refreshCardList } from './cardFiles.js'
+import { createExportMiddleware } from './cardExport.js'
 import { createSaveMiddleware } from './cardSave.js'
 import { createImportMetaMiddleware } from './cardImportMeta.js'
 import { createHistoryMiddleware } from './cardHistory.js'
@@ -48,10 +50,12 @@ export {
   createPublishMiddleware,
   createCardVersionMiddleware,
   createCardHistoryMiddleware,
+  createCardPublishVersionsMiddleware,
   createSliceUploadMiddleware,
   createCardFilesMiddleware,
   createSaveMiddleware,
   createImportMetaMiddleware,
+  createExportMiddleware,
   createHistoryMiddleware,
   createValidateMiddleware,
   createRenderStatusMiddleware,
@@ -103,12 +107,19 @@ export function mountCoreMiddlewares(app, { root, viteServer = null, upstream =
   // 「卡片历史记录」tab 的远端版本时间线（只读）：GET /__card-history/:cardCode 取 IDC10013 的
   // schemaValueList（新→旧，含预览图 / 变更标签），复用 finmall-card-sync 的 fetchCardHistory。
   app.use(createCardHistoryMiddleware({ root }))
+  // 「导入信息」tab「发布版本记录」弹框的数据源（只读）：GET /__card-publish-versions/:cardCode
+  // 取 IDC10004 的 versionList（新→旧，版本号 / 平台 / 发布状态 / 发布时间），滚动到底懒加载下一页。
+  app.use(createCardPublishVersionsMiddleware({ root }))
   // 切图上传（顶栏「远端 → 切图上传」）：把当前卡引用的 src/slices 切图传到 FinMall 图片库，
   // 写 src/slices/manifest.json 映射并把卡片里的 /slices/ 引用改写为 @filestore/ 线上地址。
   // 仅在用户点击时触发，没有任何自动上传路径。
   app.use(createSliceUploadMiddleware({ root }))
   app.use(createCardFilesMiddleware({ root, notify }))
   app.use(createSaveMiddleware({ root }))
+  // 卡片导出（编辑器「网格预览 → 勾选 → 导出」）：产物契约见 server/core/cardExport.js 头注释
+  // 与 docs/卡片导出产物逆向分析与导出功能.md；previewSchema 经 viteServer.ssrLoadModule 复用
+  // 编辑器同源 buildPreview，故本中间件需要 viteServer（无则退化为 schema 原样序列化）。
+  app.use(createExportMiddleware({ root, viteServer, upstream }))
   app.use(createHistoryMiddleware({ root }))
   app.use(createValidateMiddleware({ root }))
   app.use(createRenderStatusMiddleware({ root, viteServer }))

package/dist/vendored/skills/finmall-card-sync/SKILL.md

@@ -212,6 +212,52 @@ headers: token / iCIFID / eCIFID = localStorage._sessionId（只在页面上下
 | CLI 跑完进程不退出 | 已修：CLI 末尾显式 `process.exit`（后台 Chrome 的 CDP 连接会挂住事件循环）；Chrome 进程本身按约定常驻不关 |
 | 想撤销改写 | `git checkout -- src/cards/<id>/`；清单里的地址仍有效，重跑一次即可再改写回来 |
 
+## 卡片预览图上传（推送成功后自动，`IDC10014.do`）
+
+编辑器顶栏「远端 → 推送」走 `POST /__save`（`saveCardToRemote`）。**推送成功后**，服务端会用无头
+Chrome 渲染当前卡片（`server/core/screenshot.js → generateCardCover`：透明底、与卡片实际渲染尺寸
+1:1 的 PNG），再把这张图作为**远端列表预览图**上传（`uploadCardPreview` → `IDC10014.do`），
+使 FinMall 卡片列表的缩略图与刚推上去的内容一致。
+
+| 项 | 值 |
+|---|---|
+| 触发点 | 仅 `/__save` 成功后，一个请求内完成（前端 `saveToRemote` 已带 2.5s 自保存抑制） |
+| 总预算 | 45s（`CARDBUDDY_PUSH_PREVIEW_TIMEOUT_MS`）；到点放弃等待，响应带 `preview.error` |
+| 开关 | `CARDBUDDY_PUSH_PREVIEW=0` 关闭（远端图片库维护时避免每条推送多等一次失败） |
+| 失败语义 | **best-effort**：日志 + 响应 `preview:{ok:false,error,message}`，推送本身的成功结论不变 |
+
+### 接口契约（`IDC10014.do`，取自线上编辑器抓包）
+
+```
+POST {baseUrl}/ubomp-web/IDC10014.do          # 注意：sassAppId/Workspace 走表单，不是查询串
+Content-Type: multipart/form-data
+  cardId          = 10000363                  # 数字型 cardId（= schema.pageId）
+  file            = <二进制 PNG>               # filename = <cardId>.png
+  sassAppId       = <FINMALL_APP_ID>
+  sassWorkspaceId = <FINMALL_WORKSPACE_ID>
+headers: token = localStorage._sessionId（只在页面上下文内读取，不出页面）
+```
+
+与切图上传（`CC0000.do`）的四点差异，改动时别混用：①字段是 `cardId` + `file`（**没有** `fileName`
+纯文本字段）；②`sassAppId/Workspace` 在表单里；③filename 固定 `<cardId>.png`（抓包里该 part 的
+Content-Type 是 `application/octet-stream`，照抄）；④鉴权头只有 `token`。
+
+响应判定按 FinMall 通用信封做**宽松**处理（`parsePreviewUploadResponse`）：空响应体视为成功；
+非 JSON 非空（网关 HTML 错误页）报错；`header.errorCode` 与 `body.errorCode` **逐个**检查
+（不能用 `a || b` 短路——`header.errorCode='0'` 会把 body 的业务错误盖掉）；成功时尽力取
+`body.picUrl | previewUrl | imageUrl | filePath | url`，取不到不影响「上传成功」。命中
+`BLEC0006` 等会话失效特征时自动清 session 重登并重试一次（与同步 / 切图同一套自愈）。
+
+### 两条刻意的「不做」
+
+- **不写本地预览图**：不覆盖 `src/cards/<id>/<id>.png`。截图+上传耗时可能超过前端 2.5s 自保存
+  抑制窗口，写盘会触发 watcher 的 `cards-changed`，误弹「卡片已在编辑器外被修改」；本地封面仍由
+  顶栏「预览图」按钮（`POST /__card-image/<id>`）显式生成——单一触发点。
+- **不参与同步 / 发布**：拉取方向由远端 `picUrl` 覆盖本地封面；「卡片发布」只上线版本，不改预览图。
+
+> 截图渲染的是**磁盘态** schema，故前端 `saveToRemote` 在有未保存编辑（`historyDirty`）时会先
+> 落盘再推送（与「切图上传」同一处置口径），否则会截到上一版布局。
+
 ## 变量与数据规则
 
 编辑器变量面板是 `schema.dictionary.inputParams[]` 的 UI 呈现：