Skip to content
Merged
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
1 change: 1 addition & 0 deletions cmd/server/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,7 @@ func main() {
trackingService.SetFeeSettings(feeSettings)
trackingService.SetOSRM(osrm) // F3:軌跡里程偏低時以 OSRM 路線里程作計費地板
trackingService.SetReports(reportRepo) // F9-3:完成時重算每日彙總 daily_driver_earnings
trackingService.SetStops(rideStopRepo) // N5:多停靠點行程改用全程多點路線計費
driverRegistry := service.NewDriverRegistry(driverRepo)
rideQueryService := service.NewRideQueryService(trackRepo, rideRepo)
rideQueryService.SetDrivers(driverRepo) // O4/O7:乘客查自己訂單時附司機姓名/電話
Expand Down
53 changes: 43 additions & 10 deletions docs/TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -316,9 +316,34 @@
(真 FCM 是 A2 待辦)。故 stops 目前**只走 WS**。此提醒已移到
`rideAssignedPayload` 的註解,留給日後做真 FCM 的人(見 pitfall-fcm-data-all-strings)。

- [ ] **N5. 計費改吃「全程實際路線」** ✅ **已定案(2026-07-16 使用者拍板)**
- [x] **N5. 計費改吃「全程實際路線」** ✅ **已實作(2026-07-17)**(定案 2026-07-16)
(`internal/osrm/client.go` + `tracking.go` `Complete`)

**實作內容**:
1. **`osrm.Client.RouteVia(ctx, []Point)`**:URL 依序串接所有座標(`;` 分隔,`lng,lat` 順序)。
**既有兩點 `RouteDuration` 完全不動**——派單 ETA 與 F3 既有行為不受影響。
`Point` 型別自訂而非用 `model.GeoPoint`:osrm 是最底層的外部服務 client,不該依賴領域模型。
2. **`fallbackVia` 逐段累加**:OSRM 掛掉時逐段 haversine×1.4 再取和。
3. **`TrackingService.routeDistanceM`**:有未跳過的停靠點(≥2)就走全程多點路線,
否則退回現行兩點直達(相容單點訂單)。**`billableDistanceM` 取大者的邏輯完全不變**。

**已跳過的停靠點不計入**(2026-07-17 拍板「司機可跳過」的衍生結論):
沒去就沒開那段路,計入等於收乘客沒走的路的錢。軌跡那側本來就自然反映(沒去就沒軌跡)。
跳過後不足兩點時退回兩點直達,不會失敗。

**不必把 `ride.PickupPoint` 另外補進路線**:N3 已保證 `rides.pickup_point` = 第一個 pickup stop、
`dropoff_point` = seq 最大的 dropoff stop,兩者本來就在 stops 裡(補了會重複計算)。

**驗收**:`go build`/`vet`/`gofmt` 綠。
單元(`internal/osrm`,無需容器):URL 依序串接所有座標且為 `lng,lat`、點數不足回 `ErrTooFewPoints`、
**OSRM 掛掉時逐段累加**(繞路里程 > 直達,且等於手動逐段和)、nil client 走退路。
整合(真 PostGIS + fake OSRM 伺服器,斷言實際送出的座標):多停靠點走全程路線、
**跳過的站不計入**、單點訂單維持兩點直達、全部跳過時退回兩點。
**反向驗證**:拿掉 `st.Skipped()` 過濾 → 已跳過的座標出現在計費路線,FAIL;
`fallbackVia` 改成只算頭尾 → 繞路(7040) = 直達(7040),繞路被漏掉,FAIL。
**未驗**:docker compose 全服務 live E2E(含真 OSRM)。

原始定案內容如下(保留供對照):
**定案**:車資=**全程實際路線**(起點 → 各停靠點 → 最終目的地,**含繞路**),
不是「起點→最終目的地」的直達路線。理由:司機真的開了那些路,繞路不該做白工;
也與現行「軌跡 vs 路線取大者」的精神一致。
Expand Down Expand Up @@ -798,15 +823,23 @@
清潔費依乘客指定車種、上限 30%、**不計入抽成**/不降級+取消原因明確化/customer fees 端點/
**電話明碼、僅該趟乘客可見**)——**N、O、P 規格完備,可開始實作**,
建議順序:O1→O2→O3(車輛地基)→ P1→P2→P3+P4(車種)→ O6+P5(清潔費)→ O4/O7(乘客可見)→ N(多停靠點,最大塊)。
**進度:O1/O2/O3/O4/O6/O7 ✅、P1–P5 ✅(O1 為 2026-07-16,其餘皆 2026-07-17)
→ **N、O、P 三章中的 O 與 P 已全數完成**,只剩 **O5(admin 呈現/審核,可選、待拍板)**。
後端能力已到位:司機填車輛才能接單 → 乘客指定車種 → 只派同車種、找不到明確取消 →
依乘客指定車種加收清潔費、報表分項 → 乘客看得到車種車牌與司機電話、對話無時間限制。

