docs(app): 規劃「後端要加新的 ride 狀態碼」該怎麼做（跨三端，尚未動工）

[thothawei]

第二十七輪把 App 補成「不認得的狀態碼不會讓訂單從畫面上消失」——但那只是不會壞。真的要新增一個狀態碼是跨三端＋有上線順序的事，這支把清單與順序先寫死，等真的有產品理由時照著做，不要臨時想。

這是規劃，沒有動任何程式碼（docs-only）。

什麼時候才該做

目前 0/1/2/3/4/9 六碼夠用，沒有產品理由就不要加。已知會逼出新碼的情境有兩個：

1. 「司機已抵達上車點」要進 DB——現在只有 WS driver.arrived 事件，後端不存 flag，所以重開 App 就看不出司機到了沒；
2. 付款進場（Phase C）——「已完成」與「已付款」會需要分開。

契約先定死（這三條決定後面所有工作量）

• 只增不改、不重編號：4=completed／9=cancelled 的語意永遠不動（ride_events 歷史、admin 報表、三端常數都綁著它）。
• 號段有語意：admin 的 isRideCancellable 是 status >= 0 && status <= 2 的範圍判斷。所以「新增一個語意上在中途、號碼卻大於 3 的狀態」會讓所有用大小比較判階段的程式碼失效——同一批必須把範圍判斷全改成白名單。
• 後端是唯一真相來源，三端不自行推導（既有規矩，比照 O5 can_accept、O3 has_vehicle）。

逐項清單（已逐條實查過位置）

後端最容易漏的一組是 repository 的三處白名單，因為它決定「誰查得到這張單」：FindActiveByDriver = {accepted, pickedUp}、乘客的進行中訂單 = {requested, assigned, accepted, pickedUp}、三支條件式 UPDATE 的 WHERE status = ?。

App 最關鍵的兩個是 RideStatus.isActive / isTerminal 白名單（決定「訂單算不算還在跑」，漏改會讓行程卡永遠不消失或提早消失），以及司機端 phase 的二分法推導（status == pickedUp ? onTrip : enRouteToPickup）。

Admin 兩支不改也不會壞（RIDE_STATUS 有 ?? String(status) 退路），但另外兩支會安靜地出錯——見下。

完整清單見 TODO 的該段。

上線順序（比清單重要）

外面有舊版 App，所以順序不能顛倒：

1. 先出 App（三端最慢的一端，使用者要更新）；
2. 再出 admin；
3. 後端最後才開始「送出」新碼——程式碼可以先合併，但真正開始寫入新狀態要等舊版佔比降到可接受。

中間這段期間，舊版 App 靠第二十七輪的 UnknownPhaseContent 撐著：看得到「行程進行中・狀態 N・請更新 App」，不會把訂單藏起來，也還能取消。那一輪「前瞻性修補」的價值就在這裡兌現。

順帶記下兩個現在就存在的 admin 技術債

盤點時查到的，與加不加新碼無關，但加新碼會讓它們從「將就」變成「錯誤數字」：

1. isRideCancellable(status) 用範圍判斷 >= 0 && <= 2——新碼一律落在「不可取消」，若新狀態其實該可取消，會安靜地擋掉營運。
2. DashboardPage.tsx:44-45 硬編 status === 4／=== 9 算今日完成／取消數——新增任何終態都會讓儀表板安靜地少算。

這兩條屬 line-fleet-admin，不在本 PR 範圍，已寫進規劃供後續認領。

驗收

docs-only。flutter analyze 無 issue、flutter test 448 passed（未受影響）。

🤖 Generated with Claude Code