Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,22 @@ FCM data 的值一律是字串,App 端 `fleetEventFromPushData()` 會把座標
至此三端齊備:**乘客評 → 司機看得到自己的平均分 → 營運看得出誰評價低**。
詳見 [`docs/TODO.md`](docs/TODO.md)「⭐ 乘客評分司機」。

**目前**:`flutter analyze` 無 issue、`flutter test` **230 passed**(2026-07-28)。
**目前**:`flutter analyze` 無 issue、`flutter test` **277 passed**(2026-07-29)。

**2026-07-29 這一批**(詳見 [`docs/TODO.md`](docs/TODO.md) 第四~六輪 debug +「🧾 PR 佇列稽核」):
- **回到前景會對帳**:背景期間 OS 凍結 timer、WS 可能被關掉,回前景時**立刻重連 WS**
並向後端重新確認進行中行程(司機端沒有輪詢,漏掉的事件沒有第二條路補回來)。
- **搶輸的單不再給假行程卡**:後端對「這單已被其他司機接走」回的是 **HTTP 200+文案**,
App 原本只看有沒有丟例外,於是沒搶到的司機會拿到一張完整但假的行程卡。
現在接單與放棄的成敗**一律以後端的 `rides/active` 為準**。
- **弱網(連得上但通不了)**:位置回報一次只放一筆在路上、hero 在「已不在派單池」時
誠實顯示紅底降級、接單/建單逾時後跟後端對帳。
- **WS 客戶端心跳**:半開連線(對端沒了但收不到 FIN)不會觸發 onDone/onError,
重連鏈根本不會啟動——`pingInterval` 是唯一偵測得到的手段。
- **建單 409 不再是死路**:後端說「已有進行中的訂單」而畫面上一張都沒有時,
改為向後端接手那張單。
- **司機端跨裝置的停靠點同步**:`ride.stop_updated` 原本只推給乘客(後端 dispatch#53 已補),
司機端也不處理——兩台裝置會停在不同的「下一站」。

**2026-07-28 修掉的 4 個 bug**(每個都先寫測試看它 FAIL 才修,詳見
[`docs/TODO.md`](docs/TODO.md)「🐞 2026-07-28 debug」):司機端 8 秒一次的定位探針會把
Expand All @@ -217,6 +232,9 @@ SnackBar;FCM token 輪替失敗會冒出司機看不懂也無事可做的紅
- **維護項已於 2026-07-28 全數清空**(清殘留 worktree/舊分支、清 dev DB 測試殘留);
只剩「評分的營運動作」等營運說得出要對低分司機做什麼再開。
**剩下的每一項都需要使用者先提供外部資源或拍板**——沒有前置條件時不要硬找事做。
- **開工前先看 PR 佇列**(`gh pr list`):2026-07-29 盤點時三個 repo 共有 8 支未合併的
open PR,其中兩支是**同一個功能的兩份獨立實作**——平行 worktree 的 session 看不見彼此,
題目又都取自 TODO 的同一份清單。已合併/去重的經過見 TODO「🧾 PR 佇列稽核」。

## 相關文件

Expand Down
75 changes: 75 additions & 0 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -910,6 +910,66 @@ admin 的全域 query 錯誤處理有去重 key 且整個 repo 沒有 `refetchIn

---

## 🧾 2026-07-29 PR 佇列稽核:兩條 stack 做了同一件事(本批清掉)

> 這一輪的起點不是程式碼,是**盤點三個 repo 的實際狀態**:
> app **6 支 open PR(#59–#64)**、dispatch **2 支(#53/#54)**、admin **0 支**。
> 全部 CI 綠(#59 為 BLOCKED)。也就是說,「還有什麼可以補強」的答案當下不是再寫新功能,
> **是這些做完的東西沒有進 main**。

### 查出來的問題:兩條平行 stack 撞在一起

| stack | PR | 內容 |
|---|---|---|
| A | #59 → #60 → #61 | 回前景對帳/接單建單對帳/司機多裝置 |
| B | #62 → #63 → #64 | 回前景對帳/搶單假行程卡/弱網 |

**#59 與 #62 是同一個功能的兩份獨立實作**——連新檔名都一樣
(`lib/shared/widgets/app_lifecycle_reactor.dart`),由兩個平行 worktree 的 session
在兩小時內各做了一次;往上疊的 #60/#61 與 #63/#64 也大量重疊(接單結果對帳、
`ride.accepted` 的多裝置處理)。兩條都合會直接衝突。

**決策**:保留較新且較完整的 B 條(#62→#63→#64 全數合併),
關閉 A 條,但**先把 A 條獨有的三項救回來**(本 PR)——這正是
[清開發殘留](#-清開發殘留-worktree舊分支維護項-52026-07-28-完成) 那次學到的:
「看起來被取代」不等於「內容都在」,要逐條比對 diff。

### A 條獨有、已救回的三項

| 救自 | 修正 | 為什麼 B 條沒有 |
|---|---|---|
| #59 | **WS 客戶端心跳**(`pingInterval` 20 秒) | B 條只做了「回前景立刻重連」,但半開連線(對端沒了、本地收不到 FIN)**不會 onDone/onError**,重連鏈根本不會啟動;後端只做了另一半(54 秒 ping、60 秒沒 pong 砍連線),保護的是伺服器不留死連線 |
| #60 | **建單 409 也去對帳** + 接手時共用建單成功的狀態切換 | B 條的 #64 只對帳連線類(`statusCode == null`),409 只顯示訊息;但 409 正是「後端說你有單、你的畫面沒有」,再按一次還是 409,出路只剩重開 App。接手時原本也只做 `_applyActiveRide`,編輯中的多乘客清單/預估會留到下一趟 |
| #61 | **司機端處理 `ride.stop_updated`** | B 條的 #63 收掉了 `ride.accepted` 的多裝置缺口,但停靠點沒有;兩台裝置會停在不同的「下一站」,而那是司機端唯一給操作鈕的一站。後端側同批合併 dispatch#53(該事件原本只推給乘客) |

**驗收**:`flutter analyze` 無 issue、`flutter test` **277 passed**(268 +新 9)。
新增 `driver_stop_updated_test.dart`(3)、`customer_create_conflict_test.dart`(4)、
`fleet_ws_client_test.dart` 兩案(心跳)。**反向確認**:拿掉 `ride.stop_updated`
處理後 1 案 FAIL、拿掉 409 分支後 2 案 FAIL;心跳那案先斷言預設 `pingInterval` 為 null
再斷言設定後的值,避免寫出恆真的斷言。
**未做**:這三項都**沒有模擬器實跑**(半開連線要斷網卡層級的手法才造得出來,
409 與跨裝置停靠點需要兩台裝置+後端),只有單元測試與反向確認。

### 兩個 GitHub 操作坑(下次做 stacked PR 一定會再踩)

1. **`--delete-branch` 會連帶關閉以該分支為 base 的 PR**。合併 #62 並刪分支的當下,
#63/#64 立刻被 GitHub 關掉,而且**重開會被拒**(`Cannot reopen`/
`Cannot change the base branch of a closed pull request`)——只能 rebase 後另開新 PR
(#63 → **#65**)。之後改用「**合併時不刪分支** → 把下一支 rebase 到 main →
`gh pr edit --base main` → 再刪舊分支」,#64 的編號就保住了。
2. **CI 不會跑,因為 workflow 的 `pull_request: branches: [main]` 是 base 過濾器**。
stacked PR 的 base 不是 main 時,push 不觸發 CI;把 base 改成 main 也不補觸發
(`edited` 不在預設 types 裡)。要 `gh pr close` 再 `gh pr reopen` 才會跑。

### 順手做的整理

- dispatch:#53(`ride.stop_updated` 也推給司機)、#54(結構化 JSON log + request_id)已合併,
遠端分支清空(只剩 main)。
- app 遠端殘留分支 `claude/todo-task-execution-pr-3978a3` 經比對 **tip 等於 PR #58 合併時的
`headRefOid`**(沒有未合併內容),可安全刪除。

---

## 下次任務

> **✅ 維護項 5「清開發殘留」已完成(2026-07-28)**,詳見上方。
Expand Down Expand Up @@ -967,6 +1027,21 @@ admin 的全域 query 錯誤處理有去重 key 且整個 repo 沒有 `refetchIn
> **➡️ 三個角落都清完了。** 再往下的 debug 題目要重新盤點;不需外部資源的方向可考慮:
> 多停靠點行程在弱網/背景切換下的狀態一致性、以及乘客端在 App 被系統殺掉後的還原路徑
> (目前只驗過冷啟動還原,沒驗過「被系統殺掉又從推播喚醒」)。
>
> ---
>
> **🎯 2026-07-29 收尾(PR 佇列稽核那一批,見上方專段)——下一次開工先做這三件**:
>
> 1. **開工第一件事是 `gh pr list`,不是 `git log`**。這一輪盤點發現三個 repo 有
> **8 支 open PR**,其中兩支是同一個功能的獨立實作——**平行 worktree 的 session
> 彼此看不見對方**,題目又都取自本檔的「下一輪 debug 角落」清單,撞題是必然的。
> 要嘛開工前先看 PR 佇列,要嘛在本檔把認領的題目**當場劃掉**。
> 2. **本批救回的三項只有單元測試,沒有模擬器實跑**:WS 心跳(半開連線)、
> 建單 409 接手、司機端跨裝置 `ride.stop_updated`。
> 有機會起兩台裝置+docker 時,這三條值得各跑一次真機閉環。
> 3. **stacked PR 的兩個 GitHub 坑**(`--delete-branch` 連帶關閉、
> `pull_request: branches: [main]` 的 base 過濾器擋掉 CI)已寫在上方專段,
> 下次再疊 PR 前先看那兩條。

> **🎨 App icon(叫車系統圖示)✅ 已完成(2026-07-15,PR #15)**:品牌綠 LINE green #06C755 + 白色計程車,
> 以 `flutter_launcher_icons` 產生 Android(含 adaptive icon)與 iOS 各尺寸,driver/customer 兩 flavor 共用。
Expand Down
31 changes: 30 additions & 1 deletion lib/core/ws/fleet_ws_client.dart
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
import 'dart:async';
import 'dart:convert';
import 'dart:io' show WebSocket;

import 'package:flutter/foundation.dart';
import 'package:web_socket_channel/io.dart';
import 'package:web_socket_channel/web_socket_channel.dart';

import '../config/app_config.dart';
Expand Down Expand Up @@ -42,7 +44,34 @@ class FleetWsClient {
required this.onEvent,
this.onConnectionChanged,
@visibleForTesting WebSocketChannel Function(Uri uri)? connector,
}) : _connector = connector ?? WebSocketChannel.connect;
}) : _connector = connector ?? defaultConnector;

/// 正式連線方式:dart:io 的 WebSocket + 客戶端心跳(見 [enableKeepAlive])。
///
/// 只出貨 Android/iOS(CI 亦只 build 這兩個),故直接用 dart:io;
/// 日後若要支援 web,這裡得改成條件匯入。
@visibleForTesting
static WebSocketChannel defaultConnector(Uri uri) => IOWebSocketChannel(
WebSocket.connect(uri.toString()).then(enableKeepAlive),
);

/// 開啟客戶端心跳:**沒有它就偵測不到半開連線**。
///
/// 手機換網路、離開 NAT/負載平衡器的閒置逾時、後端整台消失時,本地 socket 可能
/// 收不到 FIN——串流不會 `onDone`、也不會 `onError`,於是 `isConnected` 仍是 true、
/// UI 照樣顯示「即時連線正常」,而重連鏈只由 onDone/onError 觸發,**永遠不會啟動**。
/// 司機因此靜靜地收不到派單,正是這個 client 一路修掉的「畫面說謊」家族。
///
/// 後端只做了另一半(`writePump` 每 54 秒 ping、60 秒收不到 pong 就砍連線),
/// 那保護的是**伺服器**不留死連線;客戶端要自己發 ping 才知道對面還在。
/// dart:io 的 `pingInterval` 在一個間隔內收不到 pong 就關閉連線 → 走既有重連鏈。
@visibleForTesting
static WebSocket enableKeepAlive(WebSocket socket) =>
socket..pingInterval = pingInterval;

