docs: record mileage metric guard verification

docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md

@@ -381,3 +381,53 @@ Kafka spool 目录确认：
 ```
 
 说明：生产 808 中仍有部分 phone 未解析出 VIN，后续需要继续维护 `vehicle_identity_binding` 的 phone/device_id/plate 到 VIN 映射，或者增强 808 注册/鉴权帧中的 identity 回写。
+
+## 2026-07-01 23:09 808 里程统计防 0 污染复验
+
+部署版本已更新：
+
+- Git commit：`d347525`
+- 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-d347525-20260701230845`
+
+本轮修复内容：
+
+- `stat-writer` 不再把 `total_mileage_km <= 0` 的采样写入 MySQL 每日指标。
+- MySQL upsert 对历史 `first_total_mileage_km=0` / `latest_total_mileage_km=0` 做纠偏；后续首次有效总里程会替换掉历史 0。
+- `realtime-api` 合并实时快照时，非正 `total_mileage_km` 不再覆盖已有正值；速度、位置、状态等其他字段仍按事件时间更新。
+
+测试验证：
+
+```text
+go test ./...
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ./cmd/gateway
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ./cmd/history-writer
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ./cmd/stat-writer
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ./cmd/realtime-api
+```
+
+生产回放验证：
+
+- 第一条 808 帧：`device_time=2026-07-01T23:09:35+08:00`，`total_mileage_km=12345.6`
+- 第二条 808 帧：`device_time=2026-07-01T23:09:36+08:00`，`total_mileage_km=0`
+- 两条帧使用同一 VIN：`LKLG7C4E3NA774736`
+
+Redis merged 快照确认：第二条 0 里程帧没有覆盖已有有效总里程。
+
+```text
+event_time_ms=1782918576000
+source_endpoint=172.20.0.1:40946
+speed_kmh=0
+longitude=119.557997
+latitude=29.049092
+total_mileage_km=12345.6
+field_times_ms.total_mileage_km=1782918575000
+```
+
+MySQL `vehicle_daily_metric` 确认：0 里程采样未进入统计，sample_count 只因有效总里程采样增加一次。
+
+```text
+LKLG7C4E3NA774736 | JT808 | 2026-07-01 | daily_mileage_km       | 0.000     | sample_count=13 | first=12345.600 | latest=12345.600
+LKLG7C4E3NA774736 | JT808 | 2026-07-01 | daily_total_mileage_km | 12345.600 | sample_count=13 | first=12345.600 | latest=12345.600
+```
+
+说明：生产 TDengine 中已经存在大量 808 非零 `total_mileage_km` 采样，但许多 phone 尚未映射到 VIN，因此 MySQL 按 VIN 的统计只会覆盖已解析 VIN 的车辆。下一步应继续补齐 `vehicle_identity_binding`，让更多 808 车辆进入统计。