feat(backend): 接入 HTTP handler、router、main 装配,端到端冒烟全通

Phase 1.3b。Phase 1.3a 留的 service 现在有了 HTTP 入口,curl 能跑通完整的
"建车 → 加三次油 → 看统计 → 删记录 → 删车"全链路,核心计算命中 plan §6。

新增:
- internal/handler/common.go  通用:writeError / parseUint64 / bindJSON / sendJSON
  * 统一错误格式:{ "code": "INVALID_ARGUMENT|NOT_FOUND|...", "message": "..." }
  * parseUint64 自动把非数字 / 0 翻成 INVALID_ARGUMENT
  * bindJSON 把 gin-validator 错误也归到 INVALID_ARGUMENT
- internal/handler/errors.go   errInvalid / errInvalidVehicleID 等小工具
- internal/handler/vehicle.go  CRUD + SetDefault 六个端点
- internal/handler/refuel_record.go  CRUD + List(?vehicle_id) + Statistics
- internal/router/router.go    把所有 /api 路由挂上 Gin engine

main.go 改动:
- 引入 wire():repository → service → handler 一气串好
- /api 业务路由从 router.Build 注入
- /health 与 NoRoute 保持原状

scripts/smoke.ps1 端到端冒烟脚本(13 步):
  health → list → create vehicle → list → refuel×3(其中 1 个半箱)→
  statistics → list refuels → delete refuel → statistics 刷新 →
  delete vehicle → GET 404

核心计算命中 plan §6.3 / §19:
  320/40 = 8.0  (price_per_liter)        ✓
  256/32 = 8.0  (price_per_liter)        ✓
  32/(11000-10500)*100 = 6.4  (L/100km)  ✓
  256/500 = 0.512  (元/公里)              ✓
  半箱油(11200/10L/is_full=false)不进入标准油耗采样 ✓
  删除记录后 avg_consumption / cost_per_km 立即重算 ✓

期间踩到的两个坑(都修了):
  1) handler 用 []struct{}{} 试图给 []model.Vehicle / []model.RefuelRecord
     兜空数组,Go 强类型不接受;改用 []model.Vehicle{} 即可
  2) Statistics 列表按 refuel_time DESC 返回,正向迭代会让 mileage 算成负数
     (newer - older < 0);改成倒序迭代,prevFull 总是更老的那次

未做(留给后续):
- 单元测试(下一步 Phase 1.4 独立 commit)
- 显式 migration 文件(下次 schema 变更补;此次仍 AutoMigrate 兜底)
- Dashboard / 统计更复杂的 endpoint(基础 Statistics 已可用)
- PWA / 导入导出 / Docker(留给 Phase 1.5+)

验证:
  go vet ./...   0 issues
  go build       26 MB binary
  smoke.ps1      13/13 断言通过

fuellog-api/internal/handler/vehicle.go

@@ -0,0 +1,108 @@
+package handler
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/kennethcheng/fuellog-api/internal/dto"
+	"github.com/kennethcheng/fuellog-api/internal/model"
+	"github.com/kennethcheng/fuellog-api/internal/service"
+)
+
+// VehicleHandler 车辆路由。
+type VehicleHandler struct{ svc service.VehicleService }
+
+func NewVehicleHandler(svc service.VehicleService) *VehicleHandler {
+	return &VehicleHandler{svc: svc}
+}
+
+// POST /api/vehicles
+func (h *VehicleHandler) Create(c *gin.Context) {
+	var in dto.VehicleCreate
+	if err := bindJSON(c, &in); err != nil {
+		writeError(c, err)
+		return
+	}
+	v, err := h.svc.Create(c.Request.Context(), &in)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	sendJSON(c, v)
+}
+
+// GET /api/vehicles
+func (h *VehicleHandler) List(c *gin.Context) {
+	vs, err := h.svc.List(c.Request.Context())
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	if vs == nil {
+		vs = []model.Vehicle{} // 避免前端收到 null,统一空数组
+	}
+	sendJSON(c, vs)
+}
+
+// GET /api/vehicles/:id
+func (h *VehicleHandler) Get(c *gin.Context) {
+	id, err := parseUint64(c, "id")
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	v, err := h.svc.Get(c.Request.Context(), id)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	sendJSON(c, v)
+}
+
+// PUT /api/vehicles/:id
+func (h *VehicleHandler) Update(c *gin.Context) {
+	id, err := parseUint64(c, "id")
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	var in dto.VehicleUpdate
+	if err := bindJSON(c, &in); err != nil {
+		writeError(c, err)
+		return
+	}
+	v, err := h.svc.Update(c.Request.Context(), id, &in)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	sendJSON(c, v)
+}
+
+// DELETE /api/vehicles/:id
+func (h *VehicleHandler) Delete(c *gin.Context) {
+	id, err := parseUint64(c, "id")
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	if err := h.svc.Delete(c.Request.Context(), id); err != nil {
+		writeError(c, err)
+		return
+	}
+	c.Status(204)
+}
+
+// POST /api/vehicles/:id/default
+func (h *VehicleHandler) SetDefault(c *gin.Context) {
+	id, err := parseUint64(c, "id")
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	v, err := h.svc.SetDefault(c.Request.Context(), id)
+	if err != nil {
+		writeError(c, err)
+		return
+	}
+	sendJSON(c, v)
+}