同一份資料、兩種消費路徑

 1SDK 埋點（event / error / metric / lifecycle）
 2  │
 3  ├── 行為分析路徑 → Monitoring 08
 4  │     消費者：PM / 行銷 / 產品
 5  │     方法：funnel / cohort / attribution / A-B test
 6  │     決策：改 UI、調定價、投廣告
 7  │
 8  └── 訊號治理路徑 → Backend 04
 9        消費者：SRE / platform team / on-call
10        方法：cardinality budget / cost attribution / signal governance
11        決策：降 cardinality、調 sampling、改 alert、產出 evidence

這不是兩套埋點。同一個 button.click event，產品團隊看的是「哪個步驟流失最多使用者」，工程團隊看的是「這個 event 的 cardinality 是否在預算內、ingestion cost 是否合理」。event 相同，切入角度不同。

資料格式的交叉點

Monitoring SDK 送出的事件格式（02 Log Schema）和 Backend 04 的 log schema / OTel event format 有共通欄位：

格式一致性的價值是一份 event 同時餵 BigQuery（行為分析）和 Grafana Loki（訊號查詢）不需要格式轉換。如果兩邊各自定義 schema，同一個 event 要寫兩次 adapter，schema drift 的風險倍增。

資料治理的衝突

同一份資料被兩邊消費時，治理需求會衝突：

這些衝突無法靠「選一邊」解決。行為分析少了歷史資料就看不到趨勢；訊號治理存太多高粒度資料就 cardinality 爆炸。解法是分流。

解法：在 transport 層分流

把 SDK 送出的 event 在 collector 或 pipeline 層分流到不同 backend，各自按需求治理：

Hot path：即時訊號

error 和 metric 類事件即時進入 04 telemetry pipeline（Loki / Prometheus / Tempo），短期 retention（30-90 天），服務 on-call debug 和 incident triage。這條路徑要求秒級延遲、低 cardinality（聚合維度）。

Warm path：行為分析

全部四類事件進入 data warehouse（BigQuery / ClickHouse / Snowflake），長期 retention（年級），服務 funnel、cohort、attribution 和 A/B test。這條路徑接受分鐘級延遲、高粒度（per-user / per-session）。

Cold path：合規留存

audit-level event 進入 archive storage（Cloud Storage / S3 / Glacier），法規要求的年級保留（GDPR 刪除請求、HIPAA 6 年、金融業更長）。這條路徑寫入後幾乎不查詢，查詢時接受小時級延遲。

分流的關鍵設計

分流在 transport 層做，不在 SDK 層做。SDK 統一送出全部 event 到同一個 endpoint，pipeline 按 event type / source / tag 路由到不同 backend。

1SDK → Collector / OTel Collector / Cloud Logging
2         │
3         ├─ [type=error OR type=metric] → Hot path (Loki / Prometheus)
4         ├─ [all events]                → Warm path (BigQuery)
5         └─ [audit=true]               → Cold path (Cloud Storage)

SDK 不需要知道下游有幾個消費者。新增一個消費者（例如新的分析平台）只要在 pipeline 加一條路由，不用改 SDK。

實作考量

分流的實作方式取決於 pipeline 架構：

不論哪種架構，分流後的每條 path 要各自設定 retention、sampling、PII handling 和 cost budget。Hot path 的 cardinality 治理 規則不該影響 warm path 的分析粒度；warm path 的長期保留成本不該擠壓 hot path 的 freshness。

常見誤區

用兩套 SDK 替代分流

在 client 端同時整合行為分析 SDK（Mixpanel）和 error tracking SDK（Sentry），看似分工清楚，實際是兩套 schema、兩份 ingestion cost、兩組 PII 風險面、兩套 consent 管理。同一個 user action 在兩個平台各記一次，但欄位名、timestamp 精度、user identifier 可能不同，跨平台 correlation 困難。

統一 SDK + pipeline 分流的成本通常低於雙 SDK 的整合與治理成本。

Hot path 存全量高粒度

把 per-user / per-session 的完整事件直接灌進 Prometheus 或 Loki，會導致 cardinality 爆炸（4.7 Cardinality 治理）。Hot path 的正確做法是在 pipeline 層做 aggregation 或 relabeling，只保留 service / endpoint / status 等低 cardinality 維度。高粒度資料走 warm path。

