SPEC-027 「采到多少」的唯一事实源与物化投影¶
为什么立这个 spec(Tony 2026-09-22 拍板「换」)¶
v0.16.27 → v0.16.28 连续两轮修「数字在撒谎」,两轮之后用户实测截图里仍有三处矛盾:
| 位置 | 显示 | 读的是哪个源 |
|---|---|---|
| 任务卡 | doctor 708 条 | countAllByTaskIds(当前库行数) |
| 任务详情 | 净增商家 30 | local:task-ingested 账本 |
| 任务卡 | 44/29594 | finishedCount(tab 收尾次数) |
| 任务详情 | 已采集 9 | countCombos(taskId,'done') |
两路跨厂商对抗审(terra-dsh × dshf)独立得出同一结论:
只要「源不止一个 + 没有对账 + 读不到就回落」三条同时成立,矛盾就会无限复发。 708/30、44/9、30/708 是同一个根因的三个面。
v0.16.28 的修法是逐个把显示端切到更可信的源,但保留了全部兜底, 而那些兜底数正是旧版本撒谎的那几个数 —— 任何一次读失败就在无声中把旧行为搬回来。
本仓 SKILL 的判据:同类缺陷反复出现 = 基元选错,换方案别修第 N 轮。
🔴 设计前查实的硬约束(不是假设)¶
| # | 约束 | 证据 |
|---|---|---|
| 1 | 组合库与主库是两个独立的 IndexedDB ⇒ 跨库原子事务不可能 | combo-db.ts 的 getComboDatabase() 用 comboDbName、version: 2;主库 base.ts:377 是 version: 6。注释明写「这个库的版本和主库的 6 没有任何关系」「当初不把表建进主库换来的东西」 |
| 2 | jsstore 4.9.0 有 Connection.prototype.transaction(query) |
node_modules/jsstore/dist/jsstore.commonjs2.js:875 |
| 3 | 但本仓从未用过它,能力与坑位未验 | grep -rn "\.transaction(" src/utils/jsstore/ = 0 命中 |
| 4 | 不能全表求和 | ISSUE-0188「四十万条卡死」;combo-db.ts:437-450 注释「拿数据库当计算器而不是当存储,是根本错误」;unusedSumByCombos 已标 @deprecated |
| 5 | 索引 count 便宜 | countCombos(taskId, status) 已在生产路径使用 |
| 6 | 组合表已经是「每组合一行」,带 status / resultCount / searchedAt |
combo-db.ts 的 tblSearchCombo |
⇒ 约束 1 决定了不能追求「商家表与组合表原子一致」。设计必须绕开,而不是假装能做到。
基元¶
唯一事实源 = 组合表
SearchCombo的行状态。 它本来就是「每个组合一行」,天然承载状态迁移(pending → done / failed / skipped)与该组合的入库数。
其余三个数全部降级:
| 原来的数 | 新身份 |
|---|---|
local:task-ingested 账本 |
并入投影,不再是独立的源 |
MapTask.resultCount |
保留字段但不再用于显示(storage 只加不删) |
countAllByTaskIds(库行数) |
改名为它真正的含义「当前库存」,做独立标签,不再冒充「净增」 |
finishedCount(tab 收尾次数) |
改名为「派发终结数」,不再冒充「已采集」 |
物化投影 TaskRollup¶
在组合库内(同一个 IDB,绕开约束 1)新增一张表:
TaskRollup {
taskId 主键
comboDone 已回写成功的组合数
comboPending 待采集
comboFailed 失败
comboSkipped 跳过
ingestedRows 这些组合一共入库了多少商家(只增)
since 这张 rollup 从什么时候开始统计(口径起点)
rebuiltAt 上次全量重建的时间
staleAt 发现与事实源不一致的时间(null = 一致)
}
三条硬规则¶
① 唯一写入点:markComboDone 内,组合行的 resultCount 与 rollup 的 ingestedRows
在同一次调用里一起更新。同库,可串行化。
⇒ 不再有「账本加了但组合没 done」这种分叉(ISSUE-0209 遗留 ③)。
② 读端无值即未知:所有显示指标只读 rollup。 rollup 没有 / 标了 stale ⇒ 显示「未知 / 校准中」,绝不回落任何估算。 这条是本 spec 的核心 —— 上一轮的教训是「兜底 = 谎言的复活机制」。
③ 可对账的不变量(便宜、可随时跑):
- 一致 ⇒ 信 rollup 的ingestedRows
- 不一致 ⇒ 置 staleAt,UI 显示「校准中」,后台修复
⚠️ ingestedRows 本身不可便宜校验(校验它就要求和 = 违反约束 4)。
它的正确性只能靠规则 ① 的「唯一写入点」保证 —— 这是本设计明确接受的证据边界,
不要在文档或代码注释里把它写成「已对账」。
迁移¶
- 老任务(rollup 不存在):不做全表求和回填(约束 4)。
用
countCombos重建组合计数部分(便宜),ingestedRows标为「自since起累计、不完整」。 - UI 必须显式区分「完整」与「仅自 X 起累计」两种口径 —— 这正是 v0.16.28 账本翻车的地方:
账本对老任务从 0 起算,而读端只要 key 存在就判
isLedgerTruth: true, 比旧估算更权威地错。
验收判据(行为级,不是源码字面)¶
- 任务卡与详情页的「净增商家」在任何时刻读同一个投影,不可能显示两个数
- 投影读不到时,两处都显示未知态,都不回落 liveCounts / resultCount / 组合表求和
markComboDone的组合行更新与 rollup 更新不可能只成功一半(改坏任一侧,对账断言必红)- 对账不变量被破坏时,
staleAt被置上且 UI 反映为「校准中」 - 老任务(无 rollup)显示为「仅自 X 起累计」,不显示成完整真值
- 「派发终结数」与「已采集(回写成功)」是两个分别可读的量,界面不混用一个标签
- 全流程不出现任何全表求和 / 把大批行拉回主线程(
scan:unbounded-query与scan:count-window须过)
非目标¶
- 完整事件溯源(每次 ingest 写一条不可变事件、投影由回放得到):
41 万组合 × N 页的事件表在 IndexedDB + 主线程上代价不可接受。本设计用
「唯一写入点 + 可对账的计数不变量」换取同等的可信度,并明确接受
ingestedRows不可校验这一证据边界。 - 跨库(商家表 ↔ 组合表)强一致:约束 1 决定做不到。「当前库存」与「累计入库」 本来就是两件事,分别显示、各自标注口径即可。
- 用
connection.transaction()重写现有读写:本仓零使用、坑位未知(约束 3)。 先用「同库 + 串行写入链」实现规则 ①;确需原子性时先单独 smoke 验证该 API,再决定是否采用。
🔴 实施中对设计的两处修正(实施方的裁决优于原设计,记录在此)¶
修正一:ingestedRows 的证据边界被一条恒等式部分消解¶
原设计承认「ingestedRows 不可便宜校验,只能靠唯一写入点保证」,并把它写成明确的证据边界。
写端实施刀给出了更好的解:不追求跨库原子(本仓做不到),而是给差额一个去处:
回写没写成的那笔 added 落进 local:combo-writeback-unattributed(串行写链),
markComboByKey / markComboForTab 带原因返回结局,早退不再静默。
⇒ 两个数不再凭空分叉:差额有名字、有去处、可核对。 这把原设计里一条「靠约定保证」的边界,变成了一条能跑的恒等式。
⚠️ 仍未消解的部分:Σ(组合行 resultCount) 本身的求和依然昂贵(违反约束 4),
所以这条恒等式是可核对的结构,不是便宜的常规校验。
实施方在 X_OPEN 里如实回答:没有找到既便宜又能真正校验 ingestedRows 的办法。
修正二:「绝不回落」从纪律升级为「那条路不存在」¶
原设计规则 ② 写的是「读不到即未知,绝不回落」——这是一条纪律。
显示端实施刀把它做成了结构:旧账本的显示读点整体删除
(IngestedCountReader / setIngestedCountReader / readIngestedCountDetailed / readIngestedCount
全部移除,main 与 background 两处接线同删)。
⇒ 回落通道不是被禁用,而是不存在。 这比原设计强:纪律会被下一个人绕过,删掉的代码不会自己长回来。
账本停写的条件顺序(实施方给出,原设计未覆盖)¶
账本的写入目前保留。停写必须按这个顺序,少一步就丢数据:
现在停 = 升级窗口内跑着的任务,其 v0.16.28 以来的增量直接丢 (那部分历史只存在于账本里,投影靠它播种)。
补建时机只能选「不可能有在途回写」的安全点 —— running / paused 一律排除,
因为翻页路径的账本与组合回写是并发发起的,此刻播种会双计。
安全点:SW 启动清扫(restoreBatch 后、reconcileTasks 前)、task-control resume 前、显式重建入口。
实施进度¶
| 刀 | 内容 | 状态 |
|---|---|---|
E fixNoFallbackRead |
读端去兜底、修 ahooks supersede 静默、账本加来源戳 | ✅ 299f5a1 |
F fixWritebackDurable |
绑定持久化、unattributed 恒等式、拆分派发/回写语义 |
✅ 299f5a1 |
G specRollupStore |
TaskRollup 表(组合库 v2→3)、唯一写入点、对账、迁移 |
✅ 299f5a1 |
H fixDomTestFlake |
测试基建:超时预算 + 防复发判据 | ✅ 299f5a1 |
第二刀 specRollupUI |
显示端只读投影、删除回落通道、双写过渡裁决 | ✅ 本次 |
| 收尾 | 完成通知 toast 的「已采集」名实不符(batch-controller.ts) |
✅ v0.16.29 |
收尾刀的三个判断值得记(它们是本 spec「宁可不说,不可乱说」的具体化):
1. ingestedRows(一共采到多少商家)故意不说 —— 老任务 ingestedRowsComplete=false,
而通知里没有位置标注「仅自 X 起累计」这个口径。
2. 文案不再说「共 N 个」—— 那个「共」是在承诺终值,而内容脚本的 store-page-data
是 fire-and-forget、batch-done 可能先到,存在极窄窗口。改说「已采集 N 个组合」,不承诺是全部。
3. 投影读不到 / stale ⇒ 「采集量暂不可读」,一个数都不报,通知照发 —— 不说数不等于不通知。
实施顺序¶
前两刀(已在途)是本 spec 的地基,不重复:
| 刀 | 内容 | 与本 spec 的关系 |
|---|---|---|
E fixNoFallbackRead |
读端去兜底、改未知态;修 refreshDeps 反复 supersede | 规则 ② 的读端形态 |
F fixWritebackDurable |
绑定持久化;账本与组合回写不再一侧早退另一侧照加;拆分派发/回写语义 | 规则 ① 的写端前提 + 判据 6 |
本 spec 在 E/F 落地之后实施:建表 → 唯一写入点 → 对账 → 迁移 → 切显示端 → 删除降级掉的源的显示用途。