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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,8 +219,8 @@ REST 一定完整,而推播要傳達的資訊只有「有事發生了」。
至此三端齊備:**乘客評 → 司機看得到自己的平均分 → 營運看得出誰評價低**。
詳見 [`docs/TODO.md`](docs/TODO.md)「⭐ 乘客評分司機」。

**目前**:`flutter analyze` 無 issue、`flutter test` **440 passed**(56 個測試檔,2026-08-01 實跑)。
~~434 passed~~/~~425 passed~~/~~414 passed~~/~~383 passed~~/~~377 passed~~/~~361 passed~~/~~356 passed~~/~~351 passed~~/~~339 passed~~ 是漏更新的舊數字——**這一行請跟著最後一次實跑一起改**。
**目前**:`flutter analyze` 無 issue、`flutter test` **444 passed**(57 個測試檔,2026-08-01 實跑)。
~~440 passed~~/~~434 passed~~/~~425 passed~~/~~414 passed~~/~~383 passed~~/~~377 passed~~/~~361 passed~~/~~356 passed~~/~~351 passed~~/~~339 passed~~ 是漏更新的舊數字——**這一行請跟著最後一次實跑一起改**。

**2026-07-30 弱網逾時對帳的實跑收尾**(詳見 [`docs/TODO.md`](docs/TODO.md) 第十四~十五輪):
先做了一支「請求照送、回應吃掉」的代理 [`tool/lossy_proxy.py`](tool/lossy_proxy.py)——
Expand Down
95 changes: 91 additions & 4 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@
- [🔁 第二十五輪:分頁尾巴會卡死在轉圈(回頭 debug 第二十四輪自己)](#-2026-08-01-第二十五輪分頁的尾巴會卡死在轉圈回頭-debug-第二十四輪自己本批修掉-2-個)
- [🔤 第二十六輪:App 的字數上限與後端數的不是同一種單位](#-2026-08-01-第二十六輪app-的字數上限與後端數的不是同一種單位本批修掉-6-個欄位)
- [🚦 第二十七輪:後端比 App 新時,進行中的訂單會從畫面上消失](#-2026-08-01-第二十七輪後端比-app-新時進行中的訂單會從畫面上消失本批修掉-1-個補完上輪缺口)
- [📱 第二十八輪:同一帳號的第二台裝置永遠不知道有進行中的行程](#-2026-08-01-第二十八輪同一帳號的第二台裝置永遠不知道有進行中的行程本批修掉-1-個)

**四、維護、決策與待辦**
- [🧹 清開發殘留 worktree/舊分支(維護項 5)](#-清開發殘留-worktree舊分支維護項-52026-07-28-完成)
Expand All @@ -95,7 +96,7 @@
- **UI/UX 翻新(2026-07-10)**:LINE 綠亮暗雙主題;司機駕駛情境 UI;乘客地圖為底+卡片降級。靜態驗收 49 tests 通過;模擬器主鏈路待後端 docker 可起後補跑。
**登入/註冊頁 2026-07-23 補齊翻新**(先前是唯一漏網畫面),詳見下方「🔐 登入頁 UI/UX 翻新+驗證」。
- **座標導航(2026-07-10)**:司機端目的地導航改吃後端 `dropoff_point` 座標,地址僅供顯示與退路。
- 單元測試:**56 個測試檔、`flutter test` 440 passed**(2026-08-01 第二十七輪後實測;
- 單元測試:**57 個測試檔、`flutter test` 444 passed**(2026-08-01 第二十八輪後實測;
`flutter analyze` 無 issue、`flutter build apk --debug --flavor customer` 成功)。
~~(54 項)~~ 是 2026-07-10 的數字,長期沒更新,已更正——**本節的數字請跟著最後盤點日一起改**。
- 遠端:`github.com/thothawei/fleet-app`。**2026-07-29 實查**:`git ls-remote --heads origin` 只有 `main`、
Expand Down Expand Up @@ -2590,14 +2591,100 @@ TextField(maxLength: 5) 擋完後 → characters=5 runes=35

### 同族還沒碰的角落

- **司機端也有一個 `default:`**(接單/行程卡的階段判斷)——本輪只掃乘客端。
**條件**:下次動到司機端行程卡時順手看一次。
- ~~**司機端也有一個 `default:`**(接單/行程卡的階段判斷)~~
✅ **第二十八輪查完了,是乾淨的**,理由見下一段。

---

## 📱 2026-08-01 第二十八輪:同一帳號的第二台裝置永遠不知道有進行中的行程(本批修掉 1 個)

> 先把上一輪留的尾巴收掉,再開新族。

### 先收尾:司機端的 `default:` 是乾淨的(理由不是「App 有防禦」)

司機端 `ActiveRide.fromBackendJson` 的 `phase` 是
`status == pickedUp ? onTrip : enRouteToPickup`——看起來跟乘客端一樣有「未知碼落到某個分支」的風險。
**但後端擋在前面**:`FindActiveByDriver` 的 SQL 是
`status IN (accepted, pickedUp)` 的**白名單**,所以司機端的 `GET /driver/rides/active`
只可能回這兩種狀態。這是**後端契約保證**,不是 App 的防禦——
所以要記住:**哪天後端把新狀態加進那個白名單,這裡就要跟著改**。

WS 那條的 `default: break;` 是忽略未知事件型別,這是對的(事件型別本來就會增加)。

### 本輪的族:多裝置同一帳號

**根因一句話**:`_handleWsEvent` 對「不認得的行程事件」是
`if (active == null || event.rideId != active.rideId) return;`——直接丟掉;
而輪詢在「沒有進行中訂單」時是**停著的**(`_applyActiveRide` 會 `_stopPolling`)。
兩件事湊起來,第二台裝置就**永遠**不會知道有一趟車正在跑。

**這是現在就會踩到的**,不需要後端改任何東西:

1. 同一個乘客帳號登入兩台裝置(手機+平板,或舊手機還登著);
2. B 台開著、停在叫車表單;
3. A 台叫車、司機接單——後端的 WS Hub 依 `(角色, id)` 扇出,**B 台收得到** `ride.accepted`;
4. B 台把它丟掉 → 畫面永遠是叫車表單,按下去只會拿到「已有進行中訂單」。

**司機端早就處理過同一件事**(`DriverController` 的 `rideAccepted`:另一台裝置接走了這張單
→ 重讀 active,註解寫明已對真後端實測)。乘客端從來沒有做過。

### 修法與三條邊界

- 不認得的行程事件 → **去跟後端對一次帳**(`refreshActive(silent: true)`),對完就自己接回輪詢。
- **只在 `activeRide == null` 時對帳**。已經有一張單、事件卻是別的 rideId = 舊單的落隊事件
(乘客一次只有一張進行中訂單),照舊忽略——**這條是既有測試逼出來的**:
第一版沒收窄,`customer_cancel_notice_test` 的「別的行程的取消事件不觸發通知」立刻紅了。
- **`driver.location` 不觸發**:每幾秒一則的串流,會把一次對帳變成連續打點。
真正要跟上的是生命週期事件,而那些一定會跟著來。

### 驗收

- `flutter analyze` 無 issue、`flutter test` **444 passed**(440 +新 4)、57 個測試檔。
- **先紅再修**:新測試在修改前就是紅的(`activeCalls` 停在 1,事件被丟掉)。
- **反向驗證三個半邊各一次**:
- 拿掉對帳 → 主案 FAIL。
- 拿掉 `driver.location` 排除 → 「不觸發連續打點」那案 FAIL。
- 拿掉 `active == null` 收窄 → **本檔新案與既有的 `customer_cancel_notice_test` 各紅一案**。
- `flutter build apk --debug --flavor customer` 成功。

### 過程中修正的一個自己的錯誤假設

第一版測試斷言「認得的單不該多打 API」——**跑出來是紅的,而錯的是我不是程式**:
`rideAccepted` 本來就會 `refreshActive(silent: true)` 補齊完整資料。
已把那一案改成守「沒有把已知單的路徑改壞,尤其不能變成兩次補讀」。

### 同族還沒碰的角落

- **WS 斷線期間發生的事**:B 台若在事件送出的當下沒有連線,這次對帳就不會發生。
目前靠 `onAppResumed` 的無條件 `refreshActive` 自癒——**但那需要 App 進過背景再回來**,
一台一直開在前景的裝置不會走到。**條件**:等真的有人回報再處理;
要修的話是「WS 重連成功後補一次對帳」,動的是 `onConnectionChanged`。
- **司機端沒有這條對帳**:司機的 `_handleWsEvent` 對不認得的單也是丟掉,
但司機端在待命時**有**輪詢(hero 上線後持續回報位置並對帳),情境不同。**未查證,下輪可看。**

---

## 下次任務

> **🎯 2026-08-01 第二十七輪之後的狀態(開工先看這段)**
> **🎯 2026-08-01 第二十八輪之後的狀態(開工先看這段)**
>
> 1. **`gh pr list`(三個 repo)照樣是第一件事**——本輪開工時皆為 0。
> 2. **第十一次實查三個外部卡點:依然都不在**。
> 3. **這一輪學到的一條**:**既有測試是防線,紅了要先問「是不是我改太廣」。**
> 本輪第一版把「所有不認得的行程事件」都拿去對帳,
> `customer_cancel_notice_test` 立刻紅——那條測試守的是
> 「別的行程的取消事件不該影響這一趟」,而我的改動剛好踩過去。
> 收窄成「只在手上什麼都沒有時對帳」之後,兩邊都成立。
> **另一條**:測試紅了不一定是程式錯——本輪有一案是**我的假設錯**
> (`rideAccepted` 本來就會補讀),該改的是測試。
> 4. **下一輪候選**(依價值排序):
> - **司機端有沒有同一個洞**(本輪的直接延伸):司機的 `_handleWsEvent` 對不認得的單
> 也是丟掉,但司機端待命時有輪詢,情境不同。**未查證**,這是最便宜的一條。
> - **WS 重連後補一次對帳**:本輪的洞在「事件送出當下沒連線」時仍然存在,
> 目前只靠 `onAppResumed` 自癒,一直開在前景的裝置走不到。
> - **App 版本比後端新**:App 送出後端不認得的欄位/值時,後端是忽略還是 400?
> 目前三端都沒寫明這個契約。

>
> 1. **`gh pr list`(三個 repo)照樣是第一件事**——本輪開工時三個 repo 皆為 0。
> 2. **第十次實查三個外部卡點:依然都不在**。
Expand Down
104 changes: 70 additions & 34 deletions lib/customer/customer_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,12 @@ class CustomerController extends ChangeNotifier {
FleetWsClientFactory? wsFactory,
FleetPushService? push,
CustomerLocator? locator,
}) : _storage = storage ?? CustomerTokenStorage(),
_api = api ?? CustomerApiClient(),
_wsFactory = wsFactory ?? FleetWsClient.new,
_push = push ?? NoOpFleetPushService(),
_locator = locator ?? const GeolocatorCustomerLocator(),
_ws = FleetWsClient(onEvent: (_) {}) {
}) : _storage = storage ?? CustomerTokenStorage(),
_api = api ?? CustomerApiClient(),
_wsFactory = wsFactory ?? FleetWsClient.new,
_push = push ?? NoOpFleetPushService(),
_locator = locator ?? const GeolocatorCustomerLocator(),
_ws = FleetWsClient(onEvent: (_) {}) {
// token 過期/失效時把乘客送回登入頁(見 _handleUnauthorized)。
_api.onUnauthorized = _handleUnauthorized;
}
Expand Down Expand Up @@ -150,8 +150,9 @@ class CustomerController extends ChangeNotifier {

/// 待呈現的取消通知文案(P4);null = 沒有要顯示的取消。
/// 文案由機器可讀的 cancel_reason 產生(cancelMessage),不 parse 後端字串。
String? get cancelNotice =>
_rideCancelled ? cancelMessage(_cancelReason, _cancelledVehicleType) : null;
String? get cancelNotice => _rideCancelled
? cancelMessage(_cancelReason, _cancelledVehicleType)
: null;

/// 是否該給「改用不指定車種重新叫車」快捷(P4:只有指定車種找不到才建議)。
bool get suggestAnyVehicle =>
Expand Down Expand Up @@ -355,9 +356,9 @@ class CustomerController extends ChangeNotifier {
/// 只在星等確實屬於**目前這張完成卡**時才回傳,換一趟就自動失效。
int? get completedRatingScore =>
_completedRatingRideId != null &&
_completedRatingRideId == _completedSummary?.rideId
? _completedRatingScore
: null;
_completedRatingRideId == _completedSummary?.rideId
? _completedRatingScore
: null;

/// 評分送出中(按鈕轉圈、防連點)。
bool get ratingSubmitting => _ratingSubmitting;
Expand Down Expand Up @@ -456,7 +457,11 @@ class CustomerController extends ChangeNotifier {
_ratingSubmitting = true;
notifyListeners();
try {
final rating = await _api.rateRide(rideId, score: score, comment: comment);
final rating = await _api.rateRide(
rideId,
score: score,
comment: comment,
);
_applySubmittedRating(rideId, rating.score);
return null;
} on ApiException catch (e) {
Expand Down Expand Up @@ -664,8 +669,9 @@ class CustomerController extends ChangeNotifier {
///
/// 退路是「App 自己的保底值」而不是 0:0 會讓時間選擇器完全不擋,
/// 乘客選了 3 分鐘後,填完整張表才被後端以 400 拒絕。
int get scheduleMinLeadMinutes =>
_scheduleMinLeadMinutes > 0 ? _scheduleMinLeadMinutes : fallbackMinLeadMinutes;
int get scheduleMinLeadMinutes => _scheduleMinLeadMinutes > 0
? _scheduleMinLeadMinutes
: fallbackMinLeadMinutes;

/// 問不到後端時用的保底門檻(與後端當前的 ScheduledRideMinLeadMinutes 一致)。
static const fallbackMinLeadMinutes = 20;
Expand Down Expand Up @@ -820,8 +826,9 @@ class CustomerController extends ChangeNotifier {
unawaited(_handlePushEvent());
});
await _tokenRefreshSub?.cancel();
_tokenRefreshSub =
_push.tokenRefresh.listen((_) => unawaited(_syncDeviceToken()));
_tokenRefreshSub = _push.tokenRefresh.listen(
(_) => unawaited(_syncDeviceToken()),
);
}

/// 收到推播(前景或點通知喚醒)→ **跟後端對一次帳**。
Expand Down Expand Up @@ -884,22 +891,20 @@ class CustomerController extends ChangeNotifier {
required String lineUserId,
required String password,
}) async {
await _authenticate(() => _api.login(
lineUserId: lineUserId,
password: password,
));
await _authenticate(
() => _api.login(lineUserId: lineUserId, password: password),
);
}

Future<void> register({
required String lineUserId,
required String name,
required String password,
}) async {
await _authenticate(() => _api.register(
lineUserId: lineUserId,
name: name,
password: password,
));
await _authenticate(
() =>
_api.register(lineUserId: lineUserId, name: name, password: password),
);
}

Future<void> _authenticate(
Expand Down Expand Up @@ -1114,14 +1119,37 @@ class CustomerController extends ChangeNotifier {
driverName: _driverName,
fareAmountCents: (event.payload?['fare_amount_cents'] as num?)?.toInt(),
// O6:只有乘客指定寵物車的行程才有;後端未加收時**不帶這個鍵** → null。
cleaningFeeCents: (event.payload?['cleaning_fee_cents'] as num?)?.toInt(),
cleaningFeeCents: (event.payload?['cleaning_fee_cents'] as num?)
?.toInt(),
);
// WS 事件觸發,不是使用者按的 → 失敗靜默,交給輪詢補
refreshActive(silent: true);
return;
}
final active = _activeRide;
if (active == null || event.rideId != active.rideId) return;
if (active == null || event.rideId != active.rideId) {
// **不認得的行程事件不能直接丟掉**:後端的 WS Hub 依 (角色, id) 扇出,
// 同一個帳號的每一條連線都收得到這位乘客的行程事件。所以「不認得」最常見的
// 原因是**同一個帳號的另一台裝置**動了行程(手機叫車、平板還開著叫車表單)。
//
// 這台的輪詢在「沒有進行中訂單」時是停著的(`_applyActiveRide` 會 `_stopPolling`),
// 丟掉事件就等於**永遠**停在叫車表單:畫面上看不到那趟正在跑的車,
// 按下叫車還會拿到「已有進行中訂單」。司機端早就處理過同一件事
// (`DriverController` 的 rideAccepted:另一台裝置接走了這張單 → 重讀 active)。
//
// **只在「我手上什麼都沒有」時對帳**。已經有一張進行中訂單、事件卻是別的
// rideId,那是舊單的落隊事件(乘客一次只會有一張進行中訂單)——那種要照舊忽略,
// 否則「別的行程的取消事件不該影響這一趟」那條既有防線會被打破。
//
// `driver.location` 也不觸發:它是每幾秒一則的串流,會把一次對帳變成連續打點;
// 真正要跟上的是生命週期事件,而那些一定會跟著來。
if (active == null &&
event.rideId != null &&
event.type != FleetEventTypes.driverLocation) {
refreshActive(silent: true);
}
return;
}
switch (event.type) {
case FleetEventTypes.rideStopUpdated:
// N8:payload 帶**整趟** stops,直接覆蓋——不在客戶端套用差異,
Expand Down Expand Up @@ -1172,8 +1200,11 @@ class CustomerController extends ChangeNotifier {
// P4:以機器可讀的 cancel_reason 判斷,不 parse 後端文案(文案會改)。
// 只有逾時取消會帶這兩個鍵;乘客主動取消/司機放棄不帶 → 解析為 null,
// UI 走泛用訊息。
_cancelReason = CancelReason.fromCode(event.payload?['cancel_reason'] as String?);
_cancelledVehicleType = event.payload?['required_vehicle_type'] as String?;
_cancelReason = CancelReason.fromCode(
event.payload?['cancel_reason'] as String?,
);
_cancelledVehicleType =
event.payload?['required_vehicle_type'] as String?;
_rideCancelled = true;
// 行程真的結束了,「正在重新派車」不能再留著(重派沒成功才會走到這裡)。
_redispatchNotice = null;
Expand Down Expand Up @@ -1328,9 +1359,11 @@ class CustomerController extends ChangeNotifier {
Future<List<RideMessage>> fetchMessages(int rideId, {int afterId = 0}) =>
_api.fetchMessages(rideId, afterId: afterId);

Future<RideMessage> sendMessage(int rideId, String body,
{String? clientMsgId}) =>
_api.sendMessage(rideId, body, clientMsgId: clientMsgId);
Future<RideMessage> sendMessage(
int rideId,
String body, {
String? clientMsgId,
}) => _api.sendMessage(rideId, body, clientMsgId: clientMsgId);

/// 叫車:以目前 GPS 為上車點,帶乘客輸入的上車/目的地地址;
/// 若目的地由地圖選點取得,另帶精確座標(dropoffLat/Lng)。
Expand Down Expand Up @@ -1375,7 +1408,7 @@ class CustomerController extends ChangeNotifier {
pickup = pickupAddress.trim().isNotEmpty
? pickupAddress.trim()
: '目前位置 (${pos.latitude.toStringAsFixed(5)}, '
'${pos.longitude.toStringAsFixed(5)})';
'${pos.longitude.toStringAsFixed(5)})';
}
final ride = await _api.createRide(
pickupLat: pickupLat,
Expand Down Expand Up @@ -1644,7 +1677,10 @@ class CustomerController extends ChangeNotifier {

void _startPolling() {
_pollTimer?.cancel();
_pollTimer = Timer.periodic(_pollInterval, (_) => refreshActive(silent: true));
_pollTimer = Timer.periodic(
_pollInterval,
(_) => refreshActive(silent: true),
);
}

void _stopPolling() {
Expand Down
Loading
Loading