觀察

app_tunnel Flutter app 連接 ttyd WebSocket 終端機。ConnectionManager.sendData() 接收 Uint8List 型別的鍵盤輸入，直接傳給 _channel!.sink.add(data)。Dart 的 IOWebSocketChannel 對 Uint8List 發送 binary frame（opcode 0x2），ttyd 期望 text frame（opcode 0x1），收到 binary frame 靜默忽略。

判讀

1. Mock 模擬的是 Dart API 契約，不是 WebSocket 協議契約。FakeWebSocketChannel 忠實實作了 WebSocketChannel 的 Dart interface — sink.add(dynamic) 接受任何型別。但 IOWebSocketChannel 的 sink.add 實際行為是：String → text frame，List<int> / Uint8List → binary frame。Mock 沒有也不應該模擬這個協議層行為。

2. ttyd 的靜默忽略放大了問題。如果 ttyd 對 binary frame 回傳錯誤碼或斷線，app 至少會進入 error 狀態讓開發者察覺。靜默忽略讓問題從「連線失敗」變成「連線成功但無回應」，debug 方向完全錯誤。

3. 型別系統幫不上忙。Dart 的 WebSocketSink.add 簽名是 void add(dynamic event) — dynamic 吃掉了型別資訊。即使用強型別語言，如果 API 設計成 dynamic，型別檢查無法區分協議語意。

策略

1. Protocol integration test：對真實 ttyd 發送 Uint8List 和 String，斷言兩者行為差異。一個 5 行 test 就能抓到這個問題。
2. 在 sendData 層做型別轉換：不依賴下游 channel 的行為，在自己的 API 邊界確保型別正確。
3. Log 送出的 frame type：developer.log('WS send: type=${data.runtimeType}') 讓 debug 時立即可見。

下一步路由

• 想寫 protocol integration test → 模組三：協議整合測試
• 想理解 mock 遮蔽的系統性機制 → Mock 遮蔽機制分析
• 類似案例（auth handshake） → T.C2 Auth handshake 缺失

觀察

ttyd WebSocket 協議要求連線建立後發送一個 JSON frame 包含 base64 編碼的帳密（{"AuthToken":"base64(user:pass)"}），ttyd 驗證通過後才開始推送 terminal output。app_tunnel 的 ConnectionManager 建立 WS 連線後直接開始監聽 stream，沒有發送 auth token。

判讀

1. Mock 的 happy path 比真實服務寬鬆。FakeWebSocketChannel 的 ready 是 Future.value()（立即完成），stream 是開發者手動控制的 StreamController。真實 ttyd 的行為是：ready 完成代表 TCP+WS 握手成功，但 stream 要等 auth token 驗證後才有資料。Mock 把兩步合成一步。

2. Integration test 名為整合實為 fake。connection_flow_test.dart 標題是「端對端整合測試」，但內部使用 FakeWebSocketChannel + FakeBiometricService + InMemoryCredentialRepository — 三個核心依賴全是 fake。這個 test 驗證的是「假設所有外部服務都正常，內部狀態機是否正確」，不是「真實服務互動是否正確」。

3. 功能缺失比功能錯誤更難被 test 抓到。功能錯誤（T.C1 text vs binary）至少有一個實作可以斷言；功能缺失意味著沒有程式碼可以 test。只有 protocol integration test（對真實服務跑）才能暴露「應該有但沒有」的行為。

策略

1. Protocol integration test 必須涵蓋 auth handshake：連線 → 發送正確 auth token → 斷言收到 output；連線 → 不發送 auth token → 斷言 timeout 或斷線。
2. 在企劃階段列出協議握手步驟：ttyd WS 協議的 auth handshake 應該在 spec 文件中明確列出，不依賴開發者記得實作。
3. 區分「名義 integration」和「真實 integration」：test 名稱含 integration 但全用 fake，應標明 fake-integration 或改名 connection-state-machine-test。

下一步路由

• 想區分 mock 層級 → 模組一：測試策略分層
• 想建 protocol integration test → 模組三：協議整合測試
• 想設計 auth 機制的 UX fallback → U.C2 biometricOnly 無 fallback

觀察

app_tunnel 的 AnsiParser 負責解析終端機輸出的 ANSI escape 序列，轉換為帶色彩的文字 token。unit test 用手寫字串驗證：

1// 測試資料範例 — 乾淨的 SGR 色彩碼
2test('紅色文字', () {
3  final tokens = parser.parse('\x1B[31mhello\x1B[0m');
4  expect(tokens.first, isA<TextToken>());
5});

真實 zsh prompt 啟動後送出的控制序列（擷取自實機 log）：

