Skip to content

fix(app): 回到前景時對帳,並讓 WS 偵測得到半開連線 - #59

Closed
thothawei wants to merge 1 commit into
mainfrom
claude/app-lifecycle-resume-sync
Closed

thothawei wants to merge 1 commit into
mainfrom
claude/app-lifecycle-resume-sync

Conversation

@thothawei

Copy link
Copy Markdown
Owner

⚠️ base 是 claude/todo-task-execution-pr-3978a3(PR #58),不是 main — 這樣 diff 只含本批內容。#58 合併後 GitHub 會自動把 base 改成 main。

這是什麼問題

App 兩端從來不知道自己被切到背景過(grep -rn "WidgetsBindingObserver\|didChangeAppLifecycleState" lib/ 零命中)。三個獨立缺口:

  1. 司機端沒有任何回前景對帳。司機端沒有輪詢,行程狀態 100% 靠 WS。背景期間只要斷過線(切網路、進隧道、後端重啟、系統凍結進程),ride.cancelled 就再也不會補送——後端不補發歷史事件。回前景後那張行程卡還掛在畫面上,司機會繼續開去接一個已經取消的乘客。
  2. WS 沒有心跳,偵測不到半開連線。對端已消失而本地 socket 收不到 FIN 時:isConnected 仍是 true、UI 顯示「即時連線正常」,卻永遠收不到派單,而且不會觸發重連(重連只由 onDone/onError 觸發,半開兩個都不會來)。
  3. 回前景還要陪等退避(長時間離線後是 30 秒上限),而使用者正盯著畫面等派單。

順帶抓到一個既有的說謊:_scheduleReconnect() 沒清掉 _channel,整個重連等待期間 isConnected 都回 true,與同時回報的 onConnectionChanged(false) 自相矛盾。舊碼沒出事是因為沒人讀它;ensureConnected() 一讀就會誤判「還連著」而什麼都不做。

改了什麼

  • AppLifecycleReactor:只對 resumed 動作——inactive/hidden 在拉下通知欄之類的過場也會出現,對它們反應會在使用者根本沒離開 App 時打一堆沒必要的請求。兩端 root 各包一層。
  • DriverController.onAppResumed():ensureConnected() + 以後端為準重讀 active + 協尋清單。
  • CustomerController.onAppResumed():ensureConnected() + refreshActive(silent: true)(不是使用者按出來的刷新,失敗不彈 SnackBar)。
  • FleetWsClient:預設連線帶 pingInterval 20 秒(IOWebSocketChannel)讓半開連線由底層偵測並關閉,走既有重連鏈;新增 ensureConnected();斷線時清掉 _channel 讓 isConnected 誠實。

驗收

  • flutter analyze 無 issue、flutter test 248 passed(240 +新 8)。新增 test/app_lifecycle_test.dart(reactor 2 案、司機端 2 案、乘客端 1 案、ensureConnected 3 案——後三案用真的本機 WebSocket 伺服器)。
  • 反向確認:三處修正各自拿掉後,對應的 3 案 FAIL。
  • 模擬器實跑閉環(m6_pixel driver flavor + docker compose):
    • 漏事件重現:接單(ride chore: gitignore 加入 .cursor/ #6)→ HOME 切背景 → docker stop app(進入退避)→ 等 45 秒 → docker start app 後在 App 重連之前用乘客 API 取消 → 回前景 → 行程卡消失。後端 log 交叉驗證:**回前景的同一秒(18:47:59)**收到 SELECT * FROM rides WHERE driver_id = 5 AND status IN (2,3)(=GET /driver/rides/active),這個請求在修正前根本不存在。
    • 回前景立刻重連:停後端 70 秒(退避達 30 秒上限)→ 起後端 → 不動 App,5 秒後仍是紅底「連線中斷,暫時收不到派單」 → 切背景再回前景 → 2 秒後恢復「即時連線正常」。

已知限制

心跳只在 App 前景真的有效(背景被系統凍結時 timer 不跑),那正是回前景對帳要補的洞,兩者互補。iOS 尚未在實機驗過(A5 階段 5 仍卡在實機部署)。

🤖 Generated with Claude Code

App 兩端從來不知道自己被切到背景過
(`grep WidgetsBindingObserver lib/` 零命中),造成三個缺口:

1. 司機端沒有輪詢,行程狀態 100% 靠 WS。背景期間只要斷過線,
   ride.cancelled 就再也不會補送(後端不補發歷史事件)——
   回前景後那張行程卡還掛著,司機會開去接一個已取消的乘客。
2. WS 沒有心跳,偵測不到半開連線:isConnected 仍是 true、
   UI 顯示「即時連線正常」,卻永遠收不到派單,也不會觸發重連。
3. 回前景還要陪等最多 30 秒的重連退避。

修法:AppLifecycleReactor(只對 resumed 動作)包住兩端 root;
司機端回前景以後端為準重讀 active,乘客端 silent 刷新一次;
WS 預設連線帶 pingInterval 20 秒,並新增 ensureConnected()
(已連上就不動,否則取消退避立刻重試)。

順帶修掉一個既有的說謊:_scheduleReconnect() 沒清掉 _channel,
整個重連等待期間 isConnected 都回 true,與同時回報的
onConnectionChanged(false) 自相矛盾——ensureConnected 一讀它就會誤判。

驗收:flutter analyze 無 issue、flutter test 248 passed(新增 8);
反向確認三處修正各自拿掉後對應的 3 案 FAIL。
模擬器實跑:接單後切背景 → 斷線期間用 API 取消 → 回前景行程卡消失,
後端 log 在回前景的同一秒收到 rides/active 查詢(修正前沒有這個請求);
退避已達 30 秒上限時,不動 App 仍顯示「連線中斷」,
切背景再回前景則 2 秒內恢復「即時連線正常」。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@thothawei
thothawei force-pushed the claude/app-lifecycle-resume-sync branch from 2e8ef64 to 6fc7382 Compare July 28, 2026 13:33
@thothawei
thothawei changed the base branch from claude/todo-task-execution-pr-3978a3 to main July 28, 2026 13:33
@thothawei

Copy link
Copy Markdown
Owner Author

以 #62 取代(同一個功能的兩份獨立實作——連新檔名 lib/shared/widgets/app_lifecycle_reactor.dart 都一樣,由兩個平行 worktree 的 session 在兩小時內各做了一次)。保留 #62 的理由:_opening 併發保護、_connected 單一真相旗標、以及 _leftForeground 讓 inactive→resumed(下拉通知列、權限對話框)不觸發對帳。

本 PR 獨有、已救回:WS 客戶端心跳(pingInterval)——半開連線不會 onDone/onError,回前景重連補不到它。已在 #66 落地並補上測試。

@thothawei thothawei closed this Jul 29, 2026
thothawei added a commit that referenced this pull request Jul 29, 2026
* fix(ws): 補上客戶端心跳,讓半開連線偵測得到(救回 PR #59 獨有的修正)

半開連線(對端沒了但本地收不到 FIN)不會觸發 onDone/onError,重連鏈永遠不啟動,
isConnected 仍是 true——司機靜靜地收不到派單。後端只做了另一半(54 秒 ping、
60 秒沒 pong 就砍連線),保護的是伺服器不留死連線。

改用 IOWebSocketChannel 並設 pingInterval=20 秒(對齊後端派單 offer 逾時的數量級),
收不到 pong 就關閉連線 → 走既有重連鏈。

測試:enableKeepAlive 在真 socket 上開啟 ping(先校準預設為 null,斷言非恆真)、
預設 connector 仍連得上且收得到事件。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(driver): 停靠點在別處被標記時,這台也要跟上(救回 PR #61 獨有的修正)

同一司機的第二台裝置或 LINE 那條路徑標記到達/跳過時,這台的司機端不處理
ride.stop_updated——兩台會停在不同的「下一站」,而那正是唯一給操作按鈕的一站。
乘客端早就會收這則事件。後端側已於 dispatch#53 補推給司機。

修法:同一張單就以後端重讀 active(payload 沒有 phase/車資等欄位,重讀最不易對不齊),
失敗靜默(不是使用者按出來的動作,橫幅只會在他開車時干擾)。

測試:新增 driver_stop_updated_test.dart 3 案;反向確認拿掉修正後第 1 案 FAIL。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(customer): 建單 409 也去跟後端對帳,並與建單成功共用狀態切換(救回 PR #60 獨有的修正)

409「已有進行中的訂單」是後端在明說有單,而乘客畫面上一張都沒有——多半是上一次
逾時其實建成了,或訂單來自 LINE/另一台裝置。只把這句話原樣顯示,乘客無路可走:
再按一次還是 409,唯一出路是重開 App。

同時把建單成功的狀態切換抽成 _applyCreatedRide 與「接手既有訂單」共用——
原本接手只做 _applyActiveRide,編輯中的多乘客清單、預估車資、上一趟的取消通知
都會留著帶進下一次叫車。

測試:新增 customer_create_conflict_test.dart 4 案;反向確認拿掉 409 分支後 2 案 FAIL。
全套 flutter analyze 無 issue、flutter test 277 passed。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(app): 回填 PR 佇列稽核——兩條 stack 撞題、去重與救回的三項

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
thothawei added a commit that referenced this pull request Jul 29, 2026
回前景會呼叫 ensureConnected();漏看 _disposed 的話,已登出的 client 會帶著舊 token
重新連上,上一個帳號的事件就繼續進來。main 的 app_lifecycle_test 有「斷線立刻重連」
與「已連上不重建」,唯獨缺這條。

誠實標記:這是 defense-in-depth 的行為斷言,不是釘住某一行——
ensureConnected 與 _open() 各有一道 _disposed 守門,單獨拿掉任一道測試都仍 PASS,
兩道同時拿掉才 FAIL(connector 被呼叫 2 次)。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
thothawei added a commit that referenced this pull request Jul 29, 2026
* test(customer): 救回接手既有訂單的三個邊界(來自被取代的 PR #60)

關掉重複 PR 前逐檔比對,發現 #60 的 customer_place_order_timeout_test 裡有三條
main 完全沒有的斷言:接手時要一併帶出司機資訊(否則乘客會先看到一段假的「配對中」,
司機可能已經在門口)、對帳本身失敗時要維持原錯誤、後端回終態訂單時不算數
(把已完成的上一趟接手過來,乘客會盯著一張永遠不會動的行程)。

反向確認:拿掉 _applyActiveRide 與 isTerminal 判斷後,這三案中有 2 案 FAIL
(第三案「對帳失敗」由既有 catch 覆蓋,仍保留以釘住行為)。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(ws): 救回「登出後回前景不可偷偷連回去」(來自被取代的 PR #59)

回前景會呼叫 ensureConnected();漏看 _disposed 的話,已登出的 client 會帶著舊 token
重新連上,上一個帳號的事件就繼續進來。main 的 app_lifecycle_test 有「斷線立刻重連」
與「已連上不重建」,唯獨缺這條。

誠實標記:這是 defense-in-depth 的行為斷言,不是釘住某一行——
ensureConnected 與 _open() 各有一道 _disposed 守門,單獨拿掉任一道測試都仍 PASS,
兩道同時拿掉才 FAIL(connector 被呼叫 2 次)。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
@thothawei
thothawei deleted the claude/app-lifecycle-resume-sync branch July 29, 2026 06:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant