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 抽出来的,
客户端才能判断「云端这条比我本地的新还是旧」。
四、客户端侧的配套改动(后端就绪后再做)¶
writeCloudRecords的 merge 规则加一条: 云端记录的serverRev/extractorVersion优于本地时,允许覆盖 emails/phonesmarkUploaded要不要把source翻成'cloud'(当前不翻,导致 local 永久)—— 取决于后端对「谁是权威」的定义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/sourcepool-miss:每次官网抓取未命中时记一条
🔴 在拿到真实 hit/miss 之前,这件事的收益无法评估。 上一轮对抗给的量化闸门:
两条同时满足,才谈云端合并的价值。
七、另外三个上一轮查出的事实(后端要知道)¶
enableMultiStageScrape默认 false(src/utils/storage-data.ts:247),scraper-executor.ts:240是=== true硬门。 ⇒ 未开多阶段的用户,池被 tab 路径无条件写入,却从来不被读。scrape_status全仓没有 2→0 路径(三个写点:status=1 回收、在飞中断、新任务入库)。 ⇒ 已采集的行永远不再进队列,抽取逻辑的任何修复对存量数据收益恒为 0,与池无关。- 池短路上游还压着两道无开关的字符串精确匹配闸:
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现有断言不得退步