/// 心跳間隔:也是「半開之後多久才會發現自己收不到派單」的上限。
/// 取 20 秒對齊後端的派單 offer 逾時(同一個數量級),比它久就等於整輪派單白白錯過。
static const pingInterval = Duration(seconds: 20);

final FleetEventHandler onEvent;
final void Function(bool connected)? onConnectionChanged;
Expand Down
73 changes: 46 additions & 27 deletions lib/customer/customer_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -856,29 +856,7 @@ class CustomerController extends ChangeNotifier {
// P2:null =不指定,client 端不會帶這個鍵。
requiredVehicleType: _requiredVehicleType?.code,
);
_activeRide = ride;
_lastActiveRide = ride;
// 這趟已送出,編輯狀態不該留到下一趟。
_passengers.clear();
// 預估屬於「建單前」的輔助資訊,送出後就該收掉,不留到下一趟。
_estimate = null;
_estimating = false;
_estDropoffLat = null;
_estDropoffLng = null;
_driverName = null;
_driverInfo = null;
// 新的一趟開始 → 上一趟的取消原因不該還掛著。
_cancelReason = null;
_cancelledVehicleType = null;
_rideCancelled = false;
_liveEtaSec = null;
_liveDistM = null;
_liveDriverLat = null;
_liveDriverLng = null;
_driverArrived = false;
_completedSummary = null;
_error = null;
_startPolling();
_applyCreatedRide(ride);
} on ApiException catch (e) {
await _handleCreateFailure(e);
} finally {
Expand All @@ -903,25 +881,66 @@ class CustomerController extends ChangeNotifier {

Future<void> _handleCreateFailure(ApiException e) async {
_error = e.message;
if (e.statusCode == null) await _adoptRideIfCreated();
// **409 也要對帳**:那句話是後端在明說「你已經有一張進行中的訂單」,
// 而畫面上一張都沒有——多半就是上一次逾時其實建成了(或訂單來自 LINE/另一台裝置)。
// 只把這句話原樣丟給乘客,他無事可做:再按一次還是 409,唯一出路是重開 App。
if (e.statusCode == null || e.statusCode == 409) {
await _adoptRideIfCreated();
}
}

/// 建單請求逾時後,向後端確認訂單到底有沒有成立。
/// 建單失敗後向後端確認訂單到底有沒有成立。
///
/// 有 → 套用它(畫面直接進入追蹤)並清掉那句逾時錯誤(他其實叫到車了)。
/// 沒有 → 什麼都不動,逾時訊息留著讓他重試。
/// 有 → 套用它(畫面直接進入追蹤)並清掉那句錯誤(他其實叫到車了)。
/// 沒有 → 什麼都不動,錯誤訊息留著讓他重試。
/// 查詢本身也失敗 → 同樣什麼都不動(不知道就不亂改)。
Future<void> _adoptRideIfCreated() async {
try {
final ride = await _api.activeRide();
if (ride == null || RideStatus.isTerminal(ride.status)) return;
// 這趟其實成立了 → 走**與建單成功同一套**狀態切換。
// 只做 `_applyActiveRide` 是不夠的:編輯中的多乘客清單、預估車資、
// 上一趟的取消通知都會留著,下一次叫車就帶著別趟的殘骸。
_applyCreatedRide(ride);
// 這段空窗可能已經被司機接走了:把司機姓名/車牌/電話補回來,
// 不必等下一個輪詢週期才顯示。
_applyActiveRide(ride);
_error = null;
} on ApiException {
// 弱網下這一問也可能逾時;維持原本的錯誤訊息。
}
}

/// 一趟新訂單成立後的狀態切換(建單成功與「其實已經建好了」共用)。
///
/// 兩條路徑必須共用同一份清單:漏掉其中一項,就會把上一趟的司機、取消通知或
/// 完成卡帶進這一趟。
void _applyCreatedRide(CustomerRide ride) {
_activeRide = ride;
_lastActiveRide = ride;
// 這趟已送出,編輯狀態不該留到下一趟。
_passengers.clear();
// 預估屬於「建單前」的輔助資訊,送出後就該收掉,不留到下一趟。
_estimate = null;
_estimating = false;
_estDropoffLat = null;
_estDropoffLng = null;
_driverName = null;
_driverInfo = null;
// 新的一趟開始 → 上一趟的取消原因不該還掛著。
_cancelReason = null;
_cancelledVehicleType = null;
_rideCancelled = false;
_liveEtaSec = null;
_liveDistM = null;
_liveDriverLat = null;
_liveDriverLng = null;
_driverArrived = false;
_completedSummary = null;
_error = null;
_startPolling();
}

/// [silent] = 這次刷新不是使用者按出來的(背景輪詢),失敗時**不寫全域 error**。
/// 15 秒一次的輪詢若把失敗丟給畫面層,後端一斷線就變成每 15 秒彈一次 SnackBar
/// 蓋住 sheet 上的按鈕,而使用者沒有任何辦法讓它停——他根本沒按過什麼。
Expand Down
12 changes: 12 additions & 0 deletions lib/driver/driver_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -885,6 +885,18 @@ class DriverController extends ChangeNotifier {
_activeRide = _activeRide!.copyWith(phase: DriverRidePhase.onTrip);
notifyListeners();
}
case FleetEventTypes.rideStopUpdated:
// 停靠點在**別處**被標記了(同一司機的另一台裝置、或 LINE 那條路徑)。
// 乘客端早就會收這則事件並更新進度,司機端先前完全不處理——兩台裝置會停在
// 不同的「下一站」,而「下一站」正是司機端唯一給操作按鈕的那一站,
// 於是兩台會對不同的乘客顯示「已上車/已下車/跳過」。
//
// 事件 payload 帶整趟 stops,但這裡仍以**後端重讀**為準:司機端行程卡還要
// 階段(phase)與車資等 payload 沒有的欄位,重讀一次最不容易對不齊。
// 失敗靜默——這不是使用者按出來的動作,跳錯誤橫幅只會干擾他開車。
if (event.rideId != null && _activeRide?.rideId == event.rideId) {
unawaited(_restoreActiveRide(silent: true));
}
case FleetEventTypes.rideCompleted:
case FleetEventTypes.rideCancelled:
if (event.rideId != null &&
Expand Down
Loading
Loading