From df7771890143c79c400cf3ccb81db9c2957217f2 Mon Sep 17 00:00:00 2001 From: awei Date: Wed, 29 Jul 2026 14:21:34 +0800 Subject: [PATCH] =?UTF-8?q?docs(todo):=20=E8=A3=9C=E8=A8=98=20App=20?= =?UTF-8?q?=E7=AB=AF=E5=AF=A6=E8=B7=91=E6=9F=A5=E5=87=BA=E7=9A=84=E5=9B=9B?= =?UTF-8?q?=E5=80=8B=E5=BE=8C=E7=AB=AF=E7=BC=BA=E5=8F=A3=EF=BC=88T1?= =?UTF-8?q?=E2=80=93T4=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit App 的搶單/多裝置/弱網三輪 debug 對真後端逐則印 payload 查出四件事, 但先前只寫在 fleet-app 的 TODO:接單/放棄失敗回 200+文案(應為 409)、 沒搶到的司機收不到任何事件、逾時取消只通知乘客、多裝置位置互相覆蓋且無踢舊 session。 後端這份清單上沒有它們,等於這些缺口沒人會排進後端的工作。 ride.stop_updated 只推乘客那一項已於 PR #53 修掉,一併標記。 Co-Authored-By: Claude Opus 5 --- docs/TODO.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) 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 加入,尚未實作,皆需後端地基先行)**: