cardbuddy 0.19.3 → 0.21.0

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

@@ -0,0 +1,831 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import zlib from 'node:zlib'
+import { spawn } from 'node:child_process'
+import { log } from './logger.js'
+import { readImportMeta } from './cardImportMeta.js'
+import { resolveCardDir } from './cardOpenFolder.js'
+
+/**
+ * 卡片导出端点（编辑器「卡片网格预览 → 勾选 → 导出」的服务端实现）。
+ *
+ * 产物契约（对桌面两份 FinMall 导出样本的逆向结论，详见
+ * docs/卡片导出产物逆向分析与导出功能.md）：
+ *   <targetDir>/<yyMMddHHmmss+4位序号>/        ← 临时文件夹（完成后删除）
+ *     cards.json                               ← 卡片清单（cardPO 数组，殿后写入）
+ *     <数字id>/<数字id>.json                   ← { cardPO, cardJobPO, variablePOS, imageLists, platformStatus }
+ *     <数字id>/<封面文件>                      ← 封面，文件名恒等于 cards.json 里该卡 picUrl 的末段
+ *     <数字id>/image/<imageName>               ← schema.view 树引用的 @filestore 图片下载落盘
+ *   <targetDir>/<同名>.zip                     ← 纯 Node 写出的 zip（条目平铺、无顶层文件夹）
+ *
+ * 封面铁律（2026-10-22 事故后定，依据 57 张官方导出样本 + ImportCardAction.java:61-64）：
+ * - picUrl 恒非空，且末段 === `<数字id>/` 下封面文件名。导入侧按 picUrl 末段推文件名后直接读该文件，
+ *   对所有空值/缺失零防御（空串时路径退化成卡目录，读目录抛异常）。
+ * - 无本地封面的卡**不允许导出**（计入 failed 并给出补齐指引），不产「有卡无封面」的残包。
+ * - 有 `.import-meta.json` 的 remote 快照时沿用远端真值（picUrl/cardClassId/applyScene）；
+ *   本地新建卡按同一形态合成 picUrl，cardClassId 留空、applyScene 回落 '1'。
+ * - 写 zip 前跑 verifyCardsJsonInvariants 自检，违例即整单失败。
+ * 任务制端点（与 /__sync 同构：单飞制 + 看门狗 + 轮询 + 取消）：
+ * - POST /__export-cards          body { cardIds[], targetDir } → { ok, jobId, total }
+ * - GET  /__export/progress?jobId → { ok, done, total, currentId, currentTitle, finished, result }
+ * - POST /__export/cancel         body { jobId } → 下一张卡片前中止（已写内容随任务清理）
+ * - GET  /__export/dir-suggestions → { ok, home, desktop, downloads, default }
+ *
+ * previewSchema 生成复用编辑器同源实现：经 viteServer.ssrLoadModule 加载
+ * card-editor/runtime/toPreview.js 的 buildPreview（与 SSR 自检端点同一模式），
+ * 无 vite 实例时退化为 schema 原样序列化（可用但非预览态）。
+ */
+
+/** 单次导出勾选上限（与 /__sync 的 500 上限同口径） */
+const MAX_EXPORT_CARDS = 500
+
+/** 导出任务硬超时（看门狗）：大批量卡片下载图片可能很慢，10 分钟不收尾即代收 */
+const EXPORT_JOB_TIMEOUT_MS = Number(process.env.CARDBUDDY_EXPORT_JOB_TIMEOUT_MS || 10 * 60 * 1000)
+
+/** 图片下载超时（与资源代理回源超时同口径） */
+const IMAGE_FETCH_TIMEOUT_MS = 12000
+
+/** 封面候选扩展名（与 finmall-card-sync 的 findExistingCover 同集） */
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg'])
+
+/**
+ * 本地无远端 picUrl 时，封面在包内所用的 filestore 前缀。
+ * 依据 57 张官方导出的实测：picUrl 恒为 `@filestore/<桶名>/<文件名>`，桶名出现两种
+ * （dzqd-download 54 张、sit-public-cbbiz 3 张）——说明导入侧只取末段做文件名，桶名不参与校验。
+ * 取多数派即可，不必也无法还原真实桶。
+ */
+const COVER_FILESTORE_PREFIX = '@filestore/dzqd-download'
+
+/** 平台状态常量：两份样本恒为三端全平台（与 FinMall 发布接口默认平台集一致） */
+const PLATFORM_STATUS = ['iOS', 'Android', 'HarmonyOS']
+
+/** 最小合法骨架屏 SVG：样本为线上编辑器按布局生成，本地不做布局推测，占位保证字段非空 */
+const MIN_SKELETON =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="375" height="200" viewBox="0 0 375 200">' +
+  '<rect width="100%" height="100%" fill="#ffffff"/></svg>'
+
+/* ------------------------------ 任务表（单例） ------------------------------ */
+
+const exportJobs = new Map() // jobId -> job
+const EXPORT_JOB_KEEP = 8
+let exportJobSeq = 0
+
+function activeExportJob() {
+  for (const job of exportJobs.values()) {
+    if (!job.finished) return job
+  }
+  return null
+}
+
+function rememberExportJob(job) {
+  exportJobs.set(job.id, job)
+  while (exportJobs.size > EXPORT_JOB_KEEP) {
+    const oldest = exportJobs.keys().next().value
+    exportJobs.delete(oldest)
+  }
+}
+
+/* ------------------------------ ZIP 写入器（纯 Node） ------------------------------ */
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n += 1) {
+    let c = n
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c >>> 0
+  }
+  return t
+})()
+
+function crc32(buf) {
+  let c = 0xffffffff
+  for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+function dosDateTime(d) {
+  const time = ((d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1)) & 0xffff
+  const date = (((d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate()) & 0xffff
+  return { time, date }
+}
+
+/**
+ * 生成 zip 文件字节（无外部依赖，条目平铺、不含目录项、不含顶层文件夹）。
+ * 每条目自动在 deflate / store 中取小者；非 ASCII 文件名置 UTF-8 标志位（bit 11），
+ * 保证中文 imageName 在 unzip 后不乱码（样本产物的图片名大量含中文）。
+ * @param {Array<{ name: string, data: Buffer }>} entries
+ * @param {Date} [when] 条目时间戳（默认现在）
+ * @returns {Buffer}
+ */
+function buildZip(entries, when = new Date()) {
+  const { time, date } = dosDateTime(when)
+  const chunks = []
+  const central = []
+  let offset = 0
+
+  for (const entry of entries) {
+    const nameBuf = Buffer.from(entry.name, 'utf8')
+    const raw = entry.data
+    const deflated = zlib.deflateRawSync(raw, { level: 9 })
+    // 已压缩数据（png/jpg）deflate 可能反而变大：取小者，方法号随之切换
+    const useDeflate = deflated.length < raw.length
+    const body = useDeflate ? deflated : raw
+    const method = useDeflate ? 8 : 0
+    const crc = crc32(raw)
+    // 非 ASCII 名置 UTF-8 语言编码标志（EFS）
+    const flags = /[^\x20-\x7e]/.test(entry.name) ? 0x0800 : 0
+
+    const local = Buffer.alloc(30)
+    local.writeUInt32LE(0x04034b50, 0) // local file header 签名
+    local.writeUInt16LE(20, 4) // 解压所需版本
+    local.writeUInt16LE(flags, 6)
+    local.writeUInt16LE(method, 8)
+    local.writeUInt16LE(time, 10)
+    local.writeUInt16LE(date, 12)
+    local.writeUInt32LE(crc, 14)
+    local.writeUInt32LE(body.length, 18) // 压缩后大小
+    local.writeUInt32LE(raw.length, 22) // 原始大小
+    local.writeUInt16LE(nameBuf.length, 26)
+    local.writeUInt16LE(0, 28) // extra 长度
+    chunks.push(local, nameBuf, body)
+
+    const cd = Buffer.alloc(46)
+    cd.writeUInt32LE(0x02014b50, 0) // central directory header 签名
+    cd.writeUInt16LE(20, 4) // 制作版本
+    cd.writeUInt16LE(20, 6) // 解压所需版本
+    cd.writeUInt16LE(flags, 8)
+    cd.writeUInt16LE(method, 10)
+    cd.writeUInt16LE(time, 12)
+    cd.writeUInt16LE(date, 14)
+    cd.writeUInt32LE(crc, 16)
+    cd.writeUInt32LE(body.length, 20)
+    cd.writeUInt32LE(raw.length, 24)
+    cd.writeUInt16LE(nameBuf.length, 28)
+    cd.writeUInt32LE(0, 38) // 外部属性（普通文件）
+    cd.writeUInt32LE(offset, 42) // 本地头偏移
+    central.push(cd, nameBuf)
+
+    offset += local.length + nameBuf.length + body.length
+  }
+
+  const cdBuf = Buffer.concat(central)
+  const eocd = Buffer.alloc(22)
+  eocd.writeUInt32LE(0x06054b50, 0)
+  eocd.writeUInt16LE(entries.length, 8)
+  eocd.writeUInt16LE(entries.length, 10)
+  eocd.writeUInt32LE(cdBuf.length, 12)
+  eocd.writeUInt32LE(offset, 16)
+
+  return Buffer.concat([...chunks, cdBuf, eocd])
+}
+
+/* ------------------------------ 平台 reveal ------------------------------ */
+
+/**
+ * 在系统文件管理器中 reveal 指定文件（选中态）。
+ * macOS: open -R；Windows: explorer /select,；Linux: xdg-open 所在目录。
+ * @returns {boolean} 是否成功触发（仅表示进程拉起）
+ */
+export function revealFileInOS(filePath) {
+  let spec = null
+  switch (process.platform) {
+    case 'darwin':
+      spec = { cmd: 'open', args: ['-R', filePath] }
+      break
+    case 'win32':
+      spec = { cmd: 'explorer', args: [`/select,${filePath}`] }
+      break
+    case 'linux':
+      spec = { cmd: 'xdg-open', args: [path.dirname(filePath)] }
+      break
+    default:
+      break
+  }
+  if (!spec) {
+    log.warn('reveal 文件不支持当前平台', { platform: process.platform })
+    return false
+  }
+  try {
+    const child = spawn(spec.cmd, spec.args, { shell: false, stdio: 'ignore' })
+    child.on('error', (e) => {
+      log.error('reveal 文件命令失败', { cmd: spec.cmd, message: String(e.message) })
+    })
+    return true
+  } catch (e) {
+    log.error('reveal 文件异常', e)
+    return false
+  }
+}
+
+/* ------------------------------ 产物构建 ------------------------------ */
+
+/** URL 段编码：已带 %XX 的段保持原样，其余段 encodeURIComponent（与资源代理同规则） */
+function encodePath(p) {
+  return p
+    .split('/')
+    .map((seg) => (/%[0-9a-fA-F]{2}/.test(seg) ? seg : encodeURIComponent(seg)))
+    .join('/')
+}
+
+/** @filestore/x → <upstream>/minio/x（minio 公网可读，无需凭据） */
+function filestoreUrlFor(ref, upstream) {
+  if (!upstream) return ''
+  if (ref.startsWith('@filestore/')) return `${upstream}/minio/${encodePath(ref.slice('@filestore/'.length))}`
+  if (ref.startsWith('/')) return `${upstream}${encodePath(ref)}`
+  return ''
+}
+
+/** 时间戳文件夹名：yyMMddHHmmss + 4 位序号（样本规律；重名顺延保证唯一） */
+function stampFolderName(targetDir, now = new Date()) {
+  const p = (n) => String(n).padStart(2, '0')
+  const base =
+    `${String(now.getFullYear() % 100).padStart(2, '0')}${p(now.getMonth() + 1)}${p(now.getDate())}` +
+    `${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`
+  for (let seq = 1; seq <= 9999; seq += 1) {
+    const name = base + String(seq).padStart(4, '0')
+    if (!fs.existsSync(path.join(targetDir, name)) && !fs.existsSync(path.join(targetDir, `${name}.zip`))) {
+      return name
+    }
+  }
+  // 9999 个同名全部占用（理论上不可能）：加随机后缀兜底
+  return base + Math.random().toString(36).slice(2, 6).padStart(4, '0')
+}
+
+/** 找本地封面预览图（<cardId>.<ext>）；没有返回 null（与 finmall-card-sync 同规则） */
+function findExistingCover(cardDir, id) {
+  let entries = []
+  try {
+    entries = fs.readdirSync(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
+}
+
+/**
+ * 采集 schema.view 组件树中的图片引用（首现序去重）。
+ * 规则（样本逆向结论）：仅 view 树，不含 dictionary；@filestore 走远端下载，
+ * /slices/ 走本地切图拷贝。两者按遍历首现顺序混合排列。
+ * @returns {Array<{ ref: string, kind: 'filestore'|'slice' }>}
+ */
+function collectViewImageRefs(view) {
+  const out = []
+  const seen = new Set()
+  const push = (ref) => {
+    if (seen.has(ref)) return
+    seen.add(ref)
+    if (ref.startsWith('@filestore/')) out.push({ ref, kind: 'filestore' })
+    else if (ref.startsWith('/slices/')) out.push({ ref, kind: 'slice' })
+  }
+  const walk = (v) => {
+    if (typeof v === 'string') {
+      // 与 imageLists 提取口径一致：字符串内可能嵌多个引用（如 style backgroundImage）
+      const re = /(?:@filestore\/|\/slices\/)[^\s"'\\)]+/g
+      let m
+      while ((m = re.exec(v)) !== null) push(m[0])
+      return
+    }
+    if (Array.isArray(v)) {
+      for (const x of v) walk(x)
+      return
+    }
+    if (v && typeof v === 'object') {
+      for (const x of Object.values(v)) walk(x)
+    }
+  }
+  walk(view)
+  return out
+}
+
+/** 末段文件名（@filestore 路径的 imageName；/slices/ 的切片名） */
+function refBasename(ref) {
+  const seg = ref.split('/').pop() || ''
+  return seg
+}
+
+/**
+ * 计算导出用的封面文件名与 `cardPO.picUrl`，两者必须自洽：**picUrl 末段 === 包内卡目录根的封面文件名**。
+ *
+ * 契约依据（57 张官方导出样本逐卡核对：picUrl 非空 57/57、末段与目录根封面文件名一致 57/57）：
+ * 导入侧 `ImportCardAction.java:61-64` 用 `extractFileNameMethod1(picUrl)` 得到文件名后
+ * `new File(cardUrl + File.separator + imageName)` 去读封面，**无任何空值/存在性防御**：
+ * picUrl 为空串时路径退化成卡目录本身，读目录抛异常，整卡导入失败。
+ * 故此处绝不允许产出空 picUrl。
+ *
+ * @param {{ remotePicUrl?: string, coverPath: string }} o
+ *   remotePicUrl：`.import-meta.json` 记录的远端真值（有则原样沿用，形态与官方产物同构）；
+ *   coverPath：本地封面绝对路径（无远端真值时以其文件名为准）。
+ * @returns {{ fileName: string, picUrl: string, inherited: boolean }}
+ */
+export function resolveCoverForExport({ remotePicUrl, coverPath }) {
+  const localName = path.basename(coverPath)
+  const remote = typeof remotePicUrl === 'string' ? remotePicUrl.trim() : ''
+  if (remote) {
+    // 远端真值可能带 query（极少见），取文件名时剥掉；picUrl 本身保持原样不重写
+    const name = path.basename(remote.split('?')[0].split('#')[0])
+    if (name) return { fileName: name, picUrl: remote, inherited: true }
+  }
+  return { fileName: localName, picUrl: `${COVER_FILESTORE_PREFIX}/${localName}`, inherited: false }
+}
+
+/**
+ * 产物自检：cards.json 的每条 cardPO 都能被导入侧无障碍消费。
+ * 只做**与后端无关**的结构断言（不依赖远端服务，纯本地即可证伪）：
+ * 1. picUrl 非空；
+ * 2. picUrl 末段在 `<id>/` 卡目录根存在且是文件（不是目录）；
+ * 3. 每张卡都有 `<id>/<id>.json`。
+ * 返回问题清单（空数组 = 通过）。任何一条违例都会被导入侧的同一段逻辑打出异常。
+ * @param {{ cardsPO: Array<object>, outDir: string }} o
+ * @returns {string[]}
+ */
+export function verifyCardsJsonInvariants({ cardsPO, outDir }) {
+  const problems = []
+  for (const po of cardsPO || []) {
+    const id = String(po && po.id)
+    const picUrl = po && po.picUrl
+    if (!picUrl) {
+      problems.push(`${id}: picUrl 为空（导入侧会按空串推封面文件名）`)
+      continue
+    }
+    const name = path.basename(String(picUrl).split('?')[0])
+    const coverAbs = path.join(outDir, id, name)
+    let stat = null
+    try {
+      stat = fs.statSync(coverAbs)
+    } catch {
+      /* 不存在即视为违例 */
+    }
+    if (!stat) problems.push(`${id}: 封面文件缺失 ${name}`)
+    else if (!stat.isFile()) problems.push(`${id}: 封面路径不是文件 ${name}`)
+    if (!fs.existsSync(path.join(outDir, id, `${id}.json`))) problems.push(`${id}: 单卡 JSON 缺失`)
+  }
+  return problems
+}
+
+
+/**
+ * 导出单张卡：写 <id>.json + 落图片/封面，返回 { cardPO, imageLists }。
+ * 图片下载失败不中断该卡（记 warnings），契约字段 imageLists 仍按全量引用生成。
+ */
+async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
+  const cardDir = resolveCardDir(root, id)
+  if (!cardDir) throw new Error('非法卡片 id')
+  const schemaPath = path.join(cardDir, 'schema.json')
+  let schema
+  try {
+    schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+  } catch (e) {
+    throw new Error(`读取 schema.json 失败：${e && e.message}`)
+  }
+  if (!schema || typeof schema !== 'object') throw new Error('schema.json 内容非法')
+
+  // 数字 id：优先 schema.pageId（导入卡与远端一致）；自建卡 pageId 常等于 code，回落目录名
+  const numericId = /^\d+$/.test(String(schema.pageId)) ? String(schema.pageId) : id
+
+  let meta = null
+  try {
+    meta = readImportMeta(cardDir)
+  } catch {
+    /* 侧车缺失/损坏不影响导出 */
+  }
+
+  // 封面先定：picUrl 与封面文件名是同一个决定，缺封面必须当场失败（不能产出自带空 picUrl 的包）。
+  const coverPath = findExistingCover(cardDir, id)
+  if (!coverPath) {
+    throw new Error(
+      `本地无封面图（src/cards/${id}/${id}.png）：导入侧无条件按 picUrl 末段读卡目录根的封面，` +
+        '无封面必导入失败。请先在卡片上「生成封面预览图」补齐，再重试导出'
+    )
+  }
+  const remoteMeta = (meta && meta.remote) || null
+  const cover = resolveCoverForExport({
+    remotePicUrl: remoteMeta && remoteMeta.picUrl,
+    coverPath,
+  })
+
+  const cardPO = {
+    id: numericId,
+    name: (schema.name || '').toString(),
+    cardStatus: '1',
+    createTime: null,
+    updateTime: null,
+    sassAppId: (meta && meta.appId) || '100001',
+    sassWorkspaceId: (meta && meta.workspaceId) || 'dev',
+    // picUrl 恒非空，且末段 === 卡目录根封面文件名（见 resolveCoverForExport 的契约说明）：
+    // 有远端真值（侧车 remote.picUrl）就原样沿用，与官方产物同构；本地新建卡按同一形态合成。
+    picUrl: cover.picUrl,
+    // 远端列表才有的分类字段：有真值用真值（官方 57 张样本里恒非空），未知时留空由导入侧兜底
+    cardClassId: (remoteMeta && remoteMeta.cardClassId) || '',
+    code: id,
+    // applyScene 不是常量：官方两份产物分别是 '1'（2 张）与 '2'（57 张），必须取真值
+    applyScene: (remoteMeta && remoteMeta.applyScene) || '1',
+  }
+
+  // previewSchema：优先 buildPreview（编辑器同源实现）；不可用或抛错时退化为 schema 原样。
+  // 序列化时剥离 _schemaNode：全代码库约定（server/core/cardFiles.js、App.vue 存档 /
+  // 剪贴板 / dirty 比对等同一 replacer），它是对原始 schema 节点的运行时自引用，
+  // 不带 replacer 会让 previewSchema 膨胀约 6 倍并偏离样本形态（样本无该字段）。
+  let previewSchema
+  try {
+    const preview = buildPreview ? buildPreview(schema) : schema
+    previewSchema = JSON.stringify(preview, (k, v) => (k === '_schemaNode' ? undefined : v))
+  } catch (e) {
+    previewSchema = JSON.stringify(schema)
+    log.warn('previewSchema 生成失败，退化为 schema 原样', { id, error: e && e.message })
+  }
+
+  const cardJobPO = {
+    id: null,
+    cardId: numericId,
+    schemaValue: JSON.stringify(schema),
+    previewSchema,
+    screenshotUrl: '',
+    createTime: null,
+    updateTime: null,
+    skeletonScreen: MIN_SKELETON,
+  }
+
+  const variablePOS = ((schema.dictionary && schema.dictionary.inputParams) || []).map((p) => ({
+    id: null,
+    cardId: numericId,
+    variableKey: p.key,
+    variableName: p.name != null ? p.name : p.key,
+    variableType: p.type,
+    variableDescribe: p.desc || '',
+    variableDefaultValue: JSON.stringify(p.defaultValue === undefined ? null : p.defaultValue),
+    variableStructure: JSON.stringify(p),
+    createTime: null,
+    updateTime: null,
+  }))
+
+  const refs = collectViewImageRefs(schema.view)
+  const imageLists = refs.map(({ ref }) => {
+    const imageName = refBasename(ref)
+    return {
+      originalUrls: ref,
+      localUrl: `/image/${imageName}`,
+      targetUrl: null,
+      imageName,
+    }
+  })
+
+  // 落盘：<outDir>/<numericId>/
+  const cardOutDir = path.join(outDir, numericId)
+  fs.mkdirSync(cardOutDir, { recursive: true })
+  const warnings = []
+
+  // 图片：@filestore 走 minio 公网下载；/slices/ 从 src/slices 拷贝
+  for (const { ref, kind } of refs) {
+    const imageName = refBasename(ref)
+    if (!imageName) continue
+    const dest = path.join(cardOutDir, 'image', imageName)
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true })
+      if (kind === 'slice') {
+        const src = path.join(root, 'src', 'slices', imageName)
+        if (!fs.existsSync(src)) throw new Error('本地切图不存在')
+        fs.copyFileSync(src, dest)
+      } else {
+        const url = filestoreUrlFor(ref, upstream)
+        if (!url) throw new Error('未配置 FinMall 上游地址，无法下载 @filestore 图片')
+        const res = await fetch(url, {
+          headers: { 'User-Agent': 'Mozilla/5.0', Referer: upstream ? `${upstream}/` : '' },
+          signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
+        })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const ct = res.headers.get('content-type') || ''
+        if (ct.includes('text/html')) throw new Error('上游返回 HTML（疑似 404 页）')
+        const buf = Buffer.from(await res.arrayBuffer())
+        if (!buf.length) throw new Error('空响应')
+        fs.writeFileSync(dest, buf)
+      }
+    } catch (e) {
+      warnings.push(`图片落地失败 ${imageName}：${e && e.message}`)
+      log.warn('导出图片落地失败', { id, imageName, error: e && e.message })
+    }
+  }
+
+  // 封面：以 picUrl 末段的文件名落卡目录根（导入侧按此名取文件；官方产物同形）
+  fs.copyFileSync(coverPath, path.join(cardOutDir, cover.fileName))
+  if (!cover.inherited) {
+    warnings.push(`本地无远端 picUrl，封面已合成 ${cover.picUrl}（文件名为本地预览图名）`)
+  }
+
+  const cardJson = JSON.stringify({
+    cardPO,
+    cardJobPO,
+    variablePOS,
+    imageLists,
+    platformStatus: PLATFORM_STATUS,
+  })
+  fs.writeFileSync(path.join(cardOutDir, `${numericId}.json`), cardJson, 'utf8')
+
+  return { cardPO, warnings }
+}
+
+/**
+ * 跑导出任务（后台执行，进度经 job.progress 暴露）。
+ * @param {object} job
+ * @param {{ root: string, cardIds: string[], targetDir: string, upstream: string, viteServer: object|null }} ctx
+ */
+async function runExportJob(job, { root, cardIds, targetDir, upstream, viteServer }) {
+  // buildPreview：优先经 vite ssrLoadModule 复用编辑器同源实现（与 /__render-status 同模式）
+  let buildPreview = null
+  if (viteServer && typeof viteServer.ssrLoadModule === 'function') {
+    try {
+      const mod = await viteServer.ssrLoadModule('/runtime/toPreview.js')
+      if (typeof mod.buildPreview === 'function') buildPreview = mod.buildPreview
+    } catch (e) {
+      log.warn('toPreview 模块加载失败，previewSchema 将退化为 schema 原样', { error: e && e.message })
+    }
+  }
+  if (!buildPreview) log.warn('无 vite 实例或 toPreview 不可用，previewSchema 退化为 schema 原样')
+
+  const cardsPO = []
+  const failed = []
+  const warnings = []
+  const zipEntries = []
+  const folderName = stampFolderName(targetDir)
+  const outDir = path.join(targetDir, folderName)
+  let revealed = false
+
+  try {
+    fs.mkdirSync(outDir, { recursive: true })
+    log.ok('开始导出卡片', { jobId: job.id, folderName, targetDir, total: cardIds.length })
+
+    for (const id of cardIds) {
+      if (job.cancelRequested) break
+      job.progress.currentId = id
+      job.progress.currentTitle = ''
+      try {
+        const { cardPO, warnings: w } = await exportOneCard({
+          root,
+          id,
+          outDir,
+          upstream,
+          buildPreview,
+        })
+        cardsPO.push(cardPO)
+        for (const x of w) warnings.push(`${id}: ${x}`)
+      } catch (e) {
+        failed.push({ id, error: e && e.message })
+        log.error('导出单卡失败', { id, error: e && e.message })
+      }
+      job.progress.done = cardsPO.length + failed.length
+    }
+
+    if (job.cancelRequested) {
+      // 取消：清理半成品目录（无 zip 产出，留着会违反命名契约），不 reveal
+      fs.rmSync(outDir, { recursive: true, force: true })
+      job.result = {
+        success: false,
+        cancelled: true,
+        exported: cardsPO.length,
+        failed,
+        message: `导出已取消（已完成 ${cardsPO.length} 张）`,
+      }
+      log.warn('导出任务被取消', { jobId: job.id, done: cardsPO.length })
+      return
+    }
+
+    if (!cardsPO.length) {
+      throw new Error(failed.length ? `全部 ${failed.length} 张卡片导出失败` : '没有可导出的卡片')
+    }
+
+    // 产物自检：卡片清单的每条都必须能被导入侧无防御地消费（picUrl 非空 + 封面文件在位）。
+    // 与后端无关的纯本地断言，任何一条违例都意味着导入侧同一段逻辑必炸 —— 宁可整单失败，不出残包。
+    const problems = verifyCardsJsonInvariants({ cardsPO, outDir })
+    if (problems.length) {
+      throw new Error(
+        `导出产物自检未通过（${problems.length} 项）：${problems.slice(0, 5).join('；')}` +
+          (problems.length > 5 ? ' 等' : '')
+      )
+    }
+
+    // 收集 zip 条目（按名排序保证确定性），cards.json 殿后（与样本一致）
+    const collectEntries = (dir, prefix) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name)
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name
+        if (entry.isDirectory()) collectEntries(full, rel)
+        else zipEntries.push({ name: rel, data: fs.readFileSync(full) })
+      }
+    }
+    collectEntries(outDir, '')
+    zipEntries.sort((a, b) => a.name.localeCompare(b.name))
+    fs.writeFileSync(path.join(outDir, 'cards.json'), JSON.stringify(cardsPO), 'utf8')
+    zipEntries.push({ name: 'cards.json', data: Buffer.from(JSON.stringify(cardsPO), 'utf8') })
+
+    const zipPath = path.join(targetDir, `${folderName}.zip`)
+    fs.writeFileSync(zipPath, buildZip(zipEntries))
+
+    // 原文件夹删除，只留同名 zip
+    fs.rmSync(outDir, { recursive: true, force: true })
+
+    revealed = revealFileInOS(zipPath)
+
+    job.result = {
+      success: true,
+      folderName,
+      zipPath,
+      exported: cardsPO.length,
+      failed,
+      warnings,
+      revealed,
+    }
+    log.ok('导出完成', { jobId: job.id, folderName, zipPath, exported: cardsPO.length, failed: failed.length })
+  } catch (e) {
+    try {
+      fs.rmSync(outDir, { recursive: true, force: true })
+    } catch {
+      /* 清理失败不掩盖原始错误 */
+    }
+    job.result = { success: false, error: e && e.message, exported: cardsPO.length, failed }
+    log.error('导出任务失败', e)
+  }
+}
+
+/**
+ * @param {{ root: string, viteServer?: import('vite').ViteDevServer|null, upstream?: string }} opts
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
+ */
+export function createExportMiddleware({ root, viteServer = null, upstream = '' }) {
+  const readJsonBody = (req, res, cb) => {
+    let body = ''
+    req.setEncoding('utf8')
+    req.on('data', (c) => {
+      body += c
+      if (body.length > 1024 * 1024) req.destroy()
+    })
+    req.on('end', () => {
+      try {
+        cb(JSON.parse(body || '{}'))
+      } catch (e) {
+        res.statusCode = 400
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify({ ok: false, error: 'invalid json', message: String(e.message) }))
+      }
+    })
+  }
+  const sendJson = (res, status, obj) => {
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.setHeader('Cache-Control', 'no-store')
+    res.end(JSON.stringify(obj))
+  }
+
+  return function exportMiddleware(req, res, next) {
+    const pathname = decodeURIComponent((req.url || '').split('?')[0])
+    const method = (req.method || 'GET').toUpperCase()
+
+    // ---- 目录建议（导出目录弹框预填）：桌面 / 下载 / 主目录，跨平台尽力而为 ----
+    if (pathname === '/__export/dir-suggestions') {
+      if (method !== 'GET') return next()
+      const home = os.homedir()
+      const pick = (name) => {
+        const p = path.join(home, name)
+        return fs.existsSync(p) ? p : ''
+      }
+      const desktop = pick('Desktop') || home
+      const downloads = pick('Downloads') || home
+      return sendJson(res, 200, { ok: true, home, desktop, downloads, default: desktop })
+    }
+
+    // ---- 导出进度查询（轮询） ----
+    if (pathname === '/__export/progress') {
+      if (method !== 'GET') return next()
+      const jobId = new URL(req.url, 'http://127.0.0.1').searchParams.get('jobId') || ''
+      const job = exportJobs.get(jobId)
+      if (!job) {
+        return sendJson(res, 404, { ok: false, error: 'unknown job', message: '导出任务不存在或已过期' })
+      }
+      return sendJson(res, 200, {
+        ok: true,
+        jobId: job.id,
+        done: job.progress.done,
+        total: job.progress.total,
+        currentId: job.progress.currentId,
+        currentTitle: job.progress.currentTitle,
+        finished: job.finished,
+        result: job.result,
+      })
+    }
+
+    // ---- 取消导出（下一张卡片前生效） ----
+    if (pathname === '/__export/cancel') {
+      if (method !== 'POST') return next()
+      return readJsonBody(req, res, (payload) => {
+        const jobId = String(payload.jobId || '')
+        const job = exportJobs.get(jobId)
+        if (!job || job.finished) {
+          return sendJson(res, 404, { ok: false, error: 'unknown job', message: '导出任务不存在或已结束' })
+        }
+        job.cancelRequested = true
+        return sendJson(res, 200, { ok: true })
+      })
+    }
+
+    if (pathname !== '/__export-cards') return next()
+    if (method !== 'POST') return next()
+
+    return readJsonBody(req, res, (payload) => {
+      // 入参：cardIds 集合 + targetDir 导出目录
+      const ids = Array.isArray(payload.cardIds)
+        ? [...new Set(payload.cardIds.filter((c) => typeof c === 'string'))]
+        : []
+      const targetDirRaw = typeof payload.targetDir === 'string' ? payload.targetDir.trim() : ''
+
+      if (!ids.length) {
+        return sendJson(res, 400, { ok: false, error: 'empty_card_ids', message: '请先勾选要导出的卡片' })
+      }
+      if (ids.length > MAX_EXPORT_CARDS) {
+        return sendJson(res, 400, { ok: false, error: 'too_many', message: `单次导出勾选不能超过 ${MAX_EXPORT_CARDS} 张` })
+      }
+      if (!targetDirRaw || !path.isAbsolute(targetDirRaw)) {
+        return sendJson(res, 400, { ok: false, error: 'invalid_target_dir', message: '导出目录必须是绝对路径' })
+      }
+      // 卡片 id 合法性 + 归属校验（resolveCardDir 内含白名单与穿越防护）
+      const safeIds = []
+      for (const id of ids) {
+        const dir = resolveCardDir(root, id)
+        if (!dir || !fs.existsSync(dir)) {
+          return sendJson(res, 400, { ok: false, error: 'invalid_card_id', message: `卡片不存在或 id 非法：${id}` })
+        }
+        safeIds.push(id)
+      }
+
+      const targetDir = path.resolve(targetDirRaw)
+      // 功能性禁区：src/cards（会被卡片列表扫描成垃圾卡片）与 node_modules（污染依赖目录）
+      const cardsRoot = path.resolve(root, 'src', 'cards')
+      const nmRoot = path.resolve(root, 'node_modules')
+      if (targetDir === cardsRoot || targetDir.startsWith(cardsRoot + path.sep)) {
+        return sendJson(res, 400, {
+          ok: false,
+          error: 'forbidden_target_dir',
+          message: '不能导出到 src/cards 目录（会被卡片列表扫描收录）',
+        })
+      }
+      if (targetDir === nmRoot || targetDir.startsWith(nmRoot + path.sep)) {
+        return sendJson(res, 400, {
+          ok: false,
+          error: 'forbidden_target_dir',
+          message: '不能导出到 node_modules 目录',
+        })
+      }
+      try {
+        fs.mkdirSync(targetDir, { recursive: true })
+      } catch (e) {
+        return sendJson(res, 400, { ok: false, error: 'target_dir_unwritable', message: `导出目录不可用：${e && e.message}` })
+      }
+
+      // 同一时刻只允许一个导出任务（与 /__sync 同口径）
+      if (activeExportJob()) {
+        return sendJson(res, 409, { ok: false, error: 'export_in_progress', message: '已有导出任务正在进行，请等待完成或取消' })
+      }
+
+      exportJobSeq += 1
+      const job = {
+        id: `ej-${Date.now().toString(36)}-${exportJobSeq}`,
+        createdAt: Date.now(),
+        cancelRequested: false,
+        timedOut: false,
+        finished: false,
+        progress: { done: 0, total: safeIds.length, currentId: '', currentTitle: '' },
+        result: null,
+      }
+      rememberExportJob(job)
+
+      // 看门狗：与同步任务同款兜底，防单次导出无限期占用服务
+      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(EXPORT_JOB_TIMEOUT_MS / 1000)} 秒未完成，已自动收尾。请重试，或检查网络（导出需下载远端图片）。`,
+        }
+        log.error('导出看门狗触发：任务超时，已代其收尾', { jobId: job.id })
+      }, EXPORT_JOB_TIMEOUT_MS)
+      if (typeof watchdog.unref === 'function') watchdog.unref()
+
+      ;(async () => {
+        try {
+          await runExportJob(job, { root, cardIds: safeIds, targetDir, upstream, viteServer })
+        } finally {
+          clearTimeout(watchdog)
+          // 看门狗已代收尾时不回滚结论
+          if (!job.timedOut) job.finished = true
+        }
+      })()
+
+      return sendJson(res, 200, { ok: true, jobId: job.id, total: job.progress.total })
+    })
+  }
+}