Warm path 不做 PII 處理

行為分析需要 user segment，但不需要 PII 原文。warm path 的 ingestion pipeline 應該在寫入 warehouse 前做 PII redaction（hash user_id、truncate IP、strip email）。Monitoring 07 去識別化 的策略同時適用於 hot 和 warm path。

讀者路由

Filter 必須跟它過濾的資料源在同一層運作。 把 filter 寫在視覺層（querySelector + show/hide）、把 source 留在資料層分批產出（paginated fetch / streaming / lazy iterator）— 兩層的「一筆」定義不一致、filter 看不到 source 還沒產出的東西、結果跟使用者意圖之間有語意縫。

更廣義的說法：stream 操作（filter / sort / count / transform / search）必須跟 stream 的 materialization 同層或更上游。在下游做 stream 操作、操作的對象是已經 materialize 的 subset、不是完整的 stream。

為什麼層錯位產生語意縫

「一筆」在不同層有不同定義

Filter 寫在視覺層、它的「過濾全部」≡「過濾螢幕上看得見的全部」≡「過濾已 fetch 已 render 的子集」。離資料層的真實全集差兩層。使用者意圖（「給我所有 title 含 X 的結果」）對應的是資料層的全集、不是視覺層的子集。

Silent 失敗的條件

層錯位不會在「filter 子集裡有命中」的情境下被發現。它只在以下條件下顯露：

1. 已 materialize 的子集裡剛好沒命中
2. 但完整 stream 裡有命中、只是還沒 materialize
3. 使用者沒有訊號知道「還有沒抓的」

三個條件同時滿足、使用者看到「filter 後是空的」、誤以為是「沒有命中」、放棄。

為什麼這個 bug 容易寫出來

視覺層 filter 是寫起來最簡單的版本：

1items.forEach(el => {
2  el.style.display = el.dataset.title.includes(query) ? '' : 'none';
3});

5 行解決、看起來能用、第一輪測試（手動輸入 query → 看到 filter 生效）會通過。「能用」的訊號出現太早、掩蓋了語意缺口。

這是 #67 寫作便利度跟意圖對齊反相關 在「filter × source」情境的具體展現 — 容易寫的位置（已 materialize 的 view 層）跟對齊意圖的位置（source 層）方向相反。

哪些 source 形狀有層錯位風險

四類 source 共用同個結構：source 分批 / 限額 / 延遲 materialize、filter 在下游 → silent 缺口。詳細形狀分析見 #63 資料源的形狀決定 feature 的形狀。

這次任務的實際情境

觀察

搜尋頁實作 title / content filter：

 1// pagefind 分批 load (load more 按鈕)
 2const results = await pagefind.search(query);
 3results.results.slice(start, start + 10).forEach(r => container.append(render(r)));
 4
 5// 我們在 view 層 post-filter
 6function applyFilter(scope) {
 7  document.querySelectorAll('.result').forEach(el => {
 8    el.hidden = !matchesScope(el, scope);
 9  });
10}

跑出來的問題：使用者選 title-only filter、第二批 8 筆全部 title 不含 query → 點 “load more” 後畫面閃了一下、新增的 8 筆全 hidden、使用者看到的內容沒變。

判讀

問題的根因不在「畫面閃」這個視覺現象、而在 filter 的層級錯位：

兩個定義在一般狀況看起來一樣（已載入子集裡有命中）、稀疏 case 暴露縫。

執行（解法選擇）

解法選擇展開見 #59 Filter × Source 合成策略五選一 — A 推進 query / B 自動續抓 / C 預先 index / D 誠實 UX / E 明示縮小。本文聚焦「先識別這是層錯位、不是 UI bug」 — 識別錯了、後續解法都會在錯誤的層上補救。

內在屬性比較：filter 該放哪一層

「寫作成本最低」跟「跟意圖最近」是反相關 — 這個反相關本身是 #67 的核心命題、本卡是它在 filter × source 情境的展開。

識別層錯位的三問

寫 filter / sort / count / transform 之前自問：

1. 這個操作的「對象」是什麼層的「一筆」？

如果寫在 view 層、對象是「螢幕上的元素」 — 那源頭如果分批、就有缺口。

2. Source 是「一次給完整 dataset」還是「分批 / 限額」？

對照前面「哪些 source 形狀有層錯位風險」表 — 任何分批 / 限額 / streaming / cached source 都有風險。一次性 fetch 或靜態陣列才安全。

3. 「沒命中」與「還沒 materialize」對使用者要不要區分？

要區分 → filter 必須在 source 層或自動續抓、否則使用者無法判斷。 不區分（可接受「在已載入範圍內找」這個語意） → view 層 filter 加誠實 UX。

三問跑完才寫 filter — 跳過任一問就可能掉進層錯位。

判讀徵兆

核心原則：filter / sort / count / transform 是 stream operation、必須跟 stream 的 materialization 同層或更上游。寫在下游 = 操作 subset 而不是 stream、語意縫是必然、不是偶發 bug。

Filter 跟分批 source 的合成有五種策略、各自機會成本不同。沒有絕對最佳 — 選哪個取決於三個變數：

1. Source 是否支援 server-side filter（capabilities）
2. Match 密度（稀疏 vs 密集）
3. UX 容忍度（要不要誠實顯示「掃描範圍」）

本文是 #55 Filter 與 Source 的層錯位 的解法展開、列出五個合理選項與適用情境。

五策略對照表

五策略一句話總覽

每個策略各自一張獨立 pattern 卡片、本卡只給總覽與選擇規則。

策略 A：推進 query

把 filter 條件變成 source 的 query 參數、source 端就回符合的。最優、無層錯位 — 但要 source 支援。詳見 #61 Pattern：推進 query。

策略 B：自動續抓直到湊滿

抓一批 → filter → 不夠再抓 → 湊滿 N 個或 source 結束。需要上限保護避免拉爆。詳見 #60 Pattern：自動續抓。

策略 C：預先建獨立 index

Build time 為每種 filter mode 各建一份 source、runtime 切 mode = 切 source。前提是能控 build、mode 有限。詳見 #65 Pattern：多 index。

策略 D：誠實進度 UX

保留 view 層 filter、UI 顯示「已掃 N / 命中 K / 共 M」三數字 + 「再掃一批」、使用者手動觸發續抓。詳見 #62 Pattern：誠實進度 UX。

策略 E：明示語意縮小

明示告訴使用者「filter 範圍 = 已載入、不承諾全集」、不假裝是全集 filter。比 D 顯眼度低、但成本最低。詳見 #66 Pattern：明示語意縮小。

D 跟 E 都是 subset 上做、差別：D 用三數字持續顯示掃描範圍、E 用文字一次性告知。silent 縮小（既不三數字、也不告知）= 反模式、撞回 #55 層錯位。

選擇規則：決定矩陣

多策略並用

實務上常見組合：

• A + D fallback：query 推進失敗（如使用者用 source 不支援的條件）→ fallback 到 D
• B + 上限 → D：自動續抓到上限後切 D（顯示「已掃 N 筆、再掃？」）
• C + B 補強：預先 index 解一般 case、B 解 index 沒覆蓋的組合

並用通常比單選有效、但複雜度也最高。詳細的疊加判準（解不同層 / 沒副作用衝突 / 增量成本可接受）見 #75 主策略 + 補強策略 — 本表的「並用」就是 #75 的具體展現。

「先 ship 哪個策略、哪個下輪」見 #76 分批 ship 準則 — 例如 D（UX）通常先 ship、A/C（結構）下輪。

判讀徵兆

核心原則：Filter × Source 沒有最佳解、只有「對齊三變數（capabilities / 密度 / UX）的取捨」。識別三變數、選對策略 → 比寫漂亮的程式重要。

跟 #45 跟外部組件合作的四層次 同構：A 推進 query ≈ 公共介面層（最穩定）、C 多 index ≈ 邊界層（build pipeline 控制）、B 自動續抓 ≈ 邊界 DOM 層（client 補足）、D / E 誠實或縮小 ≈ 內部結構層（接受限制）。兩個原則的選擇順序都是「離 source 公共介面越近、合作越穩」。

抓一批 → filter → 不夠就再抓 → 湊滿 N 個 match 或 source 結束。

對應 #59 Filter × Source 合成策略 的策略 B。

何時用、何時不用

用

• Source 不支援 server-side filter（不能用策略 A）
• 不能控 build pipeline 重 index（不能用策略 C）
• Match 密度可預期、不會稀疏到要拉光整個 dataset
• 使用者期望「filter 後自動湊夠 N 個」、不要手動續抓

