跳转至

Contact 数据池重做

零、先订正我上一轮的判断

Tony 问「这块逻辑是不是有点奇怪」,我当时给的建议是 「服务端上线前根本不写这个池」。

那个建议是错的,因为我没看全就下了结论。漏掉两件事:

  1. ContactPool 有 source: 'local' | 'cloud' 字段 —— 它有意把「我抓的」和「别人抓的」装在一张表,为的是抓之前一次查询同时命中两者
  2. website-scrape-pipeline.ts:141 的池命中是 pipeline 的第 ⓪ 步 —— 命中就直接返回,完全跳过这次抓取

也就是说:这个池现在就在实打实地省你的抓取次数。 关掉它 = 每个抓过的网址都要重抓一遍。

一、那「奇怪」在哪

不在存储模型,在表达。它不是主表的冗余副本,是另一个维度的索引:

主表 MapTaskData 池 ContactPool
主键 按商家 按 url hash
回答 这个商家的联系方式是什么 这个网址上能挖到什么
独有 评分 / 地址 / 分类 / 任务归属 source、contributorCount、consensus

连锁品牌的多个分店共用一个官网 —— 按商家存会把同一个站抓 N 遍,按 url 存才能「抓前查命中」。

⇒ 17801(池) vs 6502(官网去重)的差额不是垃圾,是历史抓取记录,那正是它的价值。

真正的问题只有一个:用户只看得到成本,看不到收益。

  • 看得到:占空间、数字和商家列表对不上、清空时一句吓人的「将删除所有本地数据」
  • 看不到:它已经帮你跳过了多少次抓取

一个只显示成本的功能,用户当然会想删掉它 —— Tony 就删了,而且删完毫无感觉。

二、四件事

① 让收益可见(最高优先级)

pipeline 已经在记 pool-hit / pool-miss(v0.10.131 加的观测字段), 命中率是现成的,只是没人显示。

概览区改成:

网址缓存
  已缓存 17,801 个网址    我抓的 17,801 · 别人的 0
  最近 7 天命中 1,204 次  ≈ 省下 1,204 次网站抓取
  • 「省下 N 次抓取」按 pool-hit 计数,日志里就有
  • 别人的那半为 0 时显示「服务端待上线」,别让它看起来像出了错

⚠️ 判据:命中数必须来自真实日志计数,不许估算。 估出来的数字一旦和用户直觉对不上,比不显示更伤信任。

② 把它是什么写在脸上

现在 改成
「Contact 数据池」 「已挖过的网址」+ 副标题「下次遇到直接用,不再重抓」
「总 17801 / 本地 17801 / 云端 0」 「我挖的 17,801 · 别人共享的 0(服务端待上线)」
(没有解释) 「数字比「官网列表」多,是因为这里按网址算,且保留历史抓过的记录 —— 那正是它能省下重抓的原因」

③ v2 重写(双路对抗审判 NO-GO 之后)

v1 我提的是「超过 STALE_DAYS 就不短路,重抓覆盖,失败时旧记录兜底」。 terra + dshf 两路都判 NO-GO,四条 P0。逐条认领并改方向:

F1 兜底会把陈旧数据伪装成新鲜抓取 ⇒ 取消兜底

审查方追到调用方:兜底若以 kind:'success' 返回, scraper-executor.ts:591 会 finalizeScrapedRow(scrape_status: 2, sync: 0) ⇒ 三年前的邮箱进主表、进邮箱计数、进 CSV、还重新排队上传。 而 PipelineOutcome 现有三个 kind 没有一个能表达「这是兜底缓存」。 我 v1 只写了「UI 上标明」——根本没动这个契约,而 UI 标不标, 数据已经以「挖掘完成」的身份写进去了。

⇒ 不兜底。 抓取失败就是失败,不拿旧数据充数。 旧记录仍留在池里、下次仍可命中(未过期时),但不参与本次抓取的结果。

「给一个三年前的数据且用户不知道」比「不给」更糟。 附带好处:不改 PipelineOutcome 契约,方案反而变简单。

F3 「抓到 0 条不写池」⇒ 池要能表达「确认没有」

这条最值钱,因为它暴露的是现在就存在的浪费,不只是 v1 方案的问题:

  • 抓到 0 条走 kind:'skip'(website-scrape-pipeline.ts:331-339),从不写池
  • 命中判据是 emails.length + phones.length > 0(:142)⇒ 空记录也不算命中

⇒ 池只记录「成功挖到什么」,不记录「抓过,确认没有」。 这两件事现在都表现为「查不到」,于是一个确认过没有邮箱的网址,每次遇到都要重抓。 而「确认没有」恰恰是抓了才知道的,同样值钱。

改法:池记录加一列 outcome: 'found' | 'empty'。

池里状态 现在 改后
抓到了 found + 数据 命中,跳过 命中,跳过
抓过、确实没有 ~~不写~~ → empty 每次重抓 命中,跳过
从没抓过 无记录 抓 抓

命中判据从「有数据」改成「有记录且未过期」。

🔴 这条不依赖 STALE 机制就能立刻见效 —— 它解决的是今天正在发生的重复抓取。 ⇒ 建议先单独上它,与 ③ 的其余部分解耦。

F2 「新结果覆盖旧记录」是整条替换 ⇒ 空不覆盖

writeContactRecord 丢弃旧 emails/phones(contact-pool.ts:141-163)。 可复现:池里是历史上 tab 抓到的 5 个邮箱 → 过期后重抓走快路径只命中 1 个 → 覆盖成 1 个,且 source 翻 local ⇒ 按 SPEC-013 的 local-first,云端再也补不回那 4 个。

