跳转至

SPEC-013 · ContactPool 云端合并契约

给谁看:接手云端后端的开发。 为什么写:客户端 v0.10.131 起把云端数据挡在门外了,这是有意的止血, 不是 bug。要让它重新流进来,需要后端先提供本文列的东西。 Tony 2026-09-01 拍板:「云端后边让开发做后端,文档要留好」。

一、现在是什么状态

客户端做了什么(v0.10.131,ISSUE-0108)

src/utils/contact-pool.ts 的 writeCloudRecords 从「整条覆盖式 upsert」改成字段级 merge:

本地已有 source='local' 的记录时:
  云端【只能】写 contributorCount / consensus / lastVerifiedAt 三个聚合字段
  emails / phones / socials / normalizedUrl / domain / source / syncedAt /
  scrapedAt / scrapeMethod —— 全部保留本地原值
本地没有 local 记录时:
  走原来的整条覆盖式 upsert(没有本地在制品可丢)

为什么改

对抗实跑复现的翻车:本地 {phones:['+33 1 42 60 30 30'], emails:['a@b.com'], source:'local'} 被云端旧版本覆盖后 —— phones 回滚(ISSUE-0097 删掉的坐标噪音原样回来)、 emails 清空、source 翻 'cloud'、syncedAt 被抹, 甚至 normalizedUrl / domain 在服务端不回这两个字段时被 || '' 兜底成空串。

🔴 这条规则的真实射程(比"保护在制品"大得多)

markUploaded(src/utils/contact-pool.ts:192)只 set syncedAt,从不把 source 翻成 'cloud'。

⇒ source === 'local' 是「一次抓取即永久」的状态,不是"还没上传成功"的临时态。 ⇒ 任何本机抓过的 URL,今后云端池里别的贡献者补的 emails / phones 永远进不来。

这可能正是想要的语义(「我自己抓的压过池子」),但它是产品判断。 要改成「云端可以补充本地缺失的联系方式」,见下面第三节。

二、现有接口(客户端侧已实现,后端要对齐)

src/utils/cloud-sync-client.ts:

函数 路径 方向
apiContactPoolUpload(items) POST /contact-pool/upload 上行
apiContactPoolQuery(hashes) POST /contact-pool/query 按 hash 查
apiContactPoolSince(since, limit, domain?) GET /contact-pool/since 增量拉取
apiDomainStateUpload(items) POST /domain-state/upload 域名状态上行
apiDomainStateList(since, limit) GET /domain-state/list 域名状态拉取
apiContributionLog(items) POST /contribution/log 贡献流水

上行的数据形状(ContactUploadItem):

{
  urlHash: string;          // 主键
  normalizedUrl: string;
  domain: string;
  emails: string[];
  phones: string[];
  socials: Record<string, string>;
  scrapedAt: number;
  scrapeMethod: 'fetch' | 'tab';
  clientVersion: string;    // ← 已经在传了,见第三节 ③
}

upload 的返回:{ accepted, rejected, newRecords, updatedRecords, contributionEarned, details? } since 的返回:{ items, hasMore, nextSince }

三、要让云端数据回流,后端需要提供三样东西

客户端不打算靠猜。以下三条任何一条缺失,客户端都无法安全地接受云端的 emails/phones:

① 一个可跨机比较的「谁更新」判据

现有字段都不行:

字段 为什么不行
scrapedAt 跨机时钟不可比;且服务端 r.scrapedAt \|\| now 会把缺字段的记录洗成"刚刚"
syncedAt 客户端 writeContactRecord 无条件写 0,markUploaded 只在上传成功后置非 0 —— 服务端未上线时恒为 0
contributorCount / consensus 是聚合量,不是版本

需要后端提供:一个单调递增的服务端版本号(如 serverRev: number,全局或 per-record), 或者一个明确的 updatedAt(服务端时钟,不是客户端上报的)。

② 不做并集的理由,或做并集的安全边界

🔴 客户端明确拒绝 emails/phones 的并集: 并集会让 ISSUE-0089 / 0097 / 0098 三轮「删假号」的修复复活垃圾 —— 那些坐标噪音、千分位金额、截断残片曾经被上传到云端, 如果云端把它们并回来,等于把三轮修复全部回滚。

