docs(app): 回填第二輪 debug——協尋鏈路、admin REST、模擬器 UI 實機閉環

README.md

@@ -197,13 +197,15 @@ FCM data 的值一律是字串，App 端 `fleetEventFromPushData()` 會把座標
   至此三端齊備：**乘客評 → 司機看得到自己的平均分 → 營運看得出誰評價低**。
   詳見 [`docs/TODO.md`](docs/TODO.md)「⭐ 乘客評分司機」。
 
-**目前**：`flutter analyze` 無 issue、`flutter test` **227 passed**（2026-07-28）。
+**目前**：`flutter analyze` 無 issue、`flutter test` **230 passed**（2026-07-28）。
 
 **2026-07-28 修掉的 4 個 bug**（每個都先寫測試看它 FAIL 才修，詳見
 [`docs/TODO.md`](docs/TODO.md)「🐞 2026-07-28 debug」）：司機端 8 秒一次的定位探針會把
 **業務錯誤**（如完成行程被 409 擋下）一起洗掉；乘客端 15 秒一次的背景輪詢失敗會不停彈
 SnackBar；FCM token 輪替失敗會冒出司機看不懂也無事可做的紅色橫幅；
-**司機放棄訂單時 App 乘客收不到任何事件**（後端只推 LINE，跨端對帳抓到）。
+**司機放棄訂單時 App 乘客收不到任何事件**（後端只推 LINE，跨端對帳抓到）；
+**production 首頁沒有遺失物協尋入口**（banner 只寫在非 production 的卡片版首頁，乘客付不了處理費就拿不回東西）。
+三個「畫面沒人讀」類的修正已於同日在 `m6_pixel` 模擬器上**逐一實機閉環驗證**。
 
 ## 規劃中（尚未實作）
 

docs/TODO.md

@@ -618,7 +618,52 @@ admin 的全域 query 錯誤處理有去重 key 且整個 repo 沒有 `refetchIn
 **下次要重跑對帳**：dev DB 是空的，腳本要重建帳號（司機還要走 O5 審核才能接單）。
 腳本邏輯：註冊司機／乘客 → admin 核准車輛 → 上線＋回報位置 → 雙方連 `ws://…/ws?token=`
 → 叫車 → 接單 → 上車 → 完成 → 評分，全程把 REST 與 WS 的原始 payload 印出來比對。
-**沒覆蓋到的**：遺失物協尋鏈路、admin 端的 REST 形狀（只驗過司機／乘客兩端）。
+**沒覆蓋到的**：~~遺失物協尋鏈路、admin 端的 REST 形狀~~ → **兩者都已於同日補完**（見下兩段）。
+
+---
+
+## 🔎 2026-07-28 第二輪 debug：協尋鏈路、admin REST、模擬器 UI
+
+### 遺失物協尋鏈路（app PR #55）
+
+**抓到 1 個 bug**：**production 首頁（地圖版）完全沒有協尋入口**——持久性 banner 只寫在
+卡片版首頁裡，換版時掉了。唯一剩下的入口是完成卡，而它按「再叫一輛」或重開 App 就消失。
+後果：乘客建了協尋單、司機標記「已尋獲」後，**必須付處理費才能拿回東西，卻沒有畫面進得去付**。
+2026-07-15 的 E2E 之所以「驗過」，是因為當時本機無 Maps key 走的是**卡片版**。
+修法：抽成共用 `LostItemBanner` 兩版共用（根因是各抄一份），掛在 sheet 最上方且不受行程狀態影響。
+
+**其餘驗過乾淨**：`open→found→paid→returned` 四段狀態機、雙方 WS 事件、5 個狀態常數兩端一致、
+「未結案」集合兩端一致（open/found/paid）、終態後雙方清單自動清空、司機角標由清單長度推導、
+守門回應（404／409／403）皆有中文訊息。
+處理費 2100 分一度看似算錯（20600×10%＝2060），查證是 `roundNtd` 把 NT$20.6 進位成
+**NT$21**，符合整數台幣政策——**不是 bug**。
+
+### admin 端 REST 形狀（admin PR #28）
+
+**沒有 active bug**。揪出一個**型別謊言**：`PATCH /admin/drivers/:id/status` 實際回混合大小寫
+且不含評價欄，前端卻宣告回 `Driver` 又不正規化——車輛三欄與評價都是 `undefined`。
+目前呼叫端只 `invalidateQueries` 不看回傳值所以沒出事，但哪天有人拿去 `setQueryData`
+就會讓那一列的車種車牌憑空消失。已改走 `normalizeDriver`，測試 mock 換成真後端形狀。
+
+**驗過乾淨**：訂單列表 8 鍵、**六個篩選參數實跑證明真的有篩**（負向對照 `status=9`→0、
+不存在關鍵字→0、未來日期→0）、分頁 `total` 正確、訂單詳情
+`events`／`ride`／`track_geojson`／`stops`／`rating`（特地造一筆評過分的訂單才驗到）、
+日／月報表欄位、遺失物 13 鍵、會費帳單 7 鍵（`period` 鍵名正確）。
+
+### 模擬器 UI 實跑（`m6_pixel` ＋ customer flavor ＋ docker）
+
+**這一輪沒有新 bug**，但把當天三個「靠讀程式碼修」的修正在**真 App 上閉環**：
+
+| 修正 | 真機驗證結果 |
+|---|---|
+| 協尋入口（PR #55） | 地圖版首頁**即時**（未重啟，靠 WS）長出「遺失物協尋：藍色雨傘／司機已尋獲，待支付處理費」；點進去→付款 NT$21→狀態轉「已付款，等待歸還」→司機歸還後 banner 消失 |
+| 司機放棄通知（PR #52／#53） | 司機卡片（車牌／撥號）**被清掉**並顯示「司機取消了行程，正在為您重新派車」＋回到配對中 |
+| 背景輪詢靜默（PR #52） | 停掉後端 40 秒（跨 2 個輪詢週期）**零 SnackBar**；同一斷線下按「取消叫車」**仍跳出**「無法連線到伺服器，請檢查網路」 |
+
+**旁見（不是 bug，但下次做 UI 測試要知道）**：用 API 在 App 外建的訂單，**閒置中的 App 不會發現**——
+`_activeRide` 為 null 時不輪詢，且 `ride.accepted` 的處理有 `if (active == null) return` 早退。
+真實使用是 App 自己建單所以不受影響；跨管道（LINE 建單 ＋ App 開著）才會遇到，
+要測 UI 就得從 App 建單、或重啟 App 走 REST 還原。
 
 ---