事件設計是三維結構：動機（為什麼收）決定需要什麼事件、感測器（怎麼收）決定在前端哪裡埋點、生命週期（什麼時候收）決定各事件在哪個產品階段啟用。本章展開從需求推導收集策略的四個方向到具體事件名稱級。從動機出發反推事件清單，比從技術能力出發（「SDK 能收什麼就收什麼」）更精準 — 每個事件都能回指一個具體的消費場景。

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 的統計基礎。

完整對照總表

下一步路由

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