需要后端明确:服务端存的是「所有贡献者上报过的并集」还是「经过判定的最优集」? - 若是并集 ⇒ 客户端只能整条替换或整条拒绝,不能合并 - 若是最优集 ⇒ 需要说明判定规则,客户端才能判断要不要信

③ 抽取器版本的可比性

clientVersion 已经在上行数据里传了。但服务端目前没有用它。

抽取逻辑在 v0.10.126 → v0.10.132 之间有 6 次实质变更 (ISSUE-0102/0103/0105/0106/0107/0109),同一个页面在不同版本下抽出的结果不同且后者更准。

需要后端提供:since 返回的每条记录带上它是哪个 clientVersion 抽出来的, 客户端才能判断「云端这条比我本地的新还是旧」。

四、客户端侧的配套改动(后端就绪后再做)

  1. writeCloudRecords 的 merge 规则加一条: 云端记录的 serverRev / extractorVersion 优于本地时,允许覆盖 emails/phones
  2. markUploaded 要不要把 source 翻成 'cloud'(当前不翻,导致 local 永久)—— 取决于后端对「谁是权威」的定义
  3. ContactRecord 加 serverRev 列 —— ⚠️ 走 jsstore 加列,见下

五、⚠️ jsstore 加列的既有结论(客户端侧的硬约束)

逐行读 node_modules/jsstore/dist/jsstore.worker.js 4.9.0 得出,别重复踩:

  • 加列不丢数据
  • 但只改 columns 不 bump version = 两套 schema:升级安装无索引、全新安装有索引, 同一份代码两种行为
  • 旧记录该字段读出来是 undefined,不会被 default 回填
  • enableSearch 缺省是 true(不是 false),要 false 必须显式写
  • 即使建了索引也没用:IndexedDB 不收录 keyPath 为 undefined 的记录, where:{serverRev:{'<':N}} 恰恰扫不到老记录,静默返回空 ⇒ 版本列只能按 urlHash 取单条后在 JS 里比对,永不进 where
  • version 单向:回滚到旧构建 open(name, 5) 抛 VersionError,整库读不出来
  • 当前 src/utils/jsstore/base.ts 是 version: 5,历史三次 bump 全是加新表,从未给已有表加过列

六、当前的观测数据(判断这件事值不值得做)

v0.10.131 起在 src/utils/website-scrape-pipeline.ts 加了埋点:

  • pool-hit:带 scrapeMethod / scrapedAt / source
  • pool-miss:每次官网抓取未命中时记一条

🔴 在拿到真实 hit/miss 之前,这件事的收益无法评估。 上一轮对抗给的量化闸门:

pool-hit / (pool-hit + pool-miss) ≥ 10%
  且  hit 中 scrapeMethod === 'fetch' 占比 ≥ 30%

两条同时满足,才谈云端合并的价值。

七、另外三个上一轮查出的事实(后端要知道)

  1. enableMultiStageScrape 默认 false(src/utils/storage-data.ts:247), scraper-executor.ts:240 是 === true 硬门。 ⇒ 未开多阶段的用户,池被 tab 路径无条件写入,却从来不被读。
  2. scrape_status 全仓没有 2→0 路径(三个写点:status=1 回收、在飞中断、新任务入库)。 ⇒ 已采集的行永远不再进队列,抽取逻辑的任何修复对存量数据收益恒为 0,与池无关。
  3. 池短路上游还压着两道无开关的字符串精确匹配闸: engine-manager.ts:181 batchDedupeByUrl(每 SW session 一次)和 scraper-executor.ts:201 的 per-row 复用。 ⇒ 池的边际命中只剩「归一化等价但字符串不同的 URL」+「行被 deleteNoEmail 删过而池记录还在」 +「云端记录」三条窄路。

八、验收(后端就绪后)

  • since 返回的记录带 serverRev(或等价的服务端版本)与 clientVersion
  • 明确回答第三节 ② 的问题(并集 or 最优集)
  • 客户端侧加一组 merge 规则测试: 云端新 → 覆盖;云端旧 → 保留本地;版本缺失 → 保留本地(fail-closed)
  • 回归:tests/contact-pool-merge.test.ts 现有断言不得退步