cardbuddy 0.20.0 → 0.21.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,916 @@
1
+ import fs from 'node:fs'
2
+ import os from 'node:os'
3
+ import path from 'node:path'
4
+ import zlib from 'node:zlib'
5
+ import { spawn } from 'node:child_process'
6
+ import { log } from './logger.js'
7
+ import { readImportMeta } from './cardImportMeta.js'
8
+ import { resolveCardDir } from './cardOpenFolder.js'
9
+
10
+ /**
11
+ * 卡片导出端点(编辑器「卡片网格预览 → 勾选 → 导出」的服务端实现)。
12
+ *
13
+ * 产物契约(对桌面两份 FinMall 导出样本的逆向结论,详见
14
+ * docs/卡片导出产物逆向分析与导出功能.md):
15
+ * <targetDir>/<yyMMddHHmmss+4位序号>/ ← 临时文件夹(完成后删除)
16
+ * cards.json ← 卡片清单(cardPO 数组,殿后写入)
17
+ * <数字id>/<数字id>.json ← { cardPO, cardJobPO, variablePOS, imageLists, platformStatus }
18
+ * <数字id>/<封面文件> ← 封面,文件名恒等于 cards.json 里该卡 picUrl 的末段
19
+ * <数字id>/image/<imageName> ← schema.view 树引用的 @filestore 图片下载落盘
20
+ * <targetDir>/<同名>.zip ← 纯 Node 写出的 zip(条目平铺、无顶层文件夹)
21
+ *
22
+ * 封面铁律(2026-10-22 事故后定,依据 57 张官方导出样本 + ImportCardAction.java:61-64):
23
+ * - picUrl 恒非空,且末段 === `<数字id>/` 下封面文件名。导入侧按 picUrl 末段推文件名后直接读该文件,
24
+ * 对所有空值/缺失零防御(空串时路径退化成卡目录,读目录抛异常)。
25
+ * - 无本地封面的卡**不允许导出**(计入 failed 并给出补齐指引),不产「有卡无封面」的残包。
26
+ * - 有 `.import-meta.json` 的 remote 快照时沿用远端真值(picUrl/cardClassId/applyScene);
27
+ * 本地新建卡按同一形态合成 picUrl,cardClassId 留空、applyScene 回落 '1'。
28
+ * - 写 zip 前跑 verifyCardsJsonInvariants 自检,违例即整单失败。
29
+ *
30
+ * 条目名铁律(2026-10-23 事故后定):**zip 条目名必须全 ASCII**。官方 57 卡大样本
31
+ * 439 个条目里非 ASCII 为 0;中文名一律 percent-encode 成 `%XX`(整段 encodeURIComponent),
32
+ * 而 JSON 里的 picUrl / imageName / localUrl 保持中文原文。后端读 zip 条目名不认 UTF-8
33
+ * 标志位,非 ASCII 名会被解成乱码 → 找不到 JSON 引用的文件 → 导入失败。
34
+ * 写 zip 前跑 verifyZipEntryNames 自检(全 ASCII / 无重名 / 封面条目按编码名命中)。
35
+ * 任务制端点(与 /__sync 同构:单飞制 + 看门狗 + 轮询 + 取消):
36
+ * - POST /__export-cards body { cardIds[], targetDir } → { ok, jobId, total }
37
+ * - GET /__export/progress?jobId → { ok, done, total, currentId, currentTitle, finished, result }
38
+ * - POST /__export/cancel body { jobId } → 下一张卡片前中止(已写内容随任务清理)
39
+ * - GET /__export/dir-suggestions → { ok, home, desktop, downloads, default }
40
+ *
41
+ * previewSchema 生成复用编辑器同源实现:经 viteServer.ssrLoadModule 加载
42
+ * card-editor/runtime/toPreview.js 的 buildPreview(与 SSR 自检端点同一模式),
43
+ * 无 vite 实例时退化为 schema 原样序列化(可用但非预览态)。
44
+ */
45
+
46
+ /** 单次导出勾选上限(与 /__sync 的 500 上限同口径) */
47
+ const MAX_EXPORT_CARDS = 500
48
+
49
+ /** 导出任务硬超时(看门狗):大批量卡片下载图片可能很慢,10 分钟不收尾即代收 */
50
+ const EXPORT_JOB_TIMEOUT_MS = Number(process.env.CARDBUDDY_EXPORT_JOB_TIMEOUT_MS || 10 * 60 * 1000)
51
+
52
+ /** 图片下载超时(与资源代理回源超时同口径) */
53
+ const IMAGE_FETCH_TIMEOUT_MS = 12000
54
+
55
+ /** 封面候选扩展名(与 finmall-card-sync 的 findExistingCover 同集) */
56
+ const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg'])
57
+
58
+ /**
59
+ * 本地无远端 picUrl 时,封面在包内所用的 filestore 前缀。
60
+ * 依据 57 张官方导出的实测:picUrl 恒为 `@filestore/<桶名>/<文件名>`,桶名出现两种
61
+ * (dzqd-download 54 张、sit-public-cbbiz 3 张)——说明导入侧只取末段做文件名,桶名不参与校验。
62
+ * 取多数派即可,不必也无法还原真实桶。
63
+ */
64
+ const COVER_FILESTORE_PREFIX = '@filestore/dzqd-download'
65
+
66
+ /** 平台状态常量:两份样本恒为三端全平台(与 FinMall 发布接口默认平台集一致) */
67
+ const PLATFORM_STATUS = ['iOS', 'Android', 'HarmonyOS']
68
+
69
+ /** 最小合法骨架屏 SVG:样本为线上编辑器按布局生成,本地不做布局推测,占位保证字段非空 */
70
+ const MIN_SKELETON =
71
+ '<svg xmlns="http://www.w3.org/2000/svg" width="375" height="200" viewBox="0 0 375 200">' +
72
+ '<rect width="100%" height="100%" fill="#ffffff"/></svg>'
73
+
74
+ /* ------------------------------ 任务表(单例) ------------------------------ */
75
+
76
+ const exportJobs = new Map() // jobId -> job
77
+ const EXPORT_JOB_KEEP = 8
78
+ let exportJobSeq = 0
79
+
80
+ function activeExportJob() {
81
+ for (const job of exportJobs.values()) {
82
+ if (!job.finished) return job
83
+ }
84
+ return null
85
+ }
86
+
87
+ function rememberExportJob(job) {
88
+ exportJobs.set(job.id, job)
89
+ while (exportJobs.size > EXPORT_JOB_KEEP) {
90
+ const oldest = exportJobs.keys().next().value
91
+ exportJobs.delete(oldest)
92
+ }
93
+ }
94
+
95
+ /* ------------------------------ ZIP 写入器(纯 Node) ------------------------------ */
96
+
97
+ const CRC_TABLE = (() => {
98
+ const t = new Uint32Array(256)
99
+ for (let n = 0; n < 256; n += 1) {
100
+ let c = n
101
+ for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
102
+ t[n] = c >>> 0
103
+ }
104
+ return t
105
+ })()
106
+
107
+ function crc32(buf) {
108
+ let c = 0xffffffff
109
+ for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8)
110
+ return (c ^ 0xffffffff) >>> 0
111
+ }
112
+
113
+ function dosDateTime(d) {
114
+ const time = ((d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1)) & 0xffff
115
+ const date = (((d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate()) & 0xffff
116
+ return { time, date }
117
+ }
118
+
119
+ /**
120
+ * 生成 zip 文件字节(无外部依赖,条目平铺、不含目录项、不含顶层文件夹)。
121
+ * 每条目自动在 deflate / store 中取小者;非 ASCII 文件名置 UTF-8 标志位(bit 11),
122
+ * 保证中文 imageName 在 unzip 后不乱码(样本产物的图片名大量含中文)。
123
+ * @param {Array<{ name: string, data: Buffer }>} entries
124
+ * @param {Date} [when] 条目时间戳(默认现在)
125
+ * @returns {Buffer}
126
+ */
127
+ function buildZip(entries, when = new Date()) {
128
+ const { time, date } = dosDateTime(when)
129
+ const chunks = []
130
+ const central = []
131
+ let offset = 0
132
+
133
+ for (const entry of entries) {
134
+ const nameBuf = Buffer.from(entry.name, 'utf8')
135
+ const raw = entry.data
136
+ const deflated = zlib.deflateRawSync(raw, { level: 9 })
137
+ // 已压缩数据(png/jpg)deflate 可能反而变大:取小者,方法号随之切换
138
+ const useDeflate = deflated.length < raw.length
139
+ const body = useDeflate ? deflated : raw
140
+ const method = useDeflate ? 8 : 0
141
+ const crc = crc32(raw)
142
+ // 非 ASCII 名置 UTF-8 语言编码标志(EFS)
143
+ const flags = /[^\x20-\x7e]/.test(entry.name) ? 0x0800 : 0
144
+
145
+ const local = Buffer.alloc(30)
146
+ local.writeUInt32LE(0x04034b50, 0) // local file header 签名
147
+ local.writeUInt16LE(20, 4) // 解压所需版本
148
+ local.writeUInt16LE(flags, 6)
149
+ local.writeUInt16LE(method, 8)
150
+ local.writeUInt16LE(time, 10)
151
+ local.writeUInt16LE(date, 12)
152
+ local.writeUInt32LE(crc, 14)
153
+ local.writeUInt32LE(body.length, 18) // 压缩后大小
154
+ local.writeUInt32LE(raw.length, 22) // 原始大小
155
+ local.writeUInt16LE(nameBuf.length, 26)
156
+ local.writeUInt16LE(0, 28) // extra 长度
157
+ chunks.push(local, nameBuf, body)
158
+
159
+ const cd = Buffer.alloc(46)
160
+ cd.writeUInt32LE(0x02014b50, 0) // central directory header 签名
161
+ cd.writeUInt16LE(20, 4) // 制作版本
162
+ cd.writeUInt16LE(20, 6) // 解压所需版本
163
+ cd.writeUInt16LE(flags, 8)
164
+ cd.writeUInt16LE(method, 10)
165
+ cd.writeUInt16LE(time, 12)
166
+ cd.writeUInt16LE(date, 14)
167
+ cd.writeUInt32LE(crc, 16)
168
+ cd.writeUInt32LE(body.length, 20)
169
+ cd.writeUInt32LE(raw.length, 24)
170
+ cd.writeUInt16LE(nameBuf.length, 28)
171
+ cd.writeUInt32LE(0, 38) // 外部属性(普通文件)
172
+ cd.writeUInt32LE(offset, 42) // 本地头偏移
173
+ central.push(cd, nameBuf)
174
+
175
+ offset += local.length + nameBuf.length + body.length
176
+ }
177
+
178
+ const cdBuf = Buffer.concat(central)
179
+ const eocd = Buffer.alloc(22)
180
+ eocd.writeUInt32LE(0x06054b50, 0)
181
+ eocd.writeUInt16LE(entries.length, 8)
182
+ eocd.writeUInt16LE(entries.length, 10)
183
+ eocd.writeUInt32LE(cdBuf.length, 12)
184
+ eocd.writeUInt32LE(offset, 16)
185
+
186
+ return Buffer.concat([...chunks, cdBuf, eocd])
187
+ }
188
+
189
+ /* ------------------------------ 平台 reveal ------------------------------ */
190
+
191
+ /**
192
+ * 在系统文件管理器中 reveal 指定文件(选中态)。
193
+ * macOS: open -R;Windows: explorer /select,;Linux: xdg-open 所在目录。
194
+ * @returns {boolean} 是否成功触发(仅表示进程拉起)
195
+ */
196
+ export function revealFileInOS(filePath) {
197
+ let spec = null
198
+ switch (process.platform) {
199
+ case 'darwin':
200
+ spec = { cmd: 'open', args: ['-R', filePath] }
201
+ break
202
+ case 'win32':
203
+ spec = { cmd: 'explorer', args: [`/select,${filePath}`] }
204
+ break
205
+ case 'linux':
206
+ spec = { cmd: 'xdg-open', args: [path.dirname(filePath)] }
207
+ break
208
+ default:
209
+ break
210
+ }
211
+ if (!spec) {
212
+ log.warn('reveal 文件不支持当前平台', { platform: process.platform })
213
+ return false
214
+ }
215
+ try {
216
+ const child = spawn(spec.cmd, spec.args, { shell: false, stdio: 'ignore' })
217
+ child.on('error', (e) => {
218
+ log.error('reveal 文件命令失败', { cmd: spec.cmd, message: String(e.message) })
219
+ })
220
+ return true
221
+ } catch (e) {
222
+ log.error('reveal 文件异常', e)
223
+ return false
224
+ }
225
+ }
226
+
227
+ /* ------------------------------ 产物构建 ------------------------------ */
228
+
229
+ /** URL 段编码:已带 %XX 的段保持原样,其余段 encodeURIComponent(与资源代理同规则) */
230
+ function encodePath(p) {
231
+ return p
232
+ .split('/')
233
+ .map((seg) => (/%[0-9a-fA-F]{2}/.test(seg) ? seg : encodeURIComponent(seg)))
234
+ .join('/')
235
+ }
236
+
237
+ /** @filestore/x → <upstream>/minio/x(minio 公网可读,无需凭据) */
238
+ function filestoreUrlFor(ref, upstream) {
239
+ if (!upstream) return ''
240
+ if (ref.startsWith('@filestore/')) return `${upstream}/minio/${encodePath(ref.slice('@filestore/'.length))}`
241
+ if (ref.startsWith('/')) return `${upstream}${encodePath(ref)}`
242
+ return ''
243
+ }
244
+
245
+ /** 时间戳文件夹名:yyMMddHHmmss + 4 位序号(样本规律;重名顺延保证唯一) */
246
+ function stampFolderName(targetDir, now = new Date()) {
247
+ const p = (n) => String(n).padStart(2, '0')
248
+ const base =
249
+ `${String(now.getFullYear() % 100).padStart(2, '0')}${p(now.getMonth() + 1)}${p(now.getDate())}` +
250
+ `${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`
251
+ for (let seq = 1; seq <= 9999; seq += 1) {
252
+ const name = base + String(seq).padStart(4, '0')
253
+ if (!fs.existsSync(path.join(targetDir, name)) && !fs.existsSync(path.join(targetDir, `${name}.zip`))) {
254
+ return name
255
+ }
256
+ }
257
+ // 9999 个同名全部占用(理论上不可能):加随机后缀兜底
258
+ return base + Math.random().toString(36).slice(2, 6).padStart(4, '0')
259
+ }
260
+
261
+ /** 找本地封面预览图(<cardId>.<ext>);没有返回 null(与 finmall-card-sync 同规则) */
262
+ function findExistingCover(cardDir, id) {
263
+ let entries = []
264
+ try {
265
+ entries = fs.readdirSync(cardDir)
266
+ } catch {
267
+ return null
268
+ }
269
+ for (const name of entries) {
270
+ const ext = path.extname(name).toLowerCase()
271
+ if (IMAGE_EXTS.has(ext) && path.basename(name, ext) === id) return path.join(cardDir, name)
272
+ }
273
+ return null
274
+ }
275
+
276
+ /**
277
+ * 采集 schema.view 组件树中的图片引用(首现序去重)。
278
+ * 规则(样本逆向结论):仅 view 树,不含 dictionary;@filestore 走远端下载,
279
+ * /slices/ 走本地切图拷贝。两者按遍历首现顺序混合排列。
280
+ * @returns {Array<{ ref: string, kind: 'filestore'|'slice' }>}
281
+ */
282
+ function collectViewImageRefs(view) {
283
+ const out = []
284
+ const seen = new Set()
285
+ const push = (ref) => {
286
+ if (seen.has(ref)) return
287
+ seen.add(ref)
288
+ if (ref.startsWith('@filestore/')) out.push({ ref, kind: 'filestore' })
289
+ else if (ref.startsWith('/slices/')) out.push({ ref, kind: 'slice' })
290
+ }
291
+ const walk = (v) => {
292
+ if (typeof v === 'string') {
293
+ // 与 imageLists 提取口径一致:字符串内可能嵌多个引用(如 style backgroundImage)
294
+ const re = /(?:@filestore\/|\/slices\/)[^\s"'\\)]+/g
295
+ let m
296
+ while ((m = re.exec(v)) !== null) push(m[0])
297
+ return
298
+ }
299
+ if (Array.isArray(v)) {
300
+ for (const x of v) walk(x)
301
+ return
302
+ }
303
+ if (v && typeof v === 'object') {
304
+ for (const x of Object.values(v)) walk(x)
305
+ }
306
+ }
307
+ walk(view)
308
+ return out
309
+ }
310
+
311
+ /** 末段文件名(@filestore 路径的 imageName;/slices/ 的切片名) */
312
+ function refBasename(ref) {
313
+ const seg = ref.split('/').pop() || ''
314
+ return seg
315
+ }
316
+
317
+ /**
318
+ * 计算导出用的封面文件名与 `cardPO.picUrl`,两者必须自洽:**picUrl 末段 === 包内卡目录根的封面文件名**。
319
+ *
320
+ * 契约依据(57 张官方导出样本逐卡核对:picUrl 非空 57/57、末段与目录根封面文件名一致 57/57):
321
+ * 导入侧 `ImportCardAction.java:61-64` 用 `extractFileNameMethod1(picUrl)` 得到文件名后
322
+ * `new File(cardUrl + File.separator + imageName)` 去读封面,**无任何空值/存在性防御**:
323
+ * picUrl 为空串时路径退化成卡目录本身,读目录抛异常,整卡导入失败。
324
+ * 故此处绝不允许产出空 picUrl。
325
+ *
326
+ * @param {{ remotePicUrl?: string, coverPath: string }} o
327
+ * remotePicUrl:`.import-meta.json` 记录的远端真值(有则原样沿用,形态与官方产物同构);
328
+ * coverPath:本地封面绝对路径(无远端真值时以其文件名为准)。
329
+ * @returns {{ fileName: string, picUrl: string, inherited: boolean }}
330
+ */
331
+ export function resolveCoverForExport({ remotePicUrl, coverPath }) {
332
+ const localName = path.basename(coverPath)
333
+ const remote = typeof remotePicUrl === 'string' ? remotePicUrl.trim() : ''
334
+ if (remote) {
335
+ // 远端真值可能带 query(极少见),取文件名时剥掉;picUrl 本身保持原样不重写
336
+ const name = path.basename(remote.split('?')[0].split('#')[0])
337
+ if (name) return { fileName: name, picUrl: remote, inherited: true }
338
+ }
339
+ return { fileName: localName, picUrl: `${COVER_FILESTORE_PREFIX}/${localName}`, inherited: false }
340
+ }
341
+
342
+ /**
343
+ * zip 条目名转 ASCII:**JSON 保留原名,包内文件名 percent-encode**。
344
+ *
345
+ * 契约依据(官方 57 卡大样本 `2609091710000055.zip`:439 个条目里非 ASCII 为 0):
346
+ * 中文名一律整段 `encodeURIComponent`——`20260519101312_右箭头@3x.png` 落地为
347
+ * `20260519101312_%E5%8F%B3%E7%AE%AD%E5%A4%B4%403x.png`(注意 `@`→`%40`、空格→`%20`),
348
+ * 而 `cards.json`/`<id>.json` 里的 `picUrl`、`imageName`、`localUrl` 全部保持中文原文。
349
+ *
350
+ * 为什么必须这样(2026-10-23 事故):后端(Java)读 zip 条目名不认 UTF-8 语言编码标志位,
351
+ * 非 ASCII 名会被按默认字符集解成乱码 → 解压落盘的文件名与 JSON 里引用的名字对不上 →
352
+ * 导入报错。上一版只落中文原名(旧 §8.1「只落原名一份」)正是这次失败的直接原因。
353
+ *
354
+ * **所有段无条件编码**(不是「命中中文才编码」):官方样本 `20260522173828_VS-44@3x.png`
355
+ * 整段无中文,仍落地为 `20260522173828_VS-44%403x.png`——说明规则是「整段 encodeURIComponent」,
356
+ * 而不是「含非 ASCII 才编码」。纯 ASCII 名里出现 `@`/空格/`#` 同样要编(本地 greetingRecommend
357
+ * 的 `mascotDing@2x.png` 就属这一类)。
358
+ *
359
+ * 幂等:已编码段(本地切图名可能本来就是 %XX 形式)先 decode 再 encode,避免二次编码;
360
+ * 含裸 `%` 无法解码时按原文编码(`%`→`%25`)。
361
+ * @param {string} rel 相对路径(POSIX 分隔符)
362
+ * @returns {string}
363
+ */
364
+ export function zipEntryName(rel) {
365
+ return String(rel)
366
+ .split('/')
367
+ .map((seg) => {
368
+ let raw = seg
369
+ try {
370
+ raw = decodeURIComponent(seg)
371
+ } catch {
372
+ /* 含裸 % / 非法转义:直接按原文编码 */
373
+ }
374
+ return encodeURIComponent(raw)
375
+ })
376
+ .join('/')
377
+ }
378
+
379
+ /**
380
+ * zip 层自检(与后端无关的结构断言):
381
+ * 1. 条目名全 ASCII(官方 439/439 全 ASCII;非 ASCII 名会被后端按错误字符集解成乱码);
382
+ * 2. 无重名(同卡两个不同文件编码后撞名会让其中一份被覆盖);
383
+ * 3. 每张卡的封面以「picUrl 末段编码后」的条目名存在(后端编码后按此名取文件)。
384
+ * @param {{ cardsPO: Array<object>, zipNames: string[] }} o
385
+ * @returns {string[]}
386
+ */
387
+ export function verifyZipEntryNames({ cardsPO, zipNames }) {
388
+ const problems = []
389
+ const names = zipNames || []
390
+ for (const n of names) {
391
+ if (/[^\x00-\x7F]/.test(n)) problems.push(`条目名非 ASCII:${n}`)
392
+ }
393
+ const seen = new Set()
394
+ for (const n of names) {
395
+ if (seen.has(n)) problems.push(`条目名重复:${n}`)
396
+ seen.add(n)
397
+ }
398
+ for (const po of cardsPO || []) {
399
+ if (!po || !po.picUrl) continue
400
+ const id = String(po.id)
401
+ const cover = path.basename(String(po.picUrl).split('?')[0])
402
+ const expect = zipEntryName(`${id}/${cover}`)
403
+ if (!seen.has(expect)) problems.push(`${id}: 封面条目缺失 ${expect}`)
404
+ }
405
+ return problems
406
+ }
407
+
408
+ /**
409
+ * 产物自检:cards.json 的每条 cardPO 都能被导入侧无障碍消费。
410
+ * 只做**与后端无关**的结构断言(不依赖远端服务,纯本地即可证伪):
411
+ * 1. picUrl 非空;
412
+ * 2. picUrl 末段在 `<id>/` 卡目录根存在且是文件(不是目录);
413
+ * 3. 每张卡都有 `<id>/<id>.json`。
414
+ * 返回问题清单(空数组 = 通过)。任何一条违例都会被导入侧的同一段逻辑打出异常。
415
+ * @param {{ cardsPO: Array<object>, outDir: string }} o
416
+ * @returns {string[]}
417
+ */
418
+ export function verifyCardsJsonInvariants({ cardsPO, outDir }) {
419
+ const problems = []
420
+ for (const po of cardsPO || []) {
421
+ const id = String(po && po.id)
422
+ const picUrl = po && po.picUrl
423
+ if (!picUrl) {
424
+ problems.push(`${id}: picUrl 为空(导入侧会按空串推封面文件名)`)
425
+ continue
426
+ }
427
+ const name = path.basename(String(picUrl).split('?')[0])
428
+ const coverAbs = path.join(outDir, id, name)
429
+ let stat = null
430
+ try {
431
+ stat = fs.statSync(coverAbs)
432
+ } catch {
433
+ /* 不存在即视为违例 */
434
+ }
435
+ if (!stat) problems.push(`${id}: 封面文件缺失 ${name}`)
436
+ else if (!stat.isFile()) problems.push(`${id}: 封面路径不是文件 ${name}`)
437
+ if (!fs.existsSync(path.join(outDir, id, `${id}.json`))) problems.push(`${id}: 单卡 JSON 缺失`)
438
+ }
439
+ return problems
440
+ }
441
+
442
+
443
+ /**
444
+ * 导出单张卡:写 <id>.json + 落图片/封面,返回 { cardPO, imageLists }。
445
+ * 图片下载失败不中断该卡(记 warnings),契约字段 imageLists 仍按全量引用生成。
446
+ */
447
+ async function exportOneCard({ root, id, outDir, upstream, buildPreview }) {
448
+ const cardDir = resolveCardDir(root, id)
449
+ if (!cardDir) throw new Error('非法卡片 id')
450
+ const schemaPath = path.join(cardDir, 'schema.json')
451
+ let schema
452
+ try {
453
+ schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
454
+ } catch (e) {
455
+ throw new Error(`读取 schema.json 失败:${e && e.message}`)
456
+ }
457
+ if (!schema || typeof schema !== 'object') throw new Error('schema.json 内容非法')
458
+
459
+ // 数字 id:优先 schema.pageId(导入卡与远端一致);自建卡 pageId 常等于 code,回落目录名
460
+ const numericId = /^\d+$/.test(String(schema.pageId)) ? String(schema.pageId) : id
461
+
462
+ let meta = null
463
+ try {
464
+ meta = readImportMeta(cardDir)
465
+ } catch {
466
+ /* 侧车缺失/损坏不影响导出 */
467
+ }
468
+
469
+ // 封面先定:picUrl 与封面文件名是同一个决定,缺封面必须当场失败(不能产出自带空 picUrl 的包)。
470
+ const coverPath = findExistingCover(cardDir, id)
471
+ if (!coverPath) {
472
+ throw new Error(
473
+ `本地无封面图(src/cards/${id}/${id}.png):导入侧无条件按 picUrl 末段读卡目录根的封面,` +
474
+ '无封面必导入失败。请先在卡片上「生成封面预览图」补齐,再重试导出'
475
+ )
476
+ }
477
+ const remoteMeta = (meta && meta.remote) || null
478
+ const cover = resolveCoverForExport({
479
+ remotePicUrl: remoteMeta && remoteMeta.picUrl,
480
+ coverPath,
481
+ })
482
+
483
+ const cardPO = {
484
+ id: numericId,
485
+ name: (schema.name || '').toString(),
486
+ cardStatus: '1',
487
+ createTime: null,
488
+ updateTime: null,
489
+ sassAppId: (meta && meta.appId) || '100001',
490
+ sassWorkspaceId: (meta && meta.workspaceId) || 'dev',
491
+ // picUrl 恒非空,且末段 === 卡目录根封面文件名(见 resolveCoverForExport 的契约说明):
492
+ // 有远端真值(侧车 remote.picUrl)就原样沿用,与官方产物同构;本地新建卡按同一形态合成。
493
+ picUrl: cover.picUrl,
494
+ // 远端列表才有的分类字段:有真值用真值(官方 57 张样本里恒非空),未知时留空由导入侧兜底
495
+ cardClassId: (remoteMeta && remoteMeta.cardClassId) || '',
496
+ code: id,
497
+ // applyScene 不是常量:官方两份产物分别是 '1'(2 张)与 '2'(57 张),必须取真值
498
+ applyScene: (remoteMeta && remoteMeta.applyScene) || '1',
499
+ }
500
+
501
+ // previewSchema:优先 buildPreview(编辑器同源实现);不可用或抛错时退化为 schema 原样。
502
+ // 序列化时剥离 _schemaNode:全代码库约定(server/core/cardFiles.js、App.vue 存档 /
503
+ // 剪贴板 / dirty 比对等同一 replacer),它是对原始 schema 节点的运行时自引用,
504
+ // 不带 replacer 会让 previewSchema 膨胀约 6 倍并偏离样本形态(样本无该字段)。
505
+ let previewSchema
506
+ try {
507
+ const preview = buildPreview ? buildPreview(schema) : schema
508
+ previewSchema = JSON.stringify(preview, (k, v) => (k === '_schemaNode' ? undefined : v))
509
+ } catch (e) {
510
+ previewSchema = JSON.stringify(schema)
511
+ log.warn('previewSchema 生成失败,退化为 schema 原样', { id, error: e && e.message })
512
+ }
513
+
514
+ const cardJobPO = {
515
+ id: null,
516
+ cardId: numericId,
517
+ schemaValue: JSON.stringify(schema),
518
+ previewSchema,
519
+ screenshotUrl: '',
520
+ createTime: null,
521
+ updateTime: null,
522
+ skeletonScreen: MIN_SKELETON,
523
+ }
524
+
525
+ const variablePOS = ((schema.dictionary && schema.dictionary.inputParams) || []).map((p) => ({
526
+ id: null,
527
+ cardId: numericId,
528
+ variableKey: p.key,
529
+ variableName: p.name != null ? p.name : p.key,
530
+ variableType: p.type,
531
+ variableDescribe: p.desc || '',
532
+ variableDefaultValue: JSON.stringify(p.defaultValue === undefined ? null : p.defaultValue),
533
+ variableStructure: JSON.stringify(p),
534
+ createTime: null,
535
+ updateTime: null,
536
+ }))
537
+
538
+ const refs = collectViewImageRefs(schema.view)
539
+ const imageLists = refs.map(({ ref }) => {
540
+ const imageName = refBasename(ref)
541
+ return {
542
+ originalUrls: ref,
543
+ localUrl: `/image/${imageName}`,
544
+ targetUrl: null,
545
+ imageName,
546
+ }
547
+ })
548
+
549
+ // 落盘:<outDir>/<numericId>/
550
+ const cardOutDir = path.join(outDir, numericId)
551
+ fs.mkdirSync(cardOutDir, { recursive: true })
552
+ const warnings = []
553
+
554
+ // 图片:@filestore 走 minio 公网下载;/slices/ 从 src/slices 拷贝
555
+ for (const { ref, kind } of refs) {
556
+ const imageName = refBasename(ref)
557
+ if (!imageName) continue
558
+ const dest = path.join(cardOutDir, 'image', imageName)
559
+ try {
560
+ fs.mkdirSync(path.dirname(dest), { recursive: true })
561
+ if (kind === 'slice') {
562
+ const src = path.join(root, 'src', 'slices', imageName)
563
+ if (!fs.existsSync(src)) throw new Error('本地切图不存在')
564
+ fs.copyFileSync(src, dest)
565
+ } else {
566
+ const url = filestoreUrlFor(ref, upstream)
567
+ if (!url) throw new Error('未配置 FinMall 上游地址,无法下载 @filestore 图片')
568
+ const res = await fetch(url, {
569
+ headers: { 'User-Agent': 'Mozilla/5.0', Referer: upstream ? `${upstream}/` : '' },
570
+ signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
571
+ })
572
+ if (!res.ok) throw new Error(`HTTP ${res.status}`)
573
+ const ct = res.headers.get('content-type') || ''
574
+ if (ct.includes('text/html')) throw new Error('上游返回 HTML(疑似 404 页)')
575
+ const buf = Buffer.from(await res.arrayBuffer())
576
+ if (!buf.length) throw new Error('空响应')
577
+ fs.writeFileSync(dest, buf)
578
+ }
579
+ } catch (e) {
580
+ warnings.push(`图片落地失败 ${imageName}:${e && e.message}`)
581
+ log.warn('导出图片落地失败', { id, imageName, error: e && e.message })
582
+ }
583
+ }
584
+
585
+ // 封面:以 picUrl 末段的文件名落卡目录根(导入侧按此名取文件;官方产物同形)
586
+ fs.copyFileSync(coverPath, path.join(cardOutDir, cover.fileName))
587
+ if (!cover.inherited) {
588
+ warnings.push(`本地无远端 picUrl,封面已合成 ${cover.picUrl}(文件名为本地预览图名)`)
589
+ }
590
+
591
+ const cardJson = JSON.stringify({
592
+ cardPO,
593
+ cardJobPO,
594
+ variablePOS,
595
+ imageLists,
596
+ platformStatus: PLATFORM_STATUS,
597
+ })
598
+ fs.writeFileSync(path.join(cardOutDir, `${numericId}.json`), cardJson, 'utf8')
599
+
600
+ return { cardPO, warnings }
601
+ }
602
+
603
+ /**
604
+ * 跑导出任务(后台执行,进度经 job.progress 暴露)。
605
+ * @param {object} job
606
+ * @param {{ root: string, cardIds: string[], targetDir: string, upstream: string, viteServer: object|null }} ctx
607
+ */
608
+ async function runExportJob(job, { root, cardIds, targetDir, upstream, viteServer }) {
609
+ // buildPreview:优先经 vite ssrLoadModule 复用编辑器同源实现(与 /__render-status 同模式)
610
+ let buildPreview = null
611
+ if (viteServer && typeof viteServer.ssrLoadModule === 'function') {
612
+ try {
613
+ const mod = await viteServer.ssrLoadModule('/runtime/toPreview.js')
614
+ if (typeof mod.buildPreview === 'function') buildPreview = mod.buildPreview
615
+ } catch (e) {
616
+ log.warn('toPreview 模块加载失败,previewSchema 将退化为 schema 原样', { error: e && e.message })
617
+ }
618
+ }
619
+ if (!buildPreview) log.warn('无 vite 实例或 toPreview 不可用,previewSchema 退化为 schema 原样')
620
+
621
+ const cardsPO = []
622
+ const failed = []
623
+ const warnings = []
624
+ const zipEntries = []
625
+ const folderName = stampFolderName(targetDir)
626
+ const outDir = path.join(targetDir, folderName)
627
+ let revealed = false
628
+
629
+ try {
630
+ fs.mkdirSync(outDir, { recursive: true })
631
+ log.ok('开始导出卡片', { jobId: job.id, folderName, targetDir, total: cardIds.length })
632
+
633
+ for (const id of cardIds) {
634
+ if (job.cancelRequested) break
635
+ job.progress.currentId = id
636
+ job.progress.currentTitle = ''
637
+ try {
638
+ const { cardPO, warnings: w } = await exportOneCard({
639
+ root,
640
+ id,
641
+ outDir,
642
+ upstream,
643
+ buildPreview,
644
+ })
645
+ cardsPO.push(cardPO)
646
+ for (const x of w) warnings.push(`${id}: ${x}`)
647
+ } catch (e) {
648
+ failed.push({ id, error: e && e.message })
649
+ log.error('导出单卡失败', { id, error: e && e.message })
650
+ }
651
+ job.progress.done = cardsPO.length + failed.length
652
+ }
653
+
654
+ if (job.cancelRequested) {
655
+ // 取消:清理半成品目录(无 zip 产出,留着会违反命名契约),不 reveal
656
+ fs.rmSync(outDir, { recursive: true, force: true })
657
+ job.result = {
658
+ success: false,
659
+ cancelled: true,
660
+ exported: cardsPO.length,
661
+ failed,
662
+ message: `导出已取消(已完成 ${cardsPO.length} 张)`,
663
+ }
664
+ log.warn('导出任务被取消', { jobId: job.id, done: cardsPO.length })
665
+ return
666
+ }
667
+
668
+ if (!cardsPO.length) {
669
+ throw new Error(failed.length ? `全部 ${failed.length} 张卡片导出失败` : '没有可导出的卡片')
670
+ }
671
+
672
+ // 产物自检:卡片清单的每条都必须能被导入侧无防御地消费(picUrl 非空 + 封面文件在位)。
673
+ // 与后端无关的纯本地断言,任何一条违例都意味着导入侧同一段逻辑必炸 —— 宁可整单失败,不出残包。
674
+ const problems = verifyCardsJsonInvariants({ cardsPO, outDir })
675
+ if (problems.length) {
676
+ throw new Error(
677
+ `导出产物自检未通过(${problems.length} 项):${problems.slice(0, 5).join(';')}` +
678
+ (problems.length > 5 ? ' 等' : '')
679
+ )
680
+ }
681
+
682
+ // 收集 zip 条目(按名排序保证确定性),cards.json 殿后(与样本一致)。
683
+ // 条目名一律经 zipEntryName 转 ASCII:JSON 里保留原名,包内文件名 percent-encode。
684
+ const collectEntries = (dir, prefix) => {
685
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
686
+ const full = path.join(dir, entry.name)
687
+ const rel = prefix ? `${prefix}/${entry.name}` : entry.name
688
+ if (entry.isDirectory()) collectEntries(full, rel)
689
+ else zipEntries.push({ name: zipEntryName(rel), data: fs.readFileSync(full) })
690
+ }
691
+ }
692
+ collectEntries(outDir, '')
693
+ zipEntries.sort((a, b) => a.name.localeCompare(b.name))
694
+ fs.writeFileSync(path.join(outDir, 'cards.json'), JSON.stringify(cardsPO), 'utf8')
695
+ zipEntries.push({ name: 'cards.json', data: Buffer.from(JSON.stringify(cardsPO), 'utf8') })
696
+
697
+ // zip 层自检:条目名全 ASCII(对齐官方 439/439)、无重名、每张卡的封面条目按编码名命中
698
+ const zipProblems = verifyZipEntryNames({
699
+ cardsPO,
700
+ zipNames: zipEntries.map((e) => e.name),
701
+ })
702
+ if (zipProblems.length) {
703
+ throw new Error(
704
+ `导出产物 zip 自检未通过(${zipProblems.length} 项):${zipProblems.slice(0, 5).join(';')}` +
705
+ (zipProblems.length > 5 ? ' 等' : '')
706
+ )
707
+ }
708
+
709
+ const zipPath = path.join(targetDir, `${folderName}.zip`)
710
+ fs.writeFileSync(zipPath, buildZip(zipEntries))
711
+
712
+ // 原文件夹删除,只留同名 zip
713
+ fs.rmSync(outDir, { recursive: true, force: true })
714
+
715
+ revealed = revealFileInOS(zipPath)
716
+
717
+ job.result = {
718
+ success: true,
719
+ folderName,
720
+ zipPath,
721
+ exported: cardsPO.length,
722
+ failed,
723
+ warnings,
724
+ revealed,
725
+ }
726
+ log.ok('导出完成', { jobId: job.id, folderName, zipPath, exported: cardsPO.length, failed: failed.length })
727
+ } catch (e) {
728
+ try {
729
+ fs.rmSync(outDir, { recursive: true, force: true })
730
+ } catch {
731
+ /* 清理失败不掩盖原始错误 */
732
+ }
733
+ job.result = { success: false, error: e && e.message, exported: cardsPO.length, failed }
734
+ log.error('导出任务失败', e)
735
+ }
736
+ }
737
+
738
+ /**
739
+ * @param {{ root: string, viteServer?: import('vite').ViteDevServer|null, upstream?: string }} opts
740
+ * @returns {(req: import('http').IncomingMessage, res: import('http').ServerResponse, next: Function) => void}
741
+ */
742
+ export function createExportMiddleware({ root, viteServer = null, upstream = '' }) {
743
+ const readJsonBody = (req, res, cb) => {
744
+ let body = ''
745
+ req.setEncoding('utf8')
746
+ req.on('data', (c) => {
747
+ body += c
748
+ if (body.length > 1024 * 1024) req.destroy()
749
+ })
750
+ req.on('end', () => {
751
+ try {
752
+ cb(JSON.parse(body || '{}'))
753
+ } catch (e) {
754
+ res.statusCode = 400
755
+ res.setHeader('Content-Type', 'application/json')
756
+ res.end(JSON.stringify({ ok: false, error: 'invalid json', message: String(e.message) }))
757
+ }
758
+ })
759
+ }
760
+ const sendJson = (res, status, obj) => {
761
+ res.statusCode = status
762
+ res.setHeader('Content-Type', 'application/json')
763
+ res.setHeader('Cache-Control', 'no-store')
764
+ res.end(JSON.stringify(obj))
765
+ }
766
+
767
+ return function exportMiddleware(req, res, next) {
768
+ const pathname = decodeURIComponent((req.url || '').split('?')[0])
769
+ const method = (req.method || 'GET').toUpperCase()
770
+
771
+ // ---- 目录建议(导出目录弹框预填):桌面 / 下载 / 主目录,跨平台尽力而为 ----
772
+ if (pathname === '/__export/dir-suggestions') {
773
+ if (method !== 'GET') return next()
774
+ const home = os.homedir()
775
+ const pick = (name) => {
776
+ const p = path.join(home, name)
777
+ return fs.existsSync(p) ? p : ''
778
+ }
779
+ const desktop = pick('Desktop') || home
780
+ const downloads = pick('Downloads') || home
781
+ return sendJson(res, 200, { ok: true, home, desktop, downloads, default: desktop })
782
+ }
783
+
784
+ // ---- 导出进度查询(轮询) ----
785
+ if (pathname === '/__export/progress') {
786
+ if (method !== 'GET') return next()
787
+ const jobId = new URL(req.url, 'http://127.0.0.1').searchParams.get('jobId') || ''
788
+ const job = exportJobs.get(jobId)
789
+ if (!job) {
790
+ return sendJson(res, 404, { ok: false, error: 'unknown job', message: '导出任务不存在或已过期' })
791
+ }
792
+ return sendJson(res, 200, {
793
+ ok: true,
794
+ jobId: job.id,
795
+ done: job.progress.done,
796
+ total: job.progress.total,
797
+ currentId: job.progress.currentId,
798
+ currentTitle: job.progress.currentTitle,
799
+ finished: job.finished,
800
+ result: job.result,
801
+ })
802
+ }
803
+
804
+ // ---- 取消导出(下一张卡片前生效) ----
805
+ if (pathname === '/__export/cancel') {
806
+ if (method !== 'POST') return next()
807
+ return readJsonBody(req, res, (payload) => {
808
+ const jobId = String(payload.jobId || '')
809
+ const job = exportJobs.get(jobId)
810
+ if (!job || job.finished) {
811
+ return sendJson(res, 404, { ok: false, error: 'unknown job', message: '导出任务不存在或已结束' })
812
+ }
813
+ job.cancelRequested = true
814
+ return sendJson(res, 200, { ok: true })
815
+ })
816
+ }
817
+
818
+ if (pathname !== '/__export-cards') return next()
819
+ if (method !== 'POST') return next()
820
+
821
+ return readJsonBody(req, res, (payload) => {
822
+ // 入参:cardIds 集合 + targetDir 导出目录
823
+ const ids = Array.isArray(payload.cardIds)
824
+ ? [...new Set(payload.cardIds.filter((c) => typeof c === 'string'))]
825
+ : []
826
+ const targetDirRaw = typeof payload.targetDir === 'string' ? payload.targetDir.trim() : ''
827
+
828
+ if (!ids.length) {
829
+ return sendJson(res, 400, { ok: false, error: 'empty_card_ids', message: '请先勾选要导出的卡片' })
830
+ }
831
+ if (ids.length > MAX_EXPORT_CARDS) {
832
+ return sendJson(res, 400, { ok: false, error: 'too_many', message: `单次导出勾选不能超过 ${MAX_EXPORT_CARDS} 张` })
833
+ }
834
+ if (!targetDirRaw || !path.isAbsolute(targetDirRaw)) {
835
+ return sendJson(res, 400, { ok: false, error: 'invalid_target_dir', message: '导出目录必须是绝对路径' })
836
+ }
837
+ // 卡片 id 合法性 + 归属校验(resolveCardDir 内含白名单与穿越防护)
838
+ const safeIds = []
839
+ for (const id of ids) {
840
+ const dir = resolveCardDir(root, id)
841
+ if (!dir || !fs.existsSync(dir)) {
842
+ return sendJson(res, 400, { ok: false, error: 'invalid_card_id', message: `卡片不存在或 id 非法:${id}` })
843
+ }
844
+ safeIds.push(id)
845
+ }
846
+
847
+ const targetDir = path.resolve(targetDirRaw)
848
+ // 功能性禁区:src/cards(会被卡片列表扫描成垃圾卡片)与 node_modules(污染依赖目录)
849
+ const cardsRoot = path.resolve(root, 'src', 'cards')
850
+ const nmRoot = path.resolve(root, 'node_modules')
851
+ if (targetDir === cardsRoot || targetDir.startsWith(cardsRoot + path.sep)) {
852
+ return sendJson(res, 400, {
853
+ ok: false,
854
+ error: 'forbidden_target_dir',
855
+ message: '不能导出到 src/cards 目录(会被卡片列表扫描收录)',
856
+ })
857
+ }
858
+ if (targetDir === nmRoot || targetDir.startsWith(nmRoot + path.sep)) {
859
+ return sendJson(res, 400, {
860
+ ok: false,
861
+ error: 'forbidden_target_dir',
862
+ message: '不能导出到 node_modules 目录',
863
+ })
864
+ }
865
+ try {
866
+ fs.mkdirSync(targetDir, { recursive: true })
867
+ } catch (e) {
868
+ return sendJson(res, 400, { ok: false, error: 'target_dir_unwritable', message: `导出目录不可用:${e && e.message}` })
869
+ }
870
+
871
+ // 同一时刻只允许一个导出任务(与 /__sync 同口径)
872
+ if (activeExportJob()) {
873
+ return sendJson(res, 409, { ok: false, error: 'export_in_progress', message: '已有导出任务正在进行,请等待完成或取消' })
874
+ }
875
+
876
+ exportJobSeq += 1
877
+ const job = {
878
+ id: `ej-${Date.now().toString(36)}-${exportJobSeq}`,
879
+ createdAt: Date.now(),
880
+ cancelRequested: false,
881
+ timedOut: false,
882
+ finished: false,
883
+ progress: { done: 0, total: safeIds.length, currentId: '', currentTitle: '' },
884
+ result: null,
885
+ }
886
+ rememberExportJob(job)
887
+
888
+ // 看门狗:与同步任务同款兜底,防单次导出无限期占用服务
889
+ const watchdog = setTimeout(() => {
890
+ if (job.finished) return
891
+ job.timedOut = true
892
+ job.cancelRequested = true
893
+ job.finished = true
894
+ job.result = {
895
+ success: false,
896
+ timedOut: true,
897
+ error: `导出任务超过 ${Math.round(EXPORT_JOB_TIMEOUT_MS / 1000)} 秒未完成,已自动收尾。请重试,或检查网络(导出需下载远端图片)。`,
898
+ }
899
+ log.error('导出看门狗触发:任务超时,已代其收尾', { jobId: job.id })
900
+ }, EXPORT_JOB_TIMEOUT_MS)
901
+ if (typeof watchdog.unref === 'function') watchdog.unref()
902
+
903
+ ;(async () => {
904
+ try {
905
+ await runExportJob(job, { root, cardIds: safeIds, targetDir, upstream, viteServer })
906
+ } finally {
907
+ clearTimeout(watchdog)
908
+ // 看门狗已代收尾时不回滚结论
909
+ if (!job.timedOut) job.finished = true
910
+ }
911
+ })()
912
+
913
+ return sendJson(res, 200, { ok: true, jobId: job.id, total: job.progress.total })
914
+ })
915
+ }
916
+ }