事件命名

行為事件的命名遵循 namespace.action 格式（模組一 事件命名規範）。行為分析場景對命名的額外要求是：同一個 funnel 內的事件要能用 namespace 前綴篩選。

例：註冊流程的事件用共同前綴 signup：

1signup.page.view          使用者看到註冊頁
2signup.form.submit        使用者送出表單
3signup.email.verify       使用者點擊驗證信連結
4signup.complete           註冊完成

用 signup.* 就能篩選出整個註冊流程的事件，不需要事先知道每一步的完整名稱。

屬性設計

每個事件除了名稱，還帶有屬性（properties / parameters）描述事件的 context。屬性分成三層：

通用屬性（每個事件都有）

• timestamp：事件發生的時間（UTC，毫秒精度）
• session_id：當次使用的 session 識別碼
• user_id：使用者識別碼（去識別化後，見 模組七）
• platform：iOS / Android / Web
• app_version：app 版本號

事件類型屬性（同類事件共有）

• 頁面瀏覽事件：page_name、referrer
• 按鈕點擊事件：button_id、button_text
• 搜尋事件：query、result_count

事件專屬屬性（特定事件才有）

• signup.form.submit：form_method（email / Google / Apple）
• purchase.complete：amount、currency、product_id

屬性設計的判斷標準是：這個屬性是否用於回答一個分析問題。「註冊方式的轉換率差異」需要 form_method 屬性；如果沒有這個分析問題，就不需要這個屬性。

Funnel 定義

Funnel 是一連串有順序的事件，代表使用者完成一個目標的步驟。Funnel 定義在事件設計階段完成 — 決定哪些事件構成一個 funnel、順序是什麼、每步之間的最大時間間隔。

定義一個 funnel 需要：

步驟清單：funnel 包含哪些事件，順序是什麼。

時間窗口：步驟之間的最大間隔。使用者在步驟 A 之後 30 天才做步驟 B，是否算在同一個 funnel 內？時間窗口的設定取決於業務場景 — 電商結帳 funnel 通常是 30 分鐘，SaaS onboarding funnel 可能是 7 天。

完成條件：什麼算「完成」funnel。到達最後一步即完成，還是需要特定屬性值（purchase.complete 且 status = success）。

過度收集的成本

行為事件收集的邊界是「能回答已知的分析問題」。收集超出分析需求的事件有三個成本：

儲存成本：每個事件佔一行 JSONL。高頻事件（每次滾動、每次 hover）的資料量遠大於低頻事件（按鈕點擊、頁面瀏覽）。

隱私風險：收集的事件越多，包含可識別個人行為模式的風險越高（模組七 資安與隱私）。

噪音：分析時需要從大量事件中篩選出有意義的模式。事件越多，訊噪比越低。

設計好的行為事件直接成為 Funnel analysis 的輸入 — funnel 的每一步對應一個行為事件。行為事件在四類事件分類中屬於 Event 類，完整的分類定義見模組一 四類事件定義。收集行為事件前必須完成去識別化 — 使用者行為模式本身就是可識別資訊。

namespace.action 格式

每個事件名稱由兩部分組成：namespace（事件發生的模組或功能區域）和 action（發生了什麼）。用 . 分隔。

1terminal.connect.start      ← namespace: terminal.connect, action: start
2terminal.connect.done       ← namespace: terminal.connect, action: done
3terminal.input.submit       ← namespace: terminal.input, action: submit
4auth.biometric.success      ← namespace: auth.biometric, action: success
5auth.biometric.fallback     ← namespace: auth.biometric, action: fallback
6enrollment.qr.scan          ← namespace: enrollment.qr, action: scan

Namespace 層級

Namespace 的層級深度依功能結構而定。兩層通常足夠（terminal.connect），三層用於需要進一步區分的場景（terminal.connect.ws）。超過三層通常代表 namespace 設計過細，增加認知成本但不增加分析價值。

Action 命名

Action 使用動詞（start、submit、scan）或狀態（success、failed、timeout）。同一組動作用配對的 action 名稱：start / done（成對的生命週期）、success / failed（結果分支）。

避免在 action 中重複 namespace 的資訊。terminal.connect.terminal_connected 中 terminal 重複了；terminal.connect.done 更簡潔。

命名一致性的工程價值

Grep 友好

統一的 namespace 結構讓開發者用 grep "terminal.connect" 就能找到所有連線相關事件，不需要知道每個事件的完整名稱。

統計友好

按 namespace 前綴分群統計。terminal.* 的事件數量 = terminal 功能的使用頻率；auth.* 的事件數量 = 認證觸發頻率。層級結構讓統計的粒度可以調整。

文件友好

事件清單按 namespace 排列就是一份結構化的功能地圖。新加入的開發者讀事件清單就能理解系統有哪些功能模組。

和商業方案的命名對應

不同的商業監控方案有各自的命名慣例。自架方案用 namespace.action 格式，接入商業方案時需要做對應。

對應時保持一個原則：自架方案的事件名稱是 source of truth，商業方案的名稱是它的映射。在自架方案中改名後，映射層跟著改；不要讓商業方案的命名反過來影響自架的命名結構。

下一步路由

• 四類事件的定義 → 四類事件的完整定義
• 從需求推導收集策略 → 從需求推導「該收集哪些事件」
• 商業方案的完整比較 → 模組六 商業方案比較

辨識特徵

app_tunnel 的 connection_flow_test.dart 是具體案例。檔名標題是端對端整合測試，但內部使用了三個核心替身：FakeWebSocketChannel、FakeBiometricService、InMemoryCredentialRepository（T.C2）。

名義 integration test 有三個共同特徵可用來辨識。

特徵一：核心外部依賴全替換

Integration test 的價值在於驗證程式碼與外部系統的互動邊界。如果所有外部依賴都被 fake 取代，test 驗證的實際上是「假設外部系統行為符合開發者預期，內部邏輯是否正確」。這和 unit test 的差別只在 scope 大小 — 多個內部元件一起測 — 不在驗證對象的本質。

判斷方式：列出 test 的所有依賴注入點，計算有多少外部服務被替換成 fake。如果 100% 的外部依賴都是 fake，這個 test 不驗證任何真實互動。

特徵二：沒有真實的 I/O 操作

真正的 integration test 會產生真實的網路連線、讀寫真實的檔案、或呼叫真實的 API endpoint。名義 integration test 的所有 I/O 都在 process 內部完成 — StreamController 替代網路 stream，Map<String, String> 替代資料庫，Future.value() 替代非同步 I/O。

這些替身讓 test 執行速度快、結果穩定，但代價是完全跳過了 I/O 邊界上的所有行為差異。

特徵三：沒有環境前置條件

真正的 integration test 需要外部環境準備：啟動服務、建立連線、準備測試資料。名義 integration test 的 setUp() 只建立 fake 物件，不啟動任何外部程序，不需要網路，可以在任何環境下執行。

環境前置條件的缺席是一個實用的快速判斷訊號。如果 setUp() 裡沒有 docker compose up、Process.start、HttpClient.connect 之類的操作，這個 test 很可能不接觸真實外部服務。

名義 integration test 造成的認知偏差

名義 integration test 的技術問題可以修正（改名或補寫真實 integration test），但它造成的認知偏差更難修正。

當團隊看到 test suite 包含「integration test」資料夾且全部通過，決策者的推論是「integration 已經驗證過了」。這個推論在名義 integration test 下是錯的 — 協議層和環境層完全沒被驗證 — 但決策者沒有動機去檢查 test 的內部實作。

app_tunnel 的 11 個 connection_flow_test 全過，開發者合理認為「連線流程的整合測試已通過」。實際上這 11 個 test 驗證的是 ConnectionManager 的內部狀態機在各種情境下的轉換正確性（斷線重連、錯誤處理、狀態回報），不是「和 ttyd 的連線流程是否正確」。Auth handshake 缺失直到實機測試才被發現。

修正策略

修正命名

最低成本的修正是讓 test 名稱反映真實驗證對象。命名改動不影響 test 本身的價值 — 這些 test 驗證內部狀態機的邏輯仍然有用 — 只是消除命名造成的認知偏差。

補寫真實 integration test

命名修正只消除誤解，不補上缺失的驗證層。如果服務的協議互動是關鍵路徑（連線、認證、資料交換），需要補寫對真實服務的 protocol integration test。

補寫的判斷原則不在本章展開 — 見 判斷原則：什麼時候需要 protocol integration test。

在 test 檔案內標明依賴替換清單

在 test 檔案的頂部註釋中列出所有被 fake 取代的依賴，讓後續讀者不需要逐行追蹤就能判斷這個 test 的驗證邊界。

1// Faked dependencies: WebSocketChannel, BiometricService, CredentialRepository
2// Verifies: ConnectionManager state machine transitions
3// Does NOT verify: real WS protocol, auth handshake, biometric hardware

下一步路由

• 判斷是否需要補寫真實 integration test → 判斷原則：什麼時候需要 protocol integration test
• Mock 遮蔽機制的完整分析 → Mock 遮蔽機制分析
• 想建 protocol integration test → 模組三：協議整合測試

概念位置

名義 integration test 在 test 分類中介於 unit test 和真正的 integration test 之間。它的 scope 比 unit test 大（多個內部元件一起測），但驗證對象和 unit test 相同（程式碼內部邏輯）。它和 mock 遮蔽的關係是：名義 integration test 用 mock 替換所有外部依賴，mock 遮蔽了協議層行為，而 test 名稱讓團隊以為這些行為已被驗證。

可觀察訊號與例子

辨識名義 integration test 的三個特徵：核心外部依賴 100% 被 fake 取代、沒有真實的 I/O 操作（網路、檔案、資料庫）、setUp() 不需要啟動外部程序或建立網路連線。

設計責任

修正策略分兩步：改名（讓 test 名稱反映真實驗證對象，如 connection_state_machine_test）和補寫（如果協議互動是關鍵路徑，補寫對真實服務的 protocol integration test）。在 test 檔案頂部標明被 fake 取代的依賴清單，讓後續讀者快速判斷驗證邊界。

第一次寫的名字幾乎都不對 — 不是因為命名能力不夠、是因為第一版命名只能基於「寫的當下看到的 context」、而正確的名字需要看到「未來所有 call-site / grep 結果 / 重構場景」。

命名的正確設計是 iterated artifact：寫 → re-read → 改 → 再 re-read → 收斂。每輪用不同 frame：

每輪可能 catch 到「上一輪沒看到」的問題、迫使重命名。接受重命名是命名工作的常態、不是失敗。

為什麼第一版幾乎不對

寫第一版時、認知資源都在「概念是什麼」、剩下的給命名只夠：

• 看到當前 function 在做的事 → 命名只反映當前
• 不知道未來會有 N 個 call-site → 沒考慮一致性
• 不知道未來會有 grep / refactor → 沒考慮 unique-ness
• 不知道未來會換 impl → 命名容易洩漏現在的 impl 細節

第一版命名是對「現在的 context」過度擬合。下一輪 review 換 frame 才能看到擬合方向之外。

四輪 review 的具體 checklist

輪 1：第一版

• 名字反映「做什麼 / 是什麼」、不是「怎麼做」
• 動詞 / 名詞符合語言慣例（function 動詞、value 名詞）
• 不超過 4 個單字（長 ≠ 清楚）
• 跑得到 next step、不在這輪糾結

輪 2：Grep-ability

• grep -r "<name>" 能命中目標、不會被別的 entity 蓋過
• 跟 framework / library reserved name 不撞（避免 data、type、value 等過泛）
• 名字不是其他名字的子字串（get 會匹配 getName getUser…）
• 中英混合場景下、英文部分能 grep（不要用 處理器handler 這種 mixed）
• 縮寫慎用（usr cfg mgr 增加 grep 失敗率）

輪 3：Cross-call-site 一致性

• 從 caller 角度看、名字暗示的契約對嗎？
• 跟同 module 其他類似 entity 命名格式一致嗎？（getUser vs fetchUser 不該混用）
• 同一個概念在不同 file 用同名嗎？（不該 userId / user_id / uid 三個並存）
• 動詞時態一致嗎？（fetched vs fetching vs fetch 對應狀態 / 動作 / 命令、不該混用）

