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

---

## ⏱️ 2026-07-28 第五輪 debug:「其實成功了」與「其實沒成功」

> 接續第 3 項(弱網/逾時分支)。查下去發現真正的問題不在逾時文案,
> 而在**兩端都把「沒有丟例外」當成「成功」**。

**先對真後端取證**(curl 打實際端點):

| 情境 | 後端實際回應 | App 原本怎麼解讀 |
|---|---|---|
| 同一乘客第二次建單 | **409**「已有進行中的訂單」 | 原樣顯示——但乘客畫面上根本沒有任何訂單,這句話無法行動 |
| 司機接一張已被別人接走的單 | **HTTP 200** +「手慢了,這單已被其他司機接走」 | **當成接單成功**:樂觀行程卡留在畫面上 |
| 司機非待命狀態接單 | **HTTP 200** +「您目前無法接單(非待命狀態)」 | 同上 |

**兩個真 bug**:

1. **司機抱著一張別人的行程卡出發**。`acceptOffer` 只在丟例外時才算失敗,而後端這兩種
拒絕都是 200。舊碼的重讀 active 又寫著「回 null 或別的 rideId 時**寧可保留樂觀設定**」,
於是沒接到的情況下畫面照樣顯示行程卡,直到司機按「乘客已上車」被 409 擋下才發現。
2. **弱網下「請求送達、回應丟失」= 使用者被騙**。
- 司機端:接單其實成功了,App 卻報錯。司機按「略過」→ 行程從畫面消失,
而後端已把他設成載客中——**收不到新派單、也無法離線**,畫面上什麼都沒有
(這正是 `pitfall-driver-stuck-ontrip` 的成因之一)。
- 乘客端:建單其實成功了,App 停在叫車表單說「請求逾時」;再按一次就得到
409「已有進行中的訂單」——唯一的出路是重開 App。

**修法**(同一個原則:**有副作用的請求,結果要向後端問,不能只看有沒有丟例外**):
- 司機端 `acceptOffer`:接單後一律重讀 active,以「是不是這張單」判定三態
(`_AcceptOutcome`)。**confirmed** → 以後端資料覆蓋樂觀值(順帶補齊推播路徑缺的 stops);
**rejected** → 收掉樂觀行程卡並說明「這單已被其他司機接走」;
**unknown**(重讀本身也失敗=網路仍不通)→ 保留樂觀行程,因為「真的接到卻看不到行程」更糟。
逾時(`statusCode == null`)也走同一條確認:確認到了就當作接單成功,不報錯。
後端 `AcceptRide` 是同步寫入後才回應,所以「回應之後 active 查得到」可以依賴——
`null` 是真的沒接到,不是還沒寫好。
- 乘客端 `placeOrder`:逾時(`statusCode == null`)或 **409** 時先問後端有沒有進行中訂單,
有就直接接手(含已被接單時的司機資訊)。**400 之類的輸入錯誤不觸發對帳**——那是真的沒建。
建單成功與「其實已經建好了」共用同一份狀態切換(`_applyCreatedRide`),
避免兩份清單其中一份漏掉某項而把上一趟的司機/取消通知帶進這一趟。

**驗收**:
- 靜態:`flutter analyze` 無 issue、`flutter test` **257 passed**(248 +新 7 +改寫 2)。
新增 `test/customer_place_order_timeout_test.dart` 7 案(逾時已建/409 已建/逾時期間已被接單
連司機資訊帶出/真的沒建照常報錯/對帳也失敗不編故事/400 不觸發對帳/終態訂單不算數);
`driver_controller_test` 加 2 案(逾時但其實接到了、逾時且真的沒接到)並**改寫**原本
「回別的行程/null 時不覆蓋樂觀行程」那條——它釘的正是本輪要修掉的行為。
**反向確認**:兩處修正各自拿掉後,5 案 FAIL。
- **✅ 模擬器實跑(`m6_pixel` driver flavor + docker compose)**:
司機 A(`simexp01`)上線收到 ride #8 接單卡 → **趁他還沒按,用 API 讓司機 B(`simexp02`)接走**
→ 司機 A 按「接單」→ 後端回 200「手慢了」→ **App 沒有出現行程卡**,
改顯示紅色橫幅**「這單已被其他司機接走」**,畫面回到「等待派單中」。
DB 交叉驗證 ride #8 `driver_id = 6`(司機 B),與畫面一致。
- **誠實標記**:「逾時但其實成功」這條在真機上不好精準重現(要讓回應剛好在
`receiveTimeout` 後才丟失),**只有單元測試覆蓋**,未在模擬器上實跑過。

---

## 下次任務

> **✅ 維護項 5「清開發殘留」已完成(2026-07-28)**,詳見上方。
Expand Down Expand Up @@ -849,8 +904,12 @@ admin 的全域 query 錯誤處理有去重 key 且整個 repo 沒有 `refetchIn
> 1. ~~**App 生命週期**~~ ✅ **已完成(2026-07-28 第四輪)**,見上方專段。
> 2. **多裝置/同帳號重複登入**:同一司機在兩台裝置上線,後端沒有踢舊 session 的機制,
> 兩邊都會收派單——先確認後端行為,再決定 App 該不該處理。
> 3. **弱網**(非全斷):`adb shell svc data` 或模擬器限速下的逾時分支,
> api_error 的逾時文案與重試行為只在單元測試層驗過,沒在真裝置跑過。
> 3. ~~**弱網**(非全斷)的逾時分支~~ ✅ **已完成(2026-07-28 第五輪)**,見上方專段
> (真正的問題不是文案,是「沒丟例外 = 成功」的判定)。
> 4. **其他有副作用的操作是否也有同一個洞**:`pickUp`/`completeRide`/`cancelRide`
> 在逾時後同樣可能「其實成功了」。本輪只修了最貴的兩條(接單、建單)——
> 完成行程逾時會讓司機重按,後端回 409 而司機仍停在行程卡上。
> **條件**:等第五輪的做法在真機上跑一陣子沒問題,再用同一套 `_confirm*` 模式推廣。

> **🎨 App icon(叫車系統圖示)✅ 已完成(2026-07-15,PR #15)**:品牌綠 LINE green #06C755 + 白色計程車,
> 以 `flutter_launcher_icons` 產生 Android(含 adaptive icon)與 iOS 各尺寸,driver/customer 兩 flavor 共用。
Expand Down
80 changes: 57 additions & 23 deletions lib/customer/customer_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -852,36 +852,70 @@ 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) {
// 建單是**有副作用**的請求:逾時/斷線(`statusCode == null`)代表
// 「不知道後端有沒有收到」,而 409 更是明說「你已經有一張進行中的訂單」——
// 那張多半就是上一次逾時真的建起來的。兩者都先去問後端到底有沒有單,
// 不能直接把「請求逾時」丟給乘客:他會停在叫車表單,再按一次就得到
// 「已有進行中的訂單」,而畫面上根本沒有任何訂單可看。
if ((e.statusCode == null || e.statusCode == 409) &&
await _adoptExistingRide()) {
return;
}
_error = e.message;
} finally {
_setBusy(false);
}
}

/// 建單失敗後向後端確認是否其實已經有一張進行中的訂單;有就直接接手它。
/// 回 true 代表「這趟其實成立了」,呼叫端不該再報錯。
Future<bool> _adoptExistingRide() async {
try {
final ride = await _api.activeRide();
if (ride == null || RideStatus.isTerminal(ride.status)) return false;
_applyCreatedRide(ride);
// 逾時期間可能已經被司機接走了:這行把司機姓名/車輛補回來,
// 不必等下一個輪詢週期才顯示。
_applyActiveRide(ride);
return true;
} on ApiException {
// 連問都問不到(網路仍不通)→ 維持原本的錯誤回報,不編故事。
return false;
}
}

/// 一趟新訂單成立後的狀態切換(建單成功與「其實已經建好了」共用)。
///
/// 兩條路徑必須共用同一份清單:漏掉其中一項,就會把上一趟的司機、取消通知或
/// 完成卡帶進這一趟。
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
44 changes: 36 additions & 8 deletions lib/driver/driver_controller.dart
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,13 @@ import '../core/push/driver_push_service.dart';
import '../core/storage/token_storage.dart';
import '../core/ws/fleet_ws_client.dart';

/// 接單之後向後端確認的三種結果。
///
/// **「不知道」必須與「沒接到」分開**:兩者都不是 confirmed,但處置相反——
/// 沒接到要把樂觀行程卡收掉,不知道(重讀也失敗)則要留著,
/// 否則司機真的接到單卻看不到行程。
enum _AcceptOutcome { confirmed, rejected, unknown }

/// 司機端狀態:登入、上線、WS 派單、行程操作。
class DriverController extends ChangeNotifier {
DriverController({
Expand Down Expand Up @@ -533,28 +540,49 @@ class DriverController extends ChangeNotifier {
// 以後端為權威補齊:**推播喚醒路徑**的 offer 來自 FCM data,data 值全是字串、
// 不帶結構化的 stops 陣列(見 pitfall-fcm-data-all-strings),所以樂觀行程會缺全程。
// 重讀 active 讓多停靠點清單/多點地圖一定齊全,不必讓推播 payload 塞 stops。
await _refreshActiveAfterAccept(offer.rideId);
//
// **同時這也是「到底有沒有接到」的唯一判準**:後端在「被別人接走」與
// 「非待命狀態」時回的是 **HTTP 200 + 一句訊息**(不是錯誤),
// 只看有沒有丟例外,就會在沒接到的情況下留著一張別人的行程卡。
final outcome = await _confirmAccepted(offer.rideId);
if (outcome == _AcceptOutcome.rejected) {
_activeRide = null;
_setError('這單已被其他司機接走');
}
} on ApiException catch (e) {
_setApiError(e);
// 連線類錯誤(沒收到 HTTP 回應)= **請求可能已經送達後端**:接單也許已經成功,
// 只是回應在路上丟了。這時候若直接報錯,司機會以為沒接到而按「略過」,
// 而後端已把他設成載客中——他收不到新派單、也無法離線,且畫面上什麼都沒有。
if (e.statusCode == null &&
await _confirmAccepted(offer.rideId) == _AcceptOutcome.confirmed) {
_pendingOffer = null;
_setError(null);
} else {
_setApiError(e);
}
} finally {
_busy = false;
notifyListeners();
}
}

/// 接單後重讀 active,以後端回傳為權威補齊樂觀 offer 缺的欄位(尤其 stops)。
/// 向後端確認這張單現在是不是我的,並以後端資料覆蓋樂觀值。
///
/// **只在後端回傳非 null 且 rideId 相符時覆蓋**——active API 對剛接的單短暫回 null
/// 或競態回別的行程時,寧可保留樂觀設定,也不要把剛接到的單清掉。
/// 重讀失敗(網路)不算接單失敗:吞掉例外、不覆寫 error。
Future<void> _refreshActiveAfterAccept(int rideId) async {
/// 後端 `AcceptRide` 是同步寫入(同一個請求裡更新 rides 與 driver 狀態)後才回應,
/// 所以「回應之後 active 查得到」是可以依賴的——`null` 代表**真的不是我的**,
/// 不是還沒寫好。
/// 只有重讀本身失敗時才回 [_AcceptOutcome.unknown]:那代表網路仍不通,
/// 這時保留樂觀行程比清掉安全(真的接到卻看不到行程,司機無事可做)。
Future<_AcceptOutcome> _confirmAccepted(int rideId) async {
try {
final fresh = await _api.activeRide();
if (fresh != null && fresh.rideId == rideId) {
_activeRide = fresh;
return _AcceptOutcome.confirmed;
}
return _AcceptOutcome.rejected;
} on ApiException {
// 樂觀行程已足以繼續作業;重讀失敗不打斷接單流程。
return _AcceptOutcome.unknown;
}
}

Expand Down
Loading