連線生命週期 log

連線生命週期 log 記錄的是「流程走到第幾步、每步成功或失敗」。這一層的 log 粒度是步驟級 — 不記錄每一個封包或每一次函式呼叫，只記錄流程中的關鍵節點。

以 app_tunnel 的連線流程為例，連線生命週期包含五步：biometric 認證 → credential 讀取 → WebSocket 連線 → auth token 發送 → stream 訂閱。每步完成時記一條 log，失敗時記一條包含原因的 log。

1[conn] Step 1/5: biometric auth completed (duration: 320ms)
2[conn] Step 2/5: credential loaded (user: admin)
3[conn] Step 3/5: WebSocket connected (url: wss://...)
4[conn] Step 4/5: auth token sent
5[conn] Step 5/5: stream subscribed, ready

app_tunnel 在實機測試前六個核心元件中只有兩個有 log，且全是 W2 修復時事後補上的（T.C4）。W2-002 auth token 問題的 debug 過程中，開發者無法從任何 log 判斷失敗發生在五步中的哪一步。如果有連線生命週期 log，第一次連線就能看到「Step 3 完成，Step 4 未執行」— 直接定位到 auth token 缺失。

連線生命週期 log 在所有模式（debug 和 release）都應該啟用。這層 log 量小（每次連線 5-10 條），不影響效能，但在 production 問題回報時是第一手資訊來源。

Protocol 訊息 log

Protocol 訊息 log 記錄的是通訊協議層面的細節：發送和接收的 frame type、payload 前綴、handshake 參數、逾時值。這一層的粒度比連線生命週期更細 — 每一次 send/receive 都記錄。

1[proto] TX: text frame, payload: {"AuthToken":"base64..."} (42 bytes)
2[proto] RX: text frame, payload prefix: "0" (output data, 128 bytes)
3[proto] TX: binary frame, payload: [72, 101, 108, 108, 111] (5 bytes)

Protocol log 在 debug 時幫助確認「程式碼發送了什麼、收到了什麼」。app_tunnel 的 text/binary frame 問題（T.C1）如果有 protocol log，開發者會在 log 中看到 TX: binary frame 而非預期的 TX: text frame — 直接指向 frame type 問題。

Protocol log 在 release mode 應該能關閉。這層 log 量大（每次鍵盤輸入一條），且 payload 可能包含敏感資訊。Debug mode 預設啟用，release mode 提供開關（例如隱藏設定頁的 toggle）讓進階使用者在回報問題時開啟。

使用者行為 log

使用者行為 log 記錄的是使用者在 UI 上的操作：按鈕點擊、畫面切換、設定變更。這層 log 的粒度是操作級 — 使用者做了一個有意義的動作記一條。

1[ui] screen: HomeScreen, action: tap Connect Terminal
2[ui] screen: TerminalScreen, state: connecting → connected
3[ui] screen: TerminalScreen, action: tap back button
4[ui] screen: HomeScreen, state: returned from terminal

使用者行為 log 在兩個場景有價值：第一，debug 時還原使用者操作路徑 — 「使用者做了什麼導致問題出現」；第二，結合狀態矩陣（ux-design 模組一）做狀態轉換的實際覆蓋率分析 — 哪些狀態轉換在真實使用中經常發生，哪些從未發生。

使用者行為 log 在 release mode 啟用時需要注意隱私。記錄「使用者切換了畫面」是合理的；記錄「使用者輸入了密碼 abc123」需要 redaction 機制（monitoring 模組七 資安）。

三層的關係

三層 log 各自獨立運作，debug 時通常按照從粗到細的順序使用。

粗篩：先看連線生命週期 log，確認流程走到哪一步。如果 Step 3 失敗，問題在 WebSocket 連線層。

細查：切到 protocol 訊息 log，看 Step 3 的連線嘗試中發送和接收了什麼。如果看到 binary frame 發送但沒有回應，問題可能在 frame type。

還原：如果問題和使用者操作有關（例如只在特定操作順序下觸發），看使用者行為 log，還原操作路徑。

三層 log 用同一個時間戳和 correlation ID（例如連線 session ID），讓跨層比對可行。

下一步路由

• 在功能規格中定義 log 點 → 功能規格中的 log 點定義方法
• 事後補 log 和設計產物 log 的品質差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 收集方案選擇 → 自架 log endpoint vs 商業方案
• 事件分類與收集策略 → monitoring 模組一 監控心智模型

四類 log 點

每個功能的 log 點按執行時機分成四類。

啟動 log

功能開始執行時記錄。回答「這個功能是否被觸發了」。

啟動 log 包含觸發來源（使用者操作、系統排程、外部事件）和初始參數（連線目標、操作類型）。如果一個功能從未被觸發，啟動 log 的缺席就是線索。

步驟 log

功能執行過程中的每個關鍵步驟完成時記錄。回答「流程走到哪裡了」。

步驟 log 的粒度依功能複雜度而定。三步驟的功能每步記一條；十步驟的功能可以只記關鍵的三到五步。判斷標準是：如果這一步失敗，開發者是否需要知道失敗點在哪。

錯誤 log

步驟失敗、例外捕獲、非預期狀態出現時記錄。回答「出了什麼問題」。

錯誤 log 必須包含足夠的 context 讓開發者不需要重現問題就能判斷原因。至少包含：哪一步失敗、失敗原因（error message）、當時的關鍵狀態值。

完成 log

功能正常結束時記錄。回答「功能是否成功完成、花了多久」。

完成 log 包含執行結果和耗時。和啟動 log 配對使用 — 有啟動但沒有完成代表功能中途異常退出。

在功能規格中加可觀測性欄位

以 app_tunnel 的「連線到 ttyd 終端機」功能為例，傳統規格只寫：

• 輸入：使用者選擇的伺服器
• 處理：建立 WebSocket 連線、發送 auth token、開始接收 terminal output
• 輸出：終端機畫面顯示 terminal output

加上可觀測性欄位後：

這張表在功能規格階段就能寫出來，因為它只依賴功能的流程設計，不依賴實作細節。功能流程確定後，每一步在哪裡需要 log 點就確定了。

log 點命名規則

統一的命名規則讓 log 可以被 grep、過濾和統計。

階層式命名：{功能}.{步驟}.{事件}。例如 connect.ws.connected、connect.auth.failed。

事件後綴統一：start（啟動）、done（步驟完成）、failed（失敗）、complete（功能完成）。

和程式碼結構對應：log 點名稱對應到程式碼中的函式或模組。connect.biometric.done 對應 BiometricService.authenticate() 的成功路徑。這讓開發者看到 log 名稱就知道去哪裡找程式碼。

log 點規格的 review 檢查

功能規格 review 時，可觀測性欄位的檢查要點：

每步都有 log：流程中的每個步驟在成功和失敗時都有對應的 log 點。遺漏的步驟意味著該步驟出問題時無法從 log 判斷。

錯誤 log 有足夠 context：error log 只寫「連線失敗」不夠；需要寫「連線失敗」加上 error code、目標 URL、已完成的步驟。

敏感欄位有 redaction 標記：密碼、token、個人資料在 log 規格中標記為 redact，實作時用 redaction 機制處理。

啟動和完成配對：每個功能有啟動 log 就應該有完成 log，形成完整的生命週期。

下一步路由

• 三層 log 的詳細設計 → 三層 log 設計
• 事後補 log 和設計產物 log 的差異 → 「事後補 log」vs「設計產物 log」的品質差異
• Log 中的敏感資訊處理 → monitoring 模組七 資安

自架 log endpoint 的適用場景

自架 log endpoint 適合的前提是：client 和 server 在同一個網路內（同機、同 LAN、同 VPN/tailnet），log 的唯一消費者是開發者本人。

app_tunnel 就是這個場景。Server（ttyd）和 client（Flutter app）在同一台機器或同一個 Tailscale tailnet 內。開發者同時是使用者和維運者。Log 的消費方式是 grep — 不需要 dashboard、不需要告警、不需要多人共享。

在這個場景下，自架 log endpoint 的成本遠低於商業方案。一個 Go 程式開 HTTP endpoint 接收 JSON log 寫入檔案，20 行程式碼就能完成。Client 端的 AppLogger 在 debug mode 同時寫 console 和 POST 到 endpoint。Debug 時用 grep + jq 查詢，不需要額外工具。

1Client (Flutter) → HTTP POST /log → Go receiver → JSON file → grep/jq

這個方案沒有外部依賴、沒有帳號管理、沒有費用、沒有資料隱私顧慮（log 不離開本機網路）。

商業方案的適用場景

商業方案（Sentry、Crashlytics、Datadog）適合的前提是：使用者分佈在外部網路，log 的消費者包含非開發者（維運、客服、產品），且需要告警和趨勢分析。

商業方案提供的能力包括：跨網路收集（SDK 自動處理網路不穩定和批次傳輸）、多人查看 dashboard、告警規則設定、crash 報告自動分群、用戶 session 重播。這些能力在自用工具場景下不需要，在商業產品場景下是基礎需求。

商業方案的成本包括：SDK 整合和設定、帳號和權限管理、月費（依事件量計費）、資料隱私合規（log 傳到第三方伺服器）。

判斷流程

使用者在哪裡

使用者和 server 在同一個網路內（自用工具、內部工具、開發期測試）→ 自架 log endpoint 是成本最低的選擇。

使用者在外部網路（上架 app store、SaaS 產品、B2B 部署）→ 商業方案的跨網路收集能力是必要的，自架需要處理的 edge case（離線緩衝、重試、批次傳輸）太多。

Log 消費者是誰

只有開發者自己 → grep/jq 足夠，不需要 dashboard。

包含非技術人員（客服、產品經理）→ 需要視覺化 dashboard 和搜尋介面，商業方案的 UI 是這個需求的標準答案。

是否需要告警

開發者自己用、即時看 log → 不需要告警。

有維運值班、需要被動發現問題 → 需要告警規則，商業方案內建。

混合方案

開發期用自架 log endpoint（零成本、即時可用），production 切換到商業方案 — 這個策略可行的前提是 log 層的 API 設計足夠抽象。

AppLogger 提供統一的 log 介面（log(level, name, data)），底層實作在 debug mode 寫 console + POST 到本機 endpoint，在 release mode 寫 console + 呼叫 Sentry/Crashlytics SDK。切換只改 AppLogger 的底層實作，不改呼叫端。

這個抽象的投資在自用工具階段就值得做 — 即使目前不需要商業方案，統一的 log 介面也讓 log 點的管理更一致。

下一步路由

• 三層 log 的詳細設計 → 三層 log 設計
• 在功能規格中定義 log 點 → 功能規格中的 log 點定義方法
• Log 收集後的 schema 設計 → monitoring 模組二 Log Schema

格式統一性

app_tunnel 在 W2 修復時補的 developer.log 格式不統一（T.C4）。不同元件由不同時間點、不同 debug 需求補上的 log，各自有各自的風格：

有的帶 name: 參數讓 log 可以按元件過濾：

1developer.log('WS connected', name: 'ConnectionManager');

有的不帶，混在全域 log 裡無法過濾：

1developer.log('auth token sent');

有的帶 // i18n-exempt 標記（因為 linter 會對 hardcoded string 報警），有的忘了加。有的把錯誤訊息放在 error: 參數，有的用字串串接。

這些不一致來自事後補 log 的結構性原因：每條 log 是在解決當下問題時加的，沒有統一規範，也沒有 review。加完能定位問題就提交，下次遇到新問題再加新的 log — 格式隨機。

設計產物 log 在產出前就有命名規則和格式規範（見 功能規格中的 log 點定義方法）。所有 log 點走同一個 AppLogger 介面，name、level、結構化欄位在規格階段就定義好，實作時照規格寫。

覆蓋完整性

事後補 log 的覆蓋範圍由「哪些問題已經發生過」決定。W2-002 auth token 問題觸發了 ConnectionManager 和 TerminalScreen 的 log 補充，但 TtydProtocol、BiometricService、CredentialRepository、EnrollmentScreen 四個元件仍然零 log — 因為這四個元件在 W2 的 debug 過程中不是瓶頸。

六個核心元件中四個零 log 的狀態意味著：下次如果問題出在 BiometricService（例如特定 iOS 版本的 biometric API 行為改變），debug 又會回到「手動加 log → 重新編譯 → 插拔裝置」的循環。事後補 log 只覆蓋已知問題的路徑，對未知問題沒有防護。

設計產物 log 的覆蓋範圍由功能流程的步驟數決定。每個功能規格列出所有步驟的 log 點，不管這些步驟是否曾經出過問題。BiometricService.authenticate() 在規格中就有 start/done/failed 三個 log 點，無論是否遇過 biometric 問題。

維護成本

事後補 log 隨 debug 過程累積，沒有統一管理。隨時間推移：

• 某些 log 的觸發條件已經不存在了（被修復的 bug 對應的 log），但沒人清理
• 某些 log 的格式和新加的 log 不一致，但沒人統一
• 某些 log 的 context 資訊不足（當時能定位問題是因為開發者記得 context，半年後換人接手就不夠了）
• 某些 log 在 release build 中不該出現但忘了加條件

設計產物 log 有規格文件作為 source of truth。功能變更時更新規格中的 log 點列表，刪除的步驟對應的 log 點一起刪除，新增的步驟對應的 log 點一起新增。Log 的生命週期和功能的生命週期綁定。

從事後補過渡到設計產物

已有的事後補 log 不需要全部重寫。過渡策略是：

統一入口：建立 AppLogger 封裝，把現有的 developer.log 呼叫改為走 AppLogger。這一步不改 log 內容，只改呼叫方式，讓後續的格式統一和功能切換有統一入口。

補規格：對每個功能寫出 log 點規格表（四類 log 點），比對現有 log 和規格的差距。規格中有但程式碼中沒有的 log 點 = 覆蓋缺口，補上。程式碼中有但規格中沒有的 log 點 = 可能是過時的 debug log，評估是否刪除。

新功能走設計產物流程：從下一個新功能開始，功能規格中包含可觀測性欄位。新功能的 log 從一開始就是設計產物品質。

過渡的第一步是建立統一入口，具體的 log 點規格格式見功能規格中的 log 點定義方法。規格中的每個 log 點屬於哪一層（連線生命週期 / protocol / 使用者行為），在三層 log 設計中定義。收集到 log 之後用自架還是商業方案處理，見自架 log endpoint vs 商業方案的判斷流程。