docs: record daily metric api verification

2026-07-01 23:35:50 +08:00
parent 56f4811c68
commit 59c1c9df0f
1 changed files with 96 additions and 0 deletions
--- a/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md
+++ b/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md
@@ -561,3 +561,99 @@ new_spool_1min=0
 ```

 说明：spool 正在回放下降，且最近 1 分钟没有新增文件；生产 gateway 日志未见 `Incorrect string value`、Kafka publish error 或 replay error。
+
+## 2026-07-01 23:34 每日指标查询 API 复验
+
+部署版本已更新：
+
+- Git commit：`56f4811`
+- 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-56f4811-20260701233311`
+
+新增接口：
+
+```text
+GET /api/stats/daily-metrics
+```
+
+查询参数：
+
+```text
+vin       可选
+protocol  可选，GB32960 / JT808 / YUTONG_MQTT
+metricKey 可选，daily_mileage_km / daily_total_mileage_km
+dateFrom  可选，YYYY-MM-DD
+dateTo    可选，YYYY-MM-DD
+limit     可选，默认 50，最大 1000
+offset    可选，默认 0
+```
+
+生产可访问样例：
+
+```text
+http://115.29.187.205:20210/api/stats/daily-metrics?vin=LB9A32A21R0LS1707&protocol=GB32960&dateFrom=2020-07-01&dateTo=2020-07-01&limit=10
+```
+
+返回确认：
+
+```json
+{
+  "items": [
+    {
+      "vin": "LB9A32A21R0LS1707",
+      "stat_date": "2020-07-01",
+      "protocol": "GB32960",
+      "metric_key": "daily_mileage_km",
+      "metric_value": 0,
+      "metric_unit": "km",
+      "first_total_mileage_km": 53490.9,
+      "latest_total_mileage_km": 53490.9,
+      "sample_count": 3,
+      "calculation_method": "TOTAL_MILEAGE_DIFF",
+      "created_at": "2026-07-01 22:14:13",
+      "updated_at": "2026-07-01 22:28:25"
+    },
+    {
+      "vin": "LB9A32A21R0LS1707",
+      "stat_date": "2020-07-01",
+      "protocol": "GB32960",
+      "metric_key": "daily_total_mileage_km",
+      "metric_value": 53490.9,
+      "metric_unit": "km",
+      "first_total_mileage_km": 53490.9,
+      "latest_total_mileage_km": 53490.9,
+      "sample_count": 3,
+      "calculation_method": "TOTAL_MILEAGE_DIFF",
+      "created_at": "2026-07-01 22:14:13",
+      "updated_at": "2026-07-01 22:28:25"
+    }
+  ],
+  "limit": 10,
+  "offset": 0,
+  "total": 2
+}
+```
+
+JT808 真实生产查询：
+
+```text
+http://115.29.187.205:20210/api/stats/daily-metrics?protocol=JT808&dateFrom=2026-07-01&dateTo=2026-07-01&limit=10
+```
+
+返回 `total=0`。原因是此前合成回放产生的测试指标已清理，当前真实 808 已绑定 VIN 的车辆仍上报 `total_mileage_km=0`，stat-writer 按规则不写非正总里程指标。
+
+实时接口回归：
+
+```text
+http://115.29.187.205:20210/api/realtime/vehicles/LKLG7C4E3NA774736/online
+```
+
+返回 `online=true`，说明新增 stats API 没有影响 Redis 实时查询。
+
+发布后 spool 观察：
+
+```text
+发布后立即：spool_count=1101，new_spool_1min=102
+等待 60 秒：spool_count=1033，new_spool_1min=0
+```
+
+说明：本次发布重启窗口产生的 spool 正在回放下降，且最近 1 分钟没有新增；gateway/realtime-api 最近日志未见 error、failed、Kafka publish error。