feat(backend): service 层与 DTO,核心计算逻辑落位

Phase 1.3a。Phase 1.2 留的 repo 现在有了真正的业务出口,Phase 1.3b 紧接
handler / router 把 HTTP 接进来,业务就能跑通。

新增:
- pkg/decimal/money.go
  * PricePerLiter(total, liters)   服务端实时算实际油价,落库
  * ConsumptionL100km(l, mileage)  百公里油耗,只用于 is_full 序列
  * CostPerKm(amount, mileage)     每公里成本
  * Mileage(cur, prev)             行驶里程,负数 / 零视为无效
  * AvgFloat64(xs)                 求平均,空切片返回 0
  全部走 shopspring/decimal,避免 float64 累计误差

- internal/dto/dto.go
  * VehicleCreate / VehicleUpdate (patch 语义,*T 表示可选)
  * RefuelCreate / RefuelUpdate
  入参校验走 gin-validator 的 tag:required / gte / gt / max
  (Liters > 0、TotalAmount >= 0、Odometer >= 0 与 plan §16 一致)

- internal/service/vehicle.go
  * Create 时若 default_vehicle=true,事务内先 ClearDefault 再 Insert,
    避免出现两个默认车辆
  * Update 同样事务化 default 切换
  * SetDefault 是显式接口,业务上"切默认车"是常用操作
  全部错误用 apperror 包成 NotFound / InvalidArg / Internal

- internal/service/refuel_record.go
  * Create:校验车辆存在 + Liters > 0 + TotalAmount >= 0,服务端
    实时计算 price_per_liter,RefuelTime 统一转 UTC 存库
  * Update:patch 语义,liters / total_amount 任一变更都重新算
    price_per_liter(否则历史单价会失真)
  * Statistics(单车):返回 累计次数 / 累计升数 / 累计金额 / 平均油价 /
    标准百公里油耗 / 每公里成本 / 最近一次加油
    关键实现:仅在"连续两次 is_full=true"之间采油耗样本,
    半箱油 / 部分加油记录不会污染标准油耗 ——
    这条规则直接来自 plan §6.3 与 §19 验收要求

业务规则(AGENTS.md 强约束):
  车辆名称 / 能源类型 不允许为空(trim 后空字符串也拒)
  加油量 > 0、总金额 >= 0、里程 >= 0 都在 service 入参立即校验
  RefuelTime 统一 UTC 存库,展示按本地时区格式化
  默认车辆唯一,切换走事务,杜绝"两个默认"

未做(留给 Phase 1.3b 下一个 commit):
- HTTP handler / router / main 装配
- 单元测试(本文件不含测试,等所有 service 稳定后单独提一个测试 commit)
- Dashboard / 统计 API(基础 Statistics 已就绪,Dashboard endpoint
  留给 Phase 1.3b 末尾)

验证:
  go mod tidy    all modules verified
  go vet ./...   0 issues
  go build       25.9 MB binary
This commit is contained in:
2026-09-13 16:06:21 +08:00
parent f4c42bbb9e
commit df5db7bc36
6 changed files with 524 additions and 0 deletions
+69
View File
@@ -0,0 +1,69 @@
// Package decimal 提供金额与油耗计算相关的精度保护。
//
// 计算原则(严格按 FuelLog_PLAN.md §6):
// - 实际油价 = 总金额 / 加油量
// - 行驶里程 = 本次里程 - 上一次有效里程
// - 百公里油耗 = 加油量 / 行驶里程 * 100
// - 每公里燃油成本 = 燃油费用 / 行驶里程
//
// 所有除法走 shopspring/decimal,避免 float64 在金额上累计误差。
package decimal
import (
"github.com/shopspring/decimal"
)
// PricePerLiter 计算实际油价(元/升)。
// 若 liters <= 0,返回零值;调用方应保证 liters > 0(后端已强校验)。
func PricePerLiter(totalAmount, liters float64) float64 {
if liters <= 0 {
return 0
}
t := decimal.NewFromFloat(totalAmount)
l := decimal.NewFromFloat(liters)
return t.Div(l).Round(4).InexactFloat64()
}
// ConsumptionL100km 计算百公里油耗(升/100 公里)。
// 若 mileage <= 0,返回 0;调用方需保证 mileage > 0(半箱油场景应在 service 跳过)。
func ConsumptionL100km(liters, mileage float64) float64 {
if mileage <= 0 {
return 0
}
l := decimal.NewFromFloat(liters)
m := decimal.NewFromFloat(mileage)
// L/100km = liters / mileage * 100
return l.Div(m).Mul(decimal.NewFromInt(100)).Round(2).InexactFloat64()
}
// CostPerKm 计算每公里燃油成本(元/公里)。
// 若 mileage <= 0,返回 0。
func CostPerKm(totalAmount, mileage float64) float64 {
if mileage <= 0 {
return 0
}
t := decimal.NewFromFloat(totalAmount)
m := decimal.NewFromFloat(mileage)
return t.Div(m).Round(4).InexactFloat64()
}
// Mileage 计算两次加油之间的行驶里程。负数 / 零视为无效,返回 0。
func Mileage(current, previous float64) float64 {
d := current - previous
if d <= 0 {
return 0
}
return d
}
// AvgFloat64 返回一组数的算术平均值,空切片返回 0。
func AvgFloat64(xs []float64) float64 {
if len(xs) == 0 {
return 0
}
sum := decimal.Zero
for _, x := range xs {
sum = sum.Add(decimal.NewFromFloat(x))
}
return sum.Div(decimal.NewFromInt(int64(len(xs)))).Round(2).InexactFloat64()
}