輪 4：Impl 洩漏檢查

• 名字含 impl 細節嗎？（fetchUserViaSql ≠ fetchUser、後者較好）
• 換 impl 後名字還對嗎？（cacheGetUser 改成走 DB 後名字錯了）
• 名字洩漏 data structure 細節嗎？（userArray ≠ users、後者不綁 array）
• 介面層名字 vs 實作層名字區分嗎？（介面用「做什麼」、實作用「怎麼做」可加細節）

套用到不同命名場景

變數 / 函式

完整跑 1-4 輪。

額外注意：

• 作用域 — 越窄作用域越可短（loop counter i、close-up var tmp）；越寬作用域越要明確
• 類型暗示 — boolean 用 is / has / should 開頭

檔名 / module

跑 1-4 + 加：

• 層級表達 — 檔名能否反映在 directory 結構中的位置？
• 避免 utils / helpers / common — 這類是「不知該叫什麼」的訊號、強制再過一次輪 1-4

URL slug / route

跑 1-4 + 加：

• SEO — 跟 search query 的 substring match 對齊（#73 search 匹配模式）
• kebab-case 一致
• 不含 stop words（the、a、is、of、with、and）— 跟搜尋引擎 stemming 對齊

API endpoint / DB column

跑 1-4 + 加：

• 跨 service 一致性 — 同一概念在 client / server / DB 用同名（避免 user_id / userId / uid 跨 layer 不一致）
• 不可變更性 — DB column / API endpoint 改名成本極高、輪 1-4 多跑幾次值得

反模式：放棄重命名

何時可以跳輪

兩極：作用域越窄越可省、跨邊界 / public 越要 multi-pass。

跟其他抽象層原則的關係

判讀徵兆

核心：命名是 iterated artifact、不是 single-shot 動作。第一版基於狹窄 context 幾乎必錯。接受 N 輪 review 跟 K 次重命名是常態、命名品質會提升一個量級。試圖一次寫對 = 第一版 ship 出去 = 後續長期付 cognitive 成本。

集合型結構（問題清單、階段序列、原則組、支柱組）的命名只承載角色與層級、把成員數量留給清單自己呈現。「核心問題」這個名稱承受任意的成員增減；「核心七問」把當前成員數烤進名字、加一問、七就變八：名稱本身先失真、散落各處的引用跟著全部過期。「次要問題」「撞牆階段」「防護底線」同理 — 角色詞完成分層、數量歸清單。

區分核心問題跟次要問題、靠的是「核心 / 次要」這組角色詞；讀者選擇讀哪一組、不需要先知道組內有幾個成員。數字在名稱裡有真實的讀者側價值 — 記憶掛鉤與完整性提示（「五原則我只想起四個、漏了一個」）— 但這個價值在活集合下被漂移風險壓過、只有凍結集合能無風險收割它、這也是品牌名刻意用數字的原因；路由本身、角色詞已經完成。

為什麼數量入名比編號引用更深一層

數量是 membership 的 derivation

一個集合的成員數由「目前有哪些成員」決定 — 跟章節編號由「前面排了幾章」決定同構、都是會隨演進變動的衍生值。差別在寄生位置：編號寄生在引用句、數量寄生在名稱本身。名稱是整個知識系統裡被複製最多次的字串（標題、引用、索引、目錄、對話、commit message 都在複製它）、缺陷跟著名稱繁殖到每一個出現點。

它讓「語意標題是穩定錨」的前提失效

引用該錨在語意標題、因為標題被假設是這個單位的 fact。「核心七問」打破這個假設：標題有一半是語意（核心問題）、一半是 derivation（七）。成員一變、想守住名實一致就得全面改名、改名又回到「散落引用逐處修」的老路；想省事不改名、就留下一個說謊的名字（標題寫七問、實際有八問）、比編號錯位更糟 — 錯在系統的權威命名層。

失真的兩條路都有代價

反模式與修法

寫作時的判斷：命名一個集合時、問「這個數字提供了角色詞沒提供的資訊嗎？」— 答案幾乎都是否。讀者需要知道數量的時刻、是看到清單本身的時刻、清單天然自帶數量。

邊界：三種數字可以留

1. 外部凍結的品牌名：SOLID 五原則、OWASP Top 10、WRAP 四步驟 — 數量由發布方凍結、是名稱 fact 的一部分、跟引用 RFC 段號同理。
2. 數字是概念內容本身：兩次門檻 的二是規則的閾值、不是成員數 — 改了二就是改了概念、這種數字承載語意、該留。
3. 緊鄰清單的行內計數：「確認三件事：」後面直接跟三條列 — 數字跟清單同視野、改清單時順手改數字、漂移會立刻被看見。風險低、但仍是小負債、清單就在下面時「確認下列事項：」更省。
4. 內部宣告凍結的集合：團隊把某個方法論名稱當內部品牌用、可以明文宣告凍結後收割記憶價值 — 代價比凍結編號更嚴：凍結編號還能往後加、凍結數量連加都不能加、成員增減等於名稱重新談判。

判別線是「這個數字是 fact 還是 derivation」：發布方凍結的、概念內容本身的是 fact；內部活集合的成員數是 derivation、不入名。

跟其他抽象層原則的關係

• #155 引用章節用語意標題、不用位置編號：直接 sibling、分工在管線的兩端 — #155 修引用端（錨點選什麼）、本卡修命名端（錨點本身怎麼長）。#155 假設語意標題是穩定 fact、本卡負責讓這個假設成立：count-bearing 標題是「一半 fact 一半 derivation」的混合體、先淨化命名、#155 的引用紀律才有穩定的錨可用。實證：#155 卡初版自己用「見核心七問」當正面範例、修引用端時沒發現錨點內嵌數量。兩卡查的是不同層：引用端的檢查抓不到命名端的缺陷、反過來也一樣。
• #44 Single Source of Truth：成員數量的 truth 在清單本身（數一下就有）；把數量寫進名稱是把這個 derivation 複製成第二個源、且這個源被嵌進最高頻複製的字串裡：是 SSoT 違反裡擴散速度最快的形態。
• #84 Naming 是 iterated artifact：本卡給 #84 的命名 review 加一個檢查維度 — 數量入名是「第一版命名基於當下狹窄 context」的典型產物：寫名字的當下成員剛好七個、七看起來是這個集合的屬性；cross-time 檢驗（成員會不會變）才暴露它是快照。
• #67 寫作便利度跟意圖對齊反相關：「七問」「六階段」順口、有節奏感、好記 — 正是便利驅動的選擇；意圖對齊的名稱（核心問題）平淡但誠實。便利的代價延遲到第一次成員變動才結算。

觸發 case

同一份多階段訪談 skill、同一天內兩次命中：

1. 已發生：skill 初版有「四大支柱」、第二版需求調整後支柱變六個 — 名稱被迫改成「六大支柱」、所有提到四大支柱的地方同步修。改完的新名字仍然內嵌數量、下次支柱增減會原樣重演。
2. 被預見：第二版的「核心七問」「成長六階段」被指出同樣結構 — 核心問題若加一問、「七」就散落在標題、引用、索引、路由表裡等著逐處修。

更深的訊號是第三點：當天稍早為了修「Stage 3」編號引用立了一張卡（引用端）、該卡自己用「見核心七問」當正面範例；在專注檢查引用端時、命名端的同型缺陷完全隱形。確認了這是獨立的檢查維度、不是引用卡的子情況。

判讀徵兆

• 命名或標題出現「N 大 X」「N 問」「N 階段」「N 支柱」「N 原則」「N 步驟」且 X 是內部活集合時 — 抽掉數字、看角色詞夠不夠分層、幾乎都夠。
• Review 掃描可用：rg "[一二三四五六七八九十0-9]+ ?(大|問|階段|支柱|原則|步驟|件事|個維度)" --type md — 掃出來的不全是病灶：外部凍結品牌與概念閾值是 fact、留；內部活集合的成員數是 derivation、改。
• 集合成員增減的 commit、檢查名稱是否還誠實 — 需要同步改名的話、這次改名時順便把數量抽掉、別讓下次再來一遍。

