Skip to content
Closed
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
62 changes: 60 additions & 2 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -744,6 +744,65 @@ admin 的全域 query 錯誤處理有去重 key 且整個 repo 沒有 `refetchIn

---

## 🔄 2026-07-28 第四輪 debug:App 生命週期(背景→前景)

> 接續上一段列出的「下一輪還沒碰過的角落」第 1 項。
> 起點同樣是一句可查證的事實:`grep -rn "WidgetsBindingObserver\|didChangeAppLifecycleState" lib/`
> **全 App 零命中**——兩端從來不知道自己被切到背景過。

**三個獨立的缺口**(都不是「寫錯了」,是「從來沒做」):

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

**順帶抓到一個既有的說謊**(本批新功能踩出來的):`_scheduleReconnect()` **沒有清掉 `_channel`**,
所以整個重連等待期間 `isConnected` 都回 true——與同時回報 `onConnectionChanged(false)`
自相矛盾。舊碼沒出事是因為當時沒人讀 `isConnected`;`ensureConnected()` 一讀它就會
「以為還連著」而什麼都不做。已一併修掉(斷線時 `_channel = null` 並靜默關閉)。

**修法**:
- `AppLifecycleReactor`(`lib/shared/widgets/app_lifecycle_reactor.dart`):**只對 `resumed` 動作**——
`inactive`/`hidden` 在拉下通知欄之類的過場也會出現,對它們反應會在使用者根本沒離開 App 時
打一堆沒必要的請求。兩端 root 各包一層(登入頁也在底下,controller 未登入時早退)。
- `DriverController.onAppResumed()`:`ensureConnected()` + **以後端為準重讀 active** + 協尋清單。
- `CustomerController.onAppResumed()`:`ensureConnected()` + `refreshActive(silent: true)`——
**silent**,這不是使用者按出來的刷新(沿用第一輪的原則)。
- `FleetWsClient`:預設連線改帶 **`pingInterval` 20 秒**(`IOWebSocketChannel`)→ 半開連線由底層偵測並關閉,
走既有重連鏈;新增 `ensureConnected()`(已連上就什麼都不做,否則取消退避、歸零、立刻重試)。

**驗收**:
- 靜態:`flutter analyze` 無 issue、`flutter test` **248 passed**(240 +新 8)。
新增 `test/app_lifecycle_test.dart`:reactor 2 案(只對 resumed/移除後不再收通知)、
司機端 2 案(**背景期間行程被取消 → 回前景後行程卡消失**/未登入不打 API)、
乘客端 1 案(立刻對帳且失敗不彈錯誤)、`ensureConnected` 3 案(斷線中 2 秒內重連、
已連線不重建、登出後不偷連——後三案用真的本機 WebSocket 伺服器)。
**反向確認**:三處修正各自拿掉後,對應的 3 案 FAIL。
- **✅ 模擬器實跑閉環(2026-07-28,`m6_pixel` driver flavor + docker compose)**:
- **漏事件重現**:司機接單(ride #6 行程卡在畫面上)→ HOME 切背景 → `docker stop app`
(WS 斷、進入退避)→ 等 45 秒 → `docker start app` 後**在 App 重連之前**用乘客 API 取消
(後端 18:47:03 起來,取消也在 18:47:03;App 那時還在退避)→ 回前景 →
**行程卡消失,回到「等待派單中」**。
後端 log 交叉驗證:**回前景的同一秒(18:47:59)**收到
`SELECT * FROM rides WHERE driver_id = 5 AND status IN (2,3)`(=`GET /driver/rides/active`)
與 `lost_item_requests` 查詢——這兩個請求在修正前**根本不存在**。
- **回前景立刻重連**:`docker stop app` 70 秒(退避已達 30 秒上限)→ `docker start app` →
**不動 App,5 秒後畫面仍是紅底「連線中斷,暫時收不到派單」**+「未連線,派單可能延遲」→
切背景再回前景 → **2 秒後就變回「即時連線正常」**。

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

---

## 下次任務

> **✅ 維護項 5「清開發殘留」已完成(2026-07-28)**,詳見上方。
Expand Down Expand Up @@ -787,8 +846,7 @@ admin 的全域 query 錯誤處理有去重 key 且整個 repo 沒有 `refetchIn
> **第三輪(2026-07-28)修掉 token 過期後 App 說謊**,見上方「🔑 第三輪 debug」。
>
> **➡️ 下一輪 debug 還沒碰過的角落**(依價值排序,都不需外部資源):
> 1. **App 生命週期**:切到背景數分鐘再回前景,WS 是否確實重連、進行中行程是否對得上
> (目前只驗過「後端斷線→復原」,沒驗過「App 被系統凍結→回前景」)。
> 1. ~~**App 生命週期**~~ ✅ **已完成(2026-07-28 第四輪)**,見上方專段。
> 2. **多裝置/同帳號重複登入**:同一司機在兩台裝置上線,後端沒有踢舊 session 的機制,
> 兩邊都會收派單——先確認後端行為,再決定 App 該不該處理。
> 3. **弱網**(非全斷):`adb shell svc data` 或模擬器限速下的逾時分支,
Expand Down
39 changes: 38 additions & 1 deletion lib/core/ws/fleet_ws_client.dart
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import 'dart:async';
import 'dart:convert';

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 +43,17 @@ class FleetWsClient {
required this.onEvent,
this.onConnectionChanged,
@visibleForTesting WebSocketChannel Function(Uri uri)? connector,
}) : _connector = connector ?? WebSocketChannel.connect;
}) : _connector = connector ?? _defaultConnector;

/// 帶心跳的預設連線方式。
///
/// **沒有心跳就偵測不到半開連線**:手機切到背景、換網路、經過 NAT/負載平衡器逾時後,
/// 對端可能已經沒了,但本地 socket 收不到 FIN——`isConnected` 仍是 true、
/// UI 照樣顯示「即時連線正常」,司機卻永遠收不到派單,而且**不會觸發重連**
/// (重連只由 onDone/onError 觸發)。
/// 設 pingInterval 後底層會定期送 ping,對端沒回應就關閉 stream → 走既有重連鏈。
static WebSocketChannel _defaultConnector(Uri uri) =>
IOWebSocketChannel.connect(uri, pingInterval: _pingInterval);

final FleetEventHandler onEvent;
final void Function(bool connected)? onConnectionChanged;
Expand All @@ -59,6 +70,10 @@ class FleetWsClient {
/// 握手逾時;超過就放棄這次連線並排重連(系統 TCP 逾時太久,等它會讓司機長時間收不到派單)。
static const _readyTimeout = Duration(seconds: 15);

/// 心跳間隔:對端在一個 interval 內沒回 pong 就視為斷線(見 [_defaultConnector])。
/// 20 秒是「多久之後才發現自己收不到派單」的上限,與省電之間的折衷。
static const _pingInterval = Duration(seconds: 20);

/// 關閉舊連線的等待上限(對端已消失時 close handshake 不會回來)。
static const _closeTimeout = Duration(seconds: 2);

Expand All @@ -85,6 +100,18 @@ class FleetWsClient {
unawaited(_open());
}

/// 確保連線還在;已連上就什麼都不做,否則**立刻**重試一次。
///
/// 給「App 回到前景」用:在背景待了幾分鐘後,退避可能已經拉到 30 秒,
/// 而使用者正盯著畫面等派單/等司機——這時候值得馬上試,不該讓他再等一輪退避。
void ensureConnected() {
if (_disposed || _token == null || isConnected) return;
_reconnectTimer?.cancel();
// 使用者主動回到前景,等同一次新的連線意圖:退避歸零。
_reconnectAttempts = 0;
unawaited(_open());
}

Future<void> disconnect() async {
_disposed = true;
_reconnectTimer?.cancel();
Expand Down Expand Up @@ -178,6 +205,13 @@ class FleetWsClient {

void _scheduleReconnect() {
if (_disposed) return;
// 連線已經死了,`_channel` 就不能再留著——否則 `isConnected` 會說謊:
// 它在整個重連等待期間都回 true,而 `ensureConnected()`(回前景)看的正是它,
// 會以為還連著而什麼都不做。舊碼只有 onConnectionChanged 報 false,
// 兩個真相來源不一致。
final dead = _channel;
_channel = null;
unawaited(_closeQuietly(dead));
onConnectionChanged?.call(false);
_reconnectTimer?.cancel();
final delay = _nextReconnectDelay;
Expand Down Expand Up @@ -209,4 +243,7 @@ class _SilentWsClient extends FleetWsClient {
Future<void> disconnect() async {
onConnectionChanged?.call(false);
}

@override
void ensureConnected() {}
}
12 changes: 8 additions & 4 deletions lib/customer/app.dart
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

import '../core/theme/app_theme.dart';
import '../shared/widgets/app_lifecycle_reactor.dart';
import 'customer_controller.dart';
import 'screens/customer_login_screen.dart';
import 'screens/customer_map_home_screen.dart';
Expand Down Expand Up @@ -30,9 +31,12 @@ class _CustomerRoot extends StatelessWidget {
@override
Widget build(BuildContext context) {
final ctrl = context.watch<CustomerController>();
if (!ctrl.isLoggedIn) {
return const CustomerLoginScreen();
}
return const CustomerMapHomeScreen();
// 回前景就對帳一次:背景期間輪詢 timer 不跑,WS 也可能已經半開。
return AppLifecycleReactor(
onResumed: ctrl.onAppResumed,
child: ctrl.isLoggedIn
? const CustomerMapHomeScreen()
: const CustomerLoginScreen(),
);
}
}
11 changes: 11 additions & 0 deletions lib/customer/customer_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -426,6 +426,17 @@ class CustomerController extends ChangeNotifier {
}
}

/// App 從背景回到前景:立刻對帳一次,不等下一個輪詢週期。
///
/// 15 秒的輪詢 timer 在背景是不跑的,回前景後最久要等 15 秒才會發現行程已經變了
/// (司機接單、行程取消);WS 也可能在背景期間變成半開連線。
/// **silent**:這不是使用者按出來的刷新,失敗不該彈 SnackBar。
Future<void> onAppResumed() async {
if (_session == null) return;
_ws.ensureConnected();
await refreshActive(silent: true);
}

Future<void> login({
required String lineUserId,
required String password,
Expand Down
10 changes: 10 additions & 0 deletions lib/driver/app.dart
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import '../core/config/app_config.dart';
import '../core/models/models.dart';
import '../core/push/driver_push_service.dart';
import '../core/theme/app_theme.dart';
import '../shared/widgets/app_lifecycle_reactor.dart';
import 'driver_controller.dart';
import 'screens/driver_home_screen.dart';
import 'screens/driver_login_screen.dart';
Expand Down Expand Up @@ -36,6 +37,15 @@ class _DriverRoot extends StatelessWidget {
@override
Widget build(BuildContext context) {
final ctrl = context.watch<DriverController>();
// 回前景就以後端為準重讀一次行程:司機端沒有輪詢,背景期間斷過線就再也收不到
// 那些 WS 事件(見 DriverController.onAppResumed)。
return AppLifecycleReactor(
onResumed: ctrl.onAppResumed,
child: _buildBody(ctrl),
);
}

Widget _buildBody(DriverController ctrl) {
if (!ctrl.isLoggedIn) {
return const DriverLoginScreen();
}
Expand Down
13 changes: 13 additions & 0 deletions lib/driver/driver_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,19 @@ class DriverController extends ChangeNotifier {
await _bindPushListener();
}

/// App 從背景回到前景:補回背景期間可能漏掉的東西。
///
/// **司機端沒有輪詢,行程狀態完全靠 WS**——背景期間只要斷過線(切網路、進隧道、
/// 系統凍結進程),`ride.cancelled` 就再也不會補送。回前景後那張行程卡還掛在畫面上,
/// 司機會繼續開去接一個已經取消的乘客,直到他按下某個按鈕才被 409 擋下。
/// 所以這裡一律以後端為準重讀一次,順便把可能半開的 WS 立刻重連(不等退避)。
Future<void> onAppResumed() async {
if (_session == null) return;
_ws.ensureConnected();
await _restoreActiveRide();
await refreshLostItems();
}

/// 測試用:模擬收到 WS 事件(等同正式連線後的 onEvent)。
@visibleForTesting
void handleWsEventForTest(FleetWsEvent event) => _handleWsEvent(event);
Expand Down
45 changes: 45 additions & 0 deletions lib/shared/widgets/app_lifecycle_reactor.dart
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import 'package:flutter/material.dart';

/// 監看 App 生命週期,在回到前景(resumed)時通知呼叫端補做對帳。
///
/// 兩端的 root 都包一層:司機端與乘客端在背景期間都可能與後端脫節
/// (WS 斷線或變成半開、輪詢 timer 不跑),而回前景是使用者**正要看畫面**的那一刻,
/// 畫面上的東西這時候必須是真的。
class AppLifecycleReactor extends StatefulWidget {
const AppLifecycleReactor({
super.key,
required this.onResumed,
required this.child,
});

final VoidCallback onResumed;
final Widget child;

@override
State<AppLifecycleReactor> createState() => _AppLifecycleReactorState();
}

class _AppLifecycleReactorState extends State<AppLifecycleReactor>
with WidgetsBindingObserver {
@override
void initState() {
super.initState();
WidgetsBinding.instance.addObserver(this);
}

@override
void dispose() {
WidgetsBinding.instance.removeObserver(this);
super.dispose();
}

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
// 只在 resumed 動作。inactive/hidden 也會在切換過程中出現(例如拉下通知欄),
// 對它們反應會在使用者根本沒離開 App 時打一堆沒必要的請求。
if (state == AppLifecycleState.resumed) widget.onResumed();
}

@override
Widget build(BuildContext context) => widget.child;
}
Loading