1\x1B]0;user@host: ~\x07          ← OSC：設定終端機視窗標題
2\x1B[?2004h                      ← CSI private mode：啟用括號貼上模式
3\x1B[?1h                         ← CSI private mode：啟用應用程式游標鍵
4\x1B(B                           ← 字元集指定：選擇 ASCII
5\x1B[?25l                        ← CSI private mode：隱藏游標

Parser 只認識 \x1B[{數字;數字}{字母} 格式的標準 CSI，其他全部殘留在輸出中。

判讀

1. 測試資料的代表性是隱性假設。18 個 test 的斷言都正確 — \x1B[31m 確實應該產生紅色 token。但「測試輸入能代表真實輸入」是一個未經驗證的假設。真實 zsh 的輸出包含 5+ 種 escape 序列類型，測試只覆蓋了 1 種。

2. Parser 的行為對未知序列是「透傳」而非「報錯」。這是合理的設計 — 不認識的序列不應該讓 parser 崩潰。但透傳的後果是亂碼靜默出現在畫面上，不觸發任何錯誤或 log，開發者在 unit test 環境完全不會察覺。

3. 手寫測試資料 vs 錄製真實資料。如果測試資料是從真實 shell session 錄製的（capture 一次真實 zsh 啟動輸出），OSC 和 CSI private mode 會自然出現在測試輸入中，parser 的透傳行為會在 test 階段就被看到。

策略

1. 從真實環境錄製測試資料：用 script 命令或 WebSocket log 錄一次真實 shell session 的完整輸出，作為 integration test 的輸入。即使不改 parser 邏輯，至少能看到「哪些序列被透傳了」。
2. Parser 對未知序列記 warning log：透傳是合理的 fallback，但加一行 developer.log('Unknown escape: ${escape.codeUnits}') 讓開發者知道有未處理的序列。
3. 測試分兩類：「功能正確性」用手寫乾淨字串；「環境相容性」用錄製的真實輸出。兩類測試回答不同問題。

下一步路由

• 想理解測試資料代表性 → Test data 代表性
• 想建 protocol integration test 用真實 ttyd 輸出 → 模組三：協議整合測試
• 類似案例（mock 遮蔽） → T.C1 WS frame type mock 遮蔽

觀察

app_tunnel 的六個核心元件在實機測試前的 log 覆蓋狀態：

W2-004（P0：iOS 實機 WS stream 不觸發）的 debug 過程：無法從任何 log 判斷問題發生在 biometric → credential → WS connect → auth token → stream listen 的哪一步。開發者被迫在每個函式手動加 developer.log，重新編譯，插拔裝置測試，反覆數次才定位到「stream 訂閱時機」問題。

判讀

1. Log 缺失把 debug 成本從秒級升到分鐘級。如果 ConnectionManager 在企劃階段就設計了「Step 1: biometric → Step 2: credential → Step 3: WS connect → Step 4: auth token → Step 5: listen stream」五步 log，W2-002 的 auth token 問題在第一次連線就能從 log 看到「Step 3 完成，Step 4 未執行」。

2. 「事後補 log」的 log 品質較低。W2 修復時補的 developer.log 格式不統一（有的帶 name:，有的不帶；有的用 // i18n-exempt 標記，有的忘了），沒有統一的 log 層級，沒有結構化欄位。事後補的 log 是救火工具，不是可觀測性設計。

3. 自用工具最適合自架 log 收集。app_tunnel 的 server 和 client 都在同一台機器上（或同一個 Tailscale tailnet），client 可以直接打 HTTP POST 到本機的 log endpoint，不需要 Sentry 或 Crashlytics。一個 Go 寫的 JSON log receiver（20 行）+ grep 就是完整的 debug 工具鏈。

4. Log 設計是功能規格的一部分。「連線到 ttyd 終端機」這個功能的規格不只是「建立 WS 連線」，還包含「每步有 log、失敗有 log、成功有 log」。跟 API 規格需要定義 request/response 一樣，連線功能需要定義 log 點。

策略

1. 功能規格階段列出 log 點清單：每個功能的規格文件新增「可觀測性」欄位，列出啟動/步驟/錯誤/完成四類 log 點。
2. 建立統一 log 層：封裝 developer.log 為 AppLogger，統一 name、level、格式。開發期用 developer.log，後續可切換到 HTTP log endpoint。
3. 自架 log endpoint 方案：本機 Go server 開一個 /log POST endpoint，接收 JSON log，寫入檔案。Client 端 AppLogger 在 debug mode 同時寫 console + POST 到 endpoint。開發期 grep 查詢，不需要 dashboard。
4. Protocol log 獨立一層：WebSocket frame type、payload 前綴、auth handshake 結果獨立記錄，跟 business log 分開。這層 log 在 release mode 應該能關閉。

下一步路由

• 想設計客戶端 log 方案 → 模組二：客戶端可觀測性
• 想理解三層 log 設計 → 三層 log 設計
• 想建自架 log endpoint → 自架 log endpoint vs 商業方案