工作筆記 | Tarragon

2026-06-30 late final 欄位不能用欄位覆蓋 — Dart 欄位的隱藏 getter/setter 機制 Dart 的 late final 欄位在底層會生成 getter 和 setter。子類用另一個欄位覆蓋時，會產生兩個獨立的儲存槽，父類程式碼讀到的是未初始化的那份，導致 LateInitializationError。Dart analyzer 要求改用 getter 覆寫。
2026-06-30 Widget 子類重新宣告 key — 遮蔽父類屬性與 duplicate key 風險在 StatelessWidget 子類中重新宣告 final Key? key，會遮蔽 Widget 繼承的 key 屬性，產生兩份儲存槽。若再把同一個 key 往下傳給 child widget，同一棵子樹出現重複 key，rebuild 時 Flutter 可能拋錯。
2026-06-25 工具的預設行為決定使用者習慣 — 從版本錯置看工具設計的 opinion 責任規範與工具預設不一致時工具會贏。預設路徑就是團隊的實際流程，接受自由輸入的介面設計時要負起 opinion 責任。
2026-06-25 改善類工作放進新功能版本 — 版本歸屬判斷的工具化根因分析、重構等改善工作被塞進功能版本、語意混亂。主張工具該依工作類型建議版本歸屬（semver 的 MINOR / PATCH 語意可被工具表達）。
2026-06-25 並行 AI Agent 修改同一檔案的衝突模式與協調策略並行派多個開發者或 AI agent 同一批 ticket，反覆修改同一個檔案、卡在 branch protection 與 file-modified-since-read。問題在派發策略沒考慮檔案層級的衝突。
2026-06-25 版本狀態殘留：為什麼已完成的版本在看板上顯示未完成看板顯示早已完成的版本仍為 active、誤導查看者。根因是發布工具只檢查當前版本完成度、不掃前版本的狀態殘留；工具的檢查範圍決定了系統的一致性邊界。
2026-06-25 新增欄位忘記同步 reset — 跨測試狀態洩漏的系統性根因測試結果取決於執行順序、看似功能 bug 實為上一個 test case 狀態沒清乾淨。根因是新增 private 欄位時沒同步更新 reset，隱含契約沒被顯性化。
2026-06-23 10 個 Ticket、57 個綠燈、0 條追溯：從需求文件到測試的銜接檢討單元測試全綠、卻答不出「這些測試覆蓋了哪些 UseCase 場景」。需求到測試缺反向追溯時的流程缺口盤點與對應修法（追溯矩陣、存根策略、拆分規則）。
2026-06-19 192 個測試全過、實機全壞：Mock 遮蔽真實行為的三層測試策略 unit test 全綠、實機部署後功能整片壞掉。mock-only 策略的結構盲區（text vs binary frame、缺 auth handshake、ANSI 多樣性被 FakeWebSocketChannel 遮蔽），以及分層測試各抓什麼、各遮蔽什麼。
2026-06-19 每個畫面都需要出口：畫面狀態機設計與 UX 導航的系統性方法實機測到某畫面沒有返回或退出按鈕、使用者被困住。根因是企劃沒系統列出每個畫面的狀態與可用操作；用畫面狀態矩陣確保每個狀態都有明確出口。
2026-06-05 Git：git stash 的 -u 參數（連未追蹤檔案一起暫存） `git stash` 後新建的檔案沒被收走、還散在工作目錄。原因是 stash 預設不收 untracked 檔案，附 -u 用法與 commit-rebase 替代做法。
2026-06-01 為什麼這個場景適合用高階函式？以 Flutter 設定更新為例，比較 typedef 改寫前後高階函式的適用判準（流程固定、變化點單一且開放）與裸函式型別 vs typedef 的可讀性取捨並排比較。
2026-05-28 CI step silent hang：時間真空才是訊號、happy log 反而是 anti-signal CI step 跑很久才 timeout、最後一行卻是「下載 100% / build succeeded」這種 happy log 時回來。判讀：別急著加 timeout，先算最後一行到 cancel 的時間真空、確認是 silent hang，再用症狀詞查 upstream issue。同方向修法連 fail 2 次就是停手回資料層的訊號。
2026-05-26 寫測試時 sync try-catch 接不到 BotToast 的 async 錯誤：fire-and-forget API 的接管設計測試裡 sync try-catch 接不到錯誤，或 fire-and-forget API 從 async gap 後拋 `LateInitializationError`。用 runZonedGuarded 同時罩 sync 與 async 失敗路徑，含 fallback 訊息 signature 設計。
2026-05-19 flutter devices 卡住的訊號：device 數從 N 變 N-1 與 emulator 半活 `flutter devices` / `flutter run` 卡住又印 `Error -2 retrieving device properties` 時回來看。根因是 Android emulator 半活狀態，附恢復順序。
2026-05-18 API 認證的三層信任邊界：使用者、系統、跨系統 Provisioning API 認證的信任邊界分層（Bearer Token / Shared Secret / Provisioning）：各層的洩漏後果與撤銷方式，以及混用造成的設計失效模式。
2026-05-18 Laravel Sanctum 的 Bearer Token 設計剖析：{PK}|{secret} 為什麼這樣設計 Laravel Sanctum `{PK}|{secret}` 格式的設計理由、hash 儲存取捨、constant-time 比對位置，以及跟 GitHub PAT、Stripe API Key 的差異。
2026-05-18 mTLS 實際怎麼設定與運維：CA 階層、憑證生命週期、撤銷機制 mTLS 落地的運維決策（CA 階層、憑證儲存、撤銷機制）與基礎設施整合（nginx / envoy / service mesh），以及跟 API Key / OAuth 的成本與安全取捨。
2026-05-18 Shared Secret 安全輪替設計：雙密過渡期、自動化與緊急流程系統間 Shared Secret 輪替的核心機制：dual-secret rollover、自動化工具比較（AWS Secrets Manager / Vault / GCP）、緊急 rotation 流程與多 client 環境的失敗模式。
2026-05-11 Freezed 的三層結構解剖：with、_$、以及更好懂的替代路徑 freezed `class X with _$X implements Y` 的分層結構解剖：`with` 與 `_$` 各自的角色、沒有 freezed 怎麼手做、中間投影物件 vs DTO 直接 implements 的維護取捨。
2026-05-07 Dart test 的跨檔案 GetX 狀態污染：flaky 真因不是 fail 訊息上的那個 test `flutter test` 整套跑隨機 fail、單獨跑該 file 卻 100% 過。根因是 dart test runner 同 process 內 GetX state 跨 file 污染，fail 位置看 `+N -1` 累計而非訊息標示的 test。
2026-05-05 Dart StreamController：single-subscription vs broadcast 的設計選型問題 Dart `Bad state: Stream has already been listened to.` 的根因：預設單訂閱在第二個訂閱者出現時才爆。StreamController vs .broadcast() 修復決策、與 Rx / .obs 的比較。
2026-04-28 Git：把後面 commit 的部分檔案變更搬到前面的 commit 把某個 commit 裡部分檔案變更抽出來併進前面的 commit、保持其他檔案原狀的操作方式。
2026-04-17 Gradle Configuration 時序陷阱：afterEvaluate、evaluationDependsOn、finalized properties Gradle 報 `Cannot run Project.afterEvaluate ... already evaluated` 或 `property is final`。時序錯誤同源於 callback 註冊太晚或屬性賦值太晚，附各 API 的正確時機。
2026-04-17 Gradle JVM target 除錯復盤：七個節點的策略權衡 Gradle JVM target 不一致的除錯決策復盤，重點在每步的策略權衡與走過的彎路。
2026-04-17 Gradle 強制覆寫 plugin 的 JVM target：Kotlin 與 Java 的切入點不對稱 Kotlin / AGP 升級後 build 報 `Inconsistent JVM-target compatibility`。為何要強制覆寫 plugin 的 JVM target，以及 Kotlin 與 Java 設定切入點的不對稱。
2026-04-17 為什麼 Bug 在合併後才爆：Gradle Cache 掩蓋潛伏問題的邏輯 feature branch build 正常、合併到 main 後才爆、但合併前 main 也沒錯。根因早已潛伏，Gradle cache 掩蓋、合併只是觸發條件。
2026-04-07 Flutter HitTestBehavior：控制點擊命中測試的三種模式 GestureDetector 點空白 padding 區沒反應、或點擊穿透/阻擋行為不符預期。HitTestBehavior 各模式（deferToChild / opaque / translucent）的命中規則與適用場景。
2026-03-26 Freezed 選型評估 Dart 專案是否引入 freezed 的選型評估：原型階段選 json_serializable + Equatable 取代 freezed 的理由與優缺點對照。
2026-03-05 SSH Key 設定筆記（macOS / Linux / Windows） macOS / Linux / Windows 的 SSH key 設定操作筆記（Ed25519 金鑰產生、ssh-agent、佈到遠端主機）。
2026-02-24 Git：修復後面的 commit 意外覆蓋前面 commit 的變更用 `git commit --fixup` + `git rebase --autosquash` 改歷史 commit 後，改的內容被後面的 commit 覆蓋、變更沒生效的處理。
2026-01-20 Git Filter-Repo 使用說明從 Git 歷史徹底移除檔案或資料夾（誤提交機密、清大檔）的 git filter-repo 操作筆記。
2025-09-09 flutter 可以使用的 togglebutton 樣式 Flutter 切換選項按鈕的元件選型。並列 ToggleButtons 等可用樣式的外觀截圖與程式碼。