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
18 changes: 14 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,9 +133,10 @@ FCM data 的值一律是字串,App 端 `fleetEventFromPushData()` 會把座標
REST 一定完整,而推播要傳達的資訊只有「有事發生了」。
所以**這一側沒有額外的 payload 契約**,後端只要帶 `type`(+ `ride_id`)即可。

⚠️ **後端目前還不會推播給乘客**:`notify.Dispatcher` 只有 `NotifyDriverRideOffer`
(`grep -rn "RoleCustomer" internal/` 只命中 device-token 的存取層)。
所以乘客 token 現在只是「存起來備用」——真正的喚醒要等後端補送出路徑(已記在 dispatch TODO)。
✅ **後端送出路徑已補上**(dispatch [PR #61](https://github.com/thothawei/fleet-dispatch/pull/61),
2026-07-30):`Dispatcher.NotifyCustomerRideUpdate` + 五個發送點,data 正好只帶
`type` 與 `ride_id`。~~先前只有 `NotifyDriverRideOffer`,乘客 token 只是「存起來備用」。~~
**整條鏈路現在只剩 Firebase 憑證**(同 A2)——憑證放進來就該直接會動,不需再改程式碼。

## 功能進度

Expand Down Expand Up @@ -214,7 +215,16 @@ REST 一定完整,而推播要傳達的資訊只有「有事發生了」。
至此三端齊備:**乘客評 → 司機看得到自己的平均分 → 營運看得出誰評價低**。
詳見 [`docs/TODO.md`](docs/TODO.md)「⭐ 乘客評分司機」。

**目前**:`flutter analyze` 無 issue、`flutter test` **291 passed**(2026-07-29)。
**目前**:`flutter analyze` 無 issue、`flutter test` **317 passed**(44 個測試檔,2026-07-30 實跑)。
~~291 passed(2026-07-29)~~ 是漏更新的舊數字——**這一行請跟著最後一次實跑一起改**。

**2026-07-30 這一批**(詳見 [`docs/TODO.md`](docs/TODO.md) 第十二輪):
- **點推播喚醒的事件不再被丟掉**:`getInitialMessage()`(App 被殺後點通知的唯一管道)
在 `runApp` 之前就把事件送進廣播串流,而 controller 要到 `init()` 才訂閱——
廣播串流不緩衝,事件當場消失。**司機端「被殺 → 點推播 → 接單卡」與乘客端
「點推播 → 對帳」兩條都是死路徑**。改成沒人訂閱時留著最後一則、第一個訂閱者上來補送。
- **後端補上乘客端推播的送出路徑**(dispatch PR #61):先前 `notify.Dispatcher` 只有
司機派單那一條,乘客註冊的 token 沒有任何用途。至此整條鏈路**只剩 Firebase 憑證**。

**2026-07-29 這一批**(詳見 [`docs/TODO.md`](docs/TODO.md) 第四~六輪 debug +「🧾 PR 佇列稽核」):
- **回到前景會對帳**:背景期間 OS 凍結 timer、WS 可能被關掉,回前景時**立刻重連 WS**
Expand Down
93 changes: 78 additions & 15 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@
- [🔬 第九輪盤點:下一輪的三個候選(**未修,只取證**)](#-2026-07-29-第九輪盤點下一輪的三個候選本批只盤點沒有修)
- [🔧 第十輪:聊天室回前景補讀+三條寫入路徑的逾時對帳](#-2026-07-29-第十輪-debug把第九輪的候選-23-修掉本批)
- [📲 第十一輪:乘客端推播接線(候選 1 的前半)](#-2026-07-29-第十一輪乘客端推播接線候選-1-的前半)
- [🔔 第十二輪:點推播喚醒的事件在沒人聽時被丟掉](#-2026-07-30-第十二輪點推播喚醒的那條路事件在沒人聽的時候就被丟掉了本批修掉)

**四、維護、決策與待辦**
- [🧹 清開發殘留 worktree/舊分支(維護項 5)](#-清開發殘留-worktree舊分支維護項-52026-07-28-完成)
Expand All @@ -78,7 +79,7 @@
- **UI/UX 翻新(2026-07-10)**:LINE 綠亮暗雙主題;司機駕駛情境 UI;乘客地圖為底+卡片降級。靜態驗收 49 tests 通過;模擬器主鏈路待後端 docker 可起後補跑。
**登入/註冊頁 2026-07-23 補齊翻新**(先前是唯一漏網畫面),詳見下方「🔐 登入頁 UI/UX 翻新+驗證」。
- **座標導航(2026-07-10)**:司機端目的地導航改吃後端 `dropoff_point` 座標,地址僅供顯示與退路。
- 單元測試:**43 個測試檔、`flutter test` 312 passed**(2026-07-29 實跑;`flutter analyze` 無 issue)。
- 單元測試:**44 個測試檔、`flutter test` 317 passed**(2026-07-30 實跑;`flutter analyze` 無 issue)。
~~(54 項)~~ 是 2026-07-10 的數字,長期沒更新,已更正——**本節的數字請跟著最後盤點日一起改**。
- 遠端:`github.com/thothawei/fleet-app`。**2026-07-29 實查**:`git ls-remote --heads origin` 只有 `main`、
`gh pr list` 三個 repo 的 open PR 皆為 0(開工前請自己再跑一次,見「下次任務」第 1 點)。
Expand Down Expand Up @@ -1438,6 +1439,56 @@ App 這端該做的都做完了,真正的喚醒要等後端補送出路徑。
- **未做**:真推播的端到端(**需要 `google-services.json`**,本檔 A2 的同一個卡點)。
這批驗的是接線,不是推播本身;README 的「乘客端推播」段寫了憑證到位後要做什麼。

> **📌 2026-07-30 回填**:上面說的「留給後端的」**已經做掉了**——
> dispatch [PR #61](https://github.com/thothawei/fleet-dispatch/pull/61)
> 補上 `NotifyCustomerRideUpdate` 與五個發送點,data 也正好只帶 `type`+`ride_id`。
> 現在缺的只剩 Firebase 憑證(A2 的同一個卡點)。

---

## 🔔 2026-07-30 第十二輪:點推播喚醒的那條路,事件在沒人聽的時候就被丟掉了(本批修掉)

> 起因:接完後端送出路徑(dispatch PR #61)後,順著問一句
> **「推播真的到得了 controller 嗎」**,才發現喚醒這條路徑從頭到尾沒有人走過。

### 根因(一句話)

`FirebaseFleetPushService` 用 `StreamController.broadcast()`,而**廣播串流在沒有訂閱者的當下
`add` 的事件會直接消失**(Dart 不緩衝)。冷啟動的順序正好是這樣:

```
main() → createXxxPushService() → initialize() → getInitialMessage() → _events.add(事件)
→ runApp() → Controller.init() → ... → rideEvents.listen(...) ← 訂閱在這裡才發生
```

`getInitialMessage()` 是「**App 被殺 → 點通知 → 冷啟動**」唯一的取得管道,
而它在 `runApp` 之前就把事件送出去了。於是:

- **司機端**:A2 的招牌情境「App 被殺 → 點推播 → 接單卡」——**卡片永遠不會出現**。
- **乘客端**:第十一輪剛接好的「點推播 → 跟後端對帳」——**對帳永遠不會發生**。

兩端寫好的處理都在,缺的是事件本身。這是本專案第 N 次遇到同一個形狀
(「處理寫好了,訊號從沒到達」,見第八輪的事件收件人矩陣、`pitfall-ws-only-state-no-rest-restore`),
差別是這次的斷點在 **App 自己的串流層**,不是跨端契約。

### 改法

新增 `lib/core/push/pending_push_replay.dart` 的 `PendingReplaySink<T>`:沒有訂閱者時把事件
留著,第一個訂閱者上來時用 microtask 補送(`onListen` 在訂閱建立過程中被呼叫,
當下同步 `add` 不保證送得到那位訂閱者)。`FirebaseFleetPushService._events` 換成它,其餘不動。

**只留最後一則**:這些事件的用途都是「開一張卡」或「去對一次帳」,補送一整串舊事件
只會讓畫面閃過一連串過期狀態。**補送過就丟掉**——登出後重新訂閱不會再收到同一則。

### 驗收

- `flutter analyze` 無 issue、`flutter test` **317 passed**(312 +新 5)。
新增 `test/pending_push_replay_test.dart`:沒人訂閱時到達要補送/補送只做一次/
只留最後一則/已有訂閱者時照常即時送達/補送前就取消訂閱不 panic。
- **反向確認**:把 `add` 退回普通廣播行為(直接 `_controller.add`),**3 案 FAIL**。
- **未做**:真裝置端到端(同 A2,卡 `google-services.json`)。這批修的是「事件到不到得了
訂閱者」,那是純 Dart 串流語意,不需要 Firebase 就能釘住。

---

## 下次任務
Expand All @@ -1462,10 +1513,13 @@ App 這端該做的都做完了,真正的喚醒要等後端補送出路徑。
> **沒有低分司機的處理流程**(通知/停權/申訴)。
> **條件**:等實際累積評分、營運說得出要對低分司機做什麼再開——
> 做在前面只會做出沒人用的流程。
> 8. **清掉殘留 worktree `fleet-improvements-todo-cc8d85`**(2026-07-29 盤點新增):
> 分支 `claude/e2e-salvaged-fixes` 的內容**全部在 main**、工作區乾淨,
> 三條判定依據見 [第九輪盤點](#-2026-07-29-第九輪盤點下一輪的三個候選本批只盤點沒有修)的「維護項 8」。
> 刪之前先確認沒有 session 正在用它。
> 8. ~~**清掉殘留 worktree `fleet-improvements-todo-cc8d85`**~~ ✅ **已完成(2026-07-30)**:
> 連同另一個殘留 `todo-list-enhancement-abdd77` 一起移除,五支已合併的本機分支
> (`claude/e2e-salvaged-fixes`/`customer-push-wiring`/`chat-resume-and-timeout-reconcile`/
> `driver-cancel-notice`/`todo-list-enhancement-abdd77`)一併刪掉。
> **判定用的是兩點 diff 而非 `--merged`**(squash 合併下 `--merged` 全漏,
> 見 `pitfall-stale-branch-deletion`):`git diff main <branch>` 若只剩「main 比它新」的反向差異,
> 代表內容已全在 main。刪之前也用 `ps aux` 確認沒有 session 正在用那兩個目錄。
>
> **2026-07-28 又補了一項(不在原清單上)**:`docs/IOS_PLAN.md` 的**勾選框與散文不一致**——
> 階段 1 的四項、3-4、7-1 的散文說完成、勾選框卻仍是 `[ ]`/`[~]`。
Expand All @@ -1474,22 +1528,31 @@ App 這端該做的都做完了,真正的喚醒要等後端補送出路徑。
> `xcrun devicectl list devices` → **No devices found**(A5 階段 5 仍卡)。
> **2026-07-29 再查一次,兩者仍未到位**(另加驗 `ios/Runner/GoogleService-Info.plist` 也不存在)——
> 這兩條**每次開工都值得重跑**:它們是外部資源,隨時可能到位,而不會有人來通知我們。
> **2026-07-30 第三次實查:三者依然都不在**(兩個 Firebase 設定檔不存在、
> `xcrun devicectl list devices` → No devices found)。
>
> **2026-07-28 收尾**:清單清空後改做 debug——修掉 4 個 bug、做完一輪跨端契約對帳,
> 見上方「🐞 2026-07-28 debug」。**六份清單(本檔、admin TODO、IOS_PLAN、gap-analysis-plan、
> 兩份 UI/UX 執行計畫)的勾選現在全部對得上程式碼現況**,文件層面沒有可清的東西了。
>
> **🎯 下次開工第一件事**(2026-07-29 第十一輪後更新):先跑 `gh pr list`,再看
> [第九輪盤點](#-2026-07-29-第九輪盤點下一輪的三個候選本批只盤點沒有修)——
> 三條候選**都做完了**(2、3 在[第十輪](#-2026-07-29-第十輪-debug把第九輪的候選-23-修掉本批),
> 1 的接線在[第十一輪](#-2026-07-29-第十一輪乘客端推播接線候選-1-的前半))。
> **乘客端推播還有兩塊不在 App 這端**:Firebase 憑證(同 A2,要你提供)
> 與**後端還沒有推播給乘客的送出路徑**(`notify.Dispatcher` 只有 `NotifyDriverRideOffer`)——
> 後者不需要憑證就能先做,屬 dispatch repo。
> **兩項修正都只有測試層證據,沒有模擬器實跑**——下次起 docker/模擬器時,
> **🎯 下次開工第一件事**(2026-07-30 第十二輪後更新):先跑 `gh pr list`(三個 repo),
> 再看下面這張「推播整條鏈路現在缺什麼」的表——這是目前唯一一條**三端都動過、卻還沒通**的路:
>
> | 環節 | 狀態 | 在哪 |
> |---|---|---|
> | 乘客 App 註冊 token、收到推播去對帳 | ✅ 第十一輪 | 本 repo |
> | 後端對乘客送出(5 種事件) | ✅ dispatch [PR #61](https://github.com/thothawei/fleet-dispatch/pull/61)(2026-07-30) | dispatch |
> | 冷啟動時事件送得到訂閱者 | ✅ 第十二輪(本批) | 本 repo |
> | **Firebase 憑證** | ❌ **卡住** | 要你建 Firebase 專案 |
> | 真裝置端到端驗收 | ❌ 等憑證 | — |
>
> 也就是說:**憑證一到位,推播就該直接會動**,不需要再寫程式碼。
> 憑證到位那天要跑的驗收:司機端「App 被殺 → 點推播 → 接單卡」、
> 乘客端「App 被殺 → 點推播 → 冷啟動後畫面已是最新狀態」。
> **第十輪那兩項修正仍只有測試層證據,沒有模擬器實跑**——下次起 docker/模擬器時,
> 把第十輪寫的那兩條「怎麼證實」順手跑掉(注意 `docker pause` 造不出正向競態,
> 那一分支需要一支吃掉回應的代理)。
> 維護項只剩 7(等營運需求)與 8(刪殘留 worktree,5 分鐘的事)。
> 維護項只剩 7(等營運需求);8 已於 2026-07-30 做掉。
> 第 1–4 項仍全部需要你提供外部資源或拍板——Firebase 專案(A2)/
> iPhone+Xcode Personal Team(A5 階段 5)/金流方案(付款)/車種供給為零的產品方向。
>
Expand All @@ -1514,7 +1577,7 @@ App 這端該做的都做完了,真正的喚醒要等後端補送出路徑。
>
> | # | 候選 | 需要外部資源? | 建議順序 |
> |---|---|---|---|
> | 1 | **乘客端完全沒有推播管道**(後端 `/api/customer/device-token` 已就緒、App 從沒接) | 憑證那半要 Firebase(同 A2) | ✅ **接線已完成(第十一輪)**;**剩憑證+後端送出路徑** |
> | 1 | **乘客端完全沒有推播管道**(後端 `/api/customer/device-token` 已就緒、App 從沒接) | 憑證那半要 Firebase(同 A2) | ✅ **接線(第十一輪)+後端送出(dispatch #61)+冷啟動補送(第十二輪)都已完成**;**只剩憑證** |
> | 2 | ~~聊天室的 `afterId` 增量補讀是死路徑~~ | 不用 | ✅ **已修(第十輪)** |
> | 3 | ~~`completeTrip`/`pickUpPassenger`/`_markStop` 沒有逾時對帳~~ | 不用 | ✅ **已修(第十輪)** |
>
Expand Down
5 changes: 4 additions & 1 deletion lib/core/push/firebase_push_service.dart
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import 'package:flutter/foundation.dart';
import '../ws/fleet_ws_client.dart';
import 'fleet_push_service.dart';
import 'fcm_background.dart';
import 'pending_push_replay.dart';
import 'push_payload.dart';

/// 真實 FCM 實作:需 `android/app/google-services.json`(見 README)。
Expand All @@ -26,7 +27,9 @@ class FirebaseFleetPushService implements FleetPushService {
/// 在建構子取會在沒有 google-services.json 的裝置上直接拋 [core/no-app]。
final FirebaseMessaging? _injectedMessaging;
late final FirebaseMessaging _messaging;
final _events = StreamController<FleetWsEvent>.broadcast();
/// **不是普通的 broadcast controller**:冷啟動時 `getInitialMessage()` 發出事件的當下
/// (`runApp` 之前)還沒有任何訂閱者,普通廣播串流會把它丟掉。見 [PendingReplaySink]。
final _events = PendingReplaySink<FleetWsEvent>();
final _tokenRefresh = StreamController<String>.broadcast();
StreamSubscription<String>? _tokenRefreshSub;
bool _available = false;
Expand Down
55 changes: 55 additions & 0 deletions lib/core/push/pending_push_replay.dart
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import 'dart:async';

/// 沒有訂閱者時把事件留著,等第一個訂閱者上來再補送。
///
/// **為什麼需要這個**:`StreamController.broadcast()` 在沒有訂閱者的當下 `add`,
/// 事件會直接消失(Dart 的廣播串流不緩衝)。而「點推播喚醒被殺的 App」正是這個情況——
///
/// ```
/// main() → createXxxPushService() → initialize() → getInitialMessage() → add(事件)
/// → runApp() → Controller.init() → rideEvents.listen(...) ← 訂閱在這裡才發生
/// ```
///
/// 事件在 `runApp` 之前就發出去了,訂閱者晚了好幾拍,於是 A2 的招牌情境
/// 「App 被殺 → 點推播 → 接單卡」與乘客端「點推播 → 跟後端對帳」**兩邊都是死路徑**。
///
/// 只留**最後一則**:這些事件的用途都是「去跟後端對一次帳」或「開一張卡」,
/// 補送最新的那則即可,補送一整串舊事件只會讓畫面閃過一連串過期狀態。
/// 補送過就丟掉,所以登出後重新訂閱不會再收到同一則。
class PendingReplaySink<T> {
PendingReplaySink() {
_controller = StreamController<T>.broadcast(onListen: _flushPending);
}

late final StreamController<T> _controller;
T? _pending;

Stream<T> get stream => _controller.stream;

/// 目前是否有事件等著補送(測試與診斷用)。
bool get hasPending => _pending != null;

void add(T event) {
if (_controller.hasListener) {
_controller.add(event);
return;
}
_pending = event;
}

/// 第一個訂閱者上來時補送。
///
/// 用 microtask 而非直接 `add`:`onListen` 在訂閱**建立過程中**被呼叫,
/// 當下同步 add 進去的事件不保證送得到那位訂閱者。
void _flushPending() {
scheduleMicrotask(() {
final pending = _pending;
_pending = null;
if (pending != null && _controller.hasListener) {
_controller.add(pending);
}
});
}

Future<void> close() => _controller.close();
}
80 changes: 80 additions & 0 deletions test/pending_push_replay_test.dart
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:line_fleet_app/core/push/pending_push_replay.dart';

/// 「點推播喚醒被殺的 App」這條路徑先前是死的:
/// `getInitialMessage()` 在 `runApp` 之前就把事件 add 進廣播串流,
/// 而 controller 要到 `init()` 才訂閱——廣播串流不緩衝,事件當場消失。
///
/// 這組測試釘住補送行為。移掉 [PendingReplaySink] 的補送邏輯,第一支就會 FAIL。
void main() {
test('沒人訂閱時到達的事件,第一個訂閱者上來要補送', () async {
final sink = PendingReplaySink<String>();
sink.add('ride.assigned'); // 冷啟動:此刻沒有任何訂閱者
expect(sink.hasPending, isTrue);

final received = <String>[];
sink.stream.listen(received.add);
await Future<void>.delayed(Duration.zero);

expect(received, ['ride.assigned']);
expect(sink.hasPending, isFalse);
await sink.close();
});

test('補送只做一次,之後的訂閱者不會再收到同一則', () async {
final sink = PendingReplaySink<String>();
sink.add('driver.arrived');

final first = <String>[];
final sub = sink.stream.listen(first.add);
await Future<void>.delayed(Duration.zero);
await sub.cancel();

final second = <String>[];
sink.stream.listen(second.add);
await Future<void>.delayed(Duration.zero);

expect(first, ['driver.arrived']);
expect(second, isEmpty, reason: '登出後重新訂閱不該再收到同一則舊事件');
await sink.close();
});

test('只留最後一則:補送一整串過期狀態只會讓畫面閃過舊資料', () async {
final sink = PendingReplaySink<String>();
sink.add('ride.accepted');
sink.add('driver.arrived');
sink.add('ride.completed');

final received = <String>[];
sink.stream.listen(received.add);
await Future<void>.delayed(Duration.zero);

expect(received, ['ride.completed']);
await sink.close();
});

test('已經有訂閱者時照常即時送達,不進補送佇列', () async {
final sink = PendingReplaySink<String>();
final received = <String>[];
sink.stream.listen(received.add);
await Future<void>.delayed(Duration.zero);

sink.add('chat.message');
expect(sink.hasPending, isFalse);
await Future<void>.delayed(Duration.zero);

expect(received, ['chat.message']);
await sink.close();
});

test('補送前訂閱者就取消時不 panic(事件丟掉即可)', () async {
final sink = PendingReplaySink<String>();
sink.add('ride.cancelled');

final sub = sink.stream.listen((_) {});
await sub.cancel(); // 補送的 microtask 還沒跑就取消
await Future<void>.delayed(Duration.zero);

await sink.close();
});
}
Loading