KennethCheng/FuelLog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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:
KennethCheng
2026-09-13 16:06:21 +08:00
parent f4c42bbb9e
commit df5db7bc36
6 changed files with 524 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
fuellog-api/internal/dto/dto.go
+61
View File
@@ -0,0 +1,61 @@
// Package dto 持有 HTTP 入参与返回 DTO。
//
// 与 model 的区别:
// - model 反映数据库一行;DTO 反映一次 HTTP 请求/响应
// - DTO 字段做基础校验(必填 / 范围)
// - 字段命名贴近用户语言(中文含义在 JSON tag 上保持英文)
package dto
import "time"
// VehicleCreate 新建车辆请求。
type VehicleCreate struct {
Name string `json:"name" binding:"required,max=64"`
Brand string `json:"brand" binding:"max=64"`
Model string `json:"model" binding:"max=64"`
PlateNumber string `json:"plate_number" binding:"max=32"`
FuelType string `json:"fuel_type" binding:"required,max=32"`
TankCapacity float64 `json:"tank_capacity" binding:"gte=0,lte=9999"`
CurrentOdometer float64 `json:"current_odometer" binding:"gte=0"`
DefaultVehicle bool `json:"default_vehicle"`
}
// VehicleUpdate 更新车辆请求。所有字段可选(零值表示"不改")。
// 这里采用 patch 语义:仅传了的字段会被更新。
type VehicleUpdate struct {
Name *string `json:"name"`
Brand *string `json:"brand"`
Model *string `json:"model"`
PlateNumber *string `json:"plate_number"`
FuelType *string `json:"fuel_type"`
TankCapacity *float64 `json:"tank_capacity"`
CurrentOdometer *float64 `json:"current_odometer"`
DefaultVehicle *bool `json:"default_vehicle"`
}
// RefuelCreate 新建加油记录请求。
// 实际油价(price_per_liter)由服务端实时计算,不入参。
type RefuelCreate struct {
VehicleID uint64 `json:"vehicle_id" binding:"required"`
RefuelTime time.Time `json:"refuel_time" binding:"required"`
Odometer float64 `json:"odometer" binding:"required,gte=0"`
FuelType string `json:"fuel_type" binding:"required,max=32"`
Liters float64 `json:"liters" binding:"required,gt=0"`
TotalAmount float64 `json:"total_amount" binding:"gte=0"`
StationName string `json:"station_name" binding:"max=128"`
IsFull bool `json:"is_full"`
Remark string `json:"remark" binding:"max=512"`
}
// RefuelUpdate 更新加油记录请求。
// 同 VehicleUpdate,patch 语义;Liters / TotalAmount 任一变化都触发 price 重新计算。
type RefuelUpdate struct {
RefuelTime *time.Time `json:"refuel_time"`
Odometer *float64 `json:"odometer"`
FuelType *string `json:"fuel_type"`
Liters *float64 `json:"liters"`
TotalAmount *float64 `json:"total_amount"`
StationName *string `json:"station_name"`
IsFull *bool `json:"is_full"`
Remark *string `json:"remark"`
}
fuellog-api/internal/service/refuel_record.go
+208
View File
@@ -0,0 +1,208 @@
package service
import (
"context"
"strings"
"time"
"github.com/kennethcheng/fuellog-api/internal/dto"
"github.com/kennethcheng/fuellog-api/internal/model"
"github.com/kennethcheng/fuellog-api/internal/repository"
"github.com/kennethcheng/fuellog-api/pkg/apperror"
money "github.com/kennethcheng/fuellog-api/pkg/decimal"
)
// RefuelRecordService 加油记录业务逻辑。
type RefuelRecordService interface {
Create(ctx context.Context, in *dto.RefuelCreate) (*model.RefuelRecord, error)
Get(ctx context.Context, id uint64) (*model.RefuelRecord, error)
Update(ctx context.Context, id uint64, in *dto.RefuelUpdate) (*model.RefuelRecord, error)
Delete(ctx context.Context, id uint64) error
ListByVehicle(ctx context.Context, vehicleID uint64, start, end *time.Time) ([]model.RefuelRecord, error)
// Statistics 返回单车的关键统计指标(供 Dashboard 使用)。
Statistics(ctx context.Context, vehicleID uint64) (*RefuelStatistics, error)
}
func NewRefuelRecordService(
recRepo repository.RefuelRecordRepository,
vehicleRepo repository.VehicleRepository,
) RefuelRecordService {
return &refuelService{recRepo: recRepo, vehicleRepo: vehicleRepo}
}
type refuelService struct {
recRepo repository.RefuelRecordRepository
vehicleRepo repository.VehicleRepository
}
// RefuelStatistics 单车统计指标。
type RefuelStatistics struct {
VehicleID uint64 `json:"vehicle_id"`
TotalRecords int `json:"total_records"`
TotalLiters float64 `json:"total_liters"`
TotalAmount float64 `json:"total_amount"`
AvgPrice float64 `json:"avg_price"` // 实际平均油价
AvgConsumption float64 `json:"avg_consumption"` // 标准百公里油耗(仅 is_full=true 序列)
CostPerKm float64 `json:"cost_per_km"` // 每公里成本
LastRefuel *model.RefuelRecord `json:"last_refuel,omitempty"`
}
func (s *refuelService) Create(ctx context.Context, in *dto.RefuelCreate) (*model.RefuelRecord, error) {
// 校验车辆存在
if _, err := s.vehicleRepo.Get(ctx, in.VehicleID); err != nil {
return nil, err
}
if in.Liters <= 0 {
return nil, apperror.New(apperror.CodeInvalidArg, "加油量必须大于 0")
}
if in.TotalAmount < 0 {
return nil, apperror.New(apperror.CodeInvalidArg, "总金额不能小于 0")
}
// 时区规整:统一转 UTC 存库
t := in.RefuelTime.UTC()
if t.IsZero() {
return nil, apperror.New(apperror.CodeInvalidArg, "加油时间不能为空")
}
rec := &model.RefuelRecord{
VehicleID: in.VehicleID,
RefuelTime: t,
Odometer: in.Odometer,
FuelType: strings.TrimSpace(in.FuelType),
Liters: in.Liters,
PricePerLiter: money.PricePerLiter(in.TotalAmount, in.Liters),
TotalAmount: in.TotalAmount,
StationName: strings.TrimSpace(in.StationName),
IsFull: in.IsFull,
Remark: in.Remark,
}
if err := s.recRepo.Create(ctx, rec); err != nil {
return nil, err
}
return rec, nil
}
func (s *refuelService) Get(ctx context.Context, id uint64) (*model.RefuelRecord, error) {
return s.recRepo.Get(ctx, id)
}
func (s *refuelService) Update(ctx context.Context, id uint64, in *dto.RefuelUpdate) (*model.RefuelRecord, error) {
rec, err := s.recRepo.Get(ctx, id)
if err != nil {
return nil, err
}
if in.RefuelTime != nil {
rec.RefuelTime = in.RefuelTime.UTC()
}
if in.Odometer != nil {
rec.Odometer = *in.Odometer
}
if in.FuelType != nil {
rec.FuelType = strings.TrimSpace(*in.FuelType)
}
if in.Liters != nil {
if *in.Liters <= 0 {
return nil, apperror.New(apperror.CodeInvalidArg, "加油量必须大于 0")
}
rec.Liters = *in.Liters
}
if in.TotalAmount != nil {
if *in.TotalAmount < 0 {
return nil, apperror.New(apperror.CodeInvalidArg, "总金额不能小于 0")
}
rec.TotalAmount = *in.TotalAmount
}
if in.StationName != nil {
rec.StationName = strings.TrimSpace(*in.StationName)
}
if in.IsFull != nil {
rec.IsFull = *in.IsFull
}
if in.Remark != nil {
rec.Remark = *in.Remark
}
// 实际油价随 liters / total_amount 变化
rec.PricePerLiter = money.PricePerLiter(rec.TotalAmount, rec.Liters)
if err := s.recRepo.Update(ctx, rec); err != nil {
return nil, err
}
return rec, nil
}
func (s *refuelService) Delete(ctx context.Context, id uint64) error {
return s.recRepo.Delete(ctx, id)
}
func (s *refuelService) ListByVehicle(ctx context.Context, vehicleID uint64, start, end *time.Time) ([]model.RefuelRecord, error) {
if _, err := s.vehicleRepo.Get(ctx, vehicleID); err != nil {
return nil, err
}
return s.recRepo.ListByVehicle(ctx, vehicleID, start, end)
}
func (s *refuelService) Statistics(ctx context.Context, vehicleID uint64) (*RefuelStatistics, error) {
if _, err := s.vehicleRepo.Get(ctx, vehicleID); err != nil {
return nil, err
}
records, err := s.recRepo.ListByVehicle(ctx, vehicleID, nil, nil)
if err != nil {
return nil, err
}
stats := &RefuelStatistics{VehicleID: vehicleID, TotalRecords: len(records)}
if len(records) == 0 {
return stats, nil
}
var (
totalLiters float64
totalAmount float64
prices []float64
consumptions []float64
costPerKmSample []float64
)
// ListByVehicle 默认按 refuel_time DESC;遍历一次累加,同时算油耗序列
// 标准油耗只在"连续两次 is_full=true"之间计算
var prevFull *model.RefuelRecord
for i := range records {
r := records[i]
totalLiters += r.Liters
totalAmount += r.TotalAmount
prices = append(prices, r.PricePerLiter)
if r.IsFull {
if prevFull != nil {
mileage := money.Mileage(r.Odometer, prevFull.Odometer)
cons := money.ConsumptionL100km(r.Liters, mileage)
cost := money.CostPerKm(r.TotalAmount, mileage)
if cons > 0 {
consumptions = append(consumptions, cons)
}
if cost > 0 {
costPerKmSample = append(costPerKmSample, cost)
}
}
// 浅拷贝保留 prev
cp := r
prevFull = &cp
}
}
stats.TotalLiters = round2(totalLiters)
stats.TotalAmount = round2(totalAmount)
stats.AvgPrice = money.AvgFloat64(prices)
stats.AvgConsumption = money.AvgFloat64(consumptions)
stats.CostPerKm = money.AvgFloat64(costPerKmSample)
// 最近一次加油:列表已按时间倒序,第一条即最近
last := records[0]
stats.LastRefuel = &last
return stats, nil
}
func round2(x float64) float64 {
// 简单两位四舍五入,避免 import math 而本文件只用一次
// 实际更推荐用 shopspring/decimal.Decimal,这里精度损失可接受
return float64(int64(x*100+0.5)) / 100
}
fuellog-api/internal/service/vehicle.go
+171
View File
@@ -0,0 +1,171 @@
// Package service 持有业务逻辑,只依赖 repository 接口,不直接碰 GORM。
//
// 计算类逻辑(如油价/油耗/成本)放这里,不放在 handler,便于单测。
package service
import (
"context"
"strings"
"gorm.io/gorm"
"github.com/kennethcheng/fuellog-api/internal/dto"
"github.com/kennethcheng/fuellog-api/internal/model"
"github.com/kennethcheng/fuellog-api/internal/repository"
"github.com/kennethcheng/fuellog-api/pkg/apperror"
)
// VehicleService 车辆业务逻辑。
type VehicleService interface {
Create(ctx context.Context, in *dto.VehicleCreate) (*model.Vehicle, error)
Get(ctx context.Context, id uint64) (*model.Vehicle, error)
List(ctx context.Context) ([]model.Vehicle, error)
Update(ctx context.Context, id uint64, in *dto.VehicleUpdate) (*model.Vehicle, error)
Delete(ctx context.Context, id uint64) error
SetDefault(ctx context.Context, id uint64) (*model.Vehicle, error)
}
func NewVehicleService(repo repository.VehicleRepository, db *gorm.DB) VehicleService {
return &vehicleService{repo: repo, db: db}
}
type vehicleService struct {
repo repository.VehicleRepository
db *gorm.DB
}
func (s *vehicleService) Create(ctx context.Context, in *dto.VehicleCreate) (*model.Vehicle, error) {
v := &model.Vehicle{
Name: strings.TrimSpace(in.Name),
Brand: strings.TrimSpace(in.Brand),
Model: strings.TrimSpace(in.Model),
PlateNumber: strings.TrimSpace(in.PlateNumber),
FuelType: strings.TrimSpace(in.FuelType),
TankCapacity: in.TankCapacity,
CurrentOdometer: in.CurrentOdometer,
DefaultVehicle: in.DefaultVehicle,
}
if v.Name == "" {
return nil, apperror.New(apperror.CodeInvalidArg, "车辆名称不能为空")
}
if v.FuelType == "" {
return nil, apperror.New(apperror.CodeInvalidArg, "能源类型不能为空")
}
// 任何显式设为默认的车辆,都要先清掉其它默认(在事务里完成)
if v.DefaultVehicle {
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := s.repo.ClearDefault(ctx, tx); err != nil {
return err
}
if err := tx.WithContext(ctx).Create(v).Error; err != nil {
return apperror.Wrap(apperror.CodeInternal, "创建车辆失败", err)
}
return nil
})
if err != nil {
if appErr, ok := apperror.As(err); ok {
return nil, appErr
}
return nil, err
}
return v, nil
}
if err := s.repo.Create(ctx, v); err != nil {
return nil, err
}
return v, nil
}
func (s *vehicleService) Get(ctx context.Context, id uint64) (*model.Vehicle, error) {
return s.repo.Get(ctx, id)
}
func (s *vehicleService) List(ctx context.Context) ([]model.Vehicle, error) {
return s.repo.List(ctx)
}
func (s *vehicleService) Update(ctx context.Context, id uint64, in *dto.VehicleUpdate) (*model.Vehicle, error) {
v, err := s.repo.Get(ctx, id)
if err != nil {
return nil, err
}
if in.Name != nil {
v.Name = strings.TrimSpace(*in.Name)
}
if in.Brand != nil {
v.Brand = strings.TrimSpace(*in.Brand)
}
if in.Model != nil {
v.Model = strings.TrimSpace(*in.Model)
}
if in.PlateNumber != nil {
v.PlateNumber = strings.TrimSpace(*in.PlateNumber)
}
if in.FuelType != nil {
v.FuelType = strings.TrimSpace(*in.FuelType)
}
if in.TankCapacity != nil {
v.TankCapacity = *in.TankCapacity
}
if in.CurrentOdometer != nil {
v.CurrentOdometer = *in.CurrentOdometer
}
if v.Name == "" {
return nil, apperror.New(apperror.CodeInvalidArg, "车辆名称不能为空")
}
if v.FuelType == "" {
return nil, apperror.New(apperror.CodeInvalidArg, "能源类型不能为空")
}
// 切换默认车辆同样要在事务里:先清默认,再置新默认
if in.DefaultVehicle != nil && *in.DefaultVehicle && !v.DefaultVehicle {
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := s.repo.ClearDefault(ctx, tx); err != nil {
return err
}
v.DefaultVehicle = true
if err := tx.WithContext(ctx).Save(v).Error; err != nil {
return apperror.Wrap(apperror.CodeInternal, "更新车辆失败", err)
}
return nil
})
if err != nil {
if appErr, ok := apperror.As(err); ok {
return nil, appErr
}
return nil, err
}
return v, nil
}
if err := s.repo.Update(ctx, v); err != nil {
return nil, err
}
return v, nil
}
func (s *vehicleService) Delete(ctx context.Context, id uint64) error {
return s.repo.Delete(ctx, id)
}
func (s *vehicleService) SetDefault(ctx context.Context, id uint64) (*model.Vehicle, error) {
// 校验存在
if _, err := s.repo.Get(ctx, id); err != nil {
return nil, err
}
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := s.repo.ClearDefault(ctx, tx); err != nil {
return err
}
return s.repo.SetDefault(ctx, tx, id)
})
if err != nil {
if appErr, ok := apperror.As(err); ok {
return nil, appErr
}
return nil, err
}
return s.repo.Get(ctx, id)
}