feat(backend): 添加车辆与加油记录 model、repository 和 GORM 迁移

完成 Phase 1.2,把 GORM 真正接进来。Phase 1.1 留下的 /health 和骨架保持不变,
本 commit 在此之上铺好数据访问层,Phase 1.3 直接在 service / handler 上挂业务即可。

新增:
- internal/model/vehicle.go        车辆实体(严格按 plan §7.1)
- internal/model/refuel_record.go  加油记录实体(严格按 plan §7.2)
- internal/db/db.go                SQLite 连接 + AutoMigrate 入口
  * glebarez/sqlite 纯 Go,免 CGO,Windows / Docker 通吃
  * DSN 自动启用 WAL + 外键约束 + busy_timeout
  * 表目录若不存在会自动创建
- internal/repository/vehicle.go        车辆数据访问接口 + GORM 实现
  * Create / Get / List / Update / Delete
  * ClearDefault / SetDefault(切换默认车辆用,在事务里跑避免脏状态)
- internal/repository/refuel_record.go  加油记录数据访问接口 + GORM 实现
  * Create / Get / Update / Delete
  * ListByVehicle 支持可选时间窗口
  * PrevFullRefuel 找上一次加满,给油耗计算用

main.go 改动:
- 启动期 db.Open + db.Migrate,失败直接退出
- application 持有 *gorm.DB,Phase 1.3 起注入 repo / service

设计要点:
- repository 全是接口,Service 持有接口便于单测用 fake 替换
- 所有 repo 错误统一包成 apperror.NotFound / apperror.Internal,
  不让 GORM 原始错误泄漏到 handler
- model.TableName() 显式指定单数,避免 GORM 复数
- refuel_record 用 (vehicle_id, refuel_time) 复合场景常见,已加索引

未做(留给后续 commit):
- service 层与 DTO
- handler / router
- 显式 migration 文件(AGENTS.md 要求 schema 变更必须写 migration;
  此次为首次建表,AutoMigrate 即可,后续 schema 改动会补 goose / 自管文件)

验证:
  go mod tidy     all modules verified
  go vet ./...    0 issues
  go build        25.9 MB binary
  冷启动一次,DB 文件生成在 fuellog-api/data/fuellog.db(WAL/SHM 齐备)
  listtables 脚本 dump 出来的两表 schema 与 plan §7 完全一致
This commit is contained in:
2026-09-13 15:59:12 +08:00
parent ca9831a050
commit f4c42bbb9e
7 changed files with 368 additions and 6 deletions
+19 -4
View File
@@ -3,7 +3,7 @@
// 启动流程:
// 1. 加载 .env
// 2. 解析配置
// 3. 初始化数据库(Phase 2 起接 GORM)
// 3. 打开 SQLite + 运行迁移
// 4. 装配路由
// 5. 监听并优雅退出
package main
@@ -19,8 +19,10 @@ import (
"github.com/gin-gonic/gin"
"github.com/joho/godotenv"
"gorm.io/gorm"
"github.com/kennethcheng/fuellog-api/internal/config"
"github.com/kennethcheng/fuellog-api/internal/db"
"github.com/kennethcheng/fuellog-api/internal/middleware"
"github.com/kennethcheng/fuellog-api/pkg/apperror"
)
@@ -41,7 +43,18 @@ func main() {
Level: parseLogLevel(cfg.LogLevel),
})))
app := &application{cfg: cfg}
gormDB, err := db.Open(cfg.DBPath)
if err != nil {
slog.Error("db open failed", "err", err)
os.Exit(1)
}
if err := db.Migrate(gormDB); err != nil {
slog.Error("db migrate failed", "err", err)
os.Exit(1)
}
slog.Info("db ready", "path", cfg.DBPath)
app := &application{cfg: cfg, db: gormDB}
srv := &http.Server{
Addr: cfg.ServerAddr,
@@ -75,10 +88,12 @@ func main() {
// application 持有所有依赖,避免散落全局变量。
type application struct {
cfg *config.Config
db *gorm.DB
// Phase 1.3 起注入:vehicleRepo / refuelRepo / vehicleSvc / refuelSvc
}
// router 构建并返回 Gin 引擎。
// 当前阶段只暴露 /health;Phase 2 起逐步接 /api/vehicles、/api/refuels。
// 当前阶段只暴露 /health;Phase 1.3 起逐步接 /api/vehicles、/api/refuels。
func (a *application) router() *gin.Engine {
r := gin.New()
r.Use(
@@ -101,7 +116,7 @@ func (a *application) router() *gin.Engine {
})
})
// /api 路由组(Phase 2 起在此挂载业务路由)
// /api 路由组(Phase 1.3 起在此挂载业务路由)
api := r.Group("/api")
_ = api // 占位,避免未使用告警