事件命名

行為事件的命名遵循 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 類，完整的分類定義見模組一 四類事件定義。收集行為事件前必須完成去識別化 — 使用者行為模式本身就是可識別資訊。

從操作盤點推導事件

每個使用者操作（BDD 操作盤點的產物）至少對應一個 event 類型的事件。操作的失敗路徑對應 error 類型。操作涉及的效能測量對應 metric 類型。操作觸發的系統狀態轉換對應 lifecycle 類型。

推導鏈：操作 → 四類事件候選 → 命名 → data schema。

以一個透過 WebSocket 連接遠端終端機的 app 為例，「連線到終端機」這個操作推導出的事件：

一個操作推導出六個事件 — 因為這個操作跨越了使用者行為（event）、可能失敗（error）、有效能測量（metric）、涉及系統狀態轉換（lifecycle）四個面向。其中 connect.done 和 connect.duration 記錄的是同一事實的兩個面向（見下方邊界案例段），自用場景合併成 connect.done 帶 duration_ms 欄位更簡潔。

四類補齊檢查

列完所有操作的事件後，對每個功能區域跑一次四類補齊檢查 — 逐列確認每一類是否都有對應的事件。

空格是候選遺漏。每個空格問一個問題：

• event 空：「這個功能區域有使用者操作嗎？」有 → 補事件；沒有（純系統內部）→ 合理的空格
• error 空：「這個功能區域能失敗嗎？」能 → 補事件；不能失敗的功能極少 → 再想一次
• metric 空：「這個功能區域有值得量測的效能指標嗎？」有 → 補事件；操作瞬間完成且不涉及外部依賴 → 合理的空格
• lifecycle 空：「這個功能區域涉及系統狀態轉換嗎？」有 → 補事件；純資料操作不改系統狀態 → 合理的空格

上表中「輸入」的 metric 和 lifecycle 空格是合理的 — 文字輸入送出不涉及效能量測和系統狀態轉換。「配對」的 lifecycle 空格也合理 — 配對完成後不改變系統的執行狀態。

粒度判準

事件粒度的判斷用一個 SRP 判準：一個事件記一個事實。

拆分訊號

一個事件記了兩個獨立的事實 → 拆成兩個事件。

terminal.connect_and_auth 同時記錄「連線建立」和「認證通過」。這兩個事實的失敗模式不同（連線失敗是網路問題、認證失敗是帳密問題）、觸發時機不同、消費者不同。拆成 terminal.connect.done 和 auth.token.sent。

合併訊號

兩個事件永遠同時觸發且消費者相同 → 合併成一個事件。

terminal.input.keystroke 和 terminal.input.keystroke_logged 永遠同時觸發（每個按鍵一次），data schema 相同。合併成一個 terminal.input.keystroke。

邊界案例

connect.done 同時記 event 和 metric（成功事件 + duration）。這是一個事實（連線完成）的兩個面向，可以合併成一個事件帶 duration_ms 欄位，也可以拆成 event 和 metric 兩筆。判斷依據是查詢需求 — 如果 funnel 分析和效能分析會分開查，拆開讓各自的查詢更簡單；如果都在同一個 dashboard 看，合併減少事件量。

data schema 設計

每個事件的 data 欄位回答「發生了什麼的 context」。設計原則：

帶足 debug context：error 事件的 data 至少包含 error message、發生的步驟、當時的關鍵狀態值。看到這筆 error 事件時、開發者不需要再去查其他來源就能判斷問題方向。

避免過度收集：data 只帶回答具體問題需要的欄位。terminal.connect.start 帶 URL 和觸發方式就夠了；不需要帶使用者的全部設定。

敏感欄位標記 redaction：URL 可能含 IP、error message 可能含路徑中的使用者名稱。在事件設計階段標記需要 redaction 的欄位，SDK 實作時自動處理。

事件表的產出格式

完整的事件表每列七欄：

保留層級欄對應分層保留策略 — 哪些事件需要保留原始逐筆資料（debug 用）、哪些只需要聚合摘要（趨勢用）。

事件表是 SDK 埋點的 spec — 開發者照表實作，code review 時逐行勾選。和功能規格中的 log 點定義互補 — log 點是開發期的 debug 設計，事件表是監控期的收集設計。

下一步路由

• 四類事件的定義 → 四類事件的完整定義
• 事件命名規範 → 事件命名規範
• 行為事件的 funnel 設計 → 行為事件設計
• 事件 schema 的欄位定義 → event.schema.json 完整欄位解說
• 動機驅動的具體事件對應 → 動機驅動的事件設計

Debug 動機

Debug 動機驅動的事件收集目標是「問題發生時、開發者能從事件記錄中重建 context 並定位根因」。

要偵測的行為

• 多步驟流程的每一步完成或失敗（連線 → 認證 → 資料交換）
• 系統狀態轉換（前景/背景、連線/斷線、登入/登出）
• 非預期例外（uncaught exception、network error、timeout）
• 使用者最近的操作序列（問題發生前做了什麼）

事件表

查詢場景

Session 回放：按 session_id 過濾、按時間排序，還原「使用者做了什麼 → 系統發生了什麼 → 問題在哪裡出現」。

