Skip to content

feat(O6+P5): 寵物車清潔費(計費/落帳/報表分項)+乘客可讀費率端點 - #31

Merged
thothawei merged 1 commit into
mainfrom
claude/o6-cleaning-fee
Jul 17, 2026
Merged

thothawei merged 1 commit into
mainfrom
claude/o6-cleaning-fee

Conversation

@thothawei

Copy link
Copy Markdown
Owner

Stacked PR:base 是 #30(O2/O3/P1-P4),請先合併 #30。O6 的清潔費要靠 P1 的 rides.required_vehicle_type 判斷是否加收。

實作 O6(寵物車清潔費) 與 P5(乘客可讀費率端點)。P 章節至此全數完成。

O6 計費

Quote 簽名改為 Quote(distanceM int, requiredVehicleType string) RideQuote。刻意不留舊 wrapper——留了就是留一個「忘了帶車種=靜靜不收清潔費」的陷阱;改簽名讓漏改的呼叫點直接編譯不過(產品程式碼只有 tracking.go 一處)。

cleaning_fee = floorNtd(fare × pet_cleaning_fee_bps / 10000)   // 僅乘客指定 pet;捨去(利乘客)
commission   = floorNtd(fare × commission_bps / 10000)         // 基準只有 fare,清潔費不計入抽成
driver_net   = fare − commission + cleaning_fee                // 清潔費全額歸司機(清潔成本補償)

判斷依據是 rides.required_vehicle_type,不是 drivers.vehicle_type——Quote 只吃乘客指定的車種,司機車種根本傳不進去。乘客沒指定寵物車、卻剛好被派到寵物車司機時不得加收(那位乘客沒有要求寵物服務)。

報表分項——為什麼必須跟計費同批

daily_driver_earnings 加 cleaning_fee_cents,RollupRideDay/MonthlyDriverStats/DriverMonthlyEarnings 三段 SQL 同步。營業額(revenue_cents)維持只含車資;應付總公司=手續費+月會費,不受清潔費影響。

net_cents 來自 driver_net_amount_cents,該欄已含清潔費 → 不同步加分項欄,司機收入頁的「營業額 − 手續費」就對不上實得(差額正是清潔費),會破壞先前打通的三端對帳。等式因此改為:

營業額 − 手續費 + 清潔費 = 實得(TestCleaningFeeReports 直接斷言這條式子)

migration 000019

欄位 說明
fleet_settings.pet_cleaning_fee_bps CHECK 0..3000——上限 30% 進 DB,不只靠 API。這是乘客實際被收的錢,寫錯就是超收
rides.cleaning_fee_cents nullable,完成時定格(費率快照制)。非寵物車寫 0 而非 NULL:「沒加收」與「舊資料沒這概念」是兩件事
daily_driver_earnings.cleaning_fee_cents NOT NULL DEFAULT 0,彙總欄一律有值

ride.completed payload 加 cleaning_fee_cents,只在 >0 時帶——帶 0 會讓 App 顯示一列「清潔費 NT$0」。

P5:GET /api/customer/fees

customer JWT、唯讀,目前只回 pet_cleaning_fee_bps。回的是 FeeSettings.CustomerJSON()——另建的白名單 map,不是把 admin 的 JSON() 過濾:過濾式寫法日後新增內部費率欄位時容易忘了濾,白名單預設什麼都不給。commission_bps 與 monthly_membership_fee_cents 絕不可外洩。

驗收(實際跑過)

  • go build / go vet / gofmt 綠;service 1069s、repository 619s、handler 47s、constants 全套通過。
  • 單元:清潔費算式(釘住「不計入抽成」的具體數字——正確 2700,誤把清潔費計入基準會變 3300)、只看乘客指定車種、費率 0 不加收、捨去到整數元、上限、P5 白名單(欄位總數為 1)。
  • 整合(真 PostGIS + Redis):TestComplete_指定寵物車落帳清潔費、TestComplete_寵物車司機載到未指定的乘客不加收(最容易寫錯的一條)、TestCleaningFeeReports、TestFleetSettingsPetCleaningFeeCap(DB CHECK 擋 3001/負值)、TestPetCleaningFeeMigrationReversible。
  • 反向驗證(皆確認對應測試 FAIL):清潔費計入抽成基準 → 手續費 3300;CustomerJSON 改回 JSON() → 手續費/月會費整組外洩;Quote 改吃司機車種 → 未指定的乘客被加收。