**下一項建議**:**N(多乘客/多停靠點)**——三章中僅存的大塊,需擴充 OSRM client
支援多 waypoint(現行介面寫死兩點)並讓 haversine 退路逐段累加。
或先補 **下游 UI 同步**(admin 費率頁/月報表分項、App 完成卡分項+車輛資訊+強制填寫跳轉),
否則後端做完的能力在兩端都還看不到。**
**進度:N1–N7 ✅、O1/O2/O3/O4/O6/O7 ✅、P1–P5 ✅
(O1 為 2026-07-16,其餘皆 2026-07-17)
→ **N、O、P 三章全數完成**,只剩 **O5(admin 呈現/審核,可選、待拍板)**。

後端能力已到位:司機填車輛才能接單 → 乘客指定車種(可帶多乘客/多停靠點)→
只派同車種、找不到明確取消 → 司機看得到全程、可標記到站/跳過 →
完成時依**全程實際路線**(排除已跳過)計費、依**乘客指定車種**加收清潔費、報表分項 →
乘客看得到車種車牌與司機電話、對話無時間限制。

**下一項建議:補下游 UI**——後端已跑在兩端前面很遠,做完的能力在 admin 與 App 都還看不到:
- **admin**:費率頁 `pet_cleaning_fee_bps`、月報表清潔費分項欄、(O5 若要做)車輛審核。
- **App**(見 [line-fleet-app/docs/TODO.md](../../line-fleet-app/docs/TODO.md)):
司機車輛設定頁+強制跳轉、乘客端車種選擇+清潔費預告、完成卡分項、
司機收入頁等式改「營業額 − 手續費 + 清潔費 = 實得」、多停靠點編輯與司機端全程顯示。

**其餘後端項目**:O5(待拍板);N 的衍生風險——乘客建單時看不到預估車資
(繞路越多車資越高),若要「先報價」需要一支以全程路線試算的報價 API,目前**沒有**。**

計費地基 **F1–F8+F3 里程退路+F9-1~F9-6+M 整數台幣 已全數合併進 main**,三端對帳與 F3/F9-3/F9-4 皆 docker E2E 驗過。
其餘皆屬「量體上升後才需」的大資料量最佳化,勿過早做:
Expand Down
67 changes: 67 additions & 0 deletions internal/osrm/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@ package osrmclient
import (
"context"
"encoding/json"
"errors"
"fmt"
"net/http"
"strings"
"time"

"line-fleet-dispatch/internal/util"
Expand Down Expand Up @@ -70,3 +72,68 @@ func fallbackETA(fromLat, fromLng, toLat, toLng float64) (int, int, error) {
roadDist := dist * 1.4
return util.EstimateETASec(roadDist), int(roadDist), nil
}

// Point 路徑上的一個座標點(N5)。
// 自訂而非用 model.GeoPoint:osrm 是最底層的外部服務 client,不該依賴領域模型。
type Point struct {
Lat, Lng float64
}

// ErrTooFewPoints 多點路線至少要兩個座標點。
var ErrTooFewPoints = errors.New("路線至少需要兩個座標點")

// RouteVia 計算「依序經過所有點」的全程路線(N5):起點 → 各停靠點 → 終點,**含繞路**。
//
// OSRM 的 /route/v1 本來就支援多座標(`;` 分隔),是我們的 client 之前只開放兩點。
// 既有的兩點 RouteDuration **保留不動**——派單 ETA 與 F3 的既有行為不受影響。
//
// 失敗時退回逐段 haversine 累加(見 fallbackVia)。
func (c *Client) RouteVia(ctx context.Context, points []Point) (durationSec int, distanceM int, err error) {
if len(points) < 2 {
return 0, 0, ErrTooFewPoints
}
if c == nil {
return fallbackVia(points)
}
coords := make([]string, 0, len(points))
for _, p := range points {
// OSRM 的座標順序是 lng,lat——對調會把台北送到別的半球。
coords = append(coords, fmt.Sprintf("%f,%f", p.Lng, p.Lat))
}
url := fmt.Sprintf("%s/route/v1/driving/%s?overview=false", c.baseURL, strings.Join(coords, ";"))

req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return fallbackVia(points)
}
resp, err := c.httpClient.Do(req)
if err != nil {
return fallbackVia(points)
}
defer resp.Body.Close()

if resp.StatusCode >= 300 {
return fallbackVia(points)
}
var data routeResponse
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil || data.Code != "Ok" || len(data.Routes) == 0 {
return fallbackVia(points)
}
return int(data.Routes[0].Duration), int(data.Routes[0].Distance), nil
}

// fallbackVia OSRM 不可用時的多點退路:**逐段**累加再取和(N5 明確要求)。
//
// 不可以只算頭尾兩點——那會把繞路全部漏掉,多停靠點行程的退路里程會退化成直達距離;
// 而 billableDistanceM 取「軌跡 vs 路線」大者時就只剩軌跡可用,軌跡若稀疏(見 F3)
// 就會嚴重低估車資。
func fallbackVia(points []Point) (int, int, error) {
if len(points) < 2 {
return 0, 0, ErrTooFewPoints
}
total := 0.0
for i := 1; i < len(points); i++ {
total += util.HaversineM(points[i-1].Lat, points[i-1].Lng, points[i].Lat, points[i].Lng) * 1.4
}
return util.EstimateETASec(total), int(total), nil
}
107 changes: 107 additions & 0 deletions internal/osrm/route_via_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
package osrmclient

import (
"context"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"strings"
"testing"
)

// 台北四個點,構成一趟繞路行程。
var (
taipeiMain = Point{Lat: 25.0478, Lng: 121.5170} // 台北車站
cityHall = Point{Lat: 25.0339, Lng: 121.5645} // 市政府
songshan = Point{Lat: 25.0697, Lng: 121.5522} // 松山機場
taipei101 = Point{Lat: 25.0339, Lng: 121.5645} // 台北101
)

// TestRouteVia_URL串接所有座標 OSRM 的 /route/v1 支援多座標(`;` 分隔),
// 之前只是我們的 client 沒開放。
func TestRouteVia_URL串接所有座標(t *testing.T) {
var gotPath string
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
gotPath = r.URL.Path
_ = json.NewEncoder(w).Encode(map[string]any{
"code": "Ok",
"routes": []map[string]any{{"duration": 1234.0, "distance": 8888.0}},
})
}))
defer srv.Close()

c := NewClient(srv.URL)
sec, distM, err := c.RouteVia(context.Background(), []Point{taipeiMain, cityHall, songshan})
if err != nil {
t.Fatalf("RouteVia 失敗:%v", err)
}
if sec != 1234 || distM != 8888 {
t.Fatalf("應回 OSRM 的數值,得到 %d 秒 / %d 公尺", sec, distM)
}

// 座標順序必須是 lng,lat——對調會把台北送到別的半球。
wantCoords := "121.517000,25.047800;121.564500,25.033900;121.552200,25.069700"
if !strings.Contains(gotPath, wantCoords) {
t.Fatalf("URL 應依序串接所有座標(lng,lat):\n得到 %s\n預期含 %s", gotPath, wantCoords)
}
}

// TestRouteVia_點數不足 少於兩點無法構成路線。
func TestRouteVia_點數不足(t *testing.T) {
c := NewClient("http://unused")
for _, pts := range [][]Point{nil, {taipeiMain}} {
if _, _, err := c.RouteVia(context.Background(), pts); !errors.Is(err, ErrTooFewPoints) {
t.Fatalf("預期 ErrTooFewPoints,得到 %v", err)
}
}
}

// TestRouteVia_OSRM掛掉時逐段累加 N5 明確要求:退路要**逐段**算再取和。
//
// 只算頭尾兩點會把繞路全部漏掉——多停靠點的退路里程退化成直達距離,
// billableDistanceM 取大者時就只剩軌跡可用,軌跡稀疏(F3)就會嚴重低估車資。
func TestRouteVia_OSRM掛掉時逐段累加(t *testing.T) {
// 500 → 走 fallback。
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusInternalServerError)
}))
defer srv.Close()
c := NewClient(srv.URL)

// 繞路:台北車站 → 松山機場 → 台北101(先北再南)。
viaRoute := []Point{taipeiMain, songshan, taipei101}
_, viaM, err := c.RouteVia(context.Background(), viaRoute)
if err != nil {
t.Fatalf("fallback 不該失敗:%v", err)
}

// 直達:台北車站 → 台北101。
_, directM, err := c.RouteVia(context.Background(), []Point{taipeiMain, taipei101})
if err != nil {
t.Fatalf("fallback 不該失敗:%v", err)
}

if viaM <= directM {
t.Fatalf("繞路里程(%d) 應大於直達(%d)——逐段累加沒生效,繞路被漏掉了", viaM, directM)
}

// 逐段和:手動累加兩段,應與 RouteVia 的結果一致。
_, segA, _ := fallbackVia([]Point{taipeiMain, songshan})
_, segB, _ := fallbackVia([]Point{songshan, taipei101})
if diff := viaM - (segA + segB); diff > 1 || diff < -1 {
t.Fatalf("多點退路應等於逐段和:得到 %d,逐段和 %d", viaM, segA+segB)
}
}

// TestRouteVia_nil客戶端走退路 與既有 RouteDuration 的 nil 行為一致。
func TestRouteVia_nil客戶端走退路(t *testing.T) {
var c *Client
_, distM, err := c.RouteVia(context.Background(), []Point{taipeiMain, songshan})
if err != nil {
t.Fatalf("nil client 應走退路而非報錯:%v", err)
}
if distM <= 0 {
t.Fatalf("退路里程應為正數,得到 %d", distM)
}
}
75 changes: 66 additions & 9 deletions internal/service/tracking.go
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ type TrackingService struct {
fees *FeeSettings
osrm *osrmclient.Client
reports *repository.ReportRepository
stops *repository.RideStopRepository

etaMinInterval time.Duration
etaDistThreshold float64
Expand Down Expand Up @@ -93,6 +94,12 @@ func (s *TrackingService) SetReports(reports *repository.ReportRepository) {
s.reports = reports
}

// SetStops 注入停靠點 repo,完成計費時改用全程多點路線(N5);可選——
// 未注入時多停靠點行程會退回兩點直達路線(會低估繞路,但不會失敗)。
func (s *TrackingService) SetStops(stops *repository.RideStopRepository) {
s.stops = stops
}

// publish nil-safe 事件發佈
func (s *TrackingService) publish(rec events.Recipient, ev events.Event) {
if s.publisher == nil {
Expand Down Expand Up @@ -248,6 +255,61 @@ func billableDistanceM(trackM, routeM int) int {
return trackM
}

// routeDistanceM 計費用的路線里程(公尺);-1 =無路線可用(呼叫端改用軌跡里程)。
//
// 多停靠點行程(N5 拍板 2026-07-16)走**全程實際路線**:起點 → 各停靠點 → 最終目的地,
// **含繞路**。司機真的開了那些路,繞路不該做白工;用「起點→終點」的直達路線會嚴重低估。
//
// **已跳過的停靠點不計入**(2026-07-17 拍板的衍生結論):乘客沒出現、司機沒去那站,
// 就沒開那段路,計入等於收乘客沒走的路的錢。軌跡那側本來就自然反映(沒去就沒軌跡)。
//
// 單點訂單、未注入停靠點 repo、或跳過後不足兩點時,一律退回現行的兩點直達路線。
func (s *TrackingService) routeDistanceM(ctx context.Context, ride *model.Ride) int {
if s.osrm == nil {
return -1
}
if pts := s.billableStopPoints(ride.ID); len(pts) >= 2 {
_, routeM, err := s.osrm.RouteVia(ctx, pts)
if err == nil {
log.Info().Int64("ride_id", ride.ID).Int("stops", len(pts)).Int("route_m", routeM).
Msg("計費里程改用全程多點路線(多停靠點行程)")
return routeM
}
log.Error().Err(err).Int64("ride_id", ride.ID).Msg("多點路線計算失敗,退回兩點直達路線")
}
if ride.DropoffPoint == nil {
return -1
}
_, routeM, _ := s.osrm.RouteDuration(ctx,
ride.PickupPoint.Lat, ride.PickupPoint.Lng,
ride.DropoffPoint.Lat, ride.DropoffPoint.Lng)
return routeM
}

// billableStopPoints 依序回傳「要計費」的停靠點座標——即未被跳過者。
// 單點訂單或讀取失敗回 nil(呼叫端退回兩點路線)。
//
// 不必另外把 ride.PickupPoint 補進去:N3 已保證 rides.pickup_point = 第一個 pickup stop、
// dropoff_point = seq 最大的 dropoff stop,兩者本來就在 stops 裡。
func (s *TrackingService) billableStopPoints(rideID int64) []osrmclient.Point {
if s.stops == nil {
return nil
}
stops, err := s.stops.ListByRide(rideID)
if err != nil {
log.Error().Err(err).Int64("ride_id", rideID).Msg("讀取停靠點失敗,計費改用兩點直達路線")
return nil
}
pts := make([]osrmclient.Point, 0, len(stops))
for _, st := range stops {
if st.Skipped() {
continue // 沒去就沒開那段路
}
pts = append(pts, osrmclient.Point{Lat: st.Point.Lat, Lng: st.Point.Lng})
}
return pts
}

func (s *TrackingService) Complete(ctx context.Context, rideID, driverID int64) error {
ride, err := s.rides.GetByID(rideID)
if err != nil {
Expand All @@ -257,15 +319,10 @@ func (s *TrackingService) Complete(ctx context.Context, rideID, driverID int64)
return ErrForbidden
}
trackM, _ := s.rides.TrackDistanceM(rideID)
// F3 退路:GPS 軌跡里程可能為 0 或稀疏而偏低。有目的地座標且已注入 OSRM 時,
// 以 OSRM pickup→dropoff 路線里程作地板,計費里程取「軌跡 vs 路線」大者——
// 軌跡真的長於路線=司機繞路,仍照實計;軌跡偏低則用路線里程補回。
routeM := -1
if s.osrm != nil && ride.DropoffPoint != nil {
_, routeM, _ = s.osrm.RouteDuration(ctx,
ride.PickupPoint.Lat, ride.PickupPoint.Lng,
ride.DropoffPoint.Lat, ride.DropoffPoint.Lng)
}
// F3 退路:GPS 軌跡里程可能為 0 或稀疏而偏低。以 OSRM 路線里程作地板,
// 計費里程取「軌跡 vs 路線」大者——軌跡真的長於路線=司機繞路,仍照實計;
// 軌跡偏低則用路線里程補回。**取大者的邏輯不變**(N5),只有 routeM 的算法要改。
routeM := s.routeDistanceM(ctx, ride)
distanceM := billableDistanceM(trackM, routeM)
if routeM > trackM {
log.Info().Int64("ride_id", rideID).Int("track_m", trackM).Int("route_m", routeM).
Expand Down
Loading
Loading