Error 根因定位：按 error name GROUP BY，找出最常出現的錯誤。單筆 error 的 stack_trace + 同 session 的 lifecycle 事件組合，判斷失敗發生在流程的哪一步。

最近 N 個操作：error 發生前的 10-20 個 event/lifecycle 事件，等同 Sentry 的 breadcrumb trail。

生命週期階段

開發期起全開。Debug 事件是最早需要的 — 實機測試階段就依賴這些事件定位問題。error 類和 lifecycle 類不做取樣（量低且每筆都可能是線索）。

商業動機

商業動機驅動的事件收集目標是「回答產品決策的問題 — 使用者在哪裡流失、不同群組行為有什麼差異、哪些功能被使用」。

要偵測的行為

• 漏斗步驟完成（註冊 → 啟用 → 付費 → 續約的每一步）
• 功能使用頻率（哪些功能被頻繁使用、哪些從未被觸發）
• Session 長度和頻率（使用者多常用、每次用多久）
• 關鍵轉換事件（首次付費、邀請好友、升級方案）

事件表

查詢場景

Funnel 轉換率：每步的完成數 / 上一步的完成數。SQLite 層做每步計數，PostgreSQL 層做 session 級 JOIN 的精確轉換率（見 功能分層與 Backend 選擇）。

Cohort 留存：按「首次使用週」分群，計算每週的回訪率。需要 session.start 事件 + 使用者首次出現的時間戳。

功能使用率：feature.*.used 事件按 name GROUP BY COUNT，排序找出最常/最少使用的功能。

生命週期階段

上線後啟用。開發期不需要商業事件（沒有真實使用者）。測試期可以用模擬流量驗證 funnel 事件的觸發正確性，但不做分析。

資安動機

資安動機驅動的事件收集目標是「偵測非預期的存取模式、追蹤敏感操作、提供事後稽核的 audit trail」。

要偵測的行為

• 認證失敗（密碼錯誤、biometric 失敗、token 過期）
• 權限越界嘗試（嘗試存取非自己的資源、呼叫無權限的 API）
• 敏感資料存取（查看個資、匯出資料、修改權限設定）
• 異常存取模式（短時間大量請求、非常規時段存取、來源 IP 變化）

事件表

查詢場景

認證失敗監控：auth.*.failed 事件的 count by session_id，短時間內同一 session 多次失敗 → 暴力破解嫌疑。Rule engine 設閾值告警。

Audit trail：sensitive.* 和 admin.* 事件按時間排列，回答「誰在什麼時候存取/修改了什麼」。合規審計的必要紀錄。

異常 pattern 偵測：auth 成功後的操作事件頻率和模式分析。正常使用者每 session 操作 10-50 次；自動化腳本可能操作數千次。

生命週期階段

開發期起全開。安全事件不能延後 — 「先不收安全事件、上線後再加」等於安全審計的空白期。認證相關事件是 auto-intercept 的一部分（見 自動攔截機制），不需要手動埋點。

和 redaction 的關係

資安事件本身可能包含敏感資訊（失敗的密碼、被存取的個資欄位名稱）。事件的 data schema 設計時標記需要 redaction 的欄位 — auth.failed 記錄失敗原因但不記錄輸入的密碼、sensitive.accessed 記錄資源類型但不記錄資源內容。

效能動機

效能動機驅動的事件收集目標是「發現效能退化趨勢、定位效能瓶頸、為容量規劃提供數據」。

要偵測的行為

• 操作回應時間（API 呼叫、頁面載入、動畫轉場）
• 渲染效能（frame rate、長任務、佈局重排）
• 資源使用（記憶體、CPU、網路流量）
• 外部依賴延遲（第三方 API、CDN、資料庫查詢）

事件表

查詢場景

P95 趨勢：{operation}.duration 事件按天聚合、計算 percentile_cont(0.95)，觀察回應時間是否隨版本增加。

容量規劃：resource.memory 事件的趨勢圖，判斷記憶體是否隨使用時間穩定增長（memory leak 訊號）。

依賴健康度：dependency.*.latency 事件按 dependency_name GROUP BY，比較各依賴的平均延遲和失敗率。

生命週期階段

測試期起啟用。開發期不需要效能事件（本地環境的效能數據不代表 production）。測試期啟用用於建立效能 baseline。上線後持續收集用於趨勢監控。

效能事件量通常最大（每 30 秒一筆 resource.memory × 活躍使用者數），取樣率需要控制 — 自用場景全收、商業產品取樣 10-50%（見 前端感測器設計 的取樣策略段）。

A/B 測試動機

A/B 測試動機驅動的事件是商業動機的延伸 — 實驗期間收集實驗分組和轉換事件，實驗結束後關閉。

事件表

生命週期階段

實驗期間啟用，實驗結束後關閉（從 SDK config 或 feature flag 移除）。實驗事件的保留期限跟著實驗週期走 — 實驗結束 + 分析完成後可清除。A/B test 的統計分析見 A/B test 的統計基礎。

完整對照總表

下一步路由

• 四類事件的基礎定義 → 四類事件的完整定義
• 事件枚舉的方法論 → 事件枚舉與補齊檢查
• 前端感測器的具體設計 → 前端感測器設計
• 感測器的生命週期控制 → 感測器生命週期管理
• 查詢消費模式的完整展開 → 查詢消費模式