不用

• Source 支援 server-side filter（直接用策略 A）
• Match 稀疏、可能拉光整個 dataset 才湊到 N（換 D 誠實 UX）
• Source cardinality 大（10 萬筆）、不能拉太多次

必要元件

元件 1：Quota 跟上限

1const TARGET = 10;       // 期望湊滿的 match 數
2const MAX_BATCHES = 20;  // 最多續抓次數（保護）
3const MAX_TIME_MS = 5000; // 最大時間（保護）

沒有上限 = 稀疏時拉爆。兩個上限缺一不可。

元件 2：Loop with break conditions

 1async function fetchUntilQuota(matches, target = TARGET) {
 2  const collected = [];
 3  const start = Date.now();
 4  let batchCount = 0;
 5
 6  while (
 7    collected.length < target &&
 8    hasMore() &&
 9    batchCount < MAX_BATCHES &&
10    Date.now() - start < MAX_TIME_MS
11  ) {
12    const batch = await fetchNext();
13    collected.push(...batch.filter(matches));
14    batchCount++;
15  }
16
17  return {
18    collected,
19    reachedQuota: collected.length >= target,
20    exhaustedSource: !hasMore(),
21    hitLimit: batchCount >= MAX_BATCHES || Date.now() - start >= MAX_TIME_MS,
22  };
23}

返回值含三個 flag、UI 用來判斷該顯示哪個狀態（湊滿 / 抓完無更多 / 撞到上限）。

元件 3：可中斷

 1async function fetchUntilQuota(matches, target, signal) {
 2  // ...
 3  while (...) {
 4    if (signal?.aborted) throw new DOMException('aborted', 'AbortError');
 5    const batch = await fetchNext({ signal });
 6    // ...
 7  }
 8}
 9
10// 使用
11const ctrl = new AbortController();
12input.addEventListener('input', () => {
13  ctrl.abort();
14  ctrl = new AbortController();
15  fetchUntilQuota(matches, 10, ctrl.signal);
16});

使用者改 query / filter 時能立刻取消舊的續抓。沒有可中斷 = 競態 bug（舊 query 的結果晚到、覆蓋新 query 的）。

UX 配套

載入中顯示進度

1<div class="loading">已掃 <strong>24</strong> 筆 / 已命中 <strong>3 / 10</strong></div>

不顯示進度 = 使用者不知道是在等還是卡住。

結束時顯示原因

不區分原因 = 使用者不知道為什麼停（同 #57 三狀態問題）。

反例

反例 1：沒上限

1while (collected.length < target && hasMore()) {
2  collected.push(...(await fetchNext()).filter(matches));
3}
4// 稀疏 match → 拉光整個 source

反例 2：沒 abort signal

1input.addEventListener('input', async () => {
2  const r = await fetchUntilQuota(matches);
3  render(r);  // 舊 query 的結果可能覆蓋新 query
4});

反例 3：每批序列化等

1for (let i = 0; i < MAX; i++) {
2  const batch = await fetchNext();  // 序列、慢
3  // ...
4}

如果 source 支援平行 fetch（多個 page 同時抓） → 改成平行更快：

1const batches = await Promise.all([fetch(0), fetch(1), fetch(2)]);

但平行有 over-fetch 風險（湊滿後其他批白抓） — 適合 match 密度高的情境。

跟其他 Pattern 的關係

• 跟 #61 Pattern：推進 query（待補）：A 是最優、B 是 source 不支援時的退路
• 跟 #62 Pattern：誠實進度 UX（待補）：B 撞到上限後 fallback 到誠實 UX

判讀徵兆

核心原則：自動續抓的價值在「使用者透明」、但成本是「上限保護必要」。沒上限的 B 比 silent post-filter 更糟（會拉爆）。

把 filter 變成 source 的 query 參數、source 端就回符合的、client 不 post-filter。

對應 #59 Filter × Source 合成策略 的策略 A。

何時用、何時不用

用

• Source 支援該 filter 條件（已索引、能在 query 表達）
• 想避免任何 client-side post-filter
• 想避免層錯位（見 #55）

不用

• Source 不支援（pagefind 對 title-only 沒 native 支援）
• 條件需要 client-side 計算（依 viewport / 隨機抽樣）
• 推進 query 後 cardinality 仍大、還是要 paginate（這時 A + B 並用）