⇒ 新结果为空时不覆盖 emails/phones(只更新 outcome/scrapedAt)。

⚠️ 非空时要不要取并集,本版不定案 —— 并集会累积历史垃圾(旧的错邮箱永远留着), 需要「保留几条、按什么排序、怎么淘汰」一整套判据。 先只做「空不覆盖」这一条确定有益的,并集列为待设计。

F4 「单条失败不阻塞整批」在现有代码里是把 rejected 也 markUploaded

cloud-sync-orchestrator.ts:129-131 ⇒ 1.8 万首同步静默丢件且不重试。 ⇒ 只 markUploaded 服务端确认 accepted 的那些;rejected 保留 syncedAt=0 等下轮。 🔴 但要防死循环:连续 N 轮都被 rejected 的记录要留痕并停止重试,否则每轮都白跑。

🔴 新增:已删商家的孤儿记录(Tony 点名要解释的那条)

是什么:你删掉一条商家 → 池里那条网址的记录不跟着删 → 它的 syncedAt=0 → 服务端一上线就会被批量上传。

要紧的是删除的动机:你删它很可能正是因为它有问题(数据错、是竞争对手、 是不想让别人知道的客户)。而「删除」这个动作从来没有传达到池。

现在零风险(服务端没上线,一条都没传)。但上线那天会一次性补传。

⇒ 上线前必须做一次孤儿清理,判据待定:

候选判据 问题
池里 normalizedUrl 不在主表 website 中 ⇒ 删 ❌ 会误杀「批量 URL 采集」那条路进来的记录(它们本来就没有对应商家)
只清「曾经有过对应商家、现在没有了」的 需要记「这条池记录是谁带进来的」—— 现在没有这个字段
上线前给用户一次性确认:「有 N 条来自已删商家,要不要一起贡献?」 最诚实,但要能算出 N

🔴 三条都需要先加一个来源字段才能落地。这条要 Tony 拍: 是加字段、还是上线前一刀切「只上传当前还有对应商家的记录」。

🔴 订正:不需要「单账号首日上传上限」(Tony 质疑后收回)

上一版我写了「服务端要先定单账号首日上传上限」。Tony 问「首日为啥限制?」—— 问得对,我把两件事混为一谈了:

是谁的问题 解法
瞬时写入压力 服务端的工程问题 429 + 退避、队列削峰 —— 客户端已经准备好
「每人每天只能传 X 条」 无 ❌ 不需要,而且是在惩罚贡献者:传得越多的人越早被卡

数据池要的是「大家多传」,配额与这个目标直接相反。 ⇒ 服务端做限流(保护自己),不做配额(限制用户)。

三、不做什么

提议 为什么不做
服务端上线前不写池 我第一版的错误建议。池现在就在省抓取次数,关了立刻变慢
删商家时同步删池 一个 url 可能对应多个商家;「不要这个商家」≠「这网址数据无效」。改用上线前一次性孤儿清理(见上)
把池合并进主表 主键维度不同(商家 vs 网址)
过期就删 数据是资产,删了不可逆;改成「过期不再替你省抓取」
失败时用旧记录兜底 v2 取消(F1)。给一个三年前的数据且用户不知道,比不给更糟
非空时取 emails 并集 v2 不定案(F2)。并集会累积历史垃圾,需要一整套保留/淘汰判据。先只做「空不覆盖」

四、落地顺序(v2 重排)

🔴 最有价值的那块被拆出来单独先上 —— 它不依赖其余任何部分:

# 做什么 代价 收益
0 F3:池记录「确认没有」(加 outcome 列,命中判据改「有记录且未过期」) 一次 schema 迁移 立刻消除「确认没邮箱的网址每次都重抓」这笔正在发生的浪费
1 ①② 表达层(收益可见 + 改名) 半天,零风险 解决 Tony「这逻辑是不是有点奇怪」的困惑
2 F2「空不覆盖」+ F4「只 mark accepted」 小改 堵住两条数据倒退/丢件
3 ③ 其余(STALE 不短路) 需要 0 的 outcome 先就位 防止拿旧数据当新的
4 ④ 首同步 + 孤儿清理 等服务端 上线就绪

⚠️ ①「让收益可见」有个前置问题没解决:命中率算不准。 system-log 是 5000 条环形缓冲(两路审查都点了),光官网 6502 个就能写爆, 「最近 7 天」会被系统性低估。 ⇒ 要么给池命中单独计数(不走通用日志),要么这个数字别显示。 显示一个已知偏低的数字,比不显示更伤信任。 这条待定。

五、要你拍的

  1. 孤儿记录怎么处理(上面新增那节):加来源字段, 还是上线前一刀切「只上传当前还有对应商家的记录」?
  2. STALE_DAYS 取多少(我给 180 天,推测、无实测依据)。 它只决定「要不要重抓」,不影响数据存亡 —— 定错代价小,可以先上再调。
  3. 命中率数字要不要显示(见上面的前置问题)。

六、本版没管的

  • 隐私合规(第三方联系方式跨用户共享、日志明文 PII)—— Tony 2026-09-17:「隐私你别管,后端会处理的」。
  • 多设备双写 / 跨机 scrapedAt 不可比(dshf F16)—— 服务端上线后才成为真问题。
  • 清站点数据后无法重建(dshf F18)—— 属于「用户主动清浏览器数据」, 与本方案的取舍无关。