diff --git a/docs/TODO.md b/docs/TODO.md index e361a52..3297864 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -999,6 +999,40 @@ admin 端對應:fleet-frontEnd PR #22(司機管理頁評價欄、訂單詳情評分卡)。 +## 🎫 T. App 端實跑回報的後端缺口(2026-07-29 記錄,**尚未實作**) + +> 來源:fleet-app 的搶單/多裝置/弱網三輪 debug(app PR #62–#66)。 +> 這些缺口**都是對真後端逐則印 payload 查證出來的**,但先前只寫在 App 的 TODO 裡, +> 後端這份清單上沒有——所以在這裡補記。App 端已各自做了防線, +> 下面每一項都寫明「後端不改的話,App 只能做到什麼程度」。 + +**已修(同批合併)**: +- [x] **`ride.stop_updated` 只推給乘客**(PR #53)。`publishStops` 的註解假設「司機剛做完動作、 + 會自己重讀 active」——那句話假設司機只有一台裝置。已改為乘客與司機各推一則。 + +**待處理**: + +- [ ] **T1. 接單/放棄失敗回 HTTP 200 + 文案**(應為 409)。 + `AcceptRide` 對「已被別人接走」「非待命狀態」回的是 200+`{"message":"手慢了…"}`, + 放棄不成時同樣。**後果**:App 若只看有沒有丟例外,沒搶到的司機會拿到一張 + 完整但**假的**行程卡(他會開去接一個不存在的乘客)。 + App 端現行防線是「接單後一律重讀 `rides/active`、以後端有沒有這張單判定成敗」—— + **多打一支 API 才換得到正確性**,且逾時時仍要再對帳一次。 + 改成 409 之後 App 那條退路可以留著(無害),但錯誤處理會單純很多。 +- [ ] **T2. 沒搶到的司機收不到任何事件**。一輪 `dispatchRound` 會把同一張單同時推給半徑內 + 每一位待命司機,但 `ride.accepted` **只送給接到的那位**。其他人的全螢幕接單卡 + 沒有任何東西可以把它收掉——只有他自己按下接單、或剛好收到同一 rideId 的 + `ride.cancelled`/`ride.completed` 時才會消失。 + 建議:對「本輪收到 offer 但沒接到」的司機補送 `ride.taken`, + 或在 `ride.assigned` 的 payload 帶 `offer_expires_at` 讓 App 自己倒數收卡。 +- [ ] **T3. 逾時取消(`giveUpIfUnaccepted`)只通知乘客**,司機端同 T2。 +- [ ] **T4.(產品決策)多裝置同帳號**。Hub 依 (角色, id) 扇出,**每一條連線都收得到事件**, + 沒有踢舊 session 的機制(JWT 無狀態)。實務影響有兩個: + ① 兩台同時上線時**位置互相覆蓋**(Redis 單一 `driver::loc`),派單距離以最後回報的那台為準; + ② 要不要「一個帳號只能一台上線」屬產品決策,**不該由 App 端片面實作**。 + +--- + ## 下次任務 **新需求(2026-07-16 加入,尚未實作,皆需後端地基先行)**: