跳转至

SPEC-014 · 整页 Markdown 存储与上传契约

给谁看:接手云端后端的开发。 为什么写:v0.10.138 起客户端把抓到的网页整页转成 Markdown 存在本地, 并给每行留了 pending 标记 —— 但上传通道一根线都没接。 Tony 2026-09-01 拍板:「云端后边让开发做后端,文档要留好」。 本文写清楚存了什么、为什么这么存、以及后端要提供什么才能把它接上。

一、客户端现状(v0.10.138 已落地)

三版分工

版本 做了什么 能否回滚
v0.10.135 DB 初始化失败可见化 + 15 s 超时兜底(ISSUE-0111) ✅
v0.10.136 offscreen + turndown 转换层,结果只写 sysLog ✅
v0.10.137 offscreen 并发误杀修复(ISSUE-0113) ✅
v0.10.138 PageMarkdown 表 + version 5→6 + 淘汰 + 级联删 🔴 不可逆

为什么是 Markdown 而不是纯文本或原始 HTML

Tony 原话:「我希望是 Markdown 因为这个后续 AI 更易读」。 落地时又明确否掉了精简版:「不要精简转化 要完整页面!」—— 理由成立:按「联系方式够用」裁掉的部分,恰恰是下游 AI 判断商家类型 / 规模 / 主营的依据。

转换在 offscreen document 里跑,因为 turndown 需要 DOMParser, 而 MV3 Service Worker 里没有。这是硬约束,不是性能取舍。

二、表结构(PageMarkdown)

列 类型 enableSearch 说明
urlHash String primaryKey sha256(url)。同页重抓 upsert 覆盖,不堆历史版本
googleId String true 🔴 级联删除唯一可行的外键
domain String true 仅人工检索用,不参与删除判据
normalizedUrl String false
md String false 整页 Markdown 明文
bytes / htmlBytes Number false
visibleTextLen Number false frontmatter 后的非空白字符数,用来事后捞空壳页
scrapedAt Number true 淘汰按它走 where
pending Number(0/1) true 上传队列标记,默认 1

🔴 enableSearch 在 jsstore 里缺省是 true(worker 源码 :211), 每个 false 都必须显式写 —— 不写就是给整页正文建索引。

为什么外键必须是 googleId

  • domain 一对多,会误删同域名的其它商家;
  • getIdsByQuery 返回的是 MapTaskData 的自增 id,与 googleId 连类型都不同, 拿它匹配会命中 0 行且不报错 —— 删了个寂寞还看不出来。

客户端为此把 googleId 从 engine-manager 一路传到写库口 (processWebsiteScrape / runWebsiteScrapePipeline / scheduleMarkdownConversion 都加了可选参数)。 拿不到 googleId 就不入库,宁可少存一页,也不写一行永远删不掉的孤儿。

三、🔴 两条铁律(后端接线时也要知道)

1. 本表任何查询禁止带 order

jsstore 的 Select 构造器一见 orderQuery 就 setLimitAndSkipEvaluationAtEnd_() (worker :2989-2995)⇒ limit 只在末尾 slice、游标先扫全表。 真 jsstore 4.9.0 + fake-indexeddb 实测(25 KB/行):

行数 {order, limit:50} {where:{scrapedAt:'<'}, limit:50} count()
2,000 97 ms 4 ms 0 ms
20,000 621 ms / heap 1,274 MB 2 ms 1 ms

而 jsstore 在 MV3 SW 里跑在主线程(IS_WORKER 判据 worker :1213 在 SW 下为 false), 那 621 ms 就是采集调度器被占住的 621 ms。

2. 将来撤掉 Markdown 只能「停止写入 + 保留表定义」

从 tables 数组里删掉这张表 = 该 store 被 deleteObjectStore 静默删掉(worker :642)。 不报错、不提示。

四、上限与淘汰

  • 上限按行数:MAX_MD_ROWS = 30_000(× 25.7 KB ≈ 771 MB 明文)
  • 超限后淘汰到 90% 水位,按 scrapedAt 从老到新
  • 用实时 count() 而非影子计数器:计数器要存 storage.local, 而 SW 30 s 空闲即杀 + deepScrapeConcurrency 最高 10 的读改写竞态会让它单向漂移; 一旦漂高,库里没满也会每插一条淘汰一条,且「永不全表 sum」恰恰堵死自愈路径。 count() 只要 1 ms,直接查真值。
  • 没有 order 就拿不到「第 N 老那行」的时间戳,改用二分探 cutoff(24 轮 ≈ 24 ms)
  • 🔴 淘汰写 sysLog(warn 级),用户的数据被删掉了不能只有 console

wxt.config.ts 已加 unlimitedStorage。 🔴 它只解配额上限,不解 best-effort 逐出 —— 浏览器在磁盘吃紧时仍可能整库回收, 别拿它当持久性保证。

五、级联删除(四个入口全接)

入口 文件 做法
deleteByQuery(有 where) search-data.ts 先 collectGoogleIdsFor → 删主表 → 级联
deleteByQuery(空 where) search-data.ts clearData 主表 → clearPageMarkdown
deleteNoEmail 的 dropIds search-data.ts 同上,先收后删
删任务时删数据 task-manager.ts allRows 是全字段查询,googleId 直接在手
clearSearchData search-data.ts 主表清空 → 附属表清空

🔴 顺序不能反:collectGoogleIdsFor 一旦挪到 removeByQuery 之后, 它查的就是已被删掉的行 → 返回空数组 → 级联一行不删 → 留下永远删不掉的孤儿。 而这个失效完全静默:主表删除照样成功、无异常、无日志,只有磁盘在涨。 tests/page-markdown-cascade-order.test.ts 用源码顺序断言把它钉死了。

级联失败不抛:主表删除是用户的核心诉求且已成功,不能因附属表没删干净就报失败; 失败写 sysLog,残留会在下次 clearSearchData 时清掉。

六、⚠️ 后端要提供什么(本版未接,通道待建)

客户端当前只留接口面:

// src/utils/page-markdown-store.ts
takePendingMarkdownBatch(limit = 20): Promise<PageMarkdownRow[]>   // where:{pending:1}

🔴 绝不能走 cloud-data-sync.tsx

它的 payload 过 exNullData(parse-data.ts:174)—— 遍历全部 key、零白名单。 接上去整页正文会直接出网,且没有任何字段级控制。 Markdown 上传必须走独立的、显式字段白名单的通道。

后端需要提供

  1. 一个独立端点(不复用 SPEC-011 通道B 的商家同步端点),接收 { urlHash, normalizedUrl, domain, md, bytes, scrapedAt } —— 不含 googleId (那是本地自增域的业务主键,出网没有意义且是额外的可关联信息)。
  2. 幂等语义:以 urlHash 为幂等键。客户端会重抓同一页并 upsert 覆盖本地行, 上传可能重复发同一个 urlHash,服务端必须能安全覆盖或忽略。
  3. 明确的成功回执,客户端据此把 pending 置 0。 没有回执就不能置 0 —— 否则一次网络抖动就是永久丢页。
  4. 体积上限与拒收语义:单页明文可达数百 KB。服务端要给出上限, 并在超限时返回可区分的错误码(客户端据此把该行标记为「不再重试」而不是无限重发)。

未定,需要 Tony 拍板的

  • 整页正文出网的合规边界(抓的是公开网页,但整页存储 + 上传与只存联系方式性质不同)
  • 保留期与服务端侧的淘汰策略
  • 是否需要按域名/客户维度隔离

七、证据边界

  • 本地存储、淘汰、级联删的逻辑全部有单测(page-markdown-store.test.ts 14 条 + page-markdown-cascade-order.test.ts 8 条),并做过变异自测(五路 + 三路全部咬住)。
  • 🔴 但没有在真实 Chrome MV3 里跑过完整链路 —— 单测用内存数组 mock 掉了 jsstore helper,测的是本项目写的逻辑,不是 jsstore 的真实行为。 jsstore 的行为结论(order 扫全表、enableSearch 缺省 true、删表即 deleteObjectStore) 来自逐行读 worker 源码 + 基线里记录的 fake-indexeddb 实测,本版未复跑。
  • 30,000 行 × 25.7 KB 的容量估算是算术推算,没有真的灌满过。