建立:2026-07-07(line-fleet-dispatch)。承接 gap-analysis-plan 的 D 節,把「後端缺哪些 API」拆到端點層級。 依據:實測
cmd/server/main.go路由 +internal/handler|service現有方法。 重點結論:叫車/派單/取消/軌跡的核心 service 幾乎都已存在(RideService.CreateFromLocation、DispatchService.*、RideQueryService.TrackGeoJSON),缺的主要是「寫入類後台功能」與「推播/Phase C」,而非重寫邏輯。
| Method | Path | 認證 | 說明 |
|---|---|---|---|
| POST | /webhook/line |
LINE 簽章 | LINE 叫車入口(只帶 pickup,無目的地) |
| GET | /ws |
JWT | 即時位置/事件通道 |
| POST | /api/{driver,customer,admin}/register·/login |
公開 | 三種身分註冊/登入 |
| POST | /api/rides |
customer JWT | 乘客 App 下單(可帶 dropoff) |
| GET | /api/customer/rides/active·/api/customer/rides/:id |
customer JWT | 乘客查進行中/單筆訂單 |
| POST | /api/rides/:id/cancel-by-customer |
customer JWT | 乘客 App 取消 |
| GET | /api/driver/me |
driver JWT | 司機個人資料 |
| POST | /api/driver/online·/api/driver/offline |
driver JWT | 司機上線/下線 |
| GET | /api/driver/rides/active |
driver JWT | 司機進行中訂單(含 dropoff) |
| POST | /api/driver/location |
driver JWT | 回報 GPS |
| POST | /api/rides/:id/{accept,pickup,complete,cancel,decline} |
driver JWT | 司機行程操作 |
| GET | /api/rides/:id/track |
MultiAuth JWT | 軌跡 GeoJSON(本趟乘客/司機/admin) |
| GET | /api/admin/{fleet,drivers,rides,rides/:id,reports/daily} |
admin JWT | 後台唯讀 |
| PATCH | /api/admin/drivers/:id/status |
admin JWT | 司機啟用/停用 |
| GET·PUT | /api/admin/settings/dispatch |
admin JWT | 派單參數(執行期可調) |
| POST | /api/admin/rides/:id/cancel |
admin JWT | 後台強制取消 |
已下架:
GET /api/reports/daily(公開版,2026-07-08 移除)。
| # | Method | Path | 認證 | 說明 | 複用 |
|---|---|---|---|---|---|
| 1 | POST | /api/rides |
customer JWT | ✅ 已實作(RideService.CreateByCustomer 含進行中訂單守門,internal/handler/ride.go Create,commit 4f2ec93)。App 直接下單叫車(帶上車/目的地座標) |
複用 CreateFromLocation 核心 |
| 2 | GET | /api/customer/rides/active |
customer JWT | ✅ 已實作(RideQueryService.GetActiveRideByCustomer,internal/handler/ride.go ActiveByCustomer)。乘客當前進行中訂單(App 啟動/重連要靠它取得 ride_id 才能 WS 訂閱) |
新增 GetActiveRideByCustomer |
| 3 | GET | /api/customer/rides/:id |
customer JWT | ✅ 已實作(RideQueryService.GetRideForCustomer,internal/handler/ride.go GetByCustomer,含 owner 檢查)。乘客看自己單一訂單狀態/司機/ETA |
複用 ride repo,加 owner 檢查 |
| 4 | POST | /api/rides/:id/cancel-by-customer |
customer JWT | ✅ 已實作(DispatchService.CancelByCustomerID,internal/handler/ride.go CancelByCustomer,複用 cancelActiveRide 核心)。乘客端 App 取消(現取消只認 LINE 文字「取消」) |
DispatchService.CancelByCustomer(改吃 customer_id) |
註:#1 已支援選填
dropoff_address/dropoff_lat/dropoff_lng(commit 345b7ad)。
| # | Method | Path | 認證 | 說明 |
|---|---|---|---|---|
| 5 | GET | /api/driver/me |
driver JWT | ✅ DriverHandler.Me→DriverRegistry.Me。回 driver_id/name/phone/status(不含密碼雜湊) |
| 6 | POST | /api/driver/online·/api/driver/offline |
driver JWT | ✅ DriverRegistry.GoOnline/GoOffline。online→Idle(載客中不降級)、offline→Offline(乾淨移出派單池,dispatch 以 status 過濾);載客中下線回 409(ErrDriverOnTrip) |
| 7 | GET | /api/driver/rides/active |
driver JWT | ✅ DriverHandler.ActiveRide→RideQueryService.GetActiveRideByDriver(複用 FindActiveByDriver,回 Accepted/PickedUp)。無則 {"ride":null}。訂單 JSON 含 dropoff 欄位 |
| 8 | POST | /api/rides/:id/decline |
driver JWT | ✅ RideHandler.Decline→DispatchService.DeclineOffer(複用既有)。記錄拒接,重派跳過此司機,司機仍待命 |
驗證:service 整合測試(上下線狀態轉移+載客中守門、GetActiveRideByDriver)+對真 server 實跑 全部端點(me/online/offline/rides·active/decline 皆回正確狀態;track owner 200/他人 403)。
✅ P1 小尾巴——dropoff 資料鏈補全(2026-07-10)
- 下單流程:App
/api/ridesPOST + LINE webhook 均支援 dropoff_lat/lng/address 參數傳入- 資料層:RideRepository.Create() 條件式存 dropoff_point (PostGIS geography) 與 dropoff_address
- 派單事件:DispatchService.pushOffer() Payload 包含完整 ride object(含 dropoff),司機 WS 訂閱即可取得導航資訊
- 驗收:單元測試 (ride_dropoff_test.go with/without cases)、整合測試 (testcontainers PostGIS)、煙霧測試 (真實伺服器端點驗證 DB 寫入)
- 結果:司機「上車後導航去目的地」資料鏈已通暢
| # | Method | Path | 認證 | 說明 |
|---|---|---|---|---|
| 9 | PATCH | /api/admin/drivers/:id/status |
admin JWT | ✅ AdminHandler.PatchDriverStatus→AdminOperations.SetDriverEnabled。body {"enabled":true/false};停用→DriverStatusDisabled(3)+移出 Redis GEO;載客中停用回 409;啟用→Offline |
| 10 | GET·PUT | /api/admin/settings/dispatch |
admin JWT | ✅ 執行期 DispatchSettings(記憶體,重啟還原 env):radius_m/max_drivers/offer_timeout_sec/max_attempts/rate_limit_per_min |
| 11 | POST | /api/admin/rides/:id/cancel |
admin JWT | ✅ AdminHandler.CancelRide→CancelRideByAdmin,複用 cancelActiveRide(已上車不可取消) |
| 12 | POST·GET·DELETE | /api/admin/admins |
admin JWT | 後台使用者管理(開/停後台帳號);配 RBAC 才有意義(優先度依需求) |
| # | Method | Path | 認證 | 說明 |
|---|---|---|---|---|
| 13 | POST·DELETE | /api/driver/device-token |
driver JWT | ✅ 2026-07-08(DeviceTokenHandler,存 device_tokens;推播走 notify.LogPusher stub,可換真 FCM) |
| 14 | POST·DELETE | /api/customer/device-token |
customer JWT | ✅ 同上 |
端點只是入口;核心是後端推播抽象層(LINE / FCM / APNs 可切換)+
device_tokens表(見 gap-plan D1)。
| # | Method | Path | 認證 | 說明 |
|---|---|---|---|---|
| 15 | POST | /api/customer/rides/estimate |
customer JWT | ✅ 2026-07-23(R;EstimateService,與完成計費共用 FeeSettings.Quote) |
| 16 | POST | /api/customer/rides/:id/rating |
customer JWT | ✅ 2026-07-27(S;1–5 星+評論,一趟一評。讀回:CustomerRideView.rating/歷史列 rating_score//driver/me 的 rating_avg) |
| 17 | GET | /api/customer/rides |
customer JWT | ✅ 2026-07-19(H;ListRecentByCustomer,新到舊、只回本人) |
| 18 | GET | /api/driver/rides |
driver JWT | 司機歷史/收入列表(部分由 GET /api/driver/earnings 涵蓋,F7) |
| 19 | POST | /api/rides/:id/payment |
customer JWT | 金流請款(預授權→行程後扣款) |
| 20 | GET | /metrics |
內網/無 | Prometheus 指標(派單成功率、接單耗時、在線司機數、API 延遲) |
-
GET /api/rides/:id/track:✅ 已補認證(2026-07-08)。新增middleware.MultiAuth(接受 driver/customer/admin 任一合法 token),授權在RideQueryService.AuthorizeTrackAccess——admin 全放行、本趟乘客、被指派司機皆可,其餘 403、訂單不存在 404。後台前端不受影響(其軌跡走/admin/rides/:id內嵌的track_geojson,非此端點)。scripts/smoke_test.sh已同步(2026-07-08)。 -
GET /api/reports/daily:✅ 已下架公開版(2026-07-08)。移除路由與未用的reportHandler,刪除internal/handler/report.go(死碼);只留 admin 版/api/admin/reports/daily(reportRepo 仍供 admin handler 使用)。smoke_test.sh改走 admin JWT。
-
GeoPoint.Scanno-op → ✅ 已補(2026-07-08)。實作 EWKB 解析(支援大小端、SRID 旗標、hex 字串/位元組/原始位元組三種 pgx 回傳型態,NULL 為 no-op)。單元測試internal/model/models_test.go+ 對真 PostGIS 的 round-trip 整合測試internal/service/geopoint_roundtrip_test.go(pickup_point 由 (0,0) 修為正確 25.03/121.56)。 -
model.RideJSON tag → ✅ 已加 snake_case tag(含dropoff_point/dropoff_address暴露);GeoPoint加lat/lngtag。 - App 下單寫入 dropoff → ✅ 已補(2026-07-08,commit 345b7ad)。
CreateByCustomer持久化dropoff_address/lat/lng;rides/active與ride.acceptedWS 事件回傳;司機 App 上車後導航去目的地已通。 -
ride.assigned派單事件 dropoff → ✅ 已補(2026-07-08)。rideAssignedPayload帶dropoff_address/lat/lng;司機接單前可預覽。LINE 叫車仍無目的地。
~~P0(#1→#2→#3→#4)~~ ✅ 已完成(2026-07-07),乘客 App 端到端已解鎖
~~安全洞(track 補認證 / reports 下架)~~ + ~~資料層(GeoPoint.Scan / JSON tag / dropoff)~~ ✅ 已完成(2026-07-08)
~~P1(#5~#8 司機 App 可靠性)~~ ✅ 已完成(2026-07-08)
→ ~~P2(#9,#10,#11 後台寫入)~~ ✅ 已完成(2026-07-08),可對接前端 C2/C3
→ P3(#13,#14 推播) 配合 App A2/FCM
→ P4 Phase C 依商業需求
| 編號 | 端點 | 缺什麼 | 狀態 |
|---|---|---|---|
| #15 | GET /api/admin/rides |
offset、from/to(依 requested_at)、q(上車點/訂單 ID) |
✅ 2026-07-10 完成 |
GET /api/admin/rides?status=&limit=&offset=&from=&to=&q=
| 參數 | 型別 | 說明 |
|---|---|---|
status |
int16 | 訂單狀態;省略=全部 |
limit |
int | 1~500,預設 100;超出範圍回 400 |
offset |
int | ≥0,預設 0 |
from / to |
YYYY-MM-DD |
依 requested_at 的日期篩選,含頭尾;沿用 DailyDriverStats 的 ::date 慣例。from > to 回 400 |
q |
string | 上車點地址 ILIKE 模糊比對,或訂單 ID 的子字串比對;前後空白會去除 |
回應:
{ "rides": [...], "total": 42, "limit": 100, "offset": 0 }total是符合條件的總筆數,不受limit/offset影響,供前端分頁器使用。- 空結果的
rides是[]而非null。 - 排序固定為
id DESC(新到舊)。 - 參數格式錯誤一律回 400 並帶中文
error訊息(原本是靜默忽略)。
實作:RideRepository.List(RideListFilter) 回 (rows, total, err);ListRecent 保留為薄包裝供既有呼叫端使用。
Query 解析抽成純函式 parseRideListFilter(url.Values),故 CI 無 Docker 也測得到。
- 全部沿用既有
Handler → Service → Repository分層;下單/取消優先包裝既有 service,不重寫派單。 - 寫入端點的
ride_events審計(gap-plan D4)✅ 2026-07-08(migration000009+ 狀態轉換寫入 + admin 詳情events)。整合測試(testcontainers)仍可後補。 - 完成一段 → 對照驗收實跑 → commit + push(main,thothawei 金鑰)→ 回填本清單勾選框。
- 煙霧測試:
bash scripts/smoke_test.sh(track 帶司機 JWT、日報帶 admin JWT)。