未驗:docker compose 起全服務的 live E2E。

順帶

抽出 newMigrateHandle test helper 供可逆性測試共用(P1 的測試改用它),helper 註解記下「用版本而非 Steps(-1)」的理由——Steps(-1) 卸的是最新 migration,新增 migration 時會讓舊測試安靜地失去覆蓋(O1 踩過)。

下游待同步(別的 repo,後果是「少一個分項」而非算錯錢)

  • admin:費率設定頁加 pet_cleaning_fee_bps;月報表加 total_cleaning_fee_cents 分項欄。
  • App:完成卡分項顯示(CompletedRideSummary 加 cleaningFeeCents);司機收入頁改用「營業額 − 手續費 + 清潔費 = 實得」(GET /api/driver/earnings 已回 total_cleaning_fee_cents)。

下一步

O 章節剩 O4(乘客端可見車輛資訊)/O5(admin 呈現,可選)/O7(車輛快照+司機電話+留言板)。建議 O4+O7 同批——兩者改同一批地方。

🤖 Generated with Claude Code

O6 計費:Quote 簽名改為 Quote(distanceM, requiredVehicleType) RideQuote。
刻意不留舊 wrapper——留了就是留一個「忘了帶車種=靜靜不收清潔費」的陷阱;
改簽名讓漏改的呼叫點編譯不過(產品碼只有 tracking.go 一處)。

  cleaning_fee = floorNtd(fare × pet_cleaning_fee_bps / 10000)  // 僅乘客指定 pet
  commission   = floorNtd(fare × commission_bps / 10000)        // 基準只有 fare
  driver_net   = fare − commission + cleaning_fee               // 清潔費全額歸司機

判斷依據是 rides.required_vehicle_type,不是 drivers.vehicle_type:Quote 只吃乘客
指定的車種,司機車種傳不進去。乘客沒指定寵物車卻剛好被派到寵物車司機時不得加收。

報表分項與計費同批(不可分開):daily_driver_earnings 加 cleaning_fee_cents,
RollupRideDay/MonthlyDriverStats/DriverMonthlyEarnings 三段 SQL 同步。營業額維持
只含車資、應付總公司不受影響。net_cents 已含清潔費,不加分項欄則司機收入頁的
「營業額 − 手續費」對不上實得,破壞既有三端對帳。等式改為
「營業額 − 手續費 + 清潔費 = 實得」,測試直接釘住。

migration 000019:fleet_settings.pet_cleaning_fee_bps(CHECK 0..3000,上限進 DB)、
rides.cleaning_fee_cents(nullable,完成時定格)、daily_driver_earnings.cleaning_fee_cents。
ride.completed payload 加 cleaning_fee_cents,只在 >0 時帶(帶 0 會讓 App 顯示
一列「清潔費 NT$0」)。

P5:GET /api/customer/fees(customer JWT,唯讀)回 CustomerJSON()——另建白名單 map,
不是過濾 admin 的 JSON();過濾式寫法日後加欄位容易忘了濾。

順帶:抽出 newMigrateHandle test helper(可逆性測試共用),並把 P1 的可逆性測試
改用它。helper 註解記下「用版本而非 Steps(-1)」的理由。

驗收:build/vet/gofmt 綠;service 1069s、repository 619s、handler 47s、constants
全套通過。反向驗證 3 項皆確認 FAIL:清潔費計入抽成基準(手續費 2700→3300)、
CustomerJSON 改回 JSON()(手續費/月會費外洩)、Quote 改吃司機車種(未指定的乘客被加收)。

下游待同步(別的 repo,後果是少一個分項而非算錯錢):admin 費率頁與月報表分項欄、
App 完成卡分項與司機收入頁等式。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@thothawei
thothawei force-pushed the claude/o6-cleaning-fee branch from 98ed4c7 to 17d48cc Compare July 17, 2026 06:30
@thothawei
thothawei merged commit f09c523 into main Jul 17, 2026
1 check passed
@thothawei
thothawei deleted the claude/o6-cleaning-fee branch July 28, 2026 00:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant