跳转至

SPEC-026 把快速筛选做成内置视图

背景:我上一版理解错了

Tony 要的是「把有邮箱/有网址/高评分/挖掘状态做成视图」。 我 v0.16.12/13 做成了「在视图基础上再筛」的第二维度(chips + 视图并排一行,加了「再筛」两字)—— 那是把两套概念塞一行,不是做成视图。

我当时的依据是 use-data-source.ts:130 的 mergedFilters = [...视图 filters, ...快筛 filters] (两者叠加)。但那是现状的实现,不是要的设计 —— 要的是把快筛并入视图体系、消灭这个平行维度。

🔴 三路对抗审查的裁决(v2 重写,2026-09-21)

送审快照 d4398db,三路独立、互不参考、防自审:

路 执行方 角度 裁决
A dshf 易用性 / 心智 NO-GO(P0=4 P1=4)
B terra-dsh 冲突面 / 数据正确性 NO-GO(P0=3 P1=3)
C mimo-pro 架构 / 「有邮箱」 GO-WITH-CHANGES(P0=1)

v1 方案被打穿,本节是重写。 下面每一条都标了它来自哪一路、我坐实的结果。

三路独立一致的 P0(直接采纳,无需裁决)

① sys:* 会被写上云,而且会占满 /6 配额(A-P0① / B-P0①)

  • 放进 pinViews ⇒ table-views-header.tsx:147 的 N/6 当场变 6/6, 且 view-select-popover.tsx:138/159/182、table-views-header.tsx:104/205 的 >=6 闸全部封死, 用户再也固定不了自建视图;同时 9 个 pinViewsSave 调用点会把 sys:* 整数组 POST 上云
  • 放在 pinViews 外 ⇒ local-data-view.tsx:511-514 的 findIndex(...)<=0 → onViewIdChange('all') 会在每次 refresh 后把选中的内置视图静默打回「所有数据」 (保存 / 取消固定 / 新建视图都会触发 refresh)

⇒ v1 全文没说内置视图存在哪个 state,而两种放法都撞现有代码。必须显式定这条数据流。

② 「选视图」是第二条上云路径,v1 完全漏了(A-P0③ / B-P0②)

onViewChange 的 filters 不是本地的,来自 apiViewConfig('/api/views/view-config') 的云端响应 (local-data-view.tsx:396-410 / :435-443 / :487-490)。 sys:has-email 服务端没有记录 ⇒ 无 data ⇒ 点内置视图没有任何反应,而这次请求已把本地 id 送上云。

⇒ v1 的 R1 只盯 pinViewsSave,漏了这条。 ⇒ 连带否定 v1 把 R5「云端挂了内置视图仍可用」列为收益 —— 按 v1 实现,它没有实现路径。

③ notEdit: true 与「可取消固定」互斥(A-P0②)

table-views-tabs.tsx:174 的齿轮是 disabled={item.notEdit}, 而全行唯一的「取消固定」入口就在这个齿轮打开的菜单里(:243-254)。 'all' 之所以不受影响,是因为它压根不渲染齿轮(:167-168 渲染 <span></span>)。

⇒ v1 说「把 all 这个先例从 1 个扩展到 6 个」是错的 —— 那个先例不可迁移。 内置视图要么不渲染齿轮 + 另设取消固定入口,要么不能用 notEdit。

④ 取消固定后的找回路径不存在(A-P0④)

view-select-popover.tsx 三个 tab 100% 由 apiViewsList 云端数据填充(:81-94 / :205-223), checkbox 的 checked 取自云端 pinViewIds(:249)。v1 承诺的「能在弹层里找回来」没有载体。

⑤ 废掉 quickFilter 会咬删除安全闸(A-P1④ 变异实测 / C-②)

A 路在隔离副本实测:删掉 delete-scope.ts:56 的 quickFilter 判据 ⇒ tests/delete-scope.test.ts 由 22 passed 变 1 failed(失败用例正是 isStructurallyUnfiltered > quickFilter)。 quickFilter 是「结构性无筛选 ⇒ 才允许整表删除」这条安全判据的承重件。

⇒ v1 轻飘飘一句「整个废除」,爆炸半径一个字没列。

分歧裁决:「有邮箱」选 C,不选 B

A 路选 B、B 路选 C、C 路要求重估 ROI。不投票,回证据裁决:

论点 来自 我坐实的结果
「B 破坏 OR 语义」 B 路 ✅ 成立。exViewFiltersToQuery 确实支持 logic === 'or'(query.ts:247),而 hasEmailOnly 的 JS filter 发生在 baseQuery 查询之后(search.ts:179-184)⇒ 「有邮箱 OR 有网址」会被做成「(有网址) AND 有邮箱」
「C 的不可逆代价不可付」 A 路 ❌ 理由不成立。A 路引 ISSUE-0186 只读到「不可逆」这一半,而那份 issue 的结论恰恰是「另开独立库能力等价而零不可逆」,SPEC-025 已经这么做过(laifaxin-combos)
「B 的改动面被低估 3 倍(1 处 vs 6 处)」 C 路 ✅ 成立。v1 写的「exViewFilterToQuery 遇到 notEmpty 就设 hasEmailOnly」机制本身就是错的 —— 那个函数只构造 jsstore 查询(query.ts:297-302),hasEmailOnly 是独立 API 参数,只由 use-data-source.ts:141/:249 从 quickFilter 派生

⇒ 裁决:C(物化 hasEmail 字段)。A 路选 B 的唯一理由已被推翻,而 B 的语义缺陷是硬伤。

🔴 C 的落地前提:一条必须先实测的技术事实

C 要在 MapTaskData 的 columns 里加一个 hasEmail 字段。加字段要不要 bump 主库 version?

  • IndexedDB 的 objectStore 存任意 JS 对象,jsstore 的 columns 主要用于 建 keyPath / 建索引(enableSearch: true)和插入校验
  • ⇒ 加一个 enableSearch: false 的字段理论上不改 objectStore 结构、不需要 bump
  • ⚠️ 但这是推理,不是实测。 jsstore 4.9 是否会因 columns 变化自行要求 version 匹配,必须验。

实施前第一步:写一个最小实验验证这件事。 验不出来就退回到独立索引库方案。 (主库 version 必须停在 6 —— 那是「零不可逆」的唯一依据,见 ISSUE-0186。)

C 的连带项

  • 历史数据要一次性回填 hasEmail
  • hasEmail 不建索引 ⇒ where 查询在 jsstore 内部扫,比现状好 (现状是拉 5 万行回 JS filter),但仍受 scan:unbounded-query 管辖,要带理由
  • 回填完成前,「有邮箱」视图的行为要如实降级,不能静默给少的数据

其余三个问题的裁决

问题 裁决 依据
R3(三类系统视图并存) a:本地 6 个单独成一类 A、B 两路独立一致。理由正是 Tony 那句「你这直接塞一起去???」;弹层 Tabs 已是 scrollable,加第 4 个 tab 成本近零
R4(多设备不同步) 可接受,但不要复用云端 pin 数组 A 路判可接受(与「显示比例」同级);B 路反对 local-only 但它给的替代是「独立的账号同步设置」 —— 两路其实都反对「复用云端 pin ID 数组」,那正是 P0① 的雷。本批按本地存,跨设备同步单独立项
Q4(R1 的结构性防法) 在 apiPinViewsSave 入口统一剥离 A、B 两路独立一致。9 个调用点自动安全,逐点过滤是靠记性。且过滤按属性(notEdit)而非按 id 硬编码 —— 这个更好的写法仓内已有先例(table-views-tabs.tsx:111-115),v1 引的是脆弱版本

🔴 一条需要 Tony 拍板的取舍(三路都指出,我解不了)

合并成单选 viewId 之后,「自建视图 ∩ 有邮箱」这种组合会丢掉(A-P1②)。

现在两者叠加(use-data-source.ts:130),所以「我的高价值客户 + 只看有邮箱的」是可表达的。 而仓内三处注释正是为反对合并写的(merchant-quick-filters.tsx:9-14、 local-data-view.tsx:790-801、table-views-header.tsx:39-45),v1 既未引用也未反驳。

C 落地之后这个组合可以通过新建一个含两个条件的视图表达 —— 但必须 C 先落地。 ⇒ C 与视图化必须同批,不能分期;分期的话中间那段时间这个组合真的没有了。

🔴🔴 第 0 步的实测结果(2026-09-21)—— 推翻了 B/C 之争本身

Tony 的质疑:「为啥组合会丢掉?不是有个字段能筛选邮箱不为空吗??设置下条件不就可以?」

他是对的。我、三路审查、以及 v0.10.18 的原作者,都没验过这一点。

验证一:notNull 对 emails 数组有效

query.ts:39-41 的 notNull 实现是 { [property]: { regex: /\S/ } }, 而 jsstore worker 里的比较是 QUERY_OPTION.Regex].test(value) —— RegExp.prototype.test() 对非字符串会先 String() 转换:

值 String(值) /\S/.test()
[](无邮箱) "" false ✅ 筛不中
['a@b.com'] "a@b.com" true ✅ 筛得中
['a@b.com','c@d.com'] "a@b.com,c@d.com" true ✅

⇒ 「官网邮箱 不为空」用现有算子就能表达,走普通 filters 路径。

这推翻了整个 B vs C 之争的前提: - 不需要 B(扩算子)—— notNull 已经是那个算子 - 不需要 C(物化列 + bump version 风险) - OR 语义自动保住(走普通 filters,不是查询后过滤) - hasEmailOnly 这条特殊路径可以退役 - Tony 担心的「自建视图 ∩ 有邮箱」组合 —— 新建一个含两个条件的视图就行,今天就能做

这条特殊路径的由来(ISSUE-0006 / development-log-archive)

quickFilterAsFilters('has-email') 留了 TODO 返回空 —— jsstore 无法直接查 array.length > 0

当初的判断是「表达不了」,于是改用 JS 后过滤。而 notNull 的 regex 实现对数组是有效的。 ⇒ 这很可能是从 v0.10.18 起就存在的、可避免的复杂度,并且直接导致了 ISSUE-0018(50k 静默截断)和 ISSUE-0196(「有邮箱 29」)两个事故。

验证二:加字段要不要 bump version(Tony 指定先验的那条)

jsstore worker 源码: - enableSearch = column.enableSearch == null ? true : column.enableSearch ⇒ 默认 true - enableSearch && !store.indexNames.contains(columnName) 这行在 onupgradeneeded 内部

⇒ 加一个显式 enableSearch: false 的字段不进建索引分支 ⇒ 不需要 upgrade ⇒ 不需要 bump version。 不写 enableSearch: false 就会建索引 ⇒ 需要 bump(这是个容易踩的雷)。

⚠️ 但由于验证一,C 方案本身不再需要,这条结论留档备用。

⚠️ 仍需一次真实数据验证(做成实现的一部分)

源码级推理成立,但 jsstore 对有索引字段(emails 的 enableSearch 未声明 ⇒ 默认 true ⇒ 建了索引) 做 regex where 时,是否必然走游标扫描而非 keyRange —— 这一步是推断。

⇒ 验法:「有邮箱」内置视图用 notNull 实现后,让 Tony 点一下, 看条数是否接近左侧「邮箱列表(去重)」的量级(他的库:全库 1,532)。 一次点击即可证伪。不对就退回 hasEmailOnly 特殊路径。

四、实施顺序(重写)

  1. ✅ 已验(见上一节):version 问题有答案,且发现 C 根本不需要 —— notNull 就能表达「有邮箱」
  2. apiPinViewsSave 改成网关,入口按 notEdit 属性剥离内置 id
  3. 内置视图的数据结构与固定状态(本地存储),显式定义它在 pinViews 内还是外、以及 findIndex 那条回退线怎么处理
  4. 内置视图不渲染齿轮,另设取消固定入口;弹层加第 4 个 tab 承载「找回来」
  5. 「有邮箱」内置视图用 {property:'emails', operator:'notNull', valueType:'text'} 表达; hasEmailOnly 特殊路径暂留不动(退役要等真实数据验证过),但内置视图不再走它
  6. 废 quickFilter:同批改 delete-scope.ts:56 的判据(从 quickFilter 改为 viewId / 内置视图 id 集合), 并确认 tests/delete-scope.test.ts 仍绿
  7. /6 计数器语义(内置不计入)+ 文案

✅ 实施完成(v0.16.17)

步 内容 状态
0 验 version + 发现 notNull 可表达「邮箱非空」 ✅ 见上文「第 0 步的实测结果」
1 内置视图定义源 + apiPinViewsSave 入口剥离 ✅ v0.16.14
2 内置视图进 pinViews(显式定了数据流)+ 本地固定状态 ✅
3 齿轮对内置可点、菜单按 builtin 裁剪;弹层加第 4 个 tab ✅
4 「有邮箱」用 notNull + 内置视图保留 hasEmailOnly 双保险 ✅
5 废 quickFilter;删除安全闸由 viewId 接管 ✅
6 /6 配额排除内置 ✅

实施中发现的、三路审查也没追到的一条

🔴 快速模式的过滤完全不看视图的 filters —— 只认写死的六个 quickFilter 分支。 也就是说用户在快速模式下选任何自建视图,表格根本不会变。 这是既有 bug,而把快筛做成视图之后,不补它连内置视图都会失效。

⇒ 新建 utils/filters-eval.ts(客户端求值器),语义与 jsstore/query.ts 对齐。 特别是 notNull 对数组的判定必须一致 —— 同一个视图在两种模式下筛出不同结果,而用户看到的只是一个开关,那比两边都慢更糟。 不认识的算子标 degraded,调用方须如实告知,不能假装筛过了。

三路审查 P0 的落实对照

P0 落实
① 状态放哪未定,两种放法都撞代码 放进 pinViews(渲染/回退线都读它);/6 与 >=6 闸排除 builtin;上云由网关剥离;findIndex 判据从 <= 0 改 < 0(0 号位不再固定是「所有数据」)
② notEdit 与可取消固定互斥 齿轮 disabled={item.notEdit && !item.builtin};菜单按 builtin 裁剪(只留「取消固定」);all 仍不渲染齿轮
③ 选视图走云端 config onViewIdChange 对内置 id 短路,直接用本地 filters,不发请求
④ 取消固定后找不回 弹层加第 4 个 tab「内置视图」,checkbox 读写本地固定状态
⑤ 废 quickFilter 咬删除安全闸 判据故意保留(恒 undefined、无害),真正接管的是 viewId !== 'all';已补行为判据逐个内置视图验证拦得住