推進的層次

選哪一層 = source 的 capabilities 決定。

評估 Source Capabilities

寫之前讀 source docs / API spec、列出：

不評估就寫 = 寫到一半發現 source 不支援、回頭走策略 B 或 C。

範例：Pagefind

支援的 filter

1// pagefind 已支援 filter（透過 _pagefind/filter.json）
2const r = await pagefind.search('keyword', {
3  filters: {
4    type: 'post',           // 支援
5    tag: { any: ['js', 'css'] }, // 支援多選
6  },
7});

不支援的 filter

1// pagefind 不支援「只搜 title」
2// 因為 pagefind 的 search 對 full-text、不分區
3const r = await pagefind.search('keyword', {
4  scope: 'title-only',  // 不存在（不支援）
5});

要解決：

• 方案 1：build 時用 data-pagefind-body 把 title 標成獨立 region、用 body filter（pagefind v1.1+）
• 方案 2：建兩個獨立 index（一個只 index title、一個只 index content） — 走策略 C
• 方案 3：放棄推進 query、用策略 B 自動續抓 + post-filter

跟原本 query 邏輯的並用

推進 filter 通常不取代原本 query、是「補上條件」：

1// 使用者輸入 query "css"、選 type=post
2const r = await pagefind.search('css', {  // query
3  filters: { type: 'post' },              // filter
4});
5// 兩個都進 source、source 算交集

Filter 跟 query 是不同維度：query 是「找什麼」、filter 是「在哪些範圍找」。

反例

反例 1：推進不完全、留 client-side post-filter 補

1const r = await pagefind.search(q, { filters: { type: 'post' } });
2const filtered = r.results.filter(x => x.title.includes(q));
3// ↑ 這行還是 #55 層錯位

如果 source 不支援 title-filter、不要用「半推進」 — 直接走策略 C 或 B。

反例 2：忽略 cost cap

1input.addEventListener('input', async () => {
2  // 每個鍵盤事件 fire 一個 search query
3  const r = await pagefind.search(input.value, { filters: ... });
4});
5// → query rate 100+/秒、撞 rate limit

加 debounce：

1let timer;
2input.addEventListener('input', () => {
3  clearTimeout(timer);
4  timer = setTimeout(() => pagefind.search(input.value, ...), 200);
5});

反例 3：客製欄位沒進 index、寫了 query 失效

1// 期望 filter 「閱讀時間 > 5 分鐘」
2const r = await pagefind.search(q, { filters: { readingTime: { gt: 5 } } });
3// → 但 build 時沒把 readingTime 進 filter index → filter 被忽略

預期 source 不支援 → 評估「是否值得加進 index」（成本 vs 使用率）。

跟其他 Pattern 的關係

• A 是最優 — 在 source capabilities 範圍內優先選
• A 不可行 → 評估 C（建獨立 index）
• C 也不可行 → 退到 B（自動續抓）
• 都不可行 → D（誠實 UX）

選擇順序：A → C → B → D。

判讀徵兆

核心原則：能推進 query 就推 — 沒層錯位、沒 silent 失敗、跟使用者意圖最近。但前提是 source 支援；不支援就要退到 B / C / D、不要做半推進。

Build time 為每種 filter mode 各建一份獨立 source / index、runtime 切換 mode 等於切 source。

對應 #59 Filter × Source 合成策略 的策略 C。

何時用、何時不用

用

• 能控 source 的 build pipeline（自家 build、不是第三方 API）
• Filter mode 數量有限且穩定（< 5 個、不會爆炸組合）
• 兩個（含以上）mode 都重要、流量大、值得獨立 index
• Source 的 query 引擎不支援該 filter（不能用 #61 推進 query）

不用

• Filter 維度多、組合會爆炸（5 維 × 各 5 選項 = 3125 種 index）
• Index 大小敏感（每份 index 都重複占空間）
• Build pipeline 無法控（外部 API、vendor service）
• Mode 不穩定、常常增刪

結構

Build pipeline

1# Pagefind 範例：兩份 index 各自掃不同 region
2pagefind --site public --output-subdir _pagefind-all
3pagefind --site public/title-only --output-subdir _pagefind-title
4
5# 或用 --root-selector 限定 source 範圍
6pagefind --site public --root-selector ".post-title" --output-subdir _pagefind-title

Runtime 切換

1const indexes = {
2  all: await import('/_pagefind-all/pagefind.js'),
3  title: await import('/_pagefind-title/pagefind.js'),
4};
5
6function search(query, mode) {
7  return indexes[mode].search(query);
8}

每個 mode 對應一份完整 index、search 結果直接是該 mode 的全集。沒有 post-filter、沒有層錯位。

多 index 的成本

通常 build / 儲存的成本 < 在 runtime 自動續抓（B）的累積請求成本。

跟 #59 策略並用

C 通常跟其他策略並用：

• C + 推進 query (A)：在每份 index 內、再用 query filter 細分（如 _pagefind-post.search('css', { filters: { tag: 'js' } })）
• C 切 mode + B 自動續抓：mode 切換無感、mode 內續抓也無感

反例

反例 1：Mode 組合爆炸

1# 5 維 × 各 5 選項 = 3125 份 index
2for type in post page tutorial faq doc; do
3  for tag in js css html ts py; do
4    for date in 2020 2021 2022 2023 2024; do
5      pagefind --filter "type=$type tag=$tag date=$date" --output-subdir _pagefind-$type-$tag-$date
6    done
7  done
8done

組合爆炸時不能用 C — 改用 A（推進 query）讓 source 一份就好。

反例 2：Mode 不穩定、常常增減

每加一個 mode、build pipeline 多一份、deploy 多一份。如果 mode 半年內會大改、不適合 C。

反例 3：Index 沒對齊 mode

1pagefind --site public --output-subdir _pagefind-title
2# build 完後沒過濾、其實 index 了 title + content 全部

如果只是改 output 路徑、沒改 index 範圍 → 兩份 index 內容一樣、白做。要用 --root-selector 或 data-pagefind-body 標記正確範圍。

跟其他 Pattern 的關係

選擇順序：A → C → B → D（見 #61）：

• A 不行（source 不支援該 filter） → 評估 C
• C 不行（mode 爆炸 / 不能控 build） → 退到 B
• B 不行（match 稀疏會爆） → 退到 D

C 是 A 的 build-time 模擬 — 用 build 時間換 runtime 體驗、跟使用者意圖完全對齊（每份 index = 該 mode 的全集）。

判讀徵兆

核心原則：C 用 build-time 換 runtime 體驗。前提是 mode 有限、可控、值得 — 否則退到 A 或 B。

適用：前端 paginated UI 加 filter、後端 API + middleware filter、演算法 pipeline 加 transform、map-reduce 加 post-filter、資料庫 materialized view 加 query。 不適用：純運算演算法（沒有 stream / 沒有 materialization 概念）、純 React state 管理（沒有外部 source）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋層錯位識別、五策略選擇、跨領域範例、playwright 驗證方法。

何時參閱本文件

為什麼 filter × source 是個結構性議題

Filter 操作的定義是「從 stream 中過濾出符合條件的元素」 — stream 是隱含的對象。當 stream 被分層 materialize 時、filter 套在哪一層、決定它能「看見」的元素範圍：

使用者 / 呼叫者意圖的「filter」通常是第一層（stream 全集）— 但寫程式當下手邊的對象通常是第三層（已 materialize 的 subset）。寫起來最便利的位置 ≠ 對齊意圖的位置。

這是 #67 寫作便利度跟意圖對齊反相關 在 stream 操作上的具體展現。

跨領域：同個結構、五個情境

情境 1：前端 UI + Pagefind paginated search

1// 反例：post-filter on view layer
2const all = await pagefind.search(query);
3all.results.slice(start, start + 10).forEach(render);
4document.querySelectorAll('.result').forEach(el => {
5  el.hidden = !matches(el);  // view 層 filter
6});
7// 第二批全 hidden、使用者看到「load more 沒效果」

情境 2：後端 API + ORM middleware

1# 反例：middleware 在 pagination 之後 filter
2@app.route("/posts")
3def posts():
4    page = Post.objects.paginate(page=1, per_page=10)
5    return [p for p in page.items if p.author == "author_x"]
6    # 漏掉沒在這頁的符合項

情境 3：Async iterator + take(N)

1# 反例：先 take 後 filter
2items = list(itertools.islice(stream(), 100))
3filtered = [x for x in items if matches(x)]
4# stream 後面可能還有符合的、但被 take 100 切斷了

情境 4：Map-reduce + post-reduce filter

1[shards] → [map output] → [reduce]
2                              ↓
3                         [filter]  ← 已是 reduce 後的結果

Filter 應該在 map 階段（per-shard）或 reduce 內、不是 reduce 後。

情境 5：Materialized view + SELECT

1-- 反例：在 stale view 上 filter
2SELECT * FROM posts_summary WHERE author_id = 42;
3-- view 可能是某個時點的 snapshot、漏掉之後寫入的 posts
4
5-- 對例：filter 推進原表
6SELECT * FROM posts WHERE author_id = 42;

五個情境共用結構：source 是分層 materialize 的、filter 套在下游 → silent 缺口。

五種解法策略

詳細展開見 #59 Filter × Source 合成策略五選一。本卡只列總覽：

選擇順序：A → C → B → D → E（不寫不告知的 silent 縮小、那是反模式）。

對應的 pattern 卡片：#60 自動續抓 / #61 推進 query / #62 誠實進度 UX / #65 多 index / #66 明示語意縮小

三變數決定策略選擇

選 A / B / C / D / E 看三個變數：

變數 1：Source capabilities

Source 支援哪些 server-side filter？

• 支援該 filter 條件 → A 最優
• 不支援、能控 build → 評估 C
• 都不行 → B / D / E

變數 2：Match 密度

每抓一批、預期多少筆 match？

• 高密度（每批 ≥ 1 個 match）→ B 自動續抓 OK
• 稀疏（要抓很多批才湊到一個）→ B 會拉爆、用 D / E
• 不可預期 → 加上限保護的 B + fallback 到 D

變數 3：UX 容忍度

使用者能接受多顯眼的「掃描範圍」UX？

• 完全不行（filter 是核心互動）→ A / C
• 可以顯示三數字 → D
• 一次性文字告知就行 → E

Playwright 驗證 filter × source 行為

寫完 filter 後、用 playwright 驗證是否有層錯位 silent 缺口。

驗證 1：「Load more 後 filter 後是否該有結果」

 1async ({ page }) => {
 2  await page.goto('/search/?q=pre');
 3  await page.click('[data-scope="title"]');  // 選 title-only
 4
 5  // 載入第一批、量已掃 / 命中
 6  const before = {
 7    loaded: await page.$$eval('.result', els => els.length),
 8    visible: await page.$$eval('.result:not([hidden])', els => els.length),
 9  };
10
11  await page.click('button.load-more');
12  await page.waitForTimeout(500);
13
14  const after = {
15    loaded: await page.$$eval('.result', els => els.length),
16    visible: await page.$$eval('.result:not([hidden])', els => els.length),
17  };
18
19  // 層錯位徵兆：loaded 增加、visible 沒增加
20  return {
21    deltaLoaded: after.loaded - before.loaded,
22    deltaVisible: after.visible - before.visible,
23    isSilentGap: after.loaded > before.loaded && after.visible === before.visible,
24  };
25}

驗證 2：「稀疏 case 是否拉爆」

1// 用一個極少 match 的 query 觸發 B 策略
2await page.goto('/search/?q=very_rare_keyword');
3await page.click('[data-scope="title"]');
4const startTime = Date.now();
5await page.waitForSelector('.scan-status', { timeout: 10000 });
6// 應該在 5s 內顯示「已掃完、共命中 K 個」、不該無限續抓

驗證 3：「使用者能否區分四狀態」

1const statusVisible = await page.locator('.filter-status').textContent();
2// 應該明示 loading / partial / end / empty 之一、不只是 spinner

寫成 playwright test 固化 — 未來架構改動時 CI 立刻發現 regression（#15 layout-tests-with-playwright）。

設計決策的 checklist

寫 filter 之前、跑這份 checklist：

• Source 是不是分批 / streaming / cached / lazy？（#63 資料源形狀）
• Filter 的定義域是已載入子集還是 source 全集？（使用者意圖三問、見 #58）
• Source 是否支援 server-side filter？（決定能不能用 A）
• Match 密度可預期嗎？（決定 B 是否可行）
• 三狀態（loading / empty / end）UX 怎麼區分？（#57）
• 對於「filter 後 0 筆」的情境、使用者能否區分「沒命中」vs「還沒抓到」？

Wrong vs Right 對照

範例 1：搜尋頁 title-only filter

錯：

 1// pagefind 分批載入、view 層 post-filter
 2input.addEventListener('input', async () => {
 3  const results = await pagefind.search(input.value);
 4  results.results.slice(0, 10).forEach(render);
 5});
 6
 7document.querySelector('.scope-title').addEventListener('click', () => {
 8  document.querySelectorAll('.result').forEach(el => {
 9    const title = el.querySelector('.title').textContent;
10    el.hidden = !title.includes(query);
11  });
12});

第二批 8 筆 title 不含 query → 全 hidden、使用者看到「load more 沒效果」。

對（策略 C：多 index + 切換）：

1# Build 階段
2pagefind --site public --output-subdir _pagefind-all
3pagefind --site public --root-selector "article h1, article h2" --output-subdir _pagefind-title

 1const indexes = {
 2  all: await import('/_pagefind-all/pagefind.js'),
 3  title: await import('/_pagefind-title/pagefind.js'),
 4};
 5
 6input.addEventListener('input', async () => {
 7  const pf = currentScope === 'title' ? indexes.title : indexes.all;
 8  const results = await pf.search(input.value);
 9  // results 已是「該 scope 的全集」、無層錯位
10  results.results.slice(0, 10).forEach(render);
11});

對（策略 D：誠實進度 UX、保留 view 層 filter）：

1<div class="filter-status">
2  已掃 <strong>24</strong> / <strong>~150</strong> 筆 — 命中 <strong>3</strong>
3  <button>再掃一批</button>
4</div>

1// view 層 filter 保留、但 UI 顯示掃描範圍 + 提供續抓
2function updateStatus() {
3  const all = document.querySelectorAll('.result');
4  const visible = document.querySelectorAll('.result:not([hidden])');
5  document.querySelector('.scanned').textContent = all.length;
6  document.querySelector('.matched').textContent = visible.length;
7}

範例 2：後端 API filter

錯：

1@app.route("/posts")
2def list_posts():
3    page = request.args.get('page', 1)
4    posts = Post.objects.paginate(page=page, per_page=10)
5    if author := request.args.get('author'):
6        return [p for p in posts.items if p.author == author]
7    return posts.items

中間的 list comprehension 在 pagination 之後 filter — 漏掉沒在這頁的符合項。

對：

1@app.route("/posts")
2def list_posts():
3    query = Post.objects
4    if author := request.args.get('author'):
5        query = query.filter_by(author=author)  # 推進 ORM
6    page = request.args.get('page', 1)
7    return query.paginate(page=page, per_page=10).items

Filter 在 query 層、pagination 在 filter 之後、無層錯位。

自檢清單（dogfooding）

寫 filter / sort / count / transform 前：

• 我有沒有問「這個操作的對象是哪一層的 stream」？
• Source 是分批的嗎？是 → filter 必須同層或推進上游
• 寫了 view 層 filter？檢查：稀疏 case 會不會 silent 失敗？
• 用了 B（自動續抓）？有沒有 MAX_BATCHES + MAX_TIME_MS 上限保護？
• UX 能否區分「載入中 / 沒命中 / 還沒抓到 / 抓完了」四狀態？
• Playwright 驗證有沒有覆蓋「稀疏 case」「load more 後 visible 是否變」？

延伸閱讀

問題分析：

• #55 Filter 與 Source 的抽象層錯位 — 根因
• #56 視覺完成 ≠ 功能完成 — 「畫面對」是低資訊量訊號
• #57 Loading / Empty / End 三狀態的區分 — UX 落地

指令澄清（在 requirement-protocol skill）：

• #58 篩選類指令的澄清時機 — 三問模板

解法策略：

• #59 Filter × Source 合成策略五選一 — 總覽
• #60-#62, #65-#66 五張 Pattern 卡片 — 各策略具體實作

抽象原則：

• #63 資料源的形狀決定 feature 的形狀 — 形狀是硬約束
• #64 Feature 操作要跟 Source 同層合成 — 跨領域通用原則
• #67 寫作便利度跟意圖對齊反相關 — meta-principle
• #68 驗收的時間軸：四個 checkpoint — 驗收策略

Last Updated: 2026-04-26 Version: 0.1.0