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