FuelLog/docs/api.md

FuelLog API 文档

Base path: /api 错误统一格式: { "code": "INVALID_ARGUMENT", "message": "..." } 鉴权: MVP 阶段不要求,MVP 之后会在 Authorization: Bearer <token> 头里加。

---

通用约定

• 所有时间字段统一 UTC 存库;请求时传 RFC3339 字符串,响应回 RFC3339。
• 金额 / 加油量 / 里程 / 油耗:浮点;金额计算在服务端用 shopspring/decimal 避免累计误差。
• 列表接口默认空数组(不返回 null)。
• 删除为硬删(数据库里 DELETE);二次确认在前端做。
• 默认车辆唯一,切换走事务,避免出现两个 default。

错误码字典(在 pkg/apperror):

code	HTTP	含义
INTERNAL	500	兜底,未预期
INVALID_ARGUMENT	400	参数校验失败
NOT_FOUND	404	资源不存在
CONFLICT	409	资源冲突(预留)
UNAUTHORIZED	401	未鉴权(预留)
FORBIDDEN	403	无权限(预留)
UNAVAILABLE	503	暂不可用(预留)

---

健康检查

GET /health

{ "status": "ok", "time": "2026-09-13T16:11:32+08:00" }

---

车辆 /api/vehicles

GET /api/vehicles

列出所有车辆,按 default_vehicle DESC, id ASC 排序。

Response 200

[
  {
    "id": 1,
    "name": "我的夏",
    "brand": "比亚迪",
    "model": "秦 PLUS DM-i",
    "plate_number": "京A12345",
    "fuel_type": "hybrid",
    "tank_capacity": 48,
    "current_odometer": 10000,
    "default_vehicle": true,
    "created_at": "2026-09-13T16:00:00+08:00",
    "updated_at": "2026-09-13T16:00:00+08:00"
  }
]

POST /api/vehicles

创建车辆。

Request

字段	类型	必填	说明
name	string	✅	车辆名称,max 64
brand	string		max 64
model	string		max 64
plate_number	string		max 32
fuel_type	string	✅	gasoline / diesel / hybrid / electric / plug_in_hybrid
tank_capacity	number		升,>= 0
current_odometer	number		公里,>= 0
default_vehicle	bool		设为默认时,旧默认会被清掉(事务)

Response 200 — 完整 Vehicle 对象

GET /api/vehicles/:id

返回单辆;不存在返 404。

PUT /api/vehicles/:id

Patch 语义:*string / *number / *bool 表示可选,未传的字段不更新。 其它校验同 POST。

Response 200 — 更新后的 Vehicle

DELETE /api/vehicles/:id

硬删。返 204 No Content。

POST /api/vehicles/:id/default

设为唯一默认。事务内先清旧默认,再置新默认。

Response 200 — 更新后的 Vehicle

---

加油记录 /api/refuels

POST /api/refuels

Request

字段	类型	必填	说明
vehicle_id	uint64	✅	关联车辆
refuel_time	RFC3339	✅	加油时间,UTC 存库
odometer	number	✅	加油时里程,>= 0
fuel_type	string	✅	油品
liters	number	✅	加油量,> 0
total_amount	number	✅	总金额,>= 0
station_name	string		max 128
is_full	bool		是否加满(决定是否进入标准油耗)
remark	string		max 512

注意:price_per_liter 不入参,由服务端用 total_amount / liters 实时算出,落库保留历史真实单价。

Response 200 — 完整 RefuelRecord

GET /api/refuels/:id

PUT /api/refuels/:id

Patch 语义。liters / total_amount 任一更新都会重新算 price_per_liter。

DELETE /api/refuels/:id

返 204 No Content。

GET /api/refuels?vehicle_id=...&start_date=...&end_date=...

参数	必填	说明
vehicle_id	✅	uint64
start_date		RFC3339,只返 refuel_time >= 它的
end_date		RFC3339,只返 refuel_time <= 它的

按 refuel_time DESC, id DESC 排序。

Response 200 — RefuelRecord 数组

---

统计 /api/vehicles/:id/statistics

单车的关键统计指标,服务端正序遍历 refuel_time 倒序列表,只在 "连续两次 is_full=true"之间采样油耗 / 每公里成本;半箱油记录不会污染。

Response 200

{
  "vehicle_id": 1,
  "total_records": 3,
  "total_liters": 82.0,
  "total_amount": 656.0,
  "avg_price": 8.0,
  "avg_consumption": 6.4,
  "cost_per_km": 0.51,
  "last_refuel": { /* RefuelRecord 或 null */ }
}

字段含义:

• avg_price 全部记录的实际油价算术平均
• avg_consumption 标准百公里油耗 L/100km(仅 is_full 序列的样本平均)
• cost_per_km 每公里燃油成本 元/km(仅 is_full 序列的样本平均)
• last_refuel 最近一次加油记录(按 refuel_time DESC 第一个)

空车辆返 { total_records: 0, ...全 0, last_refuel: null }。

---

索引

• 车辆:vehicle.id PK
• 加油记录:refuel_record.id PK;(vehicle_id, refuel_time) 与 vehicle_id 各自索引