一個結構單位的語意名稱只能有一個 canonical 字串、所有引用使用同一字串。「決策收斂」跟「決策記錄 + scaffold 建議」都是語意名、都通過了「不用編號」的檢查 — 但兩個字串指同一個階段、語意引用的收益就漏了一半：工具掃描要掃兩個 pattern 才完整、漏配置一個就漏一半引用點；結構重排時、修復者要先在腦中建立「這兩個名字是同一個東西」的對應表、而這張表沒有寫在任何地方。

語意引用的承諾是「錨點穩定、且機器與人都能單次比對」。同義雙名保住了穩定、丟掉了單次比對 — 等於把 fact 寫成兩種拼法。

為什麼雙名會自然發生

雙名通常在不同檔案、不同時間寫下：標題在設計流程時取（描述產出物：「決策記錄 + scaffold 建議」）、引用在寫協作檔時取（描述階段角色：「決策收斂階段」）。每一次取名都在自己的當下語境裡合理、分裂要把兩個時間點的產物擺在一起才看得到 — 單檔 review 永遠只看到其中一個名字、所以雙名能安然通過所有單檔檢查。

偵測需要跨檔視角：把每個結構單位的「標題語意半邊」列成清單、grep 全部引用句、比對引用字串是否落在清單內。引用字串語意對、字面不在清單內、就是雙名。

反模式與修法

修法的判斷次序：canonical 字串取「標題的語意半邊」（標題是該單位的 fact 所在）；標題語意半邊太長不適合引用時、先改標題、再統一引用 — 標題改短是一次成本、引用各自簡寫是持續發散。

跟其他抽象層原則的關係

• #155 引用章節用語意標題、不用位置編號：本卡補 #155 的缺口。#155 把錨點從編號換成語意名稱、預設了「語意名稱是單一的」；雙名讓 #155 的修法只完成一半 — 錨點穩定了、可比對性沒跟上。三卡合起來是完整的引用紀律：#155 管引用端（錨什麼）、#156 管命名端的內容（名稱不含 derivation）、本卡管命名端的唯一性（一個單位一個字串）。
• #156 集合命名用角色、不內嵌數量：sibling。#156 處理名稱「內容」的 fact 純度、本卡處理名稱「數量」的唯一性 — 一個名稱可以通過 #156（不含成員數）仍違反本卡（有同義變體）。
• #44 Single Source of Truth：同一語意身分的兩個字串就是同一個 fact 的兩個源 — 比值的多源更隱蔽、因為兩個字串「語意上相等」、讀者看不出這是違規、只有工具比對才會痛。
• #84 Naming 是 iterated artifact：#84 的輪 3 明文檢查「同一個概念在不同檔案用同名嗎」、判讀徵兆也列了「同概念出現兩個以上名字、選一個改另一個」— 本卡是這個檢查項在「結構單位的標題與引用」場景的應用：被檢查的從變數名換成章節 / 階段的語意錨、檢查動作相同。

觸發 case

一份多階段訪談 skill 在一致性 audit 中被抓到兩處：階段標題寫「決策記錄 + scaffold 建議」、兩個協作檔的引用寫「決策收斂階段」；另一個階段的引用在「domain / event 切分」與「領域切分」之間混用。每個字串單獨檢查都合規（語意名、無編號、無數量）— audit reviewer 的原話是「語意可對上、但嚴格來說引用錨與標題語意半邊不同字串、下次重排時要靠人腦對應」。修法：標題語意半邊改成「決策收斂」、全 skill 引用統一；「領域切分」全部改寫為「domain / event 切分」。

判讀徵兆

• 寫引用句時、回頭看目標標題：引用字串跟標題語意半邊逐字相同嗎？語意相同、字面不同 = 雙名。
• 跨檔 review 可操作：列出所有結構單位的語意半邊、rg 每個單位的引用句、引用字串不在清單內的逐處判讀。
• 同單位的引用在不同檔案用不同說法、且沒有任何一處寫明對應 — 雙名已經發生、統一的成本隨引用點數量成長。