perf: skip raw freshness count scan

test: check raw freshness without event date filter
fix: verify raw freshness by received time
2026-07-02 09:30:15 +08:00 · 2026-07-02 09:27:22 +08:00 · 2026-07-02 09:16:45 +08:00 · 2026-07-02 09:11:50 +08:00 · 2026-07-02 08:50:19 +08:00 · 2026-07-02 08:47:05 +08:00
66 changed files with 13750 additions and 0 deletions
--- a/deploy/portainer/docker-compose-go.yml
+++ b/deploy/portainer/docker-compose-go.yml
@@ -0,0 +1,117 @@
 version: "3.8"
 # Go sidecar stack for the vehicle ingest redesign.
 # It is intentionally separate from deploy/portainer/docker-compose.yml so the
 # current Java production stack can keep running until Go evidence is captured.
 x-common-env: &common-env
  TZ: Asia/Shanghai
  KAFKA_BROKERS: ${KAFKA_BROKERS:-172.17.111.56:9092}
  KAFKA_TOPIC_GB32960_RAW: ${KAFKA_TOPIC_GB32960_RAW:-vehicle.raw.gb32960.v1}
  KAFKA_TOPIC_JT808_RAW: ${KAFKA_TOPIC_JT808_RAW:-vehicle.raw.jt808.v1}
  KAFKA_TOPIC_YUTONG_MQTT_RAW: ${KAFKA_TOPIC_YUTONG_MQTT_RAW:-vehicle.raw.yutong-mqtt.v1}
  KAFKA_TOPIC_UNIFIED: ${KAFKA_TOPIC_UNIFIED:-vehicle.event.unified.v1}
 x-restart: &restart-policy
  restart: unless-stopped
  networks:
    - vehicle-ingest
  logging:
    driver: json-file
    options:
      max-size: "100m"
      max-file: "5"
 services:
  go-vehicle-gateway:
    <<: *restart-policy
    image: ${LINGNIU_GO_IMAGE_REGISTRY:-crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com}/${LINGNIU_GO_IMAGE_NAMESPACE:-oneos}/vehicle-gateway-go:${LINGNIU_GO_IMAGE_VERSION:?set LINGNIU_GO_IMAGE_VERSION}
    container_name: go-vehicle-gateway
    command: ["/app/gateway"]
    mem_limit: ${GO_GATEWAY_MEM_LIMIT:-512m}
    environment:
      <<: *common-env
      GB32960_TCP_ADDR: ":32960"
      JT808_TCP_ADDR: ":808"
      TCP_READ_BUFFER_BYTES: ${TCP_READ_BUFFER_BYTES:-65536}
      TCP_IDLE_TIMEOUT_SECONDS: ${TCP_IDLE_TIMEOUT_SECONDS:-180}
      TCP_MAX_CONNECTIONS: ${TCP_MAX_CONNECTIONS:-20000}
      YUTONG_MQTT_ENABLED: ${YUTONG_MQTT_ENABLED:-false}
      YUTONG_MQTT_ENDPOINT: ${YUTONG_MQTT_ENDPOINT:-yutong}
      YUTONG_MQTT_URI: ${YUTONG_MQTT_URI:-}
      YUTONG_MQTT_TOPICS: ${YUTONG_MQTT_TOPICS:-/ytforward/shln/+}
      YUTONG_MQTT_QOS: ${YUTONG_MQTT_QOS:-2}
      YUTONG_MQTT_CLIENT_ID: ${YUTONG_MQTT_CLIENT_ID:-lingniu-go-yutong-mqtt}
      YUTONG_MQTT_USERNAME: ${YUTONG_MQTT_USERNAME:-}
      YUTONG_MQTT_PASSWORD: ${YUTONG_MQTT_PASSWORD:-}
      YUTONG_MQTT_CLEAN_SESSION: ${YUTONG_MQTT_CLEAN_SESSION:-false}
      YUTONG_MQTT_KEEP_ALIVE_SECONDS: ${YUTONG_MQTT_KEEP_ALIVE_SECONDS:-20}
      YUTONG_MQTT_CONNECTION_TIMEOUT_SECONDS: ${YUTONG_MQTT_CONNECTION_TIMEOUT_SECONDS:-10}
      YUTONG_MQTT_TLS_CA_PEM: ${YUTONG_MQTT_TLS_CA_PEM:-}
      YUTONG_MQTT_TLS_CLIENT_PEM: ${YUTONG_MQTT_TLS_CLIENT_PEM:-}
      YUTONG_MQTT_TLS_CLIENT_KEY: ${YUTONG_MQTT_TLS_CLIENT_KEY:-}
      YUTONG_MQTT_TLS_HOSTNAME_VERIFICATION_ENABLED: ${YUTONG_MQTT_TLS_HOSTNAME_VERIFICATION_ENABLED:-true}
      IDENTITY_MYSQL_DSN: ${IDENTITY_MYSQL_DSN:-}
      VEHICLE_IDENTITY_TABLE: ${VEHICLE_IDENTITY_TABLE:-vehicle_identity_binding}
    ports:
      - "${GO_GB32960_TCP_PORT:-32960}:32960"
      - "${GO_JT808_TCP_PORT:-808}:808"
    volumes:
      - "${KAFKA_SPOOL_HOST_DIR:-/opt/lingniu-go/spool/gateway}:${KAFKA_SPOOL_DIR:-/data/spool/gateway}"
      - "${YUTONG_MQTT_CERT_HOST_DIR:-/opt/lingniuServices/certificate/yutong/vehicledatareception}:${YUTONG_MQTT_CERT_CONTAINER_DIR:-/opt/lingniuServices/certificate/yutong/vehicledatareception}:ro"
  go-history-writer:
    <<: *restart-policy
    image: ${LINGNIU_GO_IMAGE_REGISTRY:-crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com}/${LINGNIU_GO_IMAGE_NAMESPACE:-oneos}/vehicle-gateway-go:${LINGNIU_GO_IMAGE_VERSION:?set LINGNIU_GO_IMAGE_VERSION}
    container_name: go-history-writer
    command: ["/app/history-writer"]
    mem_limit: ${GO_HISTORY_WRITER_MEM_LIMIT:-768m}
    environment:
      <<: *common-env
      KAFKA_GROUP: ${KAFKA_GROUP_GO_HISTORY:-go-history-writer}
      KAFKA_TOPICS: ${KAFKA_TOPICS_GO_HISTORY:-vehicle.raw.gb32960.v1,vehicle.raw.jt808.v1,vehicle.raw.yutong-mqtt.v1}
      TDENGINE_DRIVER: ${TDENGINE_DRIVER:-taosWS}
      TDENGINE_DSN: ${TDENGINE_DSN:?set TDENGINE_DSN, example root:password@ws(172.17.111.57:6041)/lingniu_vehicle_ts}
      TDENGINE_DATABASE: ${TDENGINE_DATABASE:-lingniu_vehicle_ts}
      TDENGINE_ENSURE_SCHEMA: ${TDENGINE_ENSURE_SCHEMA:-true}
  go-stat-writer:
    <<: *restart-policy
    image: ${LINGNIU_GO_IMAGE_REGISTRY:-crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com}/${LINGNIU_GO_IMAGE_NAMESPACE:-oneos}/vehicle-gateway-go:${LINGNIU_GO_IMAGE_VERSION:?set LINGNIU_GO_IMAGE_VERSION}
    container_name: go-stat-writer
    command: ["/app/stat-writer"]
    mem_limit: ${GO_STAT_WRITER_MEM_LIMIT:-512m}
    environment:
      <<: *common-env
      KAFKA_GROUP: ${KAFKA_GROUP_GO_STAT:-go-stat-writer}
      KAFKA_TOPICS: ${KAFKA_TOPICS_GO_STAT:-vehicle.raw.gb32960.v1,vehicle.raw.jt808.v1}
      MYSQL_DSN: ${MYSQL_DSN:?set MYSQL_DSN}
      MYSQL_ENSURE_SCHEMA: ${MYSQL_ENSURE_SCHEMA:-true}
      LOCAL_TZ: ${LOCAL_TZ:-Asia/Shanghai}
  go-realtime-api:
    <<: *restart-policy
    image: ${LINGNIU_GO_IMAGE_REGISTRY:-crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com}/${LINGNIU_GO_IMAGE_NAMESPACE:-oneos}/vehicle-gateway-go:${LINGNIU_GO_IMAGE_VERSION:?set LINGNIU_GO_IMAGE_VERSION}
    container_name: go-realtime-api
    command: ["/app/realtime-api"]
    mem_limit: ${GO_REALTIME_API_MEM_LIMIT:-512m}
    environment:
      <<: *common-env
      HTTP_ADDR: ":20210"
      KAFKA_GROUP: ${KAFKA_GROUP_GO_REALTIME:-go-realtime-api}
      KAFKA_TOPICS: ${KAFKA_TOPICS_GO_REALTIME:-vehicle.event.unified.v1}
      REDIS_ADDR: ${REDIS_ADDR:-r-bp1u741kij7e51i481.redis.rds.aliyuncs.com:6379}
      REDIS_USERNAME: ${REDIS_USERNAME:-}
      REDIS_PASSWORD: ${REDIS_PASSWORD:?set REDIS_PASSWORD}
      REDIS_DB: ${REDIS_DB:-50}
      ONLINE_TTL_SECONDS: ${ONLINE_TTL_SECONDS:-600}
      MYSQL_DSN: ${MYSQL_DSN:-}
      TDENGINE_DRIVER: ${TDENGINE_DRIVER:-taosWS}
      TDENGINE_DSN: ${TDENGINE_DSN:-}
      TDENGINE_DATABASE: ${TDENGINE_DATABASE:-lingniu_vehicle_ts}
    ports:
      - "${GO_REALTIME_HTTP_PORT:-20210}:20210"
 networks:
  vehicle-ingest:
    name: vehicle-ingest
--- a/deploy/systemd/README.md
+++ b/deploy/systemd/README.md
@@ -0,0 +1,66 @@
 # Go Vehicle Gateway Native Deployment
 本目录用于 ECS 原生部署。当前 goal 后续不再使用 Docker/Portainer 作为 Go 接入链路的部署方式。
 ## Runtime Layout
 ```text
 /opt/lingniu-go-native/
  current -> /opt/lingniu-go-native/releases/<git-short-sha>
  releases/<git-short-sha>/
    gateway
    history-writer
    stat-writer
    realtime-api
  env/
    gateway.env
    history-writer.env
    stat-writer.env
    realtime-api.env
  spool/gateway/
 ```
 ## Services
 | systemd unit | Binary | Purpose |
 |---|---|---|
 | `lingniu-go-gateway.service` | `gateway` | GB32960 TCP `32960`、JT808 TCP `808`、宇通 MQTT 接入，写 Kafka RAW/unified |
 | `lingniu-go-history-writer.service` | `history-writer` | 消费 RAW topic，写 TDengine `raw_frames` 和核心时序表 |
 | `lingniu-go-stat-writer.service` | `stat-writer` | 消费 RAW topic，写 MySQL `vehicle_daily_metric` |
 | `lingniu-go-realtime-api.service` | `realtime-api` | 消费 unified topic，写 Redis，并提供 realtime/raw/stat 查询 API |
 ## Build
 在开发机或 CI 上构建 Linux amd64 二进制：
 ```bash
 cd go/vehicle-gateway
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/gateway ./cmd/gateway
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/history-writer ./cmd/history-writer
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/stat-writer ./cmd/stat-writer
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' -o /tmp/lingniu-go-native/realtime-api ./cmd/realtime-api
 ```
 ## Cutover Notes
 1. 先上传二进制到新 release 目录并更新 `current` symlink。
 2. 从现有生产 env 生成四个 systemd 专用 env 文件；不要把密钥写入仓库。
 3. 停止旧 Docker Go 容器或 Java 容器，释放 `808`、`32960`、`20210`。
 4. 执行：
 ```bash
 systemctl daemon-reload
 systemctl enable lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api
 systemctl restart lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api
 ```
 ## Verification
 ```bash
 systemctl is-active lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api
 ss -lntp | egrep ':(808|32960|20210)\b'
 journalctl -u lingniu-go-gateway --since '5 minutes ago' --no-pager
 curl -sS 'http://127.0.0.1:20210/api/history/raw-frames?protocol=JT808&limit=1'
 curl -sS 'http://127.0.0.1:20210/api/history/raw-frames?protocol=GB32960&limit=1'
 curl -sS 'http://127.0.0.1:20210/api/history/raw-frames?protocol=YUTONG_MQTT&limit=1'
 ```
--- a/deploy/systemd/lingniu-go-gateway.service
+++ b/deploy/systemd/lingniu-go-gateway.service
@@ -0,0 +1,18 @@
 [Unit]
 Description=Lingniu Go Vehicle Gateway
 After=network-online.target
 Wants=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=/opt/lingniu-go-native/current
 EnvironmentFile=/opt/lingniu-go-native/env/gateway.env
 ExecStart=/opt/lingniu-go-native/current/gateway
 Restart=always
 RestartSec=3
 LimitNOFILE=1048576
 KillSignal=SIGTERM
 TimeoutStopSec=30
 [Install]
 WantedBy=multi-user.target
--- a/deploy/systemd/lingniu-go-history-writer.service
+++ b/deploy/systemd/lingniu-go-history-writer.service
@@ -0,0 +1,18 @@
 [Unit]
 Description=Lingniu Go History Writer
 After=network-online.target
 Wants=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=/opt/lingniu-go-native/current
 EnvironmentFile=/opt/lingniu-go-native/env/history-writer.env
 ExecStart=/opt/lingniu-go-native/current/history-writer
 Restart=always
 RestartSec=3
 LimitNOFILE=1048576
 KillSignal=SIGTERM
 TimeoutStopSec=30
 [Install]
 WantedBy=multi-user.target
--- a/deploy/systemd/lingniu-go-realtime-api.service
+++ b/deploy/systemd/lingniu-go-realtime-api.service
@@ -0,0 +1,18 @@
 [Unit]
 Description=Lingniu Go Realtime API
 After=network-online.target
 Wants=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=/opt/lingniu-go-native/current
 EnvironmentFile=/opt/lingniu-go-native/env/realtime-api.env
 ExecStart=/opt/lingniu-go-native/current/realtime-api
 Restart=always
 RestartSec=3
 LimitNOFILE=1048576
 KillSignal=SIGTERM
 TimeoutStopSec=30
 [Install]
 WantedBy=multi-user.target
--- a/deploy/systemd/lingniu-go-stat-writer.service
+++ b/deploy/systemd/lingniu-go-stat-writer.service
@@ -0,0 +1,18 @@
 [Unit]
 Description=Lingniu Go Stat Writer
 After=network-online.target
 Wants=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=/opt/lingniu-go-native/current
 EnvironmentFile=/opt/lingniu-go-native/env/stat-writer.env
 ExecStart=/opt/lingniu-go-native/current/stat-writer
 Restart=always
 RestartSec=3
 LimitNOFILE=1048576
 KillSignal=SIGTERM
 TimeoutStopSec=30
 [Install]
 WantedBy=multi-user.target
--- a/docs/operations/current-ecs-deployment.md
+++ b/docs/operations/current-ecs-deployment.md
@@ -0,0 +1,227 @@
 # 当前 ECS Go 原生部署说明
 更新时间：2026-07-02 01:30 CST
 本文档记录当前 `lingniu-vehicle-ingest` 的生产运行面。当前 goal 的接入链路已经切到 Go 原生 systemd 部署，不再以 Docker/Portainer 作为生产运行方式。密钥只维护在 ECS 环境文件或受控凭据中，不写入 Git。
 ## 部署范围
 | systemd 服务 | 二进制 | 说明 | 对外端口 |
 | --- | --- | --- | --- |
 | `lingniu-go-gateway.service` | `gateway` | GB32960 TCP、JT808 TCP、宇通 MQTT 接入，解析后写 Kafka RAW 和统一事件 | TCP `32960`、TCP `808` |
 | `lingniu-go-history-writer.service` | `history-writer` | 消费 Kafka RAW，写 TDengine RAW、位置点、里程点核心表 | 无 HTTP |
 | `lingniu-go-stat-writer.service` | `stat-writer` | 消费 Kafka RAW，按总里程差值法写 MySQL 每日指标 | 无 HTTP |
 | `lingniu-go-realtime-api.service` | `realtime-api` | 消费统一事件写 Redis，并提供实时、历史、统计查询 API | HTTP `20210` |
 信达 Push 已废弃，不参与当前 Go 生产链路。旧 Java/Docker 服务不应占用 `808`、`32960`、`20210`。
 ## 应用 ECS
 | 项 | 值 |
 | --- | --- |
 | 公网 IP | `115.29.187.205` |
 | 登录用户 | `root` |
 | 部署目录 | `/opt/lingniu-go-native` |
 | 当前 release | `/opt/lingniu-go-native/current` |
 | 环境文件目录 | `/opt/lingniu-go-native/env` |
 | systemd unit 目录 | `/etc/systemd/system` |
 | 对外服务 | `32960`、`808`、`20210` |
 运行目录结构：
 ```text
 /opt/lingniu-go-native/
  current -> /opt/lingniu-go-native/releases/<git-short-sha>
  releases/<git-short-sha>/
    gateway
    history-writer
    stat-writer
    realtime-api
  env/
    gateway.env
    history-writer.env
    stat-writer.env
    realtime-api.env
  spool/gateway/
 ```
 ## 中间件
 | 组件 | 内网地址 | 公网地址 | 用途 |
 | --- | --- | --- | --- |
 | Kafka | `172.17.111.56:9092` | `114.55.58.251:9092` | RAW 和统一事件消息总线 |
 | TDengine | `172.17.111.57:6041` | `115.29.185.82:6041` | RAW、位置、里程点时序热存储 |
 | MySQL RDS | `rm-bp179zbv481rnw3e2.mysql.rds.aliyuncs.com:3306` | `rm-bp179zbv481rnw3e2no.mysql.rds.aliyuncs.com:3306` | 身份映射、JT808 注册、每日指标 |
 | Redis RDS | `r-bp1u741kij7e51i481.redis.rds.aliyuncs.com:6379` | 无 | 准实时车辆状态缓存 |
 生产应用之间访问中间件优先使用内网地址。RDS 白名单需要允许应用 ECS 私网访问。
 ## Kafka Topic
 | Topic | 生产者 | 消费者 | 内容 |
 | --- | --- | --- | --- |
 | `vehicle.raw.go.gb32960.v1` | `gateway` | `history-writer`、`stat-writer` | GB32960 完整 RAW 记录 |
 | `vehicle.raw.go.jt808.v1` | `gateway` | `history-writer`、`stat-writer` | JT808 完整 RAW 记录 |
 | `vehicle.raw.go.yutong-mqtt.v1` | `gateway` | `history-writer` | 宇通 MQTT 完整 RAW 记录 |
 | `vehicle.event.go.unified.v1` | `gateway` | `realtime-api` | 三类协议统一事件，用于 Redis 实时状态 |
 `gateway` 配置了 Kafka retry；生产 env 中启用 `KAFKA_SPOOL_DIR` 时，本地 spool 可在 Kafka 短暂不可用后回放。
 Kafka 消费组：
 | Consumer Group | Topic | 当前验证 |
 | --- | --- | --- |
 | `go-history-writer` | 三个 `vehicle.raw.go.*` topic | 2026-07-02 验证 lag 为 `0` |
 | `go-stat-writer` | `vehicle.raw.go.gb32960.v1`、`vehicle.raw.go.jt808.v1` | 2026-07-02 验证 lag 为 `0` |
 | `go-realtime-api` | `vehicle.event.go.unified.v1` | 2026-07-02 验证 lag 为 `0` |
 可重复 smoke：
 ```bash
 python3 tools/go_kafka_prod_smoke.py --host 114.55.58.251 --user root --max-lag 100
 ```
 该脚本通过 SSH 登录 Kafka ECS，检查 Go 生产 topic 是否存在，并校验 `go-history-writer`、`go-stat-writer`、`go-realtime-api` 的消费组 lag。运行环境需要已配置 SSH 免密或已建立可用的 SSH 认证方式。
 ## TDengine 数据层
 默认数据库：`lingniu_vehicle_ts`
 | 表 | 类型 | 说明 |
 | --- | --- | --- |
 | `raw_frames` | stable | 完整 RAW 帧，包含 `raw_hex`、`parsed_json`、`fields_json`、`source_endpoint` 和协议/车辆 tags |
 | `vehicle_locations` | stable | 最小化位置历史，保留 `frame_id` 回链 RAW |
 | `vehicle_mileage_points` | stable | 最小化总里程点，供历史查询和统计复核 |
 设计原则：
 - 完整结构化 payload 只落在 `raw_frames.parsed_json` / `fields_json`。
 - `vehicle_locations` 和 `vehicle_mileage_points` 只保留核心查询字段，不重复保存完整 JSON。
 - `telemetry_fields` 不由当前服务维护，字段配置解析由独立子服务处理。
 - API 传入东八区时间时，服务会转换为 TDengine 当前存储使用的 UTC 字面量再查询。
 ## MySQL 数据层
 默认业务库：`lingniu_vehicle_data`
 | 表 | 维护方 | 说明 |
 | --- | --- | --- |
 | `vehicle_identity_binding` | 人工/外部主数据 | VIN 映射主表，用 `phone`、`device_id`、`plate` 降级定位 VIN |
 | `jt808_registration` | `gateway` 自动写入 | 仅 JT808 注册和鉴权记录，以 `phone` 作为主键，记录设备、车牌、厂家、鉴权、来源端点 |
 | `vehicle_daily_metric` | `stat-writer` 自动写入 | 每日指标表，保存 `daily_mileage_km` 和 `daily_total_mileage_km` |
 每日里程算法：
 ```text
 daily_mileage_km = 当日最大 total_mileage_km - 当日最小 total_mileage_km
 daily_total_mileage_km = 当日最大 total_mileage_km
 ```
 统计按 `Asia/Shanghai` 自然日归档，当前支持 GB32960、JT808、宇通 MQTT 中能解析出 `total_mileage_km` 的数据。JT808 的总里程来自位置附加信息 `0x01`，单位按协议转换为 km；宇通 MQTT 的 `TOTAL_MILEAGE` 原始单位为米，入库前转换为 km。
 ## Redis 实时层
 `realtime-api` 消费 `vehicle.event.go.unified.v1`，按 VIN/vehicle key 维护准实时快照。主要能力：
 | API | 说明 |
 | --- | --- |
 | `/api/realtime/vehicles/{vin}` | 查询车辆合并实时快照 |
 | `/api/realtime/vehicles/{vin}/online` | 查询车辆是否在线 |
 | `/api/realtime/vehicles/{vin}/protocols/{protocol}` | 查询指定协议的实时快照 |
 Redis 只作为实时缓存；历史和统计以 TDengine/MySQL 为准。
 ## API 入口
 公网基础地址：
 ```text
 http://115.29.187.205:20210
 ```
 常用查询：
 ```bash
 curl -sS 'http://115.29.187.205:20210/api/history/raw-frames?protocol=GB32960&dateFrom=2026-07-02T00:00:00%2B08:00&dateTo=2026-07-03T00:00:00%2B08:00&limit=1'
 curl -sS 'http://115.29.187.205:20210/api/history/raw-frames?protocol=JT808&dateFrom=2026-07-02T00:00:00%2B08:00&dateTo=2026-07-03T00:00:00%2B08:00&limit=1'
 curl -sS 'http://115.29.187.205:20210/api/history/raw-frames?protocol=YUTONG_MQTT&dateFrom=2026-07-02T00:00:00%2B08:00&dateTo=2026-07-03T00:00:00%2B08:00&limit=1'
 curl -sS 'http://115.29.187.205:20210/api/history/locations?protocol=JT808&dateFrom=2026-07-02T00:00:00%2B08:00&dateTo=2026-07-03T00:00:00%2B08:00&limit=1'
 curl -sS 'http://115.29.187.205:20210/api/history/mileage-points?protocol=JT808&dateFrom=2026-07-02T00:00:00%2B08:00&dateTo=2026-07-03T00:00:00%2B08:00&limit=1'
 curl -sS 'http://115.29.187.205:20210/api/stats/daily-metrics?dateFrom=2026-07-02&dateTo=2026-07-02&limit=20'
 ```
 分页参数统一使用 `limit` 和 `offset`。
 部署后推荐直接运行 Go 原生生产 smoke：
 ```bash
 python3 tools/go_prod_acceptance.py --date 2026-07-02
 ```
 该聚合脚本会串行执行 systemd/端口检查、Kafka topic/consumer lag 检查、HTTP 数据链路检查，任一子检查失败时整体退出码为非 0。需要 SSH 可登录应用 ECS 和 Kafka ECS。
 也可以单独运行子检查：
 ```bash
 python3 tools/go_systemd_prod_smoke.py --host 115.29.187.205 --user root
 python3 tools/go_native_prod_smoke.py --date 2026-07-02 --timeout 8
 ```
 `go_systemd_prod_smoke.py` 通过 SSH 检查四个 Go systemd 服务是否 `active` 且 `enabled`，并确认 `808`、`32960` 由 `gateway` 监听、`20210` 由 `realtime-api` 监听，同时要求 `/opt/lingniu-go-native/current` 指向有效 release、四个生产二进制均可执行、`/opt/lingniu-go-native/spool/gateway` 没有待回放文件，避免旧 Java/Docker 进程占用生产端口、部署目录错乱或 Kafka spool 静默堆积。运行环境需要已配置 SSH 免密或已建立可用的 SSH 认证方式。
 `go_native_prod_smoke.py` 通过 `20210` HTTP API 验证 GB32960、JT808、宇通 MQTT 的 RAW 查询及结构化 `parsed_json`，三类协议的位置和里程点查询及 `frame_id` RAW 回链，GB32960/JT808 的 `daily_mileage_km`、`daily_total_mileage_km` 统计公式，以及三类协议的 Redis realtime snapshot、online、protocol 查询。实时 snapshot/protocol 查询会校验 `updated_at_ms` 新鲜度；默认检查今天东八区数据时，还会要求三类 RAW 最新样本不超过 15 分钟，避免旧数据误判为接收正常；任一检查不达标时退出码为非 0。
 ## 部署命令
 推荐使用仓库脚本发布完整 Go 原生 release。脚本会在本机/CI 构建 Linux amd64 四个二进制，打包上传到应用 ECS，切换 `/opt/lingniu-go-native/current`，逐个重启四个 systemd 服务，等待 gateway Kafka spool 清空，并在发布后运行聚合生产验收：
 ```bash
 python3 tools/go_native_deploy.py --date 2026-07-02
 ```
 脚本不会保存 SSH 或数据库密钥；认证仍使用当前操作环境可用的 SSH 凭据。需要跳过发布后验收时可显式追加 `--skip-acceptance`，但生产发布默认应保留验收。发布后 spool 默认最多等待 `900` 秒，可用 `--spool-drain-timeout` 和 `--spool-poll-interval` 调整。
 脚本执行的发布动作等价于：
 ```bash
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' ./cmd/gateway
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' ./cmd/history-writer
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' ./cmd/stat-writer
 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags='-s -w' ./cmd/realtime-api
 scp release.tar.gz root@115.29.187.205:/tmp/
 ln -sfn /opt/lingniu-go-native/releases/<git-short-sha> /opt/lingniu-go-native/current
 systemctl daemon-reload
 systemctl restart lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api
 ```
 只更新查询 API 时，可以仅替换 `/opt/lingniu-go-native/current/realtime-api` 并重启：
 ```bash
 systemctl restart lingniu-go-realtime-api.service
 ```
 ## 运行检查
 ```bash
 python3 tools/go_systemd_prod_smoke.py --host 115.29.187.205 --user root
 systemctl is-active lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api
 ss -lntp | egrep ':(808|32960|20210)\b'
 journalctl -u lingniu-go-gateway --since '5 minutes ago' --no-pager
 journalctl -u lingniu-go-history-writer --since '5 minutes ago' --no-pager
 journalctl -u lingniu-go-stat-writer --since '5 minutes ago' --no-pager
 journalctl -u lingniu-go-realtime-api --since '5 minutes ago' --no-pager
 ```
 2026-07-02 01:30 CST 已验证：
 - 四个 Go systemd 服务均为 `active` 且 `enabled`。
 - `/opt/lingniu-go-native/current` 指向有效 release，四个生产二进制均存在且可执行。
 - `gateway` 正在监听 `32960` 和 `808`。
 - `realtime-api` 正在监听 `20210`。
 - gateway Kafka spool 当前无待回放文件。
 - GB32960、JT808、YUTONG_MQTT 的东八区 RAW 查询均可命中生产数据，且最新 RAW 样本包含结构化 `parsed_json`。
 - GB32960、JT808、YUTONG_MQTT 的最新 RAW 样本均在 15 分钟内。
 - GB32960、JT808、YUTONG_MQTT 的 `vehicle_locations`、`vehicle_mileage_points` 查询均可命中生产数据，且样本包含 `frame_id` 回链 RAW。
 - `vehicle_daily_metric` 可查到 `daily_mileage_km` 和 `daily_total_mileage_km`，且公式满足 `daily_mileage_km = latest_total_mileage_km - first_total_mileage_km`、`daily_total_mileage_km = latest_total_mileage_km`。
 - Redis realtime 可查到 GB32960、JT808、YUTONG_MQTT 的在线状态和协议快照，且 snapshot/protocol 快照最近刷新。
--- a/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md
+++ b/docs/operations/go-vehicle-gateway-verification-result-2026-07-01.md
@@ -0,0 +1,888 @@
 # Go Vehicle Gateway 旁路验证记录
 验证时间：2026-07-01 22:00-22:10 CST
 ## 部署版本
 - Git commit：`60ca42e`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-60ca42e-20260701220622`
 - 部署方式：ECS `115.29.187.205` 上 Docker Compose 旁路部署
 - Compose 目录：`/opt/lingniu-go`
 ## 旁路端口和 topic
 为了不影响现有 Java 生产服务，本次没有占用生产端口和生产 topic。
 | 项 | 值 |
 |---|---|
 | GB32960 旁路 TCP | `115.29.187.205:23296 -> container :32960` |
 | JT808 旁路 TCP | `115.29.187.205:18080 -> container :808` |
 | Realtime API | `115.29.187.205:20210` |
 | GB32960 RAW topic | `vehicle.raw.go.gb32960.v1` |
 | JT808 RAW topic | `vehicle.raw.go.jt808.v1` |
 | Yutong MQTT RAW topic | `vehicle.raw.go.yutong-mqtt.v1` |
 | Unified topic | `vehicle.event.go.unified.v1` |
 ## 容器状态
 ECS 上四个 Go 容器均已启动：
 ```text
 go-vehicle-gateway   Up
 go-history-writer    Up
 go-stat-writer       Up
 go-realtime-api      Up
 ```
 ## Kafka 验证
 向 `18080` 注入 JT808 样例帧后，`vehicle.raw.go.jt808.v1` 和
 `vehicle.event.go.unified.v1` 均消费到统一 JSON envelope。
 样例解析结果包含：
 - `protocol=JT808`
 - `message_id=0x0200`
 - `phone=013307795425`
 - `longitude=121.069881`
 - `latitude=30.590151`
 - `speed_kmh=23`
 - `total_mileage_km=10241.2`
 - 表 27 附加项 `0x01` 原始值 `0001900C`
 ## TDengine 验证
 目标库：`lingniu_vehicle_ts`
 ```text
 raw_frames count = 3
 vehicle_locations count = 2
 vehicle_mileage_points count = 2
 ```
 最新 RAW 标识：
 ```text
 GB32960 | LNBSCB3D4R1234567 | LNBSCB3D4R1234567 |
 JT808   | JT808:013307795425 |                    | 013307795425
 JT808   | JT808:013307795425 |                    | 013307795425
 ```
 说明：JT808 样例 phone 当前没有在 `vehicle_identity_binding` 中解析到 VIN，因此
 TDengine tag 使用 `vehicle_key=JT808:013307795425`。
 ## Redis 验证
 向 `23296` 注入带 VIN 的 GB32960 合成帧后，Realtime API 可查询：
 ```text
 GET /api/realtime/vehicles/LNBSCB3D4R1234567
 ```
 返回字段包含：
 - `vin=LNBSCB3D4R1234567`
 - `protocols=["GB32960"]`
 - `online=true`
 - `speed_kmh=30`
 - `total_mileage_km=10000`
 - `soc_percent=85`
 - `longitude=121`
 - `latitude=30.56`
 ## MySQL 统计验证
 向 `23296` 注入带 VIN 的 GB32960 合成帧后，`vehicle_daily_metric` 写入：
 ```text
 LNBSCB3D4R1234567 | 2020-07-01 | GB32960 | daily_mileage_km       | 0.000     | 10000.000 | 10000.000 | 1
 LNBSCB3D4R1234567 | 2020-07-01 | GB32960 | daily_total_mileage_km | 10000.000 | 10000.000 | 10000.000 | 1
 ```
 说明：本次 GB32960 合成帧的设备时间为测试值，因此统计日期为 `2020-07-01`。
 ## 已修复问题
 - TDengine WebSocket 普通 `INSERT` 使用参数占位符时，字符串未按预期加引号，导致语法错误。已在 `60ca42e` 中改为显式 SQL literal 转义。
 - MySQL Go DSN 中 `charset=utf8mb4%2Cutf8` 会被 driver 传给 MySQL，导致语法错误；ECS 旁路 env 已改为 `charset=utf8mb4`。
 - TDengine ECS 当前可用 root 密码与早先记录不一致，本次旁路 env 已按实际可认证值修正。
 ## 未完成
 - 未切换真实生产端口 `32960/808`。
 - 未将真实外部 32960/808 流量转发到 Go 旁路端口。
 - 未开启宇通 MQTT 正式订阅。
 - JT808 样例未解析到 VIN，需维护 `vehicle_identity_binding` 后再验证 808 每日统计。
 ## 2026-07-01 22:22 真实归档帧复验
 部署版本已更新：
 - Git commit：`5f4f4fd`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-5f4f4fd-20260701222128`
 本轮补充验证内容：
 - JT808 支持 2019 版 versioned header，真实帧 `0x0200` 可解析出 `phone=14894135060`、`longitude=117.178187`、`latitude=30.570155`、`speed_kmh=33.4`、`total_mileage_km=7868.9`。
 - GB32960 真实燃料电池帧 `VIN=LB9A32A21R0LS1707` 可解析 `0x01` 整车、`0x02` 驱动电机、`0x03` 燃料电池、`0x04` 发动机、`0x05` 位置、`0x06` 极值、`0x07` 报警、`0x08` 电压、`0x09` 温度；后续 `0x30` 广东燃料电池扩展暂以 unknown raw 保留。
 - GB32960 真实帧字段包含 `fuel_cell_hydrogen_consumption_kg_per_100km=1.8`、`longitude=120.800326`、`latitude=31.634907`、`total_mileage_km=53490.9`。
 - Realtime API `GET /api/realtime/vehicles/LB9A32A21R0LS1707` 已返回上述经纬度和氢耗字段。
 - TDengine `vehicle_locations` 和 `vehicle_mileage_points` 已写入真实 GB32960 位置和里程点：
 ```text
 2020-07-01 08:09:22 | GB32960 | LB9A32A21R0LS1707 | lon=120.800326 | lat=31.634907 | mileage=53490.9
 ```
 后续仍需补齐：
 - JT808 真实 phone `14894135060` 仍未解析到 VIN，需维护身份绑定后再验证 VIN 维度实时和统计。
 ## 2026-07-01 22:28 广东燃料电池扩展复验
 部署版本已更新：
 - Git commit：`a15de91`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-a15de91-20260701222743`
 本轮补充验证内容：
 - GB32960 真实燃料电池帧 `VIN=LB9A32A21R0LS1707` 的 vendor 尾部已从 `unknown_unit` 补为结构化块：
  `0x30 gd_fc_stack`、`0x31 gd_fc_auxiliary`、`0x32 gd_fc_dcdc`、`0x33 gd_fc_air_conditioner`、
  `0x34 gd_fc_vehicle_info`、`0x80 gd_fc_demo_extension`、`0x83 gd_fc_vendor_tlv`。
 - Kafka `vehicle.raw.go.gb32960.v1` 最新消息包含上述 block，并输出关键扁平字段：
  `gd_fc_stack_hydrogen_inlet_pressure_kpa=97`、`gd_fc_stack_cell_count=108`、
  `gd_fc_vehicle_hydrogen_mass_kg=4.3`、`gd_fc_demo_stack_temp_c=65`。
 - Realtime API `GET /api/realtime/vehicles/LB9A32A21R0LS1707` 已返回 vendor 扁平字段：
 ```text
 gd_fc_dcdc_controller_temp_c=47
 gd_fc_demo_stack_temp_c=65
 gd_fc_stack_cell_count=108
 gd_fc_stack_frame_cell_count=108
 gd_fc_stack_hydrogen_inlet_pressure_kpa=97
 gd_fc_stack_water_outlet_temp_c=65
 gd_fc_vehicle_hydrogen_mass_kg=4.3
 ```
 - TDengine `raw_frames` 中 GB32960 行数增加到 `4`，最新 RAW 标识：
 ```text
 2026-07-01 14:28:24.869 | 172.20.0.1:47082 | GB32960 | LB9A32A21R0LS1707 | OK
 ```
 后续仍需补齐：
 - JT808 真实 phone `14894135060` 到 VIN 的绑定数据维护与统计复验。
 - Go 旁路尚未切换到生产 `32960/808` 端口；仍运行在 `23296/18080`。
 ## 2026-07-01 22:43 JT808 前导零 phone 身份解析复验
 部署版本已更新：
 - Git commit：`6b55694`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-6b55694-20260701224300`
 本轮修复内容：
 - JT808 2011 老版包头的终端手机号按 BCD[6] 解析会保留前导 `0`，例如包头为 `013079963379`。
 - `vehicle_identity_binding.phone` 中实际维护的是去前导零后的手机号 `13079963379`。
 - 身份解析候选键已调整为先查原始 phone，再查去前导零 phone，之后再按 `device_id`、`plate` 降级。
 真实帧复验样本：
 - 归档帧：`/opt/lingniu/vehicle-ingest/gb32960/archive/2026/07/01/JT808/unknown/1782903942845000.bin`
 - 消息：`0x0200` 位置信息汇报
 - 包头 phone：`013079963379`
 - 绑定表 phone：`13079963379`
 - 解析 VIN：`LKLG7C4E3NA774736`
 Kafka `vehicle.raw.go.jt808.v1` 最新消息确认：
 ```text
 vin=LKLG7C4E3NA774736
 phone=013079963379
 parsed.header.phone_trim_zero=13079963379
 parsed.identity.resolved=true
 parsed.identity.source=phone
 parsed.identity.value=13079963379
 ```
 Realtime API 确认：
 ```text
 GET /api/realtime/vehicles/LKLG7C4E3NA774736
 longitude=119.557997
 latitude=29.049092
 speed_kmh=0
 total_mileage_km=0
 device_time=2026-07-01T19:05:40+08:00
 ```
 TDengine 确认：
 ```text
 raw_frames:
 2026-07-01 14:49:10.913 | JT808 | LKLG7C4E3NA774736 | phone=013079963379 | message_id=512
 vehicle_locations:
 2026-07-01 11:05:40.000 | JT808 | LKLG7C4E3NA774736 | lon=119.557997 | lat=29.049092 | speed=0 | mileage=0
 vehicle_mileage_points:
 2026-07-01 11:05:40.000 | JT808 | LKLG7C4E3NA774736 | mileage=0
 ```
 MySQL `vehicle_daily_metric` 确认：
 ```text
 LKLG7C4E3NA774736 | JT808 | 2026-07-01 | daily_mileage_km       | 0.000 | sample_count=1 | TOTAL_MILEAGE_DIFF
 LKLG7C4E3NA774736 | JT808 | 2026-07-01 | daily_total_mileage_km | 0.000 | sample_count=1 | TOTAL_MILEAGE_DIFF
 ```
 说明：该真实位置帧携带的表 27 附加项 `0x01` 总里程值为 `0`，因此本次只验证身份解析、链路落地和差值统计写入；要验证非零日里程，需要回放或等待同一 VIN 的非零总里程连续位置点。
 ## 2026-07-01 22:55 Kafka 发布重试部署复验
 部署版本已更新：
 - Git commit：`7e7066d`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-7e7066d-20260701225503`
 本轮修复内容：
 - gateway 的 Kafka 发布增加同步重试封装。
 - 默认配置：
  - `KAFKA_PUBLISH_ATTEMPTS=3`
  - `KAFKA_PUBLISH_BACKOFF_MS=100`
  - `KAFKA_PUBLISH_TIMEOUT_MS=3000`
 - RAW 仍先于 unified event 写入；RAW 写失败不会继续写 unified。
 - 单元测试覆盖首次失败后成功、重试耗尽返回错误、上下文取消时停止重试。
 部署后容器状态：
 ```text
 go-vehicle-gateway | go-7e7066d-20260701225503 | Up
 go-history-writer  | go-7e7066d-20260701225503 | Up
 go-stat-writer     | go-7e7066d-20260701225503 | Up
 go-realtime-api    | go-7e7066d-20260701225503 | Up
 ```
 真实 808 帧回放复验：
 ```text
 source_endpoint=172.20.0.1:51966
 protocol=JT808
 message_id=0x0200
 phone=013079963379
 vin=LKLG7C4E3NA774736
 parsed.identity.value=13079963379
 ```
 Kafka `vehicle.raw.go.jt808.v1` 确认新消息写入，partition 6 offset 从 `1` 增加到 `2`。最新消息包含：
 ```text
 received_at_ms=1782917751903
 source_endpoint=172.20.0.1:51966
 vin=LKLG7C4E3NA774736
 fields.longitude=119.557997
 fields.latitude=29.049092
 fields.total_mileage_km=0
 ```
 TDengine `raw_frames` 确认新 RAW 落地：
 ```text
 2026-07-01 14:55:51.903 | JT808 | LKLG7C4E3NA774736 | phone=013079963379 | source=172.20.0.1:51966
 ```
 Realtime API 确认 Redis 已刷新：
 ```text
 GET /api/realtime/vehicles/LKLG7C4E3NA774736
 received_at_ms=1782917751903
 source_endpoint=172.20.0.1:51966
 longitude=119.557997
 latitude=29.049092
 total_mileage_km=0
 ```
 说明：当前重试层只能覆盖 Kafka 短暂抖动；如果 Kafka 长时间不可用，仍需后续增加本地磁盘 spool/WAL 和恢复补发。
 ## 2026-07-01 23:02 切换 Go 到生产 32960/808 端口
 本轮操作：
 - 停止 ECS 上原有 Java Docker 容器：
  - `gb32960-ingest-app`
  - `jt808-ingest-app`
  - `yutong-mqtt-app`
  - `vehicle-history-app`
  - `vehicle-analytics-app`
  - `vehicle-state-app`
  - `telemetry-field-parser-app`
 - 保留 Go sidecar 和 Portainer agent。
 - 修改 `/opt/lingniu-go/.env`：
  - `GO_GB32960_TCP_PORT=32960`
  - `GO_JT808_TCP_PORT=808`
 - Go gateway 使用镜像：
  - `crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-243de5c-20260701230028`
 - 开启 Kafka 本地 spool：
  - host：`/opt/lingniu-go/spool/gateway`
  - container：`/data/spool/gateway`
 端口验证：
 ```text
 0.0.0.0:32960 -> go-vehicle-gateway:32960
 0.0.0.0:808   -> go-vehicle-gateway:808
 18080/23296   -> 已释放
 ```
 启动日志确认：
 ```text
 kafka durable spool enabled dir=/data/spool/gateway replay_interval_ms=1000
 tcp listener started protocol=GB32960 addr=[::]:32960
 tcp listener started protocol=JT808 addr=[::]:808
 ```
 真实连接确认：
 ```text
 GB32960 external remote: 8.134.95.166:50084
 JT808 external remote: 115.231.168.135:13801
 ```
 生产 `808` 回放复验：
 ```text
 source_endpoint=172.20.0.1:54680
 vin=LKLG7C4E3NA774736
 phone=013079963379
 longitude=119.557997
 latitude=29.049092
 total_mileage_km=0
 ```
 TDengine 最新 RAW 复验显示生产 808 已有真实外部数据持续落地：
 ```text
 2026-07-01 15:03:02.960 | JT808 | LKLG7C4E1NA774802 | 013079963291 | 222.66.200.68:28394
 2026-07-01 15:03:02.114 | JT808 |                  | 14894135583  | 122.152.221.156:33871
 2026-07-01 15:03:01.352 | JT808 |                  | 013307795519 | 115.231.168.135:13801
 2026-07-01 15:03:01.330 | JT808 | LKLG7C4E3NA774736 | 013079963379 | 222.66.200.68:28393
 ```
 Kafka spool 目录确认：
 ```text
 /opt/lingniu-go/spool/gateway file count = 0
 ```
 说明：生产 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 车辆进入统计。
 ## 2026-07-01 23:23 808 注册身份自动维护复验
 部署版本已更新：
 - Git commit：`7b44f97`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-7b44f97-20260701232200`
 本轮修复内容：
 - 808 `0x0100` 注册帧解析 `province`、`city`、`manufacturer`、`device_type`、`device_id`、`plate_color`、`plate`。
 - 808 `0x0102` 鉴权帧解析 `auth_token`。
 - Go gateway 在 identity resolve 后写入 `jt808_registration`，普通上行也会刷新 `latest_seen_at`。
 - 注册帧通过车牌解析到 VIN 后，会尝试把 phone/device/plate 反写到 `vehicle_identity_binding`。
 - 注册帧车牌支持 GBK 解码，避免 `Incorrect string value` 写入错误。
 验证命令：
 ```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
 ```
 ECS 运行状态：
 ```text
 go-vehicle-gateway | go-7b44f97-20260701232200 | 0.0.0.0:808->808, 0.0.0.0:32960->32960
 go-history-writer  | go-7b44f97-20260701232200 | Up
 go-stat-writer     | go-7b44f97-20260701232200 | Up
 go-realtime-api    | go-7b44f97-20260701232200 | 0.0.0.0:20210->20210
 ```
 生产日志确认：
 - 新版本启动后真实 808、32960 连接持续进入。
 - GBK 车牌注册帧不再出现 `Incorrect string value`。
 MySQL `jt808_registration` 确认：
 ```text
 registration_rows=214
 distinct_phone=214
 vin_rows=74
 plate_rows=74
 device_rows=72
 013079963379 | device_id=9963379 | plate=沪A06788F | vin=LKLG7C4E3NA774736 | latest_registered_at=2026-07-01 23:23:01
 013079963321 | device_id=9963321 | plate=沪A59613F | vin=LKLG7C4EXNA774796 | latest_registered_at=2026-07-01 23:23:04
 ```
 说明：`jt808_registration.phone` 保存 808 包头原始 phone；`vehicle_identity_binding.phone` 中已有部分去前导零 phone。Go resolver 会同时查询原始 phone 和去前导零 phone。
 ## 2026-07-01 23:28 生产链路与指标清理复验
 本轮复验目标：
 - 确认 Go gateway 的 Kafka durable spool 是重启窗口残留，而不是持续发布失败。
 - 确认 stat-writer / history-writer / realtime-api 的 Kafka consumer group 无 lag。
 - 确认真实 808 车辆 registration、TDengine RAW/里程点、Redis 实时查询均在持续更新。
 - 清理之前生产合成回放产生的 JT808 当日指标测试数据。
 Kafka topic / consumer group：
 ```text
 vehicle.raw.go.jt808.v1    有持续 offset
 vehicle.raw.go.gb32960.v1  有持续 offset
 vehicle.event.go.unified.v1 有持续 offset
 go-stat-writer    LAG=0
 go-history-writer LAG=0
 go-realtime-api   LAG=0
 ```
 TDengine：
 ```text
 raw_frames:
 JT808   2922
 GB32960 27
 vehicle_mileage_points:
 JT808   2050
 GB32960 2
 ```
 Redis 实时查询样例：
 ```text
 GET /api/realtime/vehicles/LKLG7C4E3NA774736
 vin=LKLG7C4E3NA774736
 source_endpoint=222.66.200.68:29646
 plate=沪A06788F
 longitude=119.556866
 latitude=29.047911
 total_mileage_km=12345.6
 ```
 说明：该 Redis merged 快照保留了此前有效 `total_mileage_km=12345.6`，后续真实 808 位置帧上报的 `total_mileage_km=0` 不会覆盖该字段。TDengine 中该 VIN 后续真实里程点的 `total_mileage_km` 均为 0，因此 stat-writer 按“只统计正总里程”的规则不再写 JT808 每日指标。
 MySQL 指标清理：
 ```text
 删除前：
 LKLG7C4E2NA774775 | JT808 | 2026-07-01 | daily_mileage_km       | first=0       | latest=0       | sample_count=7
 LKLG7C4E2NA774775 | JT808 | 2026-07-01 | daily_total_mileage_km | first=0       | latest=0       | sample_count=7
 LKLG7C4E3NA774736 | JT808 | 2026-07-01 | daily_mileage_km       | first=12345.6 | latest=12345.6 | sample_count=13
 LKLG7C4E3NA774736 | JT808 | 2026-07-01 | daily_total_mileage_km | first=12345.6 | latest=12345.6 | sample_count=13
 删除后等待真实流量窗口：
 JT808 2026-07-01 metric rows = 0
 ```
 清理原因：
 - `LKLG7C4E3NA774736` 的 12345.6 来自此前生产连通性合成回放，不是真实平台上报。
 - `LKLG7C4E2NA774775` 的 0 指标来自旧逻辑污染，当前 stat-writer 已跳过非正总里程。
 Kafka spool：
 ```text
 23:24 spool_count=904
 23:25 spool_count=862
 23:28 spool_count=722
 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。
 ## 2026-07-01 23:50 生产端口接管与 RAW 查询 API 复验
 部署版本：
 - Git commit：`5937132`
 - 镜像：`crpi-85r4m0ackrm3qpje.cn-shanghai.personal.cr.aliyuncs.com/oneos/vehicle-gateway-go:go-5937132-20260701234220`
 生产端口状态：
 ```text
 go-vehicle-gateway 0.0.0.0:808->808/tcp
 go-vehicle-gateway 0.0.0.0:32960->32960/tcp
 ```
 旧 Java 容器状态：
 ```text
 gb32960-ingest-app              restart=no status=exited
 jt808-ingest-app                restart=no status=exited
 yutong-mqtt-app                 restart=no status=exited
 vehicle-history-app             restart=no status=exited
 vehicle-analytics-app           restart=no status=exited
 vehicle-state-app               restart=no status=exited
 telemetry-field-parser-app      restart=no status=exited
 ```
 生产连接确认：
 - JT808 端口 `808` 已收到外部连接：`222.66.200.68`、`115.231.168.135`。
 - GB32960 端口 `32960` 已收到外部连接：`8.134.95.166`、`117.160.0.65`。
 - ECS 当前没有 `8089` 监听。
 RAW 查询 API：
 ```text
 GET /api/history/raw-frames
 ```
 生产可访问样例：
 ```text
 http://115.29.187.205:20210/api/history/raw-frames?protocol=JT808&vin=LKLG7C4E3NA774736&messageId=0x0200&limit=1
 http://115.29.187.205:20210/api/history/raw-frames?protocol=GB32960&vin=LB9A32A21R0LS1707&limit=1
 ```
 接口复验结果：
 ```text
 JT808_RAW:
 total=1
 protocol=JT808
 vin=LKLG7C4E3NA774736
 phone=013079963379
 message_id=512
 message_id_hex=0x0200
 parse_status=OK
 raw_hex_len=94
 parsed_json_len=651
 fields_json_len=186
 GB32960_RAW:
 total=1
 protocol=GB32960
 vin=LB9A32A21R0LS1707
 message_id=2
 message_id_hex=0x0002
 parse_status=OK
 raw_hex_len=1548
 parsed_json_len=3698
 fields_json_len=563
 ```
 同轮回归验证：
 ```text
 GET /api/realtime/vehicles/LKLG7C4E3NA774736/online
 online=true
 protocols=["JT808"]
 GET /api/stats/daily-metrics?vin=LB9A32A21R0LS1707&protocol=GB32960&dateFrom=2020-07-01&dateTo=2026-07-01&limit=1
 total=1
 protocol=GB32960
 metric_key=daily_mileage_km
 calculation_method=TOTAL_MILEAGE_DIFF
 ```
 说明：
 - RAW 查询已返回 `raw_hex`、`parsed_json`、`fields_json`，可以用于查看完整解析结果。
 - 日统计和实时查询在生产端口接管后仍可用。
 ## 2026-07-02 00:00 原生 systemd 部署与宇通 MQTT 复验
 根据本次 goal 的新要求，Go 接入链路后续不再使用 Docker 部署。本轮已中断 Docker 镜像构建路径，改为 ECS 原生 Linux 二进制 + systemd。
 部署版本：
 - Git commit：`594ab2d`
 - 部署目录：`/opt/lingniu-go-native`
 - 当前 release：`/opt/lingniu-go-native/releases/594ab2d`
 - 当前指针：`/opt/lingniu-go-native/current -> /opt/lingniu-go-native/releases/594ab2d`
 systemd 服务：
 ```text
 lingniu-go-gateway.service        active
 lingniu-go-history-writer.service active
 lingniu-go-stat-writer.service    active
 lingniu-go-realtime-api.service   active
 ```
 端口确认：
 ```text
 [::]:32960  gateway
 [::]:808    gateway
 [::]:20210  realtime-api
 ```
 Go Docker 容器已停止：
 ```text
 go-vehicle-gateway  Exited
 go-history-writer   Exited
 go-stat-writer      Exited
 go-realtime-api     Exited
 ```
 宇通 MQTT：
 ```text
 yutong mqtt client started
 mqtt subscribed broker=ssl://cpxlm.axxc.cn:38883 topic=/ytforward/shln/+ qos=1
 ```
 说明：MQTT broker 存在短连接 `EOF` 后自动重连现象，但订阅后已收到真实数据并落 RAW。
 RAW 查询复验：
 ```text
 GET /api/history/raw-frames?protocol=YUTONG_MQTT&limit=3
 total=3
 protocol=YUTONG_MQTT
 vin=LMRKH9AC1R1004131
 vehicle_key=LMRKH9AC1R1004131
 parse_status=OK
 parsed_json_len=1104
 fields_json_len=116
 ```
 同轮回归：
 ```text
 GET /api/history/raw-frames?protocol=JT808&vin=LKLG7C4E3NA774736&messageId=0x0200&limit=1
 total=1
 parse_status=OK
 GET /api/history/raw-frames?protocol=GB32960&vin=LB9A32A21R0LS1707&limit=1
 total=1
 parse_status=OK
 GET /api/realtime/vehicles/LKLG7C4E3NA774736/online
 online=true
 protocols=["JT808"]
 ```
 本轮落地文件：
 - `deploy/systemd/README.md`
 - `deploy/systemd/lingniu-go-gateway.service`
 - `deploy/systemd/lingniu-go-history-writer.service`
 - `deploy/systemd/lingniu-go-stat-writer.service`
 - `deploy/systemd/lingniu-go-realtime-api.service`
 ## 2026-07-02 00:04 宇通 MQTT EOF 诊断
 现象：
 Go 原生部署后，`lingniu-go-gateway` 日志中出现多次：
 ```text
 mqtt connection lost error=EOF
 mqtt connection lost error=write: broken pipe
 mqtt subscribed topic=/ytforward/shln/+ qos=1
 ```
 10 分钟窗口统计：
 ```text
 mqtt subscribed = 33
 mqtt connection lost = 32
 ```
 对照旧 Java `yutong-mqtt-app` 历史日志，停止前也存在同类行为：
 ```text
 mqtt endpoint [yutong] received topic=/ytforward/shln/1 bytes=574
 mqtt endpoint [yutong] connection lost
 Caused by: java.io.EOFException
 mqtt endpoint [yutong] re-subscribed topic=/ytforward/shln/+ qos=1
 mqtt endpoint [yutong] received topic=/ytforward/shln/3 bytes=586
 ```
 判断：
 - EOF/短连接不是 Go TLS 支持或 systemd 原生部署新引入的问题。
 - 旧 Java 和新 Go 都表现为：订阅、收到数据、broker 断开、自动重连。
 - 当前链路可持续收到宇通 MQTT 数据并写入 TDengine RAW。
 复验：
 ```text
 GET /api/history/raw-frames?protocol=YUTONG_MQTT&limit=1
 total=1
 protocol=YUTONG_MQTT
 vin=LMRKH9ACXR1004094
 parse_status=OK
 parsed_json_len=1080
 fields_json_len=115
 ```
 运维建议：
 - 单条 EOF 不作为不可用判断。
 - 以 `YUTONG_MQTT` RAW 入库增长、最近成功 `mqtt subscribed` 时间、服务 `systemctl is-active` 作为可用性判断。
 - 如果 EOF 频率继续升高且 RAW 不再增长，再联系宇通侧确认 broker 长连接策略、同一 clientId 并发限制或网络出口策略。
--- a/docs/operations/go-vehicle-gateway-verification.md
+++ b/docs/operations/go-vehicle-gateway-verification.md
@@ -0,0 +1,158 @@
 # Go Vehicle Gateway 验证手册
 本文档用于验证 Go 重构运行面：
 - `go-vehicle-gateway`：GB32960 TCP、JT808 TCP、宇通 MQTT 接入。
 - `go-history-writer`：Kafka RAW 写 TDengine。
 - `go-stat-writer`：Kafka RAW 写 MySQL 每日指标。
 - `go-realtime-api`：Kafka unified event 写 Redis，并提供实时查询 API。
 ## 本地构建验证
 ```bash
 cd go/vehicle-gateway
 go test ./...
 go build ./cmd/gateway
 go build ./cmd/history-writer
 go build ./cmd/stat-writer
 go build ./cmd/realtime-api
 ```
 ## 生产原生部署验证
 ```bash
 python3 tools/go_prod_acceptance.py --date 2026-07-02
 ```
 该命令会聚合执行：
 - `go_systemd_prod_smoke.py`：应用 ECS systemd 服务 active/enabled、端口归属和 gateway spool
 - `go_kafka_prod_smoke.py`：Kafka topic 和消费组 lag
 - `go_native_prod_smoke.py`：HTTP API、RAW `parsed_json`、历史核心表 `frame_id` 回链、每日指标公式、Redis 实时新鲜度、TDengine/MySQL/Redis 数据链路
 如需单独检查 systemd：
 ```bash
 python3 tools/go_systemd_prod_smoke.py --host 115.29.187.205 --user root
 ```
 脚本通过 SSH 检查：
 - `lingniu-go-gateway.service`
 - `lingniu-go-history-writer.service`
 - `lingniu-go-stat-writer.service`
 - `lingniu-go-realtime-api.service`
 - 上述服务均为 `active` 且 `enabled`
 - `808`、`32960` 由 `gateway` 监听
 - `20210` 由 `realtime-api` 监听
 - `/opt/lingniu-go-native/spool/gateway` 无待回放文件
 ## 生产环境变量
 当前 goal 的生产面使用 ECS 原生 systemd 部署，不再以 Docker/Portainer 作为生产运行方式。以下环境变量维护在 `/opt/lingniu-go-native/env/*.env`：
 ```bash
 KAFKA_BROKERS=172.17.111.56:9092
 TDENGINE_DSN=root:<password>@ws(172.17.111.57:6041)/lingniu_vehicle_ts
 MYSQL_DSN=lingniu_vehicle:<password>@tcp(rm-bp179zbv481rnw3e2.mysql.rds.aliyuncs.com:3306)/lingniu_vehicle_data?parseTime=true&charset=utf8mb4,utf8&loc=Asia%2FShanghai
 IDENTITY_MYSQL_DSN=${MYSQL_DSN}
 VEHICLE_IDENTITY_TABLE=vehicle_identity_binding
 REDIS_ADDR=r-bp1u741kij7e51i481.redis.rds.aliyuncs.com:6379
 REDIS_PASSWORD=<password>
 REDIS_DB=50
 ```
 宇通 MQTT 开启时再配置：
 ```bash
 YUTONG_MQTT_ENABLED=true
 YUTONG_MQTT_URI=<mqtt-uri>
 YUTONG_MQTT_TOPICS=/ytforward/shln/+
 YUTONG_MQTT_CLIENT_ID=lingniu-go-yutong-mqtt
 YUTONG_MQTT_USERNAME=<username>
 YUTONG_MQTT_PASSWORD=<password>
 ```
 ## ECS 进程检查
 ```bash
 systemctl is-active lingniu-go-gateway lingniu-go-history-writer lingniu-go-stat-writer lingniu-go-realtime-api
 ss -lntp | egrep ':(808|32960|20210)\b'
 ```
 ## Kafka 验证
 优先使用 smoke 脚本做可重复检查：
 ```bash
 python3 tools/go_kafka_prod_smoke.py --host 114.55.58.251 --user root --max-lag 100
 ```
 脚本会检查 `vehicle.raw.go.gb32960.v1`、`vehicle.raw.go.jt808.v1`、`vehicle.raw.go.yutong-mqtt.v1`、`vehicle.event.go.unified.v1` 是否存在，并汇总 `go-history-writer`、`go-stat-writer`、`go-realtime-api` 的消费 lag。运行环境需要 SSH 免密或已建立可用的 SSH 认证方式。
 手工核对命令：
 ```bash
 kafka-console-consumer --bootstrap-server 172.17.111.56:9092 \
  --topic vehicle.raw.go.jt808.v1 --max-messages 1 --timeout-ms 10000
 kafka-console-consumer --bootstrap-server 172.17.111.56:9092 \
  --topic vehicle.raw.go.gb32960.v1 --max-messages 1 --timeout-ms 10000
 kafka-console-consumer --bootstrap-server 172.17.111.56:9092 \
  --topic vehicle.raw.go.yutong-mqtt.v1 --max-messages 1 --timeout-ms 10000
 kafka-console-consumer --bootstrap-server 172.17.111.56:9092 \
  --topic vehicle.event.go.unified.v1 --max-messages 1 --timeout-ms 10000
 kafka-consumer-groups --bootstrap-server 172.17.111.56:9092 \
  --describe --group go-history-writer
 kafka-consumer-groups --bootstrap-server 172.17.111.56:9092 \
  --describe --group go-stat-writer
 kafka-consumer-groups --bootstrap-server 172.17.111.56:9092 \
  --describe --group go-realtime-api
 ```
 ## TDengine 验证
 ```sql
 USE lingniu_vehicle_ts;
 SHOW STABLES;
 SELECT COUNT(*) FROM raw_frames;
 SELECT COUNT(*) FROM vehicle_locations;
 SELECT COUNT(*) FROM vehicle_mileage_points;
 ```
 ## MySQL 验证
 ```sql
 SELECT protocol, metric_key, COUNT(*)
 FROM vehicle_daily_metric
 GROUP BY protocol, metric_key;
 SELECT *
 FROM vehicle_daily_metric
 WHERE metric_key IN ('daily_mileage_km', 'daily_total_mileage_km')
 ORDER BY updated_at DESC
 LIMIT 20;
 ```
 ## Redis 实时查询
 ```bash
 curl -sS 'http://115.29.187.205:20210/api/realtime/vehicles/<vin>'
 curl -sS 'http://115.29.187.205:20210/api/realtime/vehicles/<vin>/online'
 curl -sS 'http://115.29.187.205:20210/api/realtime/vehicles/<vin>/protocols/JT808'
 ```
 ## 验收证据
 正式切换前至少记录：
 - 一个真实 GB32960 VIN 的 RAW、location、mileage point、Redis snapshot。
 - 一个真实 JT808 VIN/phone 的 RAW、location、mileage point、daily metric、Redis snapshot。
 - 一个真实宇通 MQTT VIN 或 device_id 的 RAW、Redis snapshot。
 - `go-history-writer` 和 `go-stat-writer` 重启后 Kafka offset 能继续推进。
--- a/docs/superpowers/plans/2026-07-01-go-ingest-redesign-phase1.md
+++ b/docs/superpowers/plans/2026-07-01-go-ingest-redesign-phase1.md
@@ -0,0 +1,720 @@
 # Go Vehicle Ingest Redesign Phase 1 Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Build the first production-capable Go runtime for GB32960, JT808, and Yutong MQTT ingestion with unified Kafka, TDengine, MySQL statistics, and Redis realtime state boundaries.
 **Architecture:** Create a new single Go module at `go/vehicle-gateway` and migrate only the useful pieces from the existing `go/ingest-edge` and `go/vehicle-state` prototypes. The gateway produces unified envelopes to Kafka; independent consumers write TDengine history, MySQL daily metrics, and Redis realtime state.
 **Tech Stack:** Go 1.26+, Kafka (`segmentio/kafka-go`), Redis (`redis/go-redis`), MySQL (`go-sql-driver/mysql`), TDengine official Go connector, MQTT (`eclipse/paho.mqtt.golang`), standard library TCP.
 ---
 ## File Structure
 - Create: `go/vehicle-gateway/go.mod`
 - Create: `go/vehicle-gateway/cmd/gateway/main.go`
 - Create: `go/vehicle-gateway/cmd/history-writer/main.go`
 - Create: `go/vehicle-gateway/cmd/stat-writer/main.go`
 - Create: `go/vehicle-gateway/cmd/realtime-api/main.go`
 - Create: `go/vehicle-gateway/internal/envelope/envelope.go`
 - Create: `go/vehicle-gateway/internal/envelope/envelope_test.go`
 - Create: `go/vehicle-gateway/internal/protocol/jt808/*`
 - Create: `go/vehicle-gateway/internal/protocol/gb32960/*`
 - Create: `go/vehicle-gateway/internal/protocol/yutongmqtt/*`
 - Create: `go/vehicle-gateway/internal/gateway/*`
 - Create: `go/vehicle-gateway/internal/identity/*`
 - Create: `go/vehicle-gateway/internal/eventbus/*`
 - Create: `go/vehicle-gateway/internal/history/*`
 - Create: `go/vehicle-gateway/internal/stats/*`
 - Create: `go/vehicle-gateway/internal/realtime/*`
 - Create: `go/vehicle-gateway/internal/observability/*`
 - Modify: `README.md`
 - Modify: `docs/target-architecture.md`
 - Create: `deploy/portainer/docker-compose-go.yml`
 The existing `go/ingest-edge` and `go/vehicle-state` directories are migration sources only. After phase 1 is verified, remove or mark them superseded.
 ---
 ### Task 1: Create Single Go Module
 **Files:**
 - Create: `go/vehicle-gateway/go.mod`
 - Create: `go/vehicle-gateway/internal/observability/logger.go`
 - Create: `go/vehicle-gateway/cmd/gateway/main.go`
 - [ ] **Step 1: Create module manifest**
 Add `go/vehicle-gateway/go.mod`:
 ```go
 module lingniu-vehicle-ingest/go/vehicle-gateway
 go 1.26
 require (
 	github.com/eclipse/paho.mqtt.golang v1.5.1
 	github.com/go-sql-driver/mysql v1.9.3
 	github.com/redis/go-redis/v9 v9.17.2
 	github.com/segmentio/kafka-go v0.4.49
 	github.com/taosdata/driver-go/v3 v3.8.1
 )
 ```
 - [ ] **Step 2: Add logger helper**
 Add `go/vehicle-gateway/internal/observability/logger.go`:
 ```go
 package observability
 import (
 	"log/slog"
 	"os"
 )
 func NewLogger(service string) *slog.Logger {
 	handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{AddSource: true})
 	return slog.New(handler).With("service", service)
 }
 ```
 - [ ] **Step 3: Add temporary gateway entrypoint**
 Add `go/vehicle-gateway/cmd/gateway/main.go`:
 ```go
 package main
 import "lingniu-vehicle-ingest/go/vehicle-gateway/internal/observability"
 func main() {
 	logger := observability.NewLogger("vehicle-gateway")
 	logger.Info("vehicle gateway scaffold started")
 }
 ```
 - [ ] **Step 4: Verify scaffold builds**
 Run:
 ```bash
 cd go/vehicle-gateway
 go mod tidy
 go test ./...
 go build ./cmd/gateway
 ```
 Expected: all commands exit `0`.
 ---
 ### Task 2: Define Unified Envelope
 **Files:**
 - Create: `go/vehicle-gateway/internal/envelope/envelope.go`
 - Create: `go/vehicle-gateway/internal/envelope/envelope_test.go`
 - [ ] **Step 1: Write envelope tests**
 Add `go/vehicle-gateway/internal/envelope/envelope_test.go`:
 ```go
 package envelope
 import "testing"
 func TestFrameEnvelopeVehicleKeyPrefersVIN(t *testing.T) {
 	e := FrameEnvelope{Protocol: ProtocolJT808, VIN: "LNBVIN00000000001", Phone: "013307795425"}
 	if got := e.VehicleKey(); got != "LNBVIN00000000001" {
 		t.Fatalf("VehicleKey() = %q", got)
 	}
 }
 func TestFrameEnvelopeVehicleKeyFallsBackToPhone(t *testing.T) {
 	e := FrameEnvelope{Protocol: ProtocolJT808, Phone: "013307795425"}
 	if got := e.VehicleKey(); got != "JT808:013307795425" {
 		t.Fatalf("VehicleKey() = %q", got)
 	}
 }
 func TestFrameEnvelopeEventIDStable(t *testing.T) {
 	e := FrameEnvelope{
 		Protocol:     ProtocolJT808,
 		MessageID:    "0x0200",
 		Phone:        "013307795425",
 		Sequence:     1,
 		EventTimeMS:  1782745114000,
 		ReceivedAtMS: 1782745114999,
 		RawHex:       "7e02000000ff7e",
 	}
 	a := e.StableEventID()
 	b := e.StableEventID()
 	if a == "" || a != b {
 		t.Fatalf("event id must be non-empty and stable: %q %q", a, b)
 	}
 }
 ```
 - [ ] **Step 2: Run tests and confirm failure**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/envelope
 ```
 Expected: fail because `FrameEnvelope` is not defined.
 - [ ] **Step 3: Implement envelope**
 Add `go/vehicle-gateway/internal/envelope/envelope.go`:
 ```go
 package envelope
 import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"strings"
 )
 type Protocol string
 const (
 	ProtocolGB32960    Protocol = "GB32960"
 	ProtocolJT808      Protocol = "JT808"
 	ProtocolYutongMQTT Protocol = "YUTONG_MQTT"
 )
 type ParseStatus string
 const (
 	ParseOK       ParseStatus = "OK"
 	ParsePartial  ParseStatus = "PARTIAL"
 	ParseBadFrame ParseStatus = "BAD_FRAME"
 )
 type FrameEnvelope struct {
 	EventID        string         `json:"event_id"`
 	TraceID        string         `json:"trace_id"`
 	Protocol       Protocol       `json:"protocol"`
 	MessageID      string         `json:"message_id"`
 	Sequence       uint16         `json:"sequence"`
 	VIN            string         `json:"vin,omitempty"`
 	VehicleKeyHint string         `json:"vehicle_key,omitempty"`
 	Phone          string         `json:"phone,omitempty"`
 	DeviceID       string         `json:"device_id,omitempty"`
 	Plate          string         `json:"plate,omitempty"`
 	SourceEndpoint string         `json:"source_endpoint,omitempty"`
 	EventTimeMS    int64          `json:"event_time_ms"`
 	ReceivedAtMS   int64          `json:"received_at_ms"`
 	RawHex         string         `json:"raw_hex,omitempty"`
 	RawText        string         `json:"raw_text,omitempty"`
 	Parsed         map[string]any `json:"parsed,omitempty"`
 	Fields         map[string]any `json:"fields,omitempty"`
 	ParseStatus    ParseStatus    `json:"parse_status"`
 	ParseError     string         `json:"parse_error,omitempty"`
 }
 func (e FrameEnvelope) VehicleKey() string {
 	if key := strings.TrimSpace(e.VIN); key != "" {
 		return key
 	}
 	if key := strings.TrimSpace(e.VehicleKeyHint); key != "" {
 		return key
 	}
 	if key := strings.TrimSpace(e.Phone); key != "" {
 		return string(e.Protocol) + ":" + key
 	}
 	if key := strings.TrimSpace(e.DeviceID); key != "" {
 		return string(e.Protocol) + ":" + key
 	}
 	return string(e.Protocol) + ":unknown"
 }
 func (e FrameEnvelope) StableEventID() string {
 	if strings.TrimSpace(e.EventID) != "" {
 		return e.EventID
 	}
 	input := fmt.Sprintf("%s|%s|%s|%d|%d|%s",
 		e.Protocol, e.MessageID, e.VehicleKey(), e.Sequence, e.EventTimeMS, e.RawHex)
 	sum := sha256.Sum256([]byte(input))
 	return hex.EncodeToString(sum[:16])
 }
 func (e FrameEnvelope) MarshalJSONBytes() ([]byte, error) {
 	if e.EventID == "" {
 		e.EventID = e.StableEventID()
 	}
 	if e.ParseStatus == "" {
 		e.ParseStatus = ParseOK
 	}
 	return json.Marshal(e)
 }
 ```
 - [ ] **Step 4: Verify tests pass**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/envelope
 ```
 Expected: pass.
 ---
 ### Task 3: Implement JT808 Frame and 0200 Parser
 **Files:**
 - Create: `go/vehicle-gateway/internal/protocol/jt808/parser.go`
 - Create: `go/vehicle-gateway/internal/protocol/jt808/parser_test.go`
 - [ ] **Step 1: Add sample frame tests**
 Use the production sample provided in the thread:
 ```text
 7E020000320133077954250001000000000048000301D2C4C707376139000A00E6004F26063016235701040001900C2504000000000202000030011F31010F867E
 ```
 Expected assertions:
 - message id is `0x0200`
 - phone keeps normalized BCD string `013307795425`
 - sequence is `1`
 - `fields.total_mileage_km` is parsed from additional item `0x01`
 - latitude, longitude, speed, direction, alarm, status, and device time are present
 - [ ] **Step 2: Implement parser**
 Implementation rules:
 - strip `0x7e` start/end delimiters
 - unescape `0x7d 0x02 -> 0x7e`
 - unescape `0x7d 0x01 -> 0x7d`
 - verify XOR checksum
 - parse 2011/2013 common header
 - parse BCD phone from 6 bytes and keep both raw and normalized values in `parsed.header`
 - parse 0200 fixed body
 - parse additional item list as `id,length,value_hex`
 - parse additional `0x01` as `total_mileage_km = uint32 / 10`
 - [ ] **Step 3: Verify**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/protocol/jt808
 ```
 Expected: pass.
 ---
 ### Task 4: Implement GB32960 Frame and Data Unit Parser
 **Files:**
 - Create: `go/vehicle-gateway/internal/protocol/gb32960/parser.go`
 - Create: `go/vehicle-gateway/internal/protocol/gb32960/parser_test.go`
 - [ ] **Step 1: Add parser tests**
 Tests must cover:
 - `##` frame boundary
 - command id
 - response flag
 - 17-byte VIN
 - encryption flag
 - payload length
 - BCC verification
 - realtime data command `0x02`
 - reissue data command `0x03`
 - data unit `0x01` vehicle status fields
 - data unit `0x05` position fields
 - [ ] **Step 2: Implement parser**
 Implementation rules:
 - parse header without allocating large temporary buffers
 - keep RAW as hex in envelope
 - write all recognized data units to `Parsed`
 - write core fields to `Fields`
 - unsupported data unit stays in `Parsed["unknown_units"]`
 - [ ] **Step 3: Verify**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/protocol/gb32960
 ```
 Expected: pass.
 ---
 ### Task 5: Implement Kafka Sink
 **Files:**
 - Create: `go/vehicle-gateway/internal/eventbus/kafka_sink.go`
 - Create: `go/vehicle-gateway/internal/eventbus/kafka_sink_test.go`
 - [ ] **Step 1: Add sink interface**
 Create a sink interface:
 ```go
 package eventbus
 import (
 	"context"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Sink interface {
 	PublishRaw(context.Context, envelope.FrameEnvelope) error
 	PublishUnified(context.Context, envelope.FrameEnvelope) error
 	Close() error
 }
 ```
 - [ ] **Step 2: Implement Kafka topic routing**
 Rules:
 - `GB32960 -> vehicle.raw.gb32960.v1`
 - `JT808 -> vehicle.raw.jt808.v1`
 - `YUTONG_MQTT -> vehicle.raw.yutong-mqtt.v1`
 - unified topic is `vehicle.event.unified.v1`
 - message key is `env.VehicleKey()`
 - [ ] **Step 3: Verify routing with unit tests**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/eventbus
 ```
 Expected: pass.
 ---
 ### Task 6: Implement TDengine History Writer
 **Files:**
 - Create: `go/vehicle-gateway/internal/history/schema.go`
 - Create: `go/vehicle-gateway/internal/history/writer.go`
 - Create: `go/vehicle-gateway/internal/history/writer_test.go`
 - Create: `go/vehicle-gateway/cmd/history-writer/main.go`
 - [ ] **Step 1: Add schema bootstrap SQL**
 Implement schema strings for:
 - database `lingniu_vehicle_ts`
 - stable `raw_frames`
 - stable `vehicle_locations`
 - stable `vehicle_mileage_points`
 - [ ] **Step 2: Implement writer**
 Rules:
 - `AppendRawFrame` always writes one raw row.
 - `AppendLocation` writes only when longitude and latitude exist.
 - `AppendMileagePoint` writes only when `total_mileage_km` exists.
 - child table name is deterministic hash of `protocol + vehicle_key`.
 - escape tag values.
 - [ ] **Step 3: Use TDengine official driver**
 Import WebSocket driver in command:
 ```go
 import _ "github.com/taosdata/driver-go/v3/taosWS"
 ```
 Default driver name:
 ```text
 TDENGINE_DRIVER=taosWS
 ```
 Short-term compatibility:
 ```text
 TDENGINE_DRIVER=taosSql
 ```
 Only use `taosSql` when ECS TDengine WebSocket is not available.
 - [ ] **Step 4: Verify**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/history
 go build ./cmd/history-writer
 ```
 Expected: pass.
 ---
 ### Task 7: Implement MySQL Daily Metric Writer
 **Files:**
 - Create: `go/vehicle-gateway/internal/stats/schema.go`
 - Create: `go/vehicle-gateway/internal/stats/daily_metric.go`
 - Create: `go/vehicle-gateway/internal/stats/daily_metric_test.go`
 - Create: `go/vehicle-gateway/cmd/stat-writer/main.go`
 - [ ] **Step 1: Add schema bootstrap**
 Implement `vehicle_daily_metric` schema from the design spec.
 - [ ] **Step 2: Add metric derivation tests**
 Test cases:
 - no `total_mileage_km` produces no metric
 - one sample produces:
  - `daily_mileage_km = 0`
  - `daily_total_mileage_km = sample`
 - later larger sample updates:
  - `latest_total_mileage_km`
  - `daily_mileage_km`
  - `daily_total_mileage_km`
 - out-of-order smaller sample updates:
  - `first_total_mileage_km`
  - `daily_mileage_km`
 - [ ] **Step 3: Implement MySQL upsert**
 Use one table and one idempotent upsert:
 ```sql
 INSERT INTO vehicle_daily_metric
  (vin, stat_date, protocol, metric_key, metric_value, metric_unit,
   first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method)
 VALUES (?, ?, ?, ?, ?, 'km', ?, ?, 1, 'TOTAL_MILEAGE_DIFF')
 ON DUPLICATE KEY UPDATE
  first_total_mileage_km = LEAST(first_total_mileage_km, VALUES(first_total_mileage_km)),
  latest_total_mileage_km = GREATEST(latest_total_mileage_km, VALUES(latest_total_mileage_km)),
  metric_value = CASE
    WHEN metric_key = 'daily_mileage_km'
      THEN GREATEST(latest_total_mileage_km, VALUES(latest_total_mileage_km))
           - LEAST(first_total_mileage_km, VALUES(first_total_mileage_km))
    WHEN metric_key = 'daily_total_mileage_km'
      THEN GREATEST(latest_total_mileage_km, VALUES(latest_total_mileage_km))
    ELSE VALUES(metric_value)
  END,
  sample_count = sample_count + 1,
  updated_at = CURRENT_TIMESTAMP
 ```
 - [ ] **Step 4: Verify**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/stats
 go build ./cmd/stat-writer
 ```
 Expected: pass.
 ---
 ### Task 8: Implement Redis Realtime API
 **Files:**
 - Create: `go/vehicle-gateway/internal/realtime/repository.go`
 - Create: `go/vehicle-gateway/internal/realtime/repository_test.go`
 - Create: `go/vehicle-gateway/internal/realtime/http.go`
 - Create: `go/vehicle-gateway/cmd/realtime-api/main.go`
 - [ ] **Step 1: Add repository contract**
 Methods:
 - `Update(ctx, envelope.FrameEnvelope) error`
 - `GetMerged(ctx, vin string) (Snapshot, error)`
 - `GetProtocol(ctx, vin string, protocol envelope.Protocol) (Snapshot, error)`
 - `IsOnline(ctx, vin string) (OnlineStatus, error)`
 - [ ] **Step 2: Implement merge logic**
 Rules:
 - update `vehicle:latest:{vin}:{protocol}`
 - update `vehicle:latest:{vin}` with newest fields
 - update `vehicle:online:{vin}`
 - update sorted set `vehicle:last_seen`
 - [ ] **Step 3: Implement HTTP API**
 Routes:
 - `GET /api/realtime/vehicles/{vin}`
 - `GET /api/realtime/vehicles/{vin}/online`
 - `GET /api/realtime/vehicles/{vin}/protocols/{protocol}`
 - [ ] **Step 4: Verify**
 Run:
 ```bash
 cd go/vehicle-gateway
 go test ./internal/realtime
 go build ./cmd/realtime-api
 ```
 Expected: pass.
 ---
 ### Task 9: Wire Gateway Runtime
 **Files:**
 - Create: `go/vehicle-gateway/internal/gateway/tcp_server.go`
 - Create: `go/vehicle-gateway/internal/gateway/mqtt_client.go`
 - Modify: `go/vehicle-gateway/cmd/gateway/main.go`
 - [ ] **Step 1: Implement TCP server**
 Rules:
 - one goroutine per accepted connection
 - bounded max connections
 - read timeout and idle timeout
 - protocol-specific frame extractor
 - structured peer endpoint
 - graceful shutdown on SIGTERM
 - [ ] **Step 2: Implement MQTT client**
 Rules:
 - connect with official production config from environment
 - subscribe configured topic list
 - convert each message into envelope
 - publish raw and unified events
 - reconnect with backoff
 - [ ] **Step 3: Verify local JSON mode**
 Run without Kafka:
 ```bash
 cd go/vehicle-gateway
 GB32960_TCP_ADDR=:132960 JT808_TCP_ADDR=:18080 go run ./cmd/gateway
 ```
 Expected: service starts and logs configured listeners.
 ---
 ### Task 10: Docker and ECS Deployment
 **Files:**
 - Create: `go/vehicle-gateway/Dockerfile`
 - Create: `deploy/portainer/docker-compose-go.yml`
 - Modify: `docs/operations/current-ecs-deployment.md`
 - [ ] **Step 1: Add multi-stage Dockerfile**
 Build all commands:
 - `gateway`
 - `history-writer`
 - `stat-writer`
 - `realtime-api`
 - [ ] **Step 2: Add Portainer compose**
 Services:
 - `go-vehicle-gateway`
 - `go-history-writer`
 - `go-stat-writer`
 - `go-realtime-api`
 Each service must include:
 - restart policy
 - memory limit
 - Kafka env
 - MySQL/TDengine/Redis env as needed
 - logging options
 - [ ] **Step 3: Verify Linux build**
 Run:
 ```bash
 cd go/vehicle-gateway
 GOOS=linux GOARCH=amd64 go build ./cmd/gateway
 GOOS=linux GOARCH=amd64 go build ./cmd/history-writer
 GOOS=linux GOARCH=amd64 go build ./cmd/stat-writer
 GOOS=linux GOARCH=amd64 go build ./cmd/realtime-api
 ```
 Expected: all commands exit `0`.
 ---
 ### Task 11: Production Verification
 **Files:**
 - Create: `docs/operations/go-vehicle-gateway-verification.md`
 - [ ] **Step 1: Record test commands**
 Document commands to verify:
 - gateway process health
 - Kafka topic consumption
 - TDengine row counts
 - MySQL daily metric rows
 - Redis realtime lookup
 - [ ] **Step 2: Validate real traffic**
 Evidence required:
 - one real 32960 VIN with RAW, location, mileage point, daily metric, Redis snapshot
 - one real JT808 phone/VIN with RAW, location, mileage point, daily metric, Redis snapshot
 - one real Yutong MQTT VIN with RAW and Redis snapshot
 - [ ] **Step 3: Keep old Java services until evidence is captured**
 Only disable Java equivalents after the evidence file contains successful command outputs and timestamps.
 ---
 ## Self-Review Checklist
 - The plan creates one new Go module instead of extending scattered prototypes.
 - The plan covers GB32960, JT808, and Yutong MQTT ingress.
 - The plan covers Kafka, TDengine, MySQL, and Redis.
 - The plan includes 32960 and 808 daily mileage and daily total mileage.
 - The plan includes local and ECS verification.
 - The plan does not restore Xinda Push.
 - The plan keeps Java services untouched until Go evidence exists.
--- a/docs/superpowers/specs/2026-07-01-go-ingest-redesign-design.md
+++ b/docs/superpowers/specs/2026-07-01-go-ingest-redesign-design.md
@@ -0,0 +1,498 @@
 # Go 车辆接入重构设计规格
 ## 目标
 使用 Go 重新设计车辆数据接入运行面，让系统回到第一性原则：
 - 接入层只负责可靠收包、协议解析、应答、身份解析和投递。
 - Kafka 是唯一在线消息通道。
 - TDengine 保存高吞吐时序明细和完整 RAW 解析 JSON。
 - MySQL 保存低频配置、身份映射和每日统计窄表。
 - Redis 保存可重建的准实时状态。
 - 32960、JT808、宇通 MQTT 使用同一套数据层接口，避免每个协议各自落库。
 第一阶段只做生产链路的骨架和核心数据闭环：接收、解析、Kafka、TDengine、MySQL 统计、Redis 实时查询、ECS 验证。历史查询 API 和业务侧复杂分析放在后续阶段。
 ## 参考原则
 本设计只吸收开源项目的边界思想，不复制外部实现代码。
 - GB32960 参考 `DarkInno/gb32960-go-sdk`：连接管理、Handler、Forwarder、鉴权接口分离。
 - JT808 参考 `cuteLittleDevil/go-jt808`：高并发 Go 原生 TCP、协议核心小而可扩展、事件/适配器机制。
 - JT808 参考 `fakeyanss/jt808-server-go`：`FramePayload -> PacketData -> JT808Msg -> Reply` 的分层处理、Gateway 模式、保活和版本兼容。
 - TDengine 参考官方数据模型：按数据采集点建立 supertable，静态维度做 tags，明细数据按子表写入；Go 连接优先使用 WebSocket 驱动。
 ## 非目标
 - 第一阶段不继续扩展 Java 服务。
 - 第一阶段不做统一大查询 API。
 - 第一阶段不恢复信达 Push。
 - 第一阶段不把所有协议字段展开成一张超宽 TDengine 表。
 - Redis 不作为历史事实源。
 - MySQL 不保存高频原始明细。
 ## 目标目录
 新的 Go 运行面放在 `go/vehicle-gateway`，不继续沿用实验性的多 module 分散结构。现有 `go/ingest-edge` 和 `go/vehicle-state` 可以作为迁移素材，最终归并或删除。
 ```text
 go/vehicle-gateway/
  cmd/
    gateway/          # 协议接入进程：32960 TCP、JT808 TCP、宇通 MQTT
    history-writer/   # Kafka -> TDengine RAW/location/mileage points
    stat-writer/      # Kafka -> MySQL 每日统计窄表
    realtime-api/     # Redis 准实时查询 API
  internal/
    config/           # 环境变量、配置文件、校验
    gateway/          # TCP/MQTT 生命周期、连接限制、优雅停机
    protocol/
      gb32960/        # 32960 编解码
      jt808/          # 808 编解码
      yutongmqtt/     # 宇通 MQTT payload 解析
    identity/         # VIN、phone、device_id、plate 绑定
    envelope/         # 统一事件模型
    eventbus/         # Kafka producer/consumer
    history/          # TDengine adapter
    stats/            # 每日里程聚合
    realtime/         # Redis adapter 与快照合并
    observability/    # 日志、metrics、健康检查
 ```
 ## 协议接入设计
 ### GB32960
 职责：
 - 监听 TCP `32960`。
 - 支持车辆登入、实时信息上报、补发信息上报、车辆登出、平台登入/登出、心跳、校时。
 - 正确返回协议应答。
 - 完整解析 2016 数据单元：
  - 整车数据
  - 驱动电机数据
  - 燃料电池数据
  - 发动机数据
  - 车辆位置数据
  - 极值数据
  - 报警数据
  - 可充电储能装置电压数据
  - 可充电储能装置温度数据
 - RAW 中保存完整 parsed JSON。
 - 关键字段标准化为统一 field：
  - `speed_kmh`
  - `total_mileage_km`
  - `soc_percent`
  - `longitude`
  - `latitude`
  - `vehicle_status`
  - `charge_status`
 ### JT808
 职责：
 - 监听 TCP `808`。
 - 支持 2011/2013 基础兼容，预留 2019 版本标记。
 - 分层处理：
  - Frame：`0x7e` 包边界、转义、校验。
  - Packet：消息头、手机号 BCD、流水号、分包。
  - Message：注册、鉴权、心跳、注销、位置、批量位置、未知上行。
  - Reply：注册应答、平台通用应答。
 - 终端手机号按协议头 BCD 解析，内部同时保留原始 BCD、规范化 phone、去前导零 phone。
 - 注册帧和鉴权帧写入 808 registration 表。
 - 如果设备直接上报位置帧，也要走 identity 解析，尝试用 phone、device_id、plate 找到 VIN。
 - 0200 附加信息必须解析表 27：
  - `0x01` GPS 总里程，DWORD，单位 0.1 km。
  - 其他已知附加项结构化放入 `parsed_json.additional`。
 - 标准化字段：
  - `speed_kmh`
  - `total_mileage_km`
  - `longitude`
  - `latitude`
  - `altitude_m`
  - `direction_deg`
  - `alarm_flag`
  - `status_flag`
 ### 宇通 MQTT
 职责：
 - 使用正式 MQTT 配置订阅生产 topic。
 - 接收 payload 后解析为统一 envelope。
 - 按 payload 中的车辆标识解析 VIN、车牌、设备号。
 - 保存完整 payload 和 parsed JSON。
 - 标准化字段向 32960/808 对齐：
  - `speed_kmh`
  - `total_mileage_km`
  - `longitude`
  - `latitude`
  - `soc_percent`
  - `vehicle_status`
 ## 统一 Envelope
 所有协议接入后输出同一结构。
 ```json
 {
  "event_id": "string",
  "trace_id": "string",
  "protocol": "GB32960|JT808|YUTONG_MQTT",
  "message_id": "string",
  "vin": "string",
  "vehicle_key": "string",
  "phone": "string",
  "device_id": "string",
  "plate": "string",
  "source_endpoint": "ip:port or mqtt://broker/topic",
  "event_time_ms": 0,
  "received_at_ms": 0,
  "raw_hex": "string",
  "raw_text": "string",
  "parsed": {},
  "fields": {
    "speed_kmh": 0,
    "total_mileage_km": 0,
    "longitude": 0,
    "latitude": 0
  },
  "parse_status": "OK|PARTIAL|BAD_FRAME",
  "parse_error": ""
 }
 ```
 规则：
 - `event_id` 使用协议、设备标识、消息流水、事件时间、RAW hash 生成，保证幂等。
 - Kafka partition key 优先使用 VIN；没有 VIN 时使用 `protocol:phone/device_id`。
 - `parsed` 保存协议完整结构化字段。
 - `fields` 只保存跨协议核心字段，用于统计、位置和实时快照。
 ## Kafka Topic
 生产只支持 Kafka。
 | Topic | 内容 | Key |
 |---|---|---|
 | `vehicle.raw.gb32960.v1` | 32960 完整 RAW envelope | VIN 或 vehicle_key |
 | `vehicle.raw.jt808.v1` | 808 完整 RAW envelope | VIN 或 phone |
 | `vehicle.raw.yutong-mqtt.v1` | 宇通 MQTT 完整 RAW envelope | VIN 或 vehicle_key |
 | `vehicle.event.unified.v1` | 统一轻量事件，用于业务消费 | VIN 或 vehicle_key |
 接入层必须先写 RAW topic，再写 unified event。后续消费者只依赖 Kafka，不直接依赖接入进程内存。
 发布可靠性：
 - Kafka 生产端必须开启同步写入，RAW 写成功后才允许写 unified event。
 - Kafka 写入必须支持可配置重试、单次写超时和短退避，默认值为 `KAFKA_PUBLISH_ATTEMPTS=3`、`KAFKA_PUBLISH_TIMEOUT_MS=3000`、`KAFKA_PUBLISH_BACKOFF_MS=100`。
 - gateway 支持本地磁盘 spool/WAL，配置 `KAFKA_SPOOL_DIR` 后启用；Kafka 长时间不可用时，发布失败的 envelope 先原子写入本地 JSON 文件。
 - spool 补发按文件名顺序执行，补发成功后删除文件；默认补发间隔由 `KAFKA_SPOOL_REPLAY_INTERVAL_MS=1000` 控制。
 - 如果 RAW 写 Kafka 失败并已落盘，同一个 event 的 unified event 不允许抢先写 Kafka，也必须进入 spool，确保恢复后按 RAW -> unified 顺序补发。
 - Kafka topic 不允许自动创建，topic 和分区数由部署脚本或运维初始化，避免生产拼写错误造成隐性分流。
 ## TDengine 数据库设计
 如果现有 TDengine 库不符合目标，可以新建库并迁移。建议库名：
 ```sql
 CREATE DATABASE IF NOT EXISTS lingniu_vehicle_ts KEEP 7300 DURATION 10 BUFFER 256;
 ```
 ### raw_frames
 保存完整 RAW 和完整 parsed JSON。
 ```sql
 CREATE STABLE IF NOT EXISTS raw_frames (
  ts TIMESTAMP,
  frame_id NCHAR(64),
  event_id NCHAR(64),
  message_id INT,
  event_time TIMESTAMP,
  received_at TIMESTAMP,
  raw_size_bytes INT,
  raw_hex BINARY(16374),
  raw_text BINARY(16374),
  parsed_json BINARY(16374),
  fields_json BINARY(4096),
  parse_status NCHAR(16),
  parse_error BINARY(1024),
  source_endpoint NCHAR(128)
 ) TAGS (
  protocol NCHAR(32),
  vehicle_key NCHAR(64),
  vin NCHAR(32),
  phone NCHAR(32),
  device_id NCHAR(64)
 );
 ```
 说明：
 - 子表按 `protocol + vehicle_key hash` 创建。
 - RAW 查询优先按 tags 和时间范围过滤。
 - `parsed_json` 是完整协议字段；查询 API 可选择是否返回，避免默认大字段拖慢。
 ### vehicle_locations
 只保存位置查询核心字段。
 ```sql
 CREATE STABLE IF NOT EXISTS vehicle_locations (
  ts TIMESTAMP,
  event_id NCHAR(64),
  frame_id NCHAR(64),
  received_at TIMESTAMP,
  longitude DOUBLE,
  latitude DOUBLE,
  altitude_m DOUBLE,
  speed_kmh DOUBLE,
  direction_deg INT,
  alarm_flag BIGINT,
  status_flag BIGINT,
  total_mileage_km DOUBLE
 ) TAGS (
  protocol NCHAR(32),
  vehicle_key NCHAR(64),
  vin NCHAR(32),
  phone NCHAR(32),
  device_id NCHAR(64)
 );
 ```
 ### vehicle_mileage_points
 保存总里程采样点，用于回放重算和查询。
 ```sql
 CREATE STABLE IF NOT EXISTS vehicle_mileage_points (
  ts TIMESTAMP,
  event_id NCHAR(64),
  frame_id NCHAR(64),
  received_at TIMESTAMP,
  total_mileage_km DOUBLE,
  speed_kmh DOUBLE,
  longitude DOUBLE,
  latitude DOUBLE
 ) TAGS (
  protocol NCHAR(32),
  vehicle_key NCHAR(64),
  vin NCHAR(32),
  phone NCHAR(32),
  device_id NCHAR(64)
 );
 ```
 ## MySQL 数据库设计
 MySQL 只保存配置、身份映射、808 注册鉴权和每日统计窄表。
 ### vehicle_identity_binding
 用于把外部标识定位到 VIN。
 ```sql
 CREATE TABLE vehicle_identity_binding (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  vin VARCHAR(32) NOT NULL,
  plate VARCHAR(32) NULL,
  phone VARCHAR(32) NULL,
  device_id VARCHAR(64) NULL,
  remark VARCHAR(255) NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_vin (vin),
  KEY idx_plate (plate),
  KEY idx_phone (phone),
  KEY idx_device_id (device_id)
 );
 ```
 ### jt808_registration
 只记录 808 独有的注册、鉴权和在线身份信息。
 ```sql
 CREATE TABLE jt808_registration (
  phone VARCHAR(32) PRIMARY KEY,
  vin VARCHAR(32) NULL,
  plate VARCHAR(32) NULL,
  device_id VARCHAR(64) NULL,
  manufacturer_id VARCHAR(32) NULL,
  terminal_model VARCHAR(64) NULL,
  terminal_id VARCHAR(64) NULL,
  auth_code VARCHAR(128) NULL,
  source_endpoint VARCHAR(128) NULL,
  first_registered_at DATETIME NULL,
  latest_registered_at DATETIME NULL,
  latest_authed_at DATETIME NULL,
  latest_seen_at DATETIME NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  KEY idx_vin (vin),
  KEY idx_plate (plate),
  KEY idx_device_id (device_id)
 );
 ```
 ### vehicle_daily_metric
 32960 和 808 的每日里程、每日总里程都进入同一张窄表。
 ```sql
 CREATE TABLE vehicle_daily_metric (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  vin VARCHAR(32) NOT NULL,
  stat_date DATE NOT NULL,
  protocol VARCHAR(32) NOT NULL,
  metric_key VARCHAR(64) NOT NULL,
  metric_value DECIMAL(18,3) NOT NULL,
  metric_unit VARCHAR(16) NOT NULL,
  first_total_mileage_km DECIMAL(18,3) NULL,
  latest_total_mileage_km DECIMAL(18,3) NULL,
  sample_count BIGINT NOT NULL DEFAULT 0,
  calculation_method VARCHAR(64) NOT NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_daily_metric (vin, stat_date, protocol, metric_key),
  KEY idx_stat_date (stat_date),
  KEY idx_protocol_metric (protocol, metric_key)
 );
 ```
 指标：
 - `daily_mileage_km = max(total_mileage_km) - min(total_mileage_km)`
 - `daily_total_mileage_km = max(total_mileage_km)`
 统计消费者可幂等重放。每个样本 upsert 时只维护当天 `min/max total_mileage_km`，不依赖进程内状态。
 ## Redis 实时数据设计
 Redis 保存可从 Kafka 重建的数据。
 | Key | 内容 |
 |---|---|
 | `vehicle:online:{vin}` | 在线状态、最后活跃时间、协议列表 |
 | `vehicle:latest:{vin}` | 合并后的 VIN 最新快照 |
 | `vehicle:latest:{vin}:{protocol}` | 单协议最新快照 |
 | `vehicle:last_seen` | VIN 到最后接收时间的 sorted set |
 合并规则：
 - 位置以最新 event_time 为准。
 - 总里程取最新上报值，不做递增假设。
 - 32960 多帧字段按 field timestamp 合并。
 - 808 和 MQTT 不覆盖其他协议独有字段。
 - Redis TTL 用于在线判断，不作为数据删除依据。
 ## 数据流
 ```mermaid
 flowchart LR
  source["车辆 / 平台"] --> gateway["Go gateway"]
  gateway --> parser["protocol parser"]
  parser --> identity["identity resolver"]
  identity --> kafkaRaw["Kafka RAW topics"]
  identity --> kafkaEvent["Kafka unified event"]
  kafkaRaw --> history["history-writer"]
  kafkaRaw --> stats["stat-writer"]
  kafkaEvent --> realtime["realtime consumer"]
  history --> td["TDengine raw_frames / locations / mileage_points"]
  stats --> mysql["MySQL vehicle_daily_metric"]
  realtime --> redis["Redis latest state"]
 ```
 ## 错误处理
 - 协议坏帧仍写 RAW topic，`parse_status=BAD_FRAME`。
 - 可部分解析的帧写 `parse_status=PARTIAL`，保留 parse error。
 - Kafka 写失败时接入层先按配置重试；重试耗尽后不写 unified event，必须打错误日志和 metrics。
 - 启用 `KAFKA_SPOOL_DIR` 后，Kafka 重试耗尽会落本地 spool；如果 spool 写失败，才视为接入层最终失败。
 - TDengine 写失败不提交 Kafka offset。
 - MySQL 统计写失败不提交 Kafka offset。
 - Redis 写失败不影响历史和统计，但要通过 metrics 暴露。
 - 808 相同 phone 新连接时，旧连接应被替换并记录 latest_seen。
 ## 部署设计
 生产 ECS 运行 Go 二进制或容器：
 - `vehicle-gateway`
 - `vehicle-history-writer`
 - `vehicle-stat-writer`
 - `vehicle-realtime-api`
 配置来源：
 - 环境变量优先。
 - Nacos 可作为后续配置中心，但 Go 第一阶段必须能只靠环境变量启动，便于 Portainer 部署和故障恢复。
 TDengine 连接：
 - 优先 WebSocket `taosWS`。
 - 若当前 ECS 只开放原生端口，可短期兼容 `taosSql`，但代码配置必须显式标记为兼容模式。
 ## 验证计划
 ### 本地验证
 - 用样例 808 报文验证：
  - phone BCD 解析。
  - 0200 经纬度、速度、方向、时间。
  - 表 27 `0x01` GPS 总里程。
 - 用真实 32960 报文验证：
  - 登录应答正确。
  - 实时帧和补发帧都能写 RAW。
  - 位置和总里程字段进入统一 fields。
 - 用宇通 MQTT payload 验证：
  - payload 完整保存。
  - 核心字段归一化。
 - 不连 Kafka 时可输出 JSON log。
 - 连接 Kafka 时 RAW topic 可消费到 envelope。
 ### ECS 验证
 - 部署前先旁路接收或短窗口切流。
 - 验证端口：
  - `32960`
  - `808`
  - MQTT 订阅连接。
 - 验证 Kafka topic 有持续写入。
 - 验证 TDengine：
  - `raw_frames` 有三种协议数据。
  - `vehicle_locations` 能按 VIN、协议、时间分页查询。
  - `vehicle_mileage_points` 有 32960 和 808 总里程采样。
 - 验证 MySQL：
  - `vehicle_daily_metric` 有 32960 和 808 的 `daily_mileage_km`、`daily_total_mileage_km`。
 - 验证 Redis：
  - 查询 VIN 在线。
  - 查询 VIN 合并实时快照。
  - 查询 VIN 分协议实时快照。
 ## 验收标准
 - Go gateway 能在 ECS 上接收真实 32960、808、宇通 MQTT 数据。
 - 三种协议 RAW 都进入 Kafka。
 - Kafka 短暂写失败时，gateway 按配置重试；单元测试覆盖首次失败后成功和重试耗尽返回错误。
 - Kafka 长时间不可用时，gateway 可把 RAW/unified 写入本地 spool；单元测试覆盖 RAW 已落盘时 unified 也落盘、恢复后按顺序补发并删除文件。
 - 三种协议 RAW 和 parsed JSON 都进入 TDengine。
 - 32960 和 808 的位置进入 `vehicle_locations`。
 - 32960 和 808 的总里程采样进入 `vehicle_mileage_points`。
 - 32960 和 808 的每日里程、每日总里程进入 MySQL 窄表。
 - Redis 可以查询 VIN 在线和实时数据。
 - 任一消费者宕机后可通过 Kafka offset 继续恢复。
 - 查询和统计验证使用 ECS 上的真实数据完成。
 ## 实施顺序
 1. 创建 `go/vehicle-gateway` 单 module，迁移现有 Go 原型中可用的解析、Kafka、TDengine、MySQL、Redis 代码。
 2. 先写协议解析单元测试，覆盖 808 样例报文和 32960 核心字段。
 3. 完成统一 envelope 和 Kafka sink。
 4. 完成 TDengine schema bootstrap 与 history writer。
 5. 完成 MySQL schema bootstrap 与 stat writer。
 6. 完成 Redis realtime writer/API。
 7. 本地启动 gateway，用 ECS 转发流量验证。
 8. 构建 Linux 镜像，部署 ECS。
 9. 按验收标准逐项验证并记录证据。
--- a/go/vehicle-gateway/Dockerfile
+++ b/go/vehicle-gateway/Dockerfile
@@ -0,0 +1,29 @@
 FROM golang:1.26-bookworm AS build
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/gateway ./cmd/gateway \
    && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/history-writer ./cmd/history-writer \
    && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/stat-writer ./cmd/stat-writer \
    && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/realtime-api ./cmd/realtime-api
 FROM debian:bookworm-slim
 RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates tzdata \
    && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY --from=build /out/gateway /app/gateway
 COPY --from=build /out/history-writer /app/history-writer
 COPY --from=build /out/stat-writer /app/stat-writer
 COPY --from=build /out/realtime-api /app/realtime-api
 ENV TZ=Asia/Shanghai
 EXPOSE 808 32960 20210
 CMD ["/app/gateway"]
--- a/go/vehicle-gateway/cmd/gateway/main.go
+++ b/go/vehicle-gateway/cmd/gateway/main.go
@@ -0,0 +1,223 @@
 package main
 import (
 	"context"
 	"database/sql"
 	"log/slog"
 	"os"
 	"os/signal"
 	"strings"
 	"sync"
 	"syscall"
 	"time"
 	_ "github.com/go-sql-driver/mysql"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/eventbus"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/gateway"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/identity"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/observability"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/gb32960"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/jt808"
 )
 func main() {
 	logger := observability.NewLogger("vehicle-gateway")
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	sink, err := buildSink(ctx, logger)
 	if err != nil {
 		logger.Error("build sink failed", "error", err)
 		os.Exit(1)
 	}
 	defer sink.Close()
 	resolver, closeResolver, err := buildIdentityResolver(ctx, logger)
 	if err != nil {
 		logger.Error("build identity resolver failed", "error", err)
 		os.Exit(1)
 	}
 	defer closeResolver()
 	protocols := []gateway.TCPProtocol{
 		{
 			Protocol: envelope.ProtocolGB32960,
 			Addr:     env("GB32960_TCP_ADDR", ":32960"),
 			Extract:  gb32960.ExtractFrames,
 			Parse:    gb32960.ParseFrame,
 			Respond:  gb32960.AutoResponse,
 		},
 		{
 			Protocol: envelope.ProtocolJT808,
 			Addr:     env("JT808_TCP_ADDR", ":808"),
 			Extract:  jt808.ExtractFrames,
 			Parse:    jt808.ParseFrame,
 			Respond:  jt808.NewAutoResponder(env("JT808_REGISTER_AUTH_CODE", "g7gps")).Respond,
 		},
 	}
 	var wg sync.WaitGroup
 	errs := make(chan error, len(protocols))
 	for _, protocol := range protocols {
 		server, err := gateway.NewTCPServer(gateway.TCPServerConfig{
 			Protocol:       protocol,
 			Sink:           sink,
 			Resolver:       resolver,
 			Logger:         logger,
 			ReadBufferSize: envInt("TCP_READ_BUFFER_BYTES", 64*1024),
 			IdleTimeout:    time.Duration(envInt("TCP_IDLE_TIMEOUT_SECONDS", 180)) * time.Second,
 			MaxConnections: envInt("TCP_MAX_CONNECTIONS", 20_000),
 		})
 		if err != nil {
 			logger.Error("build tcp server failed", "protocol", protocol.Protocol, "error", err)
 			os.Exit(1)
 		}
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
 			if err := server.ListenAndServe(ctx); err != nil {
 				errs <- err
 			}
 		}()
 	}
 	if envBool("YUTONG_MQTT_ENABLED", false) {
 		client, err := gateway.NewMQTTClient(gateway.MQTTClientConfig{
 			EndpointName:            env("YUTONG_MQTT_ENDPOINT", env("YUTONG_MQTT_ENDPOINT_NAME", "yutong")),
 			Broker:                  env("YUTONG_MQTT_URI", ""),
 			ClientID:                env("YUTONG_MQTT_CLIENT_ID", "lingniu-go-yutong-mqtt"),
 			Username:                env("YUTONG_MQTT_USERNAME", ""),
 			Password:                env("YUTONG_MQTT_PASSWORD", ""),
 			Topics:                  splitCSV(env("YUTONG_MQTT_TOPICS", env("YUTONG_MQTT_TOPIC", "/ytforward/shln/+"))),
 			QoS:                     byte(envInt("YUTONG_MQTT_QOS", 2)),
 			CleanSession:            envBool("YUTONG_MQTT_CLEAN_SESSION", false),
 			KeepAlive:               time.Duration(envInt("YUTONG_MQTT_KEEP_ALIVE_SECONDS", 20)) * time.Second,
 			ConnectTimeout:          time.Duration(envInt("YUTONG_MQTT_CONNECTION_TIMEOUT_SECONDS", 10)) * time.Second,
 			TLSCACertPath:           env("YUTONG_MQTT_TLS_CA_PEM", ""),
 			TLSClientCertPath:       env("YUTONG_MQTT_TLS_CLIENT_PEM", ""),
 			TLSClientKeyPath:        env("YUTONG_MQTT_TLS_CLIENT_KEY", ""),
 			TLSHostnameVerification: envBool("YUTONG_MQTT_TLS_HOSTNAME_VERIFICATION_ENABLED", true),
 			Sink:                    sink,
 			Resolver:                resolver,
 			Logger:                  logger,
 		})
 		if err != nil {
 			logger.Error("build yutong mqtt client failed", "error", err)
 			os.Exit(1)
 		}
 		if err := client.Start(ctx); err != nil {
 			logger.Error("start yutong mqtt client failed", "error", err)
 			os.Exit(1)
 		}
 		logger.Info("yutong mqtt client started")
 	}
 	logger.Info("vehicle gateway started")
 	select {
 	case <-ctx.Done():
 	case err := <-errs:
 		logger.Error("vehicle gateway listener failed", "error", err)
 		stop()
 	}
 	wg.Wait()
 }
 func buildIdentityResolver(ctx context.Context, logger *slog.Logger) (identity.Resolver, func(), error) {
 	dsn := env("IDENTITY_MYSQL_DSN", strings.TrimSpace(os.Getenv("MYSQL_DSN")))
 	if strings.TrimSpace(dsn) == "" {
 		logger.Warn("identity mysql dsn is empty; using noop identity resolver")
 		return identity.NoopResolver{}, func() {}, nil
 	}
 	db, err := sql.Open("mysql", dsn)
 	if err != nil {
 		return nil, nil, err
 	}
 	if err := db.PingContext(ctx); err != nil {
 		_ = db.Close()
 		return nil, nil, err
 	}
 	table := env("VEHICLE_IDENTITY_TABLE", "vehicle_identity_binding")
 	logger.Info("identity mysql resolver enabled", "table", table)
 	return identity.NewMySQLResolver(db, table), func() { _ = db.Close() }, nil
 }
 func buildSink(ctx context.Context, logger *slog.Logger) (eventbus.Sink, error) {
 	brokers := splitCSV(os.Getenv("KAFKA_BROKERS"))
 	if len(brokers) == 0 {
 		logger.Warn("KAFKA_BROKERS is empty; using log sink")
 		return eventbus.NewLogSink(logger), nil
 	}
 	sink, err := eventbus.NewKafkaSink(eventbus.KafkaConfig{
 		Brokers: brokers,
 		RawTopics: map[envelope.Protocol]string{
 			envelope.ProtocolGB32960:    env("KAFKA_TOPIC_GB32960_RAW", "vehicle.raw.gb32960.v1"),
 			envelope.ProtocolJT808:      env("KAFKA_TOPIC_JT808_RAW", "vehicle.raw.jt808.v1"),
 			envelope.ProtocolYutongMQTT: env("KAFKA_TOPIC_YUTONG_MQTT_RAW", "vehicle.raw.yutong-mqtt.v1"),
 		},
 		UnifiedTopic: env("KAFKA_TOPIC_UNIFIED", "vehicle.event.unified.v1"),
 	})
 	if err != nil {
 		return nil, err
 	}
 	var out eventbus.Sink = eventbus.NewRetryingSink(sink, eventbus.RetryConfig{
 		Attempts:       envInt("KAFKA_PUBLISH_ATTEMPTS", 3),
 		Backoff:        time.Duration(envInt("KAFKA_PUBLISH_BACKOFF_MS", 100)) * time.Millisecond,
 		AttemptTimeout: time.Duration(envInt("KAFKA_PUBLISH_TIMEOUT_MS", 3000)) * time.Millisecond,
 	})
 	spoolDir := strings.TrimSpace(os.Getenv("KAFKA_SPOOL_DIR"))
 	if spoolDir != "" {
 		durable := eventbus.NewDurableSink(out, eventbus.DurableConfig{Directory: spoolDir})
 		interval := time.Duration(envInt("KAFKA_SPOOL_REPLAY_INTERVAL_MS", 1000)) * time.Millisecond
 		go durable.ReplayLoop(ctx, interval, func(err error) {
 			logger.Warn("kafka spool replay failed", "error", err)
 		})
 		logger.Info("kafka durable spool enabled", "dir", spoolDir, "replay_interval_ms", interval.Milliseconds())
 		out = durable
 	}
 	return out, nil
 }
 func env(key string, fallback string) string {
 	value := strings.TrimSpace(os.Getenv(key))
 	if value == "" {
 		return fallback
 	}
 	return value
 }
 func envInt(key string, fallback int) int {
 	value := strings.TrimSpace(os.Getenv(key))
 	if value == "" {
 		return fallback
 	}
 	var out int
 	for _, r := range value {
 		if r < '0' || r > '9' {
 			return fallback
 		}
 		out = out*10 + int(r-'0')
 	}
 	if out <= 0 {
 		return fallback
 	}
 	return out
 }
 func envBool(key string, fallback bool) bool {
 	value := strings.ToLower(strings.TrimSpace(os.Getenv(key)))
 	if value == "" {
 		return fallback
 	}
 	return value == "1" || value == "true" || value == "yes" || value == "on"
 }
 func splitCSV(value string) []string {
 	var out []string
 	for _, item := range strings.Split(value, ",") {
 		item = strings.TrimSpace(item)
 		if item != "" {
 			out = append(out, item)
 		}
 	}
 	return out
 }
--- a/go/vehicle-gateway/cmd/history-writer/main.go
+++ b/go/vehicle-gateway/cmd/history-writer/main.go
@@ -0,0 +1,123 @@
 package main
 import (
 	"context"
 	"database/sql"
 	"encoding/json"
 	"os"
 	"os/signal"
 	"strings"
 	"syscall"
 	"github.com/segmentio/kafka-go"
 	_ "github.com/taosdata/driver-go/v3/taosWS"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/history"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/observability"
 )
 func main() {
 	logger := observability.NewLogger("vehicle-history-writer")
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	cfg := loadConfig()
 	db, err := sql.Open(cfg.TDengineDriver, cfg.TDengineDSN)
 	if err != nil {
 		logger.Error("tdengine open failed", "error", err)
 		os.Exit(1)
 	}
 	defer db.Close()
 	if err := db.PingContext(ctx); err != nil {
 		logger.Error("tdengine ping failed", "error", err)
 		os.Exit(1)
 	}
 	writer := history.NewWriter(db)
 	if cfg.EnsureSchema {
 		if err := writer.EnsureSchema(ctx, cfg.TDengineDatabase); err != nil {
 			logger.Error("tdengine schema bootstrap failed", "error", err)
 			os.Exit(1)
 		}
 	}
 	reader := kafka.NewReader(kafka.ReaderConfig{
 		Brokers:     cfg.KafkaBrokers,
 		GroupID:     cfg.KafkaGroup,
 		GroupTopics: cfg.KafkaTopics,
 		MinBytes:    1,
 		MaxBytes:    10e6,
 	})
 	defer reader.Close()
 	logger.Info("history writer started",
 		"driver", cfg.TDengineDriver,
 		"group", cfg.KafkaGroup,
 		"topics", strings.Join(cfg.KafkaTopics, ","))
 	for {
 		message, err := reader.FetchMessage(ctx)
 		if err != nil {
 			if ctx.Err() != nil {
 				return
 			}
 			logger.Error("kafka fetch failed", "error", err)
 			continue
 		}
 		var env envelope.FrameEnvelope
 		if err := json.Unmarshal(message.Value, &env); err != nil {
 			logger.Warn("skip invalid envelope json", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 			_ = reader.CommitMessages(ctx, message)
 			continue
 		}
 		if err := writer.AppendAll(ctx, env); err != nil {
 			logger.Error("tdengine append failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "event_id", env.StableEventID(), "error", err)
 			continue
 		}
 		if err := reader.CommitMessages(ctx, message); err != nil {
 			logger.Error("kafka commit failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 		}
 	}
 }
 type config struct {
 	KafkaBrokers     []string
 	KafkaTopics      []string
 	KafkaGroup       string
 	TDengineDriver   string
 	TDengineDSN      string
 	TDengineDatabase string
 	EnsureSchema     bool
 }
 func loadConfig() config {
 	return config{
 		KafkaBrokers:     splitCSV(env("KAFKA_BROKERS", "127.0.0.1:9092")),
 		KafkaTopics:      splitCSV(env("KAFKA_TOPICS", "vehicle.raw.gb32960.v1,vehicle.raw.jt808.v1,vehicle.raw.yutong-mqtt.v1")),
 		KafkaGroup:       env("KAFKA_GROUP", "go-history-writer"),
 		TDengineDriver:   env("TDENGINE_DRIVER", "taosWS"),
 		TDengineDSN:      env("TDENGINE_DSN", ""),
 		TDengineDatabase: env("TDENGINE_DATABASE", history.DefaultDatabase),
 		EnsureSchema:     env("TDENGINE_ENSURE_SCHEMA", "true") != "false",
 	}
 }
 func env(key string, fallback string) string {
 	value := strings.TrimSpace(os.Getenv(key))
 	if value == "" {
 		return fallback
 	}
 	return value
 }
 func splitCSV(value string) []string {
 	var out []string
 	for _, item := range strings.Split(value, ",") {
 		item = strings.TrimSpace(item)
 		if item != "" {
 			out = append(out, item)
 		}
 	}
 	return out
 }
--- a/go/vehicle-gateway/cmd/realtime-api/main.go
+++ b/go/vehicle-gateway/cmd/realtime-api/main.go
@@ -0,0 +1,198 @@
 package main
 import (
 	"context"
 	"database/sql"
 	"encoding/json"
 	"net/http"
 	"os"
 	"os/signal"
 	"strconv"
 	"strings"
 	"syscall"
 	"time"
 	_ "github.com/go-sql-driver/mysql"
 	"github.com/redis/go-redis/v9"
 	"github.com/segmentio/kafka-go"
 	_ "github.com/taosdata/driver-go/v3/taosWS"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/history"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/observability"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/realtime"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/stats"
 )
 func main() {
 	logger := observability.NewLogger("vehicle-realtime-api")
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	client := redis.NewClient(&redis.Options{
 		Addr:     env("REDIS_ADDR", "127.0.0.1:6379"),
 		Username: env("REDIS_USERNAME", ""),
 		Password: env("REDIS_PASSWORD", ""),
 		DB:       envInt("REDIS_DB", 0),
 	})
 	defer client.Close()
 	if err := client.Ping(ctx).Err(); err != nil {
 		logger.Error("redis ping failed", "error", err)
 		os.Exit(1)
 	}
 	repository := realtime.NewRepository(client, realtime.Config{
 		OnlineTTL: time.Duration(envInt("ONLINE_TTL_SECONDS", 600)) * time.Second,
 	})
 	if brokers := splitCSV(os.Getenv("KAFKA_BROKERS")); len(brokers) > 0 {
 		go consumeKafka(ctx, logger, repository, brokers)
 	} else {
 		logger.Warn("KAFKA_BROKERS is empty; realtime api will serve existing redis data only")
 	}
 	mux := http.NewServeMux()
 	mux.Handle("/api/realtime/vehicles/", realtime.NewHandler(repository))
 	closeStats := func() {}
 	if dsn := strings.TrimSpace(os.Getenv("MYSQL_DSN")); dsn != "" {
 		db, err := sql.Open("mysql", dsn)
 		if err != nil {
 			logger.Error("stats mysql open failed", "error", err)
 			os.Exit(1)
 		}
 		if err := db.PingContext(ctx); err != nil {
 			_ = db.Close()
 			logger.Error("stats mysql ping failed", "error", err)
 			os.Exit(1)
 		}
 		closeStats = func() { _ = db.Close() }
 		mux.Handle("/api/stats/daily-metrics", stats.NewMetricHandler(stats.NewMetricRepository(db)))
 		logger.Info("stats mysql query enabled")
 	} else {
 		mux.HandleFunc("/api/stats/daily-metrics", func(w http.ResponseWriter, _ *http.Request) {
 			w.Header().Set("Content-Type", "application/json")
 			w.WriteHeader(http.StatusServiceUnavailable)
 			_ = json.NewEncoder(w).Encode(map[string]any{"error": "MYSQL_DSN is not configured"})
 		})
 		logger.Warn("MYSQL_DSN is empty; stats query api disabled")
 	}
 	defer closeStats()
 	closeHistory := func() {}
 	if dsn := strings.TrimSpace(os.Getenv("TDENGINE_DSN")); dsn != "" {
 		driver := env("TDENGINE_DRIVER", "taosWS")
 		db, err := sql.Open(driver, dsn)
 		if err != nil {
 			logger.Error("history tdengine open failed", "driver", driver, "error", err)
 			os.Exit(1)
 		}
 		if err := db.PingContext(ctx); err != nil {
 			_ = db.Close()
 			logger.Error("history tdengine ping failed", "driver", driver, "error", err)
 			os.Exit(1)
 		}
 		closeHistory = func() { _ = db.Close() }
 		database := env("TDENGINE_DATABASE", history.DefaultDatabase)
 		mux.Handle("/api/history/raw-frames", history.NewRawFrameHandler(history.NewRawFrameRepository(db, database)))
 		mux.Handle("/api/history/locations", history.NewLocationHandler(history.NewLocationRepository(db, database)))
 		mux.Handle("/api/history/mileage-points", history.NewMileagePointHandler(history.NewMileagePointRepository(db, database)))
 		logger.Info("history query enabled", "driver", driver, "database", database)
 	} else {
 		historyUnavailable := func(w http.ResponseWriter, _ *http.Request) {
 			w.Header().Set("Content-Type", "application/json")
 			w.WriteHeader(http.StatusServiceUnavailable)
 			_ = json.NewEncoder(w).Encode(map[string]any{"error": "TDENGINE_DSN is not configured"})
 		}
 		mux.HandleFunc("/api/history/raw-frames", historyUnavailable)
 		mux.HandleFunc("/api/history/locations", historyUnavailable)
 		mux.HandleFunc("/api/history/mileage-points", historyUnavailable)
 		logger.Warn("TDENGINE_DSN is empty; history query api disabled")
 	}
 	defer closeHistory()
 	server := &http.Server{
 		Addr:              env("HTTP_ADDR", ":20210"),
 		Handler:           mux,
 		ReadHeaderTimeout: 5 * time.Second,
 	}
 	go func() {
 		<-ctx.Done()
 		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 		defer cancel()
 		_ = server.Shutdown(shutdownCtx)
 	}()
 	logger.Info("realtime api started", "addr", server.Addr)
 	if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 		logger.Error("http server failed", "error", err)
 		os.Exit(1)
 	}
 }
 func consumeKafka(ctx context.Context, logger interface {
 	Info(string, ...any)
 	Error(string, ...any)
 	Warn(string, ...any)
 }, repository *realtime.Repository, brokers []string) {
 	reader := kafka.NewReader(kafka.ReaderConfig{
 		Brokers:     brokers,
 		GroupID:     env("KAFKA_GROUP", "go-realtime-api"),
 		GroupTopics: splitCSV(env("KAFKA_TOPICS", "vehicle.event.unified.v1")),
 		MinBytes:    1,
 		MaxBytes:    10e6,
 	})
 	defer reader.Close()
 	logger.Info("realtime kafka consumer started", "topics", env("KAFKA_TOPICS", "vehicle.event.unified.v1"))
 	for {
 		message, err := reader.FetchMessage(ctx)
 		if err != nil {
 			if ctx.Err() != nil {
 				return
 			}
 			logger.Error("kafka fetch failed", "error", err)
 			continue
 		}
 		var env envelope.FrameEnvelope
 		if err := json.Unmarshal(message.Value, &env); err != nil {
 			logger.Warn("skip invalid envelope json", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 			_ = reader.CommitMessages(ctx, message)
 			continue
 		}
 		if err := repository.Update(ctx, env); err != nil {
 			logger.Error("redis realtime update failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "event_id", env.StableEventID(), "error", err)
 			continue
 		}
 		if err := reader.CommitMessages(ctx, message); err != nil {
 			logger.Error("kafka commit failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 		}
 	}
 }
 func env(key string, fallback string) string {
 	value := strings.TrimSpace(os.Getenv(key))
 	if value == "" {
 		return fallback
 	}
 	return value
 }
 func envInt(key string, fallback int) int {
 	value := strings.TrimSpace(os.Getenv(key))
 	if value == "" {
 		return fallback
 	}
 	parsed, err := strconv.Atoi(value)
 	if err != nil {
 		return fallback
 	}
 	return parsed
 }
 func splitCSV(value string) []string {
 	var out []string
 	for _, item := range strings.Split(value, ",") {
 		item = strings.TrimSpace(item)
 		if item != "" {
 			out = append(out, item)
 		}
 	}
 	return out
 }
--- a/go/vehicle-gateway/cmd/stat-writer/main.go
+++ b/go/vehicle-gateway/cmd/stat-writer/main.go
@@ -0,0 +1,122 @@
 package main
 import (
 	"context"
 	"database/sql"
 	"encoding/json"
 	"os"
 	"os/signal"
 	"strings"
 	"syscall"
 	"time"
 	_ "github.com/go-sql-driver/mysql"
 	"github.com/segmentio/kafka-go"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/observability"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/stats"
 )
 func main() {
 	logger := observability.NewLogger("vehicle-stat-writer")
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	cfg := loadConfig()
 	db, err := sql.Open("mysql", cfg.MySQLDSN)
 	if err != nil {
 		logger.Error("mysql open failed", "error", err)
 		os.Exit(1)
 	}
 	defer db.Close()
 	if err := db.PingContext(ctx); err != nil {
 		logger.Error("mysql ping failed", "error", err)
 		os.Exit(1)
 	}
 	writer := stats.NewWriter(db, cfg.Location)
 	if cfg.EnsureSchema {
 		if err := writer.EnsureSchema(ctx); err != nil {
 			logger.Error("mysql schema bootstrap failed", "error", err)
 			os.Exit(1)
 		}
 	}
 	reader := kafka.NewReader(kafka.ReaderConfig{
 		Brokers:     cfg.KafkaBrokers,
 		GroupID:     cfg.KafkaGroup,
 		GroupTopics: cfg.KafkaTopics,
 		MinBytes:    1,
 		MaxBytes:    10e6,
 	})
 	defer reader.Close()
 	logger.Info("stat writer started", "group", cfg.KafkaGroup, "topics", strings.Join(cfg.KafkaTopics, ","))
 	for {
 		message, err := reader.FetchMessage(ctx)
 		if err != nil {
 			if ctx.Err() != nil {
 				return
 			}
 			logger.Error("kafka fetch failed", "error", err)
 			continue
 		}
 		var env envelope.FrameEnvelope
 		if err := json.Unmarshal(message.Value, &env); err != nil {
 			logger.Warn("skip invalid envelope json", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 			_ = reader.CommitMessages(ctx, message)
 			continue
 		}
 		if err := writer.Append(ctx, env); err != nil {
 			logger.Error("mysql append failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "event_id", env.StableEventID(), "error", err)
 			continue
 		}
 		if err := reader.CommitMessages(ctx, message); err != nil {
 			logger.Error("kafka commit failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 		}
 	}
 }
 type config struct {
 	KafkaBrokers []string
 	KafkaTopics  []string
 	KafkaGroup   string
 	MySQLDSN     string
 	EnsureSchema bool
 	Location     *time.Location
 }
 func loadConfig() config {
 	loc, err := time.LoadLocation(env("LOCAL_TZ", "Asia/Shanghai"))
 	if err != nil {
 		loc = time.FixedZone("Asia/Shanghai", 8*3600)
 	}
 	return config{
 		KafkaBrokers: splitCSV(env("KAFKA_BROKERS", "127.0.0.1:9092")),
 		KafkaTopics:  splitCSV(env("KAFKA_TOPICS", "vehicle.raw.gb32960.v1,vehicle.raw.jt808.v1")),
 		KafkaGroup:   env("KAFKA_GROUP", "go-stat-writer"),
 		MySQLDSN:     env("MYSQL_DSN", ""),
 		EnsureSchema: env("MYSQL_ENSURE_SCHEMA", "true") != "false",
 		Location:     loc,
 	}
 }
 func env(key string, fallback string) string {
 	value := strings.TrimSpace(os.Getenv(key))
 	if value == "" {
 		return fallback
 	}
 	return value
 }
 func splitCSV(value string) []string {
 	var out []string
 	for _, item := range strings.Split(value, ",") {
 		item = strings.TrimSpace(item)
 		if item != "" {
 			out = append(out, item)
 		}
 	}
 	return out
 }
--- a/go/vehicle-gateway/go.mod
+++ b/go/vehicle-gateway/go.mod
@@ -0,0 +1,30 @@
 module lingniu-vehicle-ingest/go/vehicle-gateway
 go 1.26
 require (
 	github.com/DATA-DOG/go-sqlmock v1.5.2
 	github.com/alicebob/miniredis/v2 v2.35.0
 	github.com/eclipse/paho.mqtt.golang v1.5.1
 	github.com/go-sql-driver/mysql v1.9.3
 	github.com/redis/go-redis/v9 v9.17.2
 	github.com/segmentio/kafka-go v0.4.49
 	github.com/taosdata/driver-go/v3 v3.8.1
 	golang.org/x/text v0.29.0
 )
 require (
 	filippo.io/edwards25519 v1.1.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.15.9 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pierrec/lz4/v4 v4.1.15 // indirect
 	github.com/yuin/gopher-lua v1.1.1 // indirect
 	golang.org/x/net v0.44.0 // indirect
 	golang.org/x/sync v0.17.0 // indirect
 )
--- a/go/vehicle-gateway/go.sum
+++ b/go/vehicle-gateway/go.sum
@@ -0,0 +1,73 @@
 filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
 filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
 github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
 github.com/alicebob/miniredis/v2 v2.35.0 h1:QwLphYqCEAo1eu1TqPRN2jgVMPBweeQcR21jeqDCONI=
 github.com/alicebob/miniredis/v2 v2.35.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM=
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
 github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
 github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
 github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/eclipse/paho.mqtt.golang v1.5.1 h1:/VSOv3oDLlpqR2Epjn1Q7b2bSTplJIeV2ISgCl2W7nE=
 github.com/eclipse/paho.mqtt.golang v1.5.1/go.mod h1:1/yJCneuyOoCOzKSsOTUc0AJfpsItBGWvYpBLimhArU=
 github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
 github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/kisielk/sqlstruct v0.0.0-20201105191214-5f3e10d3ab46/go.mod h1:yyMNCyc/Ib3bDTKd379tNMpB/7/H5TjM2Y9QJ5THLbE=
 github.com/klauspost/compress v1.15.9 h1:wKRjX6JRtDdrE9qwa4b/Cip7ACOshUI4smpCQanqjSY=
 github.com/klauspost/compress v1.15.9/go.mod h1:PhcZ0MbTNciWF3rruxRgKxI5NkcHHrHUDtV4Yw2GlzU=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 h1:ZqeYNhU3OHLH3mGKHDcjJRFFRrJa6eAM5H+CtDdOsPc=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/pierrec/lz4/v4 v4.1.15 h1:MO0/ucJhngq7299dKLwIMtgTfbkoSPF6AoMYDd8Q4q0=
 github.com/pierrec/lz4/v4 v4.1.15/go.mod h1:gZWDp/Ze/IJXGXf23ltt2EXimqmTUXEy0GFuRQyBid4=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/redis/go-redis/v9 v9.17.2 h1:P2EGsA4qVIM3Pp+aPocCJ7DguDHhqrXNhVcEp4ViluI=
 github.com/redis/go-redis/v9 v9.17.2/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
 github.com/segmentio/kafka-go v0.4.49 h1:GJiNX1d/g+kG6ljyJEoi9++PUMdXGAxb7JGPiDCuNmk=
 github.com/segmentio/kafka-go v0.4.49/go.mod h1:Y1gn60kzLEEaW28YshXyk2+VCUKbJ3Qr6DrnT3i4+9E=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0 h1:1zr/of2m5FGMsad5YfcqgdqdWrIhu+EBEJRhR1U7z/c=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.2 h1:+h33VjcLVPDHtOdpUCuF+7gSuG3yGIftsP1YvFihtJ8=
 github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/taosdata/driver-go/v3 v3.8.1 h1:kkd4ABsGiU+oXDbsw/sic985LKAvnpF9Gb/TEunTnLE=
 github.com/taosdata/driver-go/v3 v3.8.1/go.mod h1:S6OGOinfR0xxxaMGsvBi9cLkYxEIW1p6qqr8QJATTlg=
 github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
 github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
 github.com/xdg-go/scram v1.1.2 h1:FHX5I5B4i4hKRVRBCFRxq1iQRej7WO3hhBuJf+UUySY=
 github.com/xdg-go/scram v1.1.2/go.mod h1:RT/sEzTbU5y00aCK8UOx6R7YryM0iF1N2MOmC3kKLN4=
 github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
 github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
 github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
 github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw=
 golang.org/x/net v0.44.0 h1:evd8IRDyfNBMBTTY5XRF1vaZlD+EmWx6x8PkhR04H/I=
 golang.org/x/net v0.44.0/go.mod h1:ECOoLqd5U3Lhyeyo/QDCEVQ4sNgYsqvCZ722XogGieY=
 golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
 golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
 golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
--- a/go/vehicle-gateway/internal/envelope/envelope.go
+++ b/go/vehicle-gateway/internal/envelope/envelope.go
@@ -0,0 +1,95 @@
 package envelope
 import (
 	"crypto/sha256"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"strings"
 )
 type Protocol string
 const (
 	ProtocolGB32960    Protocol = "GB32960"
 	ProtocolJT808      Protocol = "JT808"
 	ProtocolYutongMQTT Protocol = "YUTONG_MQTT"
 )
 type ParseStatus string
 const (
 	ParseOK       ParseStatus = "OK"
 	ParsePartial  ParseStatus = "PARTIAL"
 	ParseBadFrame ParseStatus = "BAD_FRAME"
 )
 const (
 	FieldSpeedKMH       = "speed_kmh"
 	FieldTotalMileageKM = "total_mileage_km"
 	FieldLongitude      = "longitude"
 	FieldLatitude       = "latitude"
 	FieldSOCPercent     = "soc_percent"
 )
 type FrameEnvelope struct {
 	EventID        string         `json:"event_id"`
 	TraceID        string         `json:"trace_id"`
 	Protocol       Protocol       `json:"protocol"`
 	MessageID      string         `json:"message_id"`
 	Sequence       uint16         `json:"sequence"`
 	VIN            string         `json:"vin,omitempty"`
 	VehicleKeyHint string         `json:"vehicle_key,omitempty"`
 	Phone          string         `json:"phone,omitempty"`
 	DeviceID       string         `json:"device_id,omitempty"`
 	Plate          string         `json:"plate,omitempty"`
 	SourceEndpoint string         `json:"source_endpoint,omitempty"`
 	EventTimeMS    int64          `json:"event_time_ms"`
 	ReceivedAtMS   int64          `json:"received_at_ms"`
 	RawHex         string         `json:"raw_hex,omitempty"`
 	RawText        string         `json:"raw_text,omitempty"`
 	Parsed         map[string]any `json:"parsed,omitempty"`
 	Fields         map[string]any `json:"fields,omitempty"`
 	ParseStatus    ParseStatus    `json:"parse_status"`
 	ParseError     string         `json:"parse_error,omitempty"`
 }
 func (e FrameEnvelope) VehicleKey() string {
 	if key := strings.TrimSpace(e.VIN); key != "" {
 		return key
 	}
 	if key := strings.TrimSpace(e.VehicleKeyHint); key != "" {
 		return key
 	}
 	if key := strings.TrimSpace(e.Phone); key != "" {
 		return string(e.Protocol) + ":" + key
 	}
 	if key := strings.TrimSpace(e.DeviceID); key != "" {
 		return string(e.Protocol) + ":" + key
 	}
 	return string(e.Protocol) + ":unknown"
 }
 func (e FrameEnvelope) StableEventID() string {
 	if strings.TrimSpace(e.EventID) != "" {
 		return e.EventID
 	}
 	input := fmt.Sprintf("%s|%s|%s|%d|%d|%s",
 		e.Protocol, e.MessageID, e.VehicleKey(), e.Sequence, e.EventTimeMS, e.RawHex)
 	sum := sha256.Sum256([]byte(input))
 	return hex.EncodeToString(sum[:16])
 }
 func (e FrameEnvelope) KafkaKey() []byte {
 	return []byte(e.VehicleKey())
 }
 func (e FrameEnvelope) MarshalJSONBytes() ([]byte, error) {
 	if e.EventID == "" {
 		e.EventID = e.StableEventID()
 	}
 	if e.ParseStatus == "" {
 		e.ParseStatus = ParseOK
 	}
 	return json.Marshal(e)
 }
--- a/go/vehicle-gateway/internal/envelope/envelope_test.go
+++ b/go/vehicle-gateway/internal/envelope/envelope_test.go
@@ -0,0 +1,55 @@
 package envelope
 import (
 	"encoding/json"
 	"testing"
 )
 func TestFrameEnvelopeVehicleKeyPrefersVIN(t *testing.T) {
 	e := FrameEnvelope{Protocol: ProtocolJT808, VIN: "LNBVIN00000000001", Phone: "013307795425"}
 	if got := e.VehicleKey(); got != "LNBVIN00000000001" {
 		t.Fatalf("VehicleKey() = %q", got)
 	}
 }
 func TestFrameEnvelopeVehicleKeyFallsBackToPhone(t *testing.T) {
 	e := FrameEnvelope{Protocol: ProtocolJT808, Phone: "013307795425"}
 	if got := e.VehicleKey(); got != "JT808:013307795425" {
 		t.Fatalf("VehicleKey() = %q", got)
 	}
 }
 func TestFrameEnvelopeEventIDStable(t *testing.T) {
 	e := FrameEnvelope{
 		Protocol:     ProtocolJT808,
 		MessageID:    "0x0200",
 		Phone:        "013307795425",
 		Sequence:     1,
 		EventTimeMS:  1782745114000,
 		ReceivedAtMS: 1782745114999,
 		RawHex:       "7e02000000ff7e",
 	}
 	a := e.StableEventID()
 	b := e.StableEventID()
 	if a == "" || a != b {
 		t.Fatalf("event id must be non-empty and stable: %q %q", a, b)
 	}
 }
 func TestFrameEnvelopeMarshalDefaults(t *testing.T) {
 	e := FrameEnvelope{Protocol: ProtocolGB32960, VIN: "LNBVIN00000000002", MessageID: "0x02"}
 	payload, err := e.MarshalJSONBytes()
 	if err != nil {
 		t.Fatalf("MarshalJSONBytes() error = %v", err)
 	}
 	var decoded FrameEnvelope
 	if err := json.Unmarshal(payload, &decoded); err != nil {
 		t.Fatalf("json.Unmarshal() error = %v", err)
 	}
 	if decoded.EventID == "" {
 		t.Fatal("event id should be filled")
 	}
 	if decoded.ParseStatus != ParseOK {
 		t.Fatalf("parse status = %q", decoded.ParseStatus)
 	}
 }
--- a/go/vehicle-gateway/internal/eventbus/durable_sink.go
+++ b/go/vehicle-gateway/internal/eventbus/durable_sink.go
@@ -0,0 +1,187 @@
 package eventbus
 import (
 	"context"
 	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
 	"sort"
 	"strings"
 	"sync"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type DurableConfig struct {
 	Directory string
 }
 type DurableSink struct {
 	delegate Sink
 	dir      string
 	mu         sync.Mutex
 	seq        uint64
 	rawPending map[string]struct{}
 }
 type durableRecord struct {
 	Kind     string                 `json:"kind"`
 	Envelope envelope.FrameEnvelope `json:"envelope"`
 }
 func NewDurableSink(delegate Sink, cfg DurableConfig) *DurableSink {
 	if delegate == nil {
 		panic("durable delegate sink must not be nil")
 	}
 	return &DurableSink{
 		delegate:   delegate,
 		dir:        strings.TrimSpace(cfg.Directory),
 		rawPending: map[string]struct{}{},
 	}
 }
 func (s *DurableSink) PublishRaw(ctx context.Context, env envelope.FrameEnvelope) error {
 	if err := s.delegate.PublishRaw(ctx, env); err == nil {
 		return nil
 	}
 	if err := s.spool("raw", env); err != nil {
 		return err
 	}
 	s.markRawPending(env)
 	return nil
 }
 func (s *DurableSink) PublishUnified(ctx context.Context, env envelope.FrameEnvelope) error {
 	if s.isRawPending(env) {
 		return s.spool("unified", env)
 	}
 	if err := s.delegate.PublishUnified(ctx, env); err == nil {
 		return nil
 	}
 	return s.spool("unified", env)
 }
 func (s *DurableSink) ReplayOnce(ctx context.Context) error {
 	files, err := filepath.Glob(filepath.Join(s.dir, "*.json"))
 	if err != nil {
 		return err
 	}
 	sort.Strings(files)
 	for _, file := range files {
 		record, err := readDurableRecord(file)
 		if err != nil {
 			return err
 		}
 		if err := s.publishRecord(ctx, record); err != nil {
 			return err
 		}
 		if err := os.Remove(file); err != nil {
 			return err
 		}
 		if record.Kind == "raw" {
 			s.clearRawPending(record.Envelope)
 		}
 	}
 	return nil
 }
 func (s *DurableSink) ReplayLoop(ctx context.Context, interval time.Duration, onError func(error)) {
 	if interval <= 0 {
 		interval = time.Second
 	}
 	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
 	for {
 		select {
 		case <-ctx.Done():
 			return
 		case <-ticker.C:
 			if err := s.ReplayOnce(ctx); err != nil && onError != nil {
 				onError(err)
 			}
 		}
 	}
 }
 func (s *DurableSink) Close() error {
 	return s.delegate.Close()
 }
 func (s *DurableSink) publishRecord(ctx context.Context, record durableRecord) error {
 	switch record.Kind {
 	case "raw":
 		return s.delegate.PublishRaw(ctx, record.Envelope)
 	case "unified":
 		return s.delegate.PublishUnified(ctx, record.Envelope)
 	default:
 		return fmt.Errorf("unknown durable record kind %q", record.Kind)
 	}
 }
 func (s *DurableSink) spool(kind string, env envelope.FrameEnvelope) error {
 	if s.dir == "" {
 		return fmt.Errorf("durable spool directory is empty")
 	}
 	if env.EventID == "" {
 		env.EventID = env.StableEventID()
 	}
 	if env.ParseStatus == "" {
 		env.ParseStatus = envelope.ParseOK
 	}
 	if err := os.MkdirAll(s.dir, 0o750); err != nil {
 		return err
 	}
 	payload, err := json.Marshal(durableRecord{Kind: kind, Envelope: env})
 	if err != nil {
 		return err
 	}
 	name := s.nextFileName(env, kind)
 	path := filepath.Join(s.dir, name)
 	tmp := path + ".tmp"
 	if err := os.WriteFile(tmp, payload, 0o640); err != nil {
 		return err
 	}
 	return os.Rename(tmp, path)
 }
 func (s *DurableSink) nextFileName(env envelope.FrameEnvelope, kind string) string {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	s.seq++
 	eventID := env.StableEventID()
 	if len(eventID) > 12 {
 		eventID = eventID[:12]
 	}
 	return fmt.Sprintf("%020d-%06d-%s-%s.json", time.Now().UnixNano(), s.seq, kind, eventID)
 }
 func (s *DurableSink) markRawPending(env envelope.FrameEnvelope) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	s.rawPending[env.StableEventID()] = struct{}{}
 }
 func (s *DurableSink) clearRawPending(env envelope.FrameEnvelope) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	delete(s.rawPending, env.StableEventID())
 }
 func (s *DurableSink) isRawPending(env envelope.FrameEnvelope) bool {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	_, ok := s.rawPending[env.StableEventID()]
 	return ok
 }
 func readDurableRecord(path string) (durableRecord, error) {
 	var record durableRecord
 	payload, err := os.ReadFile(path)
 	if err != nil {
 		return record, err
 	}
 	return record, json.Unmarshal(payload, &record)
 }
--- a/go/vehicle-gateway/internal/eventbus/durable_sink_test.go
+++ b/go/vehicle-gateway/internal/eventbus/durable_sink_test.go
@@ -0,0 +1,153 @@
 package eventbus
 import (
 	"context"
 	"errors"
 	"os"
 	"path/filepath"
 	"testing"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestDurableSinkSpoolsUnifiedWhenRawWasSpooled(t *testing.T) {
 	dir := t.TempDir()
 	delegate := &scriptedSink{rawErrors: []error{errSpoolTest}}
 	sink := NewDurableSink(delegate, DurableConfig{Directory: dir})
 	env := durableTestEnvelope()
 	if err := sink.PublishRaw(context.Background(), env); err != nil {
 		t.Fatalf("PublishRaw() error = %v", err)
 	}
 	if err := sink.PublishUnified(context.Background(), env); err != nil {
 		t.Fatalf("PublishUnified() error = %v", err)
 	}
 	if delegate.rawCalls != 1 {
 		t.Fatalf("raw calls = %d, want 1", delegate.rawCalls)
 	}
 	if delegate.unifiedCalls != 0 {
 		t.Fatalf("unified should not be delegated while raw is spooled, calls = %d", delegate.unifiedCalls)
 	}
 	files := spoolFiles(t, dir)
 	if len(files) != 2 {
 		t.Fatalf("spool files = %d, want 2: %#v", len(files), files)
 	}
 	assertSpoolKind(t, files[0], "raw")
 	assertSpoolKind(t, files[1], "unified")
 }
 func TestDurableSinkReplayPublishesInFileOrderAndDeletesFiles(t *testing.T) {
 	dir := t.TempDir()
 	delegate := &scriptedSink{rawErrors: []error{errSpoolTest}}
 	sink := NewDurableSink(delegate, DurableConfig{Directory: dir})
 	env := durableTestEnvelope()
 	if err := sink.PublishRaw(context.Background(), env); err != nil {
 		t.Fatalf("PublishRaw() error = %v", err)
 	}
 	if err := sink.PublishUnified(context.Background(), env); err != nil {
 		t.Fatalf("PublishUnified() error = %v", err)
 	}
 	delegate.rawErrors = nil
 	if err := sink.ReplayOnce(context.Background()); err != nil {
 		t.Fatalf("ReplayOnce() error = %v", err)
 	}
 	got := delegate.calls
 	want := []string{"raw", "raw", "unified"}
 	if len(got) != len(want) {
 		t.Fatalf("calls = %#v, want %#v", got, want)
 	}
 	for i := range want {
 		if got[i] != want[i] {
 			t.Fatalf("calls[%d] = %q, want %q; all=%#v", i, got[i], want[i], got)
 		}
 	}
 	if files := spoolFiles(t, dir); len(files) != 0 {
 		t.Fatalf("spool files after replay = %#v, want none", files)
 	}
 }
 func durableTestEnvelope() envelope.FrameEnvelope {
 	return envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		MessageID:    "0x0200",
 		Phone:        "013079963379",
 		VIN:          "LKLG7C4E3NA774736",
 		Sequence:     183,
 		EventTimeMS:  1782903940000,
 		ReceivedAtMS: 1782917751903,
 		RawHex:       "0200002201307996337900B7",
 	}
 }
 func spoolFiles(t *testing.T, dir string) []string {
 	t.Helper()
 	matches, err := filepath.Glob(filepath.Join(dir, "*.json"))
 	if err != nil {
 		t.Fatalf("glob spool files: %v", err)
 	}
 	return matches
 }
 func assertSpoolKind(t *testing.T, path string, kind string) {
 	t.Helper()
 	payload, err := os.ReadFile(path)
 	if err != nil {
 		t.Fatalf("read spool file: %v", err)
 	}
 	if !containsString(string(payload), `"kind":"`+kind+`"`) {
 		t.Fatalf("spool file %s payload = %s, want kind %q", path, payload, kind)
 	}
 }
 func containsString(value string, needle string) bool {
 	return len(needle) == 0 || (len(value) >= len(needle) && indexString(value, needle) >= 0)
 }
 func indexString(value string, needle string) int {
 	for i := 0; i+len(needle) <= len(value); i++ {
 		if value[i:i+len(needle)] == needle {
 			return i
 		}
 	}
 	return -1
 }
 var errSpoolTest = errors.New("delegate unavailable")
 type scriptedSink struct {
 	rawErrors     []error
 	unifiedErrors []error
 	rawCalls      int
 	unifiedCalls  int
 	calls         []string
 }
 func (s *scriptedSink) PublishRaw(context.Context, envelope.FrameEnvelope) error {
 	s.rawCalls++
 	s.calls = append(s.calls, "raw")
 	if len(s.rawErrors) > 0 {
 		err := s.rawErrors[0]
 		s.rawErrors = s.rawErrors[1:]
 		return err
 	}
 	return nil
 }
 func (s *scriptedSink) PublishUnified(context.Context, envelope.FrameEnvelope) error {
 	s.unifiedCalls++
 	s.calls = append(s.calls, "unified")
 	if len(s.unifiedErrors) > 0 {
 		err := s.unifiedErrors[0]
 		s.unifiedErrors = s.unifiedErrors[1:]
 		return err
 	}
 	return nil
 }
 func (s *scriptedSink) Close() error {
 	return nil
 }
--- a/go/vehicle-gateway/internal/eventbus/kafka_sink.go
+++ b/go/vehicle-gateway/internal/eventbus/kafka_sink.go
@@ -0,0 +1,94 @@
 package eventbus
 import (
 	"context"
 	"errors"
 	"fmt"
 	"github.com/segmentio/kafka-go"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Sink interface {
 	PublishRaw(context.Context, envelope.FrameEnvelope) error
 	PublishUnified(context.Context, envelope.FrameEnvelope) error
 	Close() error
 }
 type KafkaSink struct {
 	writer       kafkaWriter
 	rawTopics    map[envelope.Protocol]string
 	unifiedTopic string
 }
 type kafkaWriter interface {
 	WriteMessages(context.Context, ...kafka.Message) error
 	Close() error
 }
 type KafkaConfig struct {
 	Brokers      []string
 	RawTopics    map[envelope.Protocol]string
 	UnifiedTopic string
 }
 func NewKafkaSink(cfg KafkaConfig) (*KafkaSink, error) {
 	if len(cfg.Brokers) == 0 {
 		return nil, errors.New("kafka brokers are required")
 	}
 	return newKafkaSinkWithWriter(&kafka.Writer{
 		Addr:                   kafka.TCP(cfg.Brokers...),
 		Balancer:               &kafka.Hash{},
 		AllowAutoTopicCreation: false,
 	}, cfg), nil
 }
 func newKafkaSinkWithWriter(writer kafkaWriter, cfg KafkaConfig) *KafkaSink {
 	rawTopics := map[envelope.Protocol]string{
 		envelope.ProtocolGB32960:    "vehicle.raw.gb32960.v1",
 		envelope.ProtocolJT808:      "vehicle.raw.jt808.v1",
 		envelope.ProtocolYutongMQTT: "vehicle.raw.yutong-mqtt.v1",
 	}
 	for protocol, topic := range cfg.RawTopics {
 		if topic != "" {
 			rawTopics[protocol] = topic
 		}
 	}
 	unifiedTopic := cfg.UnifiedTopic
 	if unifiedTopic == "" {
 		unifiedTopic = "vehicle.event.unified.v1"
 	}
 	return &KafkaSink{writer: writer, rawTopics: rawTopics, unifiedTopic: unifiedTopic}
 }
 func (s *KafkaSink) PublishRaw(ctx context.Context, env envelope.FrameEnvelope) error {
 	topic, ok := s.rawTopics[env.Protocol]
 	if !ok || topic == "" {
 		return fmt.Errorf("raw topic not configured for protocol %s", env.Protocol)
 	}
 	return s.publish(ctx, topic, env)
 }
 func (s *KafkaSink) PublishUnified(ctx context.Context, env envelope.FrameEnvelope) error {
 	return s.publish(ctx, s.unifiedTopic, env)
 }
 func (s *KafkaSink) Close() error {
 	if s == nil || s.writer == nil {
 		return nil
 	}
 	return s.writer.Close()
 }
 func (s *KafkaSink) publish(ctx context.Context, topic string, env envelope.FrameEnvelope) error {
 	payload, err := env.MarshalJSONBytes()
 	if err != nil {
 		return err
 	}
 	return s.writer.WriteMessages(ctx, kafka.Message{
 		Topic: topic,
 		Key:   env.KafkaKey(),
 		Value: payload,
 	})
 }
--- a/go/vehicle-gateway/internal/eventbus/kafka_sink_test.go
+++ b/go/vehicle-gateway/internal/eventbus/kafka_sink_test.go
@@ -0,0 +1,77 @@
 package eventbus
 import (
 	"context"
 	"encoding/json"
 	"testing"
 	"github.com/segmentio/kafka-go"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestKafkaSinkRoutesRawTopics(t *testing.T) {
 	writer := &recordingWriter{}
 	sink := newKafkaSinkWithWriter(writer, KafkaConfig{})
 	env := envelope.FrameEnvelope{Protocol: envelope.ProtocolJT808, Phone: "013307795425", MessageID: "0x0200"}
 	if err := sink.PublishRaw(context.Background(), env); err != nil {
 		t.Fatalf("PublishRaw() error = %v", err)
 	}
 	if len(writer.messages) != 1 {
 		t.Fatalf("messages = %d", len(writer.messages))
 	}
 	msg := writer.messages[0]
 	if msg.Topic != "vehicle.raw.jt808.v1" {
 		t.Fatalf("topic = %q", msg.Topic)
 	}
 	if string(msg.Key) != "JT808:013307795425" {
 		t.Fatalf("key = %q", string(msg.Key))
 	}
 	var decoded envelope.FrameEnvelope
 	if err := json.Unmarshal(msg.Value, &decoded); err != nil {
 		t.Fatalf("json.Unmarshal() error = %v", err)
 	}
 	if decoded.EventID == "" || decoded.ParseStatus != envelope.ParseOK {
 		t.Fatalf("unexpected payload defaults: %#v", decoded)
 	}
 }
 func TestKafkaSinkRoutesUnifiedTopic(t *testing.T) {
 	writer := &recordingWriter{}
 	sink := newKafkaSinkWithWriter(writer, KafkaConfig{UnifiedTopic: "custom.unified"})
 	env := envelope.FrameEnvelope{Protocol: envelope.ProtocolGB32960, VIN: "LNBVIN00000000001", MessageID: "0x02"}
 	if err := sink.PublishUnified(context.Background(), env); err != nil {
 		t.Fatalf("PublishUnified() error = %v", err)
 	}
 	if writer.messages[0].Topic != "custom.unified" {
 		t.Fatalf("topic = %q", writer.messages[0].Topic)
 	}
 	if string(writer.messages[0].Key) != "LNBVIN00000000001" {
 		t.Fatalf("key = %q", string(writer.messages[0].Key))
 	}
 }
 func TestKafkaSinkRejectsUnknownProtocol(t *testing.T) {
 	writer := &recordingWriter{}
 	sink := newKafkaSinkWithWriter(writer, KafkaConfig{})
 	err := sink.PublishRaw(context.Background(), envelope.FrameEnvelope{Protocol: envelope.Protocol("UNKNOWN")})
 	if err == nil {
 		t.Fatal("expected unknown protocol error")
 	}
 }
 type recordingWriter struct {
 	messages []kafka.Message
 }
 func (w *recordingWriter) WriteMessages(_ context.Context, messages ...kafka.Message) error {
 	w.messages = append(w.messages, messages...)
 	return nil
 }
 func (w *recordingWriter) Close() error {
 	return nil
 }
--- a/go/vehicle-gateway/internal/eventbus/log_sink.go
+++ b/go/vehicle-gateway/internal/eventbus/log_sink.go
@@ -0,0 +1,33 @@
 package eventbus
 import (
 	"context"
 	"log/slog"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type LogSink struct {
 	logger *slog.Logger
 }
 func NewLogSink(logger *slog.Logger) *LogSink {
 	if logger == nil {
 		logger = slog.Default()
 	}
 	return &LogSink{logger: logger}
 }
 func (s *LogSink) PublishRaw(_ context.Context, env envelope.FrameEnvelope) error {
 	s.logger.Info("raw envelope", "protocol", env.Protocol, "event_id", env.StableEventID(), "vehicle_key", env.VehicleKey(), "message_id", env.MessageID, "status", env.ParseStatus)
 	return nil
 }
 func (s *LogSink) PublishUnified(_ context.Context, env envelope.FrameEnvelope) error {
 	s.logger.Info("unified envelope", "protocol", env.Protocol, "event_id", env.StableEventID(), "vehicle_key", env.VehicleKey(), "message_id", env.MessageID)
 	return nil
 }
 func (s *LogSink) Close() error {
 	return nil
 }
--- a/go/vehicle-gateway/internal/eventbus/retry_sink.go
+++ b/go/vehicle-gateway/internal/eventbus/retry_sink.go
@@ -0,0 +1,80 @@
 package eventbus
 import (
 	"context"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type RetryConfig struct {
 	Attempts       int
 	Backoff        time.Duration
 	AttemptTimeout time.Duration
 }
 type RetryingSink struct {
 	delegate Sink
 	cfg      RetryConfig
 }
 func NewRetryingSink(delegate Sink, cfg RetryConfig) *RetryingSink {
 	if delegate == nil {
 		panic("retry delegate sink must not be nil")
 	}
 	if cfg.Attempts <= 0 {
 		cfg.Attempts = 1
 	}
 	return &RetryingSink{delegate: delegate, cfg: cfg}
 }
 func (s *RetryingSink) PublishRaw(ctx context.Context, env envelope.FrameEnvelope) error {
 	return s.withRetry(ctx, func(attemptCtx context.Context) error {
 		return s.delegate.PublishRaw(attemptCtx, env)
 	})
 }
 func (s *RetryingSink) PublishUnified(ctx context.Context, env envelope.FrameEnvelope) error {
 	return s.withRetry(ctx, func(attemptCtx context.Context) error {
 		return s.delegate.PublishUnified(attemptCtx, env)
 	})
 }
 func (s *RetryingSink) Close() error {
 	return s.delegate.Close()
 }
 func (s *RetryingSink) withRetry(ctx context.Context, publish func(context.Context) error) error {
 	var lastErr error
 	for attempt := 1; attempt <= s.cfg.Attempts; attempt++ {
 		attemptCtx := ctx
 		cancel := func() {}
 		if s.cfg.AttemptTimeout > 0 {
 			attemptCtx, cancel = context.WithTimeout(ctx, s.cfg.AttemptTimeout)
 		}
 		err := publish(attemptCtx)
 		cancel()
 		if err == nil {
 			return nil
 		}
 		lastErr = err
 		if ctx.Err() != nil {
 			return ctx.Err()
 		}
 		if attempt == s.cfg.Attempts {
 			break
 		}
 		if s.cfg.Backoff > 0 {
 			timer := time.NewTimer(s.cfg.Backoff)
 			select {
 			case <-ctx.Done():
 				if !timer.Stop() {
 					<-timer.C
 				}
 				return ctx.Err()
 			case <-timer.C:
 			}
 		}
 	}
 	return lastErr
 }
--- a/go/vehicle-gateway/internal/eventbus/retry_sink_test.go
+++ b/go/vehicle-gateway/internal/eventbus/retry_sink_test.go
@@ -0,0 +1,80 @@
 package eventbus
 import (
 	"context"
 	"errors"
 	"testing"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestRetryingSinkRetriesRawUntilSuccess(t *testing.T) {
 	delegate := &flakySink{rawFailures: 1}
 	sink := NewRetryingSink(delegate, RetryConfig{Attempts: 3})
 	err := sink.PublishRaw(context.Background(), envelope.FrameEnvelope{Protocol: envelope.ProtocolJT808})
 	if err != nil {
 		t.Fatalf("PublishRaw() error = %v", err)
 	}
 	if delegate.rawCalls != 2 {
 		t.Fatalf("raw calls = %d, want 2", delegate.rawCalls)
 	}
 }
 func TestRetryingSinkReturnsLastErrorAfterAttempts(t *testing.T) {
 	delegate := &flakySink{rawFailures: 3}
 	sink := NewRetryingSink(delegate, RetryConfig{Attempts: 2})
 	err := sink.PublishRaw(context.Background(), envelope.FrameEnvelope{Protocol: envelope.ProtocolJT808})
 	if !errors.Is(err, errFlakyPublish) {
 		t.Fatalf("PublishRaw() error = %v, want %v", err, errFlakyPublish)
 	}
 	if delegate.rawCalls != 2 {
 		t.Fatalf("raw calls = %d, want 2", delegate.rawCalls)
 	}
 }
 func TestRetryingSinkStopsWhenContextCanceledDuringBackoff(t *testing.T) {
 	delegate := &flakySink{rawFailures: 10}
 	sink := NewRetryingSink(delegate, RetryConfig{Attempts: 5, Backoff: time.Minute})
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
 	err := sink.PublishRaw(ctx, envelope.FrameEnvelope{Protocol: envelope.ProtocolJT808})
 	if !errors.Is(err, context.Canceled) {
 		t.Fatalf("PublishRaw() error = %v, want context canceled", err)
 	}
 	if delegate.rawCalls != 1 {
 		t.Fatalf("raw calls = %d, want 1", delegate.rawCalls)
 	}
 }
 var errFlakyPublish = errors.New("publish failed")
 type flakySink struct {
 	rawFailures     int
 	unifiedFailures int
 	rawCalls        int
 	unifiedCalls    int
 }
 func (s *flakySink) PublishRaw(context.Context, envelope.FrameEnvelope) error {
 	s.rawCalls++
 	if s.rawCalls <= s.rawFailures {
 		return errFlakyPublish
 	}
 	return nil
 }
 func (s *flakySink) PublishUnified(context.Context, envelope.FrameEnvelope) error {
 	s.unifiedCalls++
 	if s.unifiedCalls <= s.unifiedFailures {
 		return errFlakyPublish
 	}
 	return nil
 }
 func (s *flakySink) Close() error {
 	return nil
 }
--- a/go/vehicle-gateway/internal/gateway/mqtt_client.go
+++ b/go/vehicle-gateway/internal/gateway/mqtt_client.go
@@ -0,0 +1,218 @@
 package gateway
 import (
 	"context"
 	"crypto/tls"
 	"crypto/x509"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"log/slog"
 	"os"
 	"strings"
 	"time"
 	mqtt "github.com/eclipse/paho.mqtt.golang"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/eventbus"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/identity"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/yutongmqtt"
 )
 type MQTTClientConfig struct {
 	EndpointName            string
 	Broker                  string
 	ClientID                string
 	Username                string
 	Password                string
 	Topics                  []string
 	QoS                     byte
 	CleanSession            bool
 	KeepAlive               time.Duration
 	ConnectTimeout          time.Duration
 	TLSCACertPath           string
 	TLSClientCertPath       string
 	TLSClientKeyPath        string
 	TLSHostnameVerification bool
 	Sink                    eventbus.Sink
 	Resolver                identity.Resolver
 	Logger                  *slog.Logger
 }
 type MQTTClient struct {
 	cfg    MQTTClientConfig
 	client mqtt.Client
 }
 func NewMQTTClient(cfg MQTTClientConfig) (*MQTTClient, error) {
 	if strings.TrimSpace(cfg.Broker) == "" {
 		return nil, errors.New("mqtt broker is required")
 	}
 	if strings.TrimSpace(cfg.ClientID) == "" {
 		return nil, errors.New("mqtt client id is required")
 	}
 	if len(cfg.Topics) == 0 {
 		return nil, errors.New("mqtt topics are required")
 	}
 	if cfg.Sink == nil {
 		return nil, errors.New("sink is required")
 	}
 	if cfg.Logger == nil {
 		cfg.Logger = slog.Default()
 	}
 	if cfg.Resolver == nil {
 		cfg.Resolver = identity.NoopResolver{}
 	}
 	if cfg.EndpointName == "" {
 		cfg.EndpointName = "yutong"
 	}
 	return &MQTTClient{cfg: cfg}, nil
 }
 func (c *MQTTClient) Start(ctx context.Context) error {
 	opts, err := c.buildOptions(ctx)
 	if err != nil {
 		return err
 	}
 	c.client = mqtt.NewClient(opts)
 	token := c.client.Connect()
 	if token.Wait() && token.Error() != nil {
 		return token.Error()
 	}
 	go func() {
 		<-ctx.Done()
 		if c.client != nil && c.client.IsConnected() {
 			c.client.Disconnect(250)
 		}
 	}()
 	return nil
 }
 func (c *MQTTClient) buildOptions(ctx context.Context) (*mqtt.ClientOptions, error) {
 	keepAlive := c.cfg.KeepAlive
 	if keepAlive <= 0 {
 		keepAlive = 20 * time.Second
 	}
 	connectTimeout := c.cfg.ConnectTimeout
 	if connectTimeout <= 0 {
 		connectTimeout = 10 * time.Second
 	}
 	opts := mqtt.NewClientOptions().
 		AddBroker(c.cfg.Broker).
 		SetClientID(c.cfg.ClientID).
 		SetUsername(c.cfg.Username).
 		SetPassword(c.cfg.Password).
 		SetCleanSession(c.cfg.CleanSession).
 		SetAutoReconnect(true).
 		SetConnectRetry(true).
 		SetConnectRetryInterval(5 * time.Second).
 		SetResumeSubs(true).
 		SetOrderMatters(false).
 		SetKeepAlive(keepAlive).
 		SetConnectTimeout(connectTimeout)
 	opts.SetDefaultPublishHandler(func(_ mqtt.Client, message mqtt.Message) {
 		c.handleMessage(ctx, message.Topic(), message.Payload())
 	})
 	opts.OnConnect = func(client mqtt.Client) {
 		for _, topic := range c.cfg.Topics {
 			token := client.Subscribe(topic, c.cfg.QoS, nil)
 			if token.Wait() && token.Error() != nil {
 				c.cfg.Logger.Error("mqtt subscribe failed", "broker", c.cfg.Broker, "topic", topic, "error", token.Error())
 				continue
 			}
 			c.cfg.Logger.Info("mqtt subscribed", "broker", c.cfg.Broker, "topic", topic, "qos", c.cfg.QoS)
 		}
 	}
 	opts.OnConnectionLost = func(_ mqtt.Client, err error) {
 		c.cfg.Logger.Warn("mqtt connection lost", "broker", c.cfg.Broker, "error", err)
 	}
 	tlsConfig, err := c.buildTLSConfig()
 	if err != nil {
 		return nil, err
 	}
 	if tlsConfig != nil {
 		opts.SetTLSConfig(tlsConfig)
 	}
 	return opts, nil
 }
 func (c *MQTTClient) buildTLSConfig() (*tls.Config, error) {
 	caPath := strings.TrimSpace(c.cfg.TLSCACertPath)
 	certPath := strings.TrimSpace(c.cfg.TLSClientCertPath)
 	keyPath := strings.TrimSpace(c.cfg.TLSClientKeyPath)
 	if caPath == "" && certPath == "" && keyPath == "" {
 		return nil, nil
 	}
 	config := &tls.Config{
 		MinVersion:         tls.VersionTLS12,
 		InsecureSkipVerify: !c.cfg.TLSHostnameVerification,
 	}
 	if caPath != "" {
 		caPEM, err := os.ReadFile(caPath)
 		if err != nil {
 			return nil, fmt.Errorf("read mqtt ca certificate: %w", err)
 		}
 		roots := x509.NewCertPool()
 		if !roots.AppendCertsFromPEM(caPEM) {
 			return nil, fmt.Errorf("parse mqtt ca certificate %s", caPath)
 		}
 		config.RootCAs = roots
 	}
 	if certPath != "" || keyPath != "" {
 		if certPath == "" || keyPath == "" {
 			return nil, errors.New("mqtt client certificate and key must be configured together")
 		}
 		cert, err := tls.LoadX509KeyPair(certPath, keyPath)
 		if err != nil {
 			return nil, fmt.Errorf("load mqtt client certificate: %w", err)
 		}
 		config.Certificates = []tls.Certificate{cert}
 	}
 	return config, nil
 }
 func (c *MQTTClient) handleMessage(ctx context.Context, topic string, payload []byte) {
 	receivedAtMS := time.Now().UnixMilli()
 	env, err := yutongmqtt.ParseMessage(c.cfg.EndpointName, topic, payload, receivedAtMS)
 	if err != nil {
 		env = envelope.FrameEnvelope{
 			Protocol:       envelope.ProtocolYutongMQTT,
 			MessageID:      "MQTT",
 			VehicleKeyHint: "unknown",
 			SourceEndpoint: "mqtt://" + c.cfg.EndpointName + topic,
 			EventTimeMS:    receivedAtMS,
 			ReceivedAtMS:   receivedAtMS,
 			RawText:        string(payload),
 			RawHex:         strings.ToUpper(hex.EncodeToString(payload)),
 			ParseStatus:    envelope.ParseBadFrame,
 			ParseError:     err.Error(),
 		}
 		env.EventID = env.StableEventID()
 	} else {
 		resolved, resolveErr := c.cfg.Resolver.Resolve(ctx, env)
 		if resolveErr != nil {
 			c.cfg.Logger.Warn("mqtt identity resolve failed", "topic", topic, "event_id", env.StableEventID(), "error", resolveErr)
 			if env.Parsed == nil {
 				env.Parsed = map[string]any{}
 			}
 			env.Parsed["identity"] = map[string]any{"resolved": false, "error": resolveErr.Error()}
 			env.ParseStatus = envelope.ParsePartial
 		} else {
 			env = resolved
 		}
 	}
 	if err := c.cfg.Sink.PublishRaw(ctx, env); err != nil {
 		c.cfg.Logger.Error("publish mqtt raw failed", "topic", topic, "event_id", env.StableEventID(), "error", err)
 		return
 	}
 	if env.ParseStatus == envelope.ParseBadFrame {
 		return
 	}
 	if err := c.cfg.Sink.PublishUnified(ctx, env); err != nil {
 		c.cfg.Logger.Error("publish mqtt unified failed", "topic", topic, "event_id", env.StableEventID(), "error", err)
 	}
 }
--- a/go/vehicle-gateway/internal/gateway/mqtt_client_test.go
+++ b/go/vehicle-gateway/internal/gateway/mqtt_client_test.go
@@ -0,0 +1,183 @@
 package gateway
 import (
 	"context"
 	"crypto/rand"
 	"crypto/rsa"
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/pem"
 	"log/slog"
 	"math/big"
 	"os"
 	"path/filepath"
 	"testing"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestMQTTClientHandleMessagePublishesRawAndUnified(t *testing.T) {
 	sink := &recordingSink{}
 	client, err := NewMQTTClient(MQTTClientConfig{
 		EndpointName: "endpoint-a",
 		Broker:       "tcp://127.0.0.1:1883",
 		ClientID:     "test-client",
 		Topics:       []string{"/ytforward/shln/+"},
 		Sink:         sink,
 		Logger:       slog.New(slog.NewTextHandler(testWriter{t: t}, nil)),
 	})
 	if err != nil {
 		t.Fatalf("NewMQTTClient() error = %v", err)
 	}
 	client.handleMessage(context.Background(), "/ytforward/shln/dev1", []byte(`{
 	  "device":"LTEST000000000001",
 	  "time":"20260413100000",
 	  "data":{"METER_SPEED":52.3,"TOTAL_MILEAGE":123456.7}
 	}`))
 	if len(sink.raw) != 1 || len(sink.unified) != 1 {
 		t.Fatalf("raw=%d unified=%d", len(sink.raw), len(sink.unified))
 	}
 	if sink.raw[0].Protocol != envelope.ProtocolYutongMQTT || sink.raw[0].VIN != "LTEST000000000001" {
 		t.Fatalf("unexpected raw envelope: %#v", sink.raw[0])
 	}
 }
 func TestMQTTClientHandleBadPayloadPublishesOnlyRaw(t *testing.T) {
 	sink := &recordingSink{}
 	client, err := NewMQTTClient(MQTTClientConfig{
 		EndpointName: "endpoint-a",
 		Broker:       "tcp://127.0.0.1:1883",
 		ClientID:     "test-client",
 		Topics:       []string{"/ytforward/shln/+"},
 		Sink:         sink,
 		Logger:       slog.New(slog.NewTextHandler(testWriter{t: t}, nil)),
 	})
 	if err != nil {
 		t.Fatalf("NewMQTTClient() error = %v", err)
 	}
 	client.handleMessage(context.Background(), "/ytforward/shln/bad", []byte("{bad-json"))
 	if len(sink.raw) != 1 || len(sink.unified) != 0 {
 		t.Fatalf("raw=%d unified=%d", len(sink.raw), len(sink.unified))
 	}
 	if sink.raw[0].ParseStatus != envelope.ParseBadFrame {
 		t.Fatalf("parse status = %q", sink.raw[0].ParseStatus)
 	}
 }
 func TestMQTTClientBuildOptionsLoadsTLSCertificates(t *testing.T) {
 	dir := t.TempDir()
 	caPath, certPath, keyPath := writeTestTLSMaterial(t, dir)
 	client, err := NewMQTTClient(MQTTClientConfig{
 		EndpointName:            "endpoint-a",
 		Broker:                  "ssl://mqtt.example.test:8883",
 		ClientID:                "test-client",
 		Topics:                  []string{"/ytforward/shln/+"},
 		QoS:                     1,
 		Sink:                    &recordingSink{},
 		Logger:                  slog.New(slog.NewTextHandler(testWriter{t: t}, nil)),
 		TLSCACertPath:           caPath,
 		TLSClientCertPath:       certPath,
 		TLSClientKeyPath:        keyPath,
 		TLSHostnameVerification: false,
 		CleanSession:            true,
 		KeepAlive:               20 * time.Second,
 		ConnectTimeout:          10 * time.Second,
 	})
 	if err != nil {
 		t.Fatalf("NewMQTTClient() error = %v", err)
 	}
 	opts, err := client.buildOptions(context.Background())
 	if err != nil {
 		t.Fatalf("buildOptions() error = %v", err)
 	}
 	if opts.TLSConfig == nil {
 		t.Fatal("TLSConfig is nil")
 	}
 	if opts.TLSConfig.RootCAs == nil {
 		t.Fatal("RootCAs is nil")
 	}
 	if len(opts.TLSConfig.Certificates) != 1 {
 		t.Fatalf("client certificates = %d, want 1", len(opts.TLSConfig.Certificates))
 	}
 	if !opts.TLSConfig.InsecureSkipVerify {
 		t.Fatal("InsecureSkipVerify should be true when hostname verification is disabled")
 	}
 	if !opts.CleanSession {
 		t.Fatal("CleanSession should be true")
 	}
 	if opts.Order {
 		t.Fatal("OrderMatters should be false so MQTT network handling is not blocked by Kafka/DB work")
 	}
 	if !opts.ResumeSubs {
 		t.Fatal("ResumeSubs should be true to avoid subscribe failures during reconnect churn")
 	}
 	if got := opts.KeepAlive; got != 20 {
 		t.Fatalf("KeepAlive = %d, want 20", got)
 	}
 	if got := opts.ConnectTimeout; got != 10*time.Second {
 		t.Fatalf("ConnectTimeout = %v, want 10s", got)
 	}
 }
 func writeTestTLSMaterial(t *testing.T, dir string) (string, string, string) {
 	t.Helper()
 	caKey, err := rsa.GenerateKey(rand.Reader, 2048)
 	if err != nil {
 		t.Fatalf("generate ca key: %v", err)
 	}
 	caTemplate := &x509.Certificate{
 		SerialNumber:          big.NewInt(1),
 		Subject:               pkix.Name{CommonName: "test-ca"},
 		NotBefore:             time.Now().Add(-time.Hour),
 		NotAfter:              time.Now().Add(time.Hour),
 		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageCRLSign,
 		BasicConstraintsValid: true,
 		IsCA:                  true,
 	}
 	caDER, err := x509.CreateCertificate(rand.Reader, caTemplate, caTemplate, &caKey.PublicKey, caKey)
 	if err != nil {
 		t.Fatalf("create ca cert: %v", err)
 	}
 	clientKey, err := rsa.GenerateKey(rand.Reader, 2048)
 	if err != nil {
 		t.Fatalf("generate client key: %v", err)
 	}
 	clientTemplate := &x509.Certificate{
 		SerialNumber: big.NewInt(2),
 		Subject:      pkix.Name{CommonName: "test-client"},
 		NotBefore:    time.Now().Add(-time.Hour),
 		NotAfter:     time.Now().Add(time.Hour),
 		KeyUsage:     x509.KeyUsageDigitalSignature,
 		ExtKeyUsage:  []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth},
 	}
 	clientDER, err := x509.CreateCertificate(rand.Reader, clientTemplate, caTemplate, &clientKey.PublicKey, caKey)
 	if err != nil {
 		t.Fatalf("create client cert: %v", err)
 	}
 	caPath := filepath.Join(dir, "ca.pem")
 	certPath := filepath.Join(dir, "client.pem")
 	keyPath := filepath.Join(dir, "client-key.pem")
 	writePEM(t, caPath, "CERTIFICATE", caDER)
 	writePEM(t, certPath, "CERTIFICATE", clientDER)
 	keyDER := x509.MarshalPKCS1PrivateKey(clientKey)
 	writePEM(t, keyPath, "RSA PRIVATE KEY", keyDER)
 	return caPath, certPath, keyPath
 }
 func writePEM(t *testing.T, path, typ string, der []byte) {
 	t.Helper()
 	file, err := os.Create(path)
 	if err != nil {
 		t.Fatalf("create %s: %v", path, err)
 	}
 	defer file.Close()
 	if err := pem.Encode(file, &pem.Block{Type: typ, Bytes: der}); err != nil {
 		t.Fatalf("write pem %s: %v", path, err)
 	}
 }
--- a/go/vehicle-gateway/internal/gateway/tcp_server.go
+++ b/go/vehicle-gateway/internal/gateway/tcp_server.go
@@ -0,0 +1,238 @@
 package gateway
 import (
 	"context"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"io"
 	"log/slog"
 	"net"
 	"strings"
 	"sync"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/eventbus"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/identity"
 )
 type FrameExtractor func([]byte) (frames [][]byte, remainder []byte, err error)
 type FrameParser func(raw []byte, receivedAtMS int64, sourceEndpoint string) (envelope.FrameEnvelope, error)
 type FrameResponder func(raw []byte, env envelope.FrameEnvelope) (response []byte, ok bool, err error)
 type TCPProtocol struct {
 	Protocol envelope.Protocol
 	Addr     string
 	Extract  FrameExtractor
 	Parse    FrameParser
 	Respond  FrameResponder
 }
 type TCPServer struct {
 	protocol       TCPProtocol
 	sink           eventbus.Sink
 	resolver       identity.Resolver
 	logger         *slog.Logger
 	readBufferSize int
 	idleTimeout    time.Duration
 	maxConnections int
 }
 type TCPServerConfig struct {
 	Protocol       TCPProtocol
 	Sink           eventbus.Sink
 	Resolver       identity.Resolver
 	Logger         *slog.Logger
 	ReadBufferSize int
 	IdleTimeout    time.Duration
 	MaxConnections int
 }
 func NewTCPServer(cfg TCPServerConfig) (*TCPServer, error) {
 	if cfg.Protocol.Protocol == "" {
 		return nil, errors.New("protocol is required")
 	}
 	if strings.TrimSpace(cfg.Protocol.Addr) == "" {
 		return nil, errors.New("listen addr is required")
 	}
 	if cfg.Protocol.Extract == nil {
 		return nil, errors.New("frame extractor is required")
 	}
 	if cfg.Protocol.Parse == nil {
 		return nil, errors.New("frame parser is required")
 	}
 	if cfg.Sink == nil {
 		return nil, errors.New("sink is required")
 	}
 	if cfg.Logger == nil {
 		cfg.Logger = slog.Default()
 	}
 	if cfg.Resolver == nil {
 		cfg.Resolver = identity.NoopResolver{}
 	}
 	if cfg.ReadBufferSize <= 0 {
 		cfg.ReadBufferSize = 32 * 1024
 	}
 	if cfg.IdleTimeout <= 0 {
 		cfg.IdleTimeout = 2 * time.Minute
 	}
 	if cfg.MaxConnections <= 0 {
 		cfg.MaxConnections = 10_000
 	}
 	return &TCPServer{
 		protocol:       cfg.Protocol,
 		sink:           cfg.Sink,
 		resolver:       cfg.Resolver,
 		logger:         cfg.Logger,
 		readBufferSize: cfg.ReadBufferSize,
 		idleTimeout:    cfg.IdleTimeout,
 		maxConnections: cfg.MaxConnections,
 	}, nil
 }
 func (s *TCPServer) ListenAndServe(ctx context.Context) error {
 	var lc net.ListenConfig
 	listener, err := lc.Listen(ctx, "tcp", s.protocol.Addr)
 	if err != nil {
 		return err
 	}
 	defer listener.Close()
 	go func() {
 		<-ctx.Done()
 		_ = listener.Close()
 	}()
 	s.logger.Info("tcp listener started", "protocol", s.protocol.Protocol, "addr", listener.Addr().String())
 	sem := make(chan struct{}, s.maxConnections)
 	var wg sync.WaitGroup
 	defer wg.Wait()
 	for {
 		conn, err := listener.Accept()
 		if err != nil {
 			if ctx.Err() != nil {
 				return nil
 			}
 			s.logger.Warn("tcp accept failed", "protocol", s.protocol.Protocol, "error", err)
 			continue
 		}
 		select {
 		case sem <- struct{}{}:
 			wg.Add(1)
 			go func() {
 				defer wg.Done()
 				defer func() { <-sem }()
 				s.handleConnection(ctx, conn)
 			}()
 		default:
 			s.logger.Warn("tcp connection rejected: max connections reached", "protocol", s.protocol.Protocol, "remote", conn.RemoteAddr().String())
 			_ = conn.Close()
 		}
 	}
 }
 func (s *TCPServer) handleConnection(ctx context.Context, conn net.Conn) {
 	defer conn.Close()
 	source := conn.RemoteAddr().String()
 	log := s.logger.With("protocol", s.protocol.Protocol, "remote", source)
 	log.Info("tcp connection opened")
 	defer log.Info("tcp connection closed")
 	readBuffer := make([]byte, s.readBufferSize)
 	var pending []byte
 	for {
 		_ = conn.SetReadDeadline(time.Now().Add(s.idleTimeout))
 		n, err := conn.Read(readBuffer)
 		if n > 0 {
 			pending = append(pending, readBuffer[:n]...)
 			frames, remainder, extractErr := s.protocol.Extract(pending)
 			if extractErr != nil {
 				log.Warn("frame extraction failed", "error", extractErr)
 				return
 			}
 			pending = remainder
 			for _, frame := range frames {
 				s.handleFrame(ctx, conn, frame, source)
 			}
 		}
 		if err != nil {
 			if errors.Is(err, io.EOF) {
 				return
 			}
 			var netErr net.Error
 			if errors.As(err, &netErr) && netErr.Timeout() {
 				log.Warn("tcp connection idle timeout")
 				return
 			}
 			log.Warn("tcp read failed", "error", err)
 			return
 		}
 		if ctx.Err() != nil {
 			return
 		}
 	}
 }
 func (s *TCPServer) handleFrame(ctx context.Context, conn net.Conn, raw []byte, source string) {
 	receivedAtMS := time.Now().UnixMilli()
 	env, err := s.protocol.Parse(raw, receivedAtMS, source)
 	if err != nil {
 		env = envelope.FrameEnvelope{
 			Protocol:       s.protocol.Protocol,
 			SourceEndpoint: source,
 			ReceivedAtMS:   receivedAtMS,
 			EventTimeMS:    receivedAtMS,
 			RawHex:         strings.ToUpper(hex.EncodeToString(raw)),
 			ParseStatus:    envelope.ParseBadFrame,
 			ParseError:     err.Error(),
 		}
 		env.EventID = env.StableEventID()
 	} else {
 		resolved, resolveErr := s.resolver.Resolve(ctx, env)
 		if resolveErr != nil {
 			s.logger.Warn("identity resolve failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", resolveErr)
 			if env.Parsed == nil {
 				env.Parsed = map[string]any{}
 			}
 			env.Parsed["identity"] = map[string]any{"resolved": false, "error": resolveErr.Error()}
 			env.ParseStatus = envelope.ParsePartial
 		} else {
 			env = resolved
 		}
 	}
 	if err := s.sink.PublishRaw(ctx, env); err != nil {
 		s.logger.Error("publish raw failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", err)
 		return
 	}
 	if env.ParseStatus == envelope.ParseBadFrame {
 		return
 	}
 	if err := s.sink.PublishUnified(ctx, env); err != nil {
 		s.logger.Error("publish unified failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", err)
 		return
 	}
 	if s.protocol.Respond == nil {
 		return
 	}
 	response, ok, err := s.protocol.Respond(raw, env)
 	if err != nil {
 		s.logger.Warn("build protocol response failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", err)
 		return
 	}
 	if !ok || len(response) == 0 {
 		return
 	}
 	_ = conn.SetWriteDeadline(time.Now().Add(5 * time.Second))
 	if _, err := conn.Write(response); err != nil {
 		s.logger.Warn("write protocol response failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", err)
 	}
 }
 func (p TCPProtocol) String() string {
 	return fmt.Sprintf("%s@%s", p.Protocol, p.Addr)
 }
--- a/go/vehicle-gateway/internal/gateway/tcp_server_test.go
+++ b/go/vehicle-gateway/internal/gateway/tcp_server_test.go
@@ -0,0 +1,177 @@
 package gateway
 import (
 	"context"
 	"encoding/hex"
 	"io"
 	"log/slog"
 	"net"
 	"testing"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/gb32960"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/jt808"
 )
 func TestTCPServerPublishesGoodFrameToRawAndUnified(t *testing.T) {
 	frame, err := hex.DecodeString("7E020000320133077954250001000000000048000301D2C4C707376139000A00E6004F26063016235701040001900C2504000000000202000030011F31010F867E")
 	if err != nil {
 		t.Fatal(err)
 	}
 	sink := &recordingSink{}
 	server := newTestServer(t, TCPProtocol{
 		Protocol: envelope.ProtocolJT808,
 		Addr:     ":0",
 		Extract:  jt808.ExtractFrames,
 		Parse:    jt808.ParseFrame,
 	}, sink)
 	client, done := runPipe(t, server)
 	if _, err := client.Write(frame); err != nil {
 		t.Fatalf("client.Write() error = %v", err)
 	}
 	_ = client.Close()
 	<-done
 	if len(sink.raw) != 1 || len(sink.unified) != 1 {
 		t.Fatalf("raw=%d unified=%d", len(sink.raw), len(sink.unified))
 	}
 	if sink.raw[0].Phone != "013307795425" {
 		t.Fatalf("phone = %q", sink.raw[0].Phone)
 	}
 	if sink.raw[0].Fields[envelope.FieldTotalMileageKM] != 10241.2 {
 		t.Fatalf("total mileage = %#v", sink.raw[0].Fields[envelope.FieldTotalMileageKM])
 	}
 }
 func TestTCPServerPublishesBadFrameOnlyToRaw(t *testing.T) {
 	good := buildGBFrame(0x02, 0xfe, "LNBSCB3D4R1234567", nil)
 	good[len(good)-1] ^= 0xff
 	sink := &recordingSink{}
 	server := newTestServer(t, TCPProtocol{
 		Protocol: envelope.ProtocolGB32960,
 		Addr:     ":0",
 		Extract:  gb32960.ExtractFrames,
 		Parse:    gb32960.ParseFrame,
 	}, sink)
 	client, done := runPipe(t, server)
 	if _, err := client.Write(good); err != nil {
 		t.Fatalf("client.Write() error = %v", err)
 	}
 	_ = client.Close()
 	<-done
 	if len(sink.raw) != 1 || len(sink.unified) != 0 {
 		t.Fatalf("raw=%d unified=%d", len(sink.raw), len(sink.unified))
 	}
 	if sink.raw[0].ParseStatus != envelope.ParseBadFrame {
 		t.Fatalf("parse status = %q", sink.raw[0].ParseStatus)
 	}
 	if sink.raw[0].ParseError == "" {
 		t.Fatal("parse error should be recorded")
 	}
 }
 func TestTCPServerWritesProtocolResponseAfterPublish(t *testing.T) {
 	frame := buildGBFrame(0x07, 0xfe, "LNBSCB3D4R1234567", nil)
 	sink := &recordingSink{}
 	server := newTestServer(t, TCPProtocol{
 		Protocol: envelope.ProtocolGB32960,
 		Addr:     ":0",
 		Extract:  gb32960.ExtractFrames,
 		Parse:    gb32960.ParseFrame,
 		Respond: func(_ []byte, env envelope.FrameEnvelope) ([]byte, bool, error) {
 			if len(sink.unified) != 1 || sink.unified[0].EventID != env.EventID {
 				t.Fatalf("response built before publish: raw=%d unified=%d", len(sink.raw), len(sink.unified))
 			}
 			return []byte("ACK"), true, nil
 		},
 	}, sink)
 	client, done := runPipe(t, server)
 	if _, err := client.Write(frame); err != nil {
 		t.Fatalf("client.Write() error = %v", err)
 	}
 	buf := make([]byte, 3)
 	if _, err := io.ReadFull(client, buf); err != nil {
 		t.Fatalf("read response error = %v", err)
 	}
 	if string(buf) != "ACK" {
 		t.Fatalf("response = %q", string(buf))
 	}
 	_ = client.Close()
 	<-done
 }
 func newTestServer(t *testing.T, protocol TCPProtocol, sink *recordingSink) *TCPServer {
 	t.Helper()
 	server, err := NewTCPServer(TCPServerConfig{
 		Protocol:       protocol,
 		Sink:           sink,
 		Logger:         slog.New(slog.NewTextHandler(testWriter{t: t}, nil)),
 		ReadBufferSize: 1024,
 		IdleTimeout:    time.Second,
 		MaxConnections: 1,
 	})
 	if err != nil {
 		t.Fatalf("NewTCPServer() error = %v", err)
 	}
 	return server
 }
 func runPipe(t *testing.T, server *TCPServer) (net.Conn, <-chan struct{}) {
 	t.Helper()
 	client, srv := net.Pipe()
 	done := make(chan struct{})
 	go func() {
 		defer close(done)
 		server.handleConnection(context.Background(), srv)
 	}()
 	return client, done
 }
 type recordingSink struct {
 	raw     []envelope.FrameEnvelope
 	unified []envelope.FrameEnvelope
 }
 func (s *recordingSink) PublishRaw(_ context.Context, env envelope.FrameEnvelope) error {
 	s.raw = append(s.raw, env)
 	return nil
 }
 func (s *recordingSink) PublishUnified(_ context.Context, env envelope.FrameEnvelope) error {
 	s.unified = append(s.unified, env)
 	return nil
 }
 func (s *recordingSink) Close() error {
 	return nil
 }
 type testWriter struct {
 	t *testing.T
 }
 func (w testWriter) Write(p []byte) (int, error) {
 	w.t.Log(string(p))
 	return len(p), nil
 }
 func buildGBFrame(command byte, response byte, vin string, body []byte) []byte {
 	frame := []byte{'#', '#', command, response}
 	vinBytes := []byte(vin)
 	if len(vinBytes) < 17 {
 		vinBytes = append(vinBytes, make([]byte, 17-len(vinBytes))...)
 	}
 	frame = append(frame, vinBytes[:17]...)
 	frame = append(frame, 0x01, byte(len(body)>>8), byte(len(body)))
 	frame = append(frame, body...)
 	var bcc byte
 	for _, value := range frame[2:] {
 		bcc ^= value
 	}
 	return append(frame, bcc)
 }
--- a/go/vehicle-gateway/internal/history/query.go
+++ b/go/vehicle-gateway/internal/history/query.go
@@ -0,0 +1,908 @@
 package history
 import (
 	"context"
 	"database/sql"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
 	"time"
 )
 type Queryer interface {
 	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
 }
 type RawFrameQuery struct {
 	Protocol     string
 	VehicleKey   string
 	VIN          string
 	Phone        string
 	DeviceID     string
 	MessageID    string
 	OrderBy      string
 	IncludeTotal bool
 	DateFrom     string
 	DateTo       string
 	Limit        int
 	Offset       int
 }
 type RawFrameRow struct {
 	TS             string `json:"ts"`
 	FrameID        string `json:"frame_id"`
 	EventID        string `json:"event_id"`
 	MessageID      int64  `json:"message_id"`
 	MessageIDHex   string `json:"message_id_hex"`
 	EventTime      string `json:"event_time"`
 	ReceivedAt     string `json:"received_at"`
 	RawSizeBytes   int64  `json:"raw_size_bytes"`
 	RawHex         string `json:"raw_hex,omitempty"`
 	RawText        string `json:"raw_text,omitempty"`
 	ParsedJSON     string `json:"parsed_json,omitempty"`
 	FieldsJSON     string `json:"fields_json,omitempty"`
 	ParseStatus    string `json:"parse_status"`
 	ParseError     string `json:"parse_error,omitempty"`
 	SourceEndpoint string `json:"source_endpoint"`
 	Protocol       string `json:"protocol"`
 	VehicleKey     string `json:"vehicle_key"`
 	VIN            string `json:"vin"`
 	Phone          string `json:"phone,omitempty"`
 	DeviceID       string `json:"device_id,omitempty"`
 }
 type LocationQuery struct {
 	Protocol   string
 	VehicleKey string
 	VIN        string
 	Phone      string
 	DeviceID   string
 	DateFrom   string
 	DateTo     string
 	Limit      int
 	Offset     int
 }
 type LocationRow struct {
 	TS             string   `json:"ts"`
 	EventID        string   `json:"event_id"`
 	FrameID        string   `json:"frame_id"`
 	ReceivedAt     string   `json:"received_at"`
 	Longitude      float64  `json:"longitude"`
 	Latitude       float64  `json:"latitude"`
 	AltitudeM      *float64 `json:"altitude_m,omitempty"`
 	SpeedKMH       *float64 `json:"speed_kmh,omitempty"`
 	DirectionDeg   *int64   `json:"direction_deg,omitempty"`
 	AlarmFlag      *int64   `json:"alarm_flag,omitempty"`
 	StatusFlag     *int64   `json:"status_flag,omitempty"`
 	TotalMileageKM *float64 `json:"total_mileage_km,omitempty"`
 	Protocol       string   `json:"protocol"`
 	VehicleKey     string   `json:"vehicle_key"`
 	VIN            string   `json:"vin"`
 	Phone          string   `json:"phone,omitempty"`
 	DeviceID       string   `json:"device_id,omitempty"`
 }
 type MileagePointQuery struct {
 	Protocol   string
 	VehicleKey string
 	VIN        string
 	Phone      string
 	DeviceID   string
 	DateFrom   string
 	DateTo     string
 	Limit      int
 	Offset     int
 }
 type MileagePointRow struct {
 	TS             string   `json:"ts"`
 	EventID        string   `json:"event_id"`
 	FrameID        string   `json:"frame_id"`
 	ReceivedAt     string   `json:"received_at"`
 	TotalMileageKM float64  `json:"total_mileage_km"`
 	SpeedKMH       *float64 `json:"speed_kmh,omitempty"`
 	Longitude      *float64 `json:"longitude,omitempty"`
 	Latitude       *float64 `json:"latitude,omitempty"`
 	Protocol       string   `json:"protocol"`
 	VehicleKey     string   `json:"vehicle_key"`
 	VIN            string   `json:"vin"`
 	Phone          string   `json:"phone,omitempty"`
 	DeviceID       string   `json:"device_id,omitempty"`
 }
 type RawFrameRepository struct {
 	db       Queryer
 	database string
 }
 func NewRawFrameRepository(db Queryer, database string) *RawFrameRepository {
 	if db == nil {
 		panic("raw frame query db must not be nil")
 	}
 	database = strings.TrimSpace(database)
 	if database != "" && !safeIdentifier(database) {
 		database = ""
 	}
 	return &RawFrameRepository{db: db, database: database}
 }
 type LocationRepository struct {
 	db       Queryer
 	database string
 }
 type MileagePointRepository struct {
 	db       Queryer
 	database string
 }
 func NewLocationRepository(db Queryer, database string) *LocationRepository {
 	if db == nil {
 		panic("location query db must not be nil")
 	}
 	database = strings.TrimSpace(database)
 	if database != "" && !safeIdentifier(database) {
 		database = ""
 	}
 	return &LocationRepository{db: db, database: database}
 }
 func NewMileagePointRepository(db Queryer, database string) *MileagePointRepository {
 	if db == nil {
 		panic("mileage point query db must not be nil")
 	}
 	database = strings.TrimSpace(database)
 	if database != "" && !safeIdentifier(database) {
 		database = ""
 	}
 	return &MileagePointRepository{db: db, database: database}
 }
 func (r *RawFrameRepository) Query(ctx context.Context, query RawFrameQuery) ([]RawFrameRow, error) {
 	query = normalizeRawFrameQuery(query)
 	sqlText, args := buildRawFrameSQL(r.tableName(), query)
 	rows, err := r.db.QueryContext(ctx, sqlText, args...)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
 	out := make([]RawFrameRow, 0)
 	for rows.Next() {
 		var row RawFrameRow
 		var ts scanDateTime
 		var eventTime scanDateTime
 		var receivedAt scanDateTime
 		if err := rows.Scan(
 			&ts,
 			&row.FrameID,
 			&row.EventID,
 			&row.MessageID,
 			&eventTime,
 			&receivedAt,
 			&row.RawSizeBytes,
 			&row.RawHex,
 			&row.RawText,
 			&row.ParsedJSON,
 			&row.FieldsJSON,
 			&row.ParseStatus,
 			&row.ParseError,
 			&row.SourceEndpoint,
 			&row.Protocol,
 			&row.VehicleKey,
 			&row.VIN,
 			&row.Phone,
 			&row.DeviceID,
 		); err != nil {
 			return nil, err
 		}
 		row.TS = ts.String
 		row.EventTime = eventTime.String
 		row.ReceivedAt = receivedAt.String
 		row.MessageIDHex = fmt.Sprintf("0x%04X", row.MessageID)
 		out = append(out, row)
 	}
 	return out, rows.Err()
 }
 func (r *RawFrameRepository) Count(ctx context.Context, query RawFrameQuery) (int64, error) {
 	query = normalizeRawFrameQuery(query)
 	sqlText, args := buildRawFrameCountSQL(r.tableName(), query)
 	return countRows(ctx, r.db, sqlText, args...)
 }
 func (r *LocationRepository) Query(ctx context.Context, query LocationQuery) ([]LocationRow, error) {
 	query = normalizeLocationQuery(query)
 	sqlText, args := buildLocationSQL(r.tableName(), query)
 	rows, err := r.db.QueryContext(ctx, sqlText, args...)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
 	out := make([]LocationRow, 0)
 	for rows.Next() {
 		var row LocationRow
 		var ts scanDateTime
 		var receivedAt scanDateTime
 		var altitude sql.NullFloat64
 		var speed sql.NullFloat64
 		var direction sql.NullInt64
 		var alarm sql.NullInt64
 		var status sql.NullInt64
 		var mileage sql.NullFloat64
 		if err := rows.Scan(
 			&ts,
 			&row.EventID,
 			&row.FrameID,
 			&receivedAt,
 			&row.Longitude,
 			&row.Latitude,
 			&altitude,
 			&speed,
 			&direction,
 			&alarm,
 			&status,
 			&mileage,
 			&row.Protocol,
 			&row.VehicleKey,
 			&row.VIN,
 			&row.Phone,
 			&row.DeviceID,
 		); err != nil {
 			return nil, err
 		}
 		row.TS = ts.String
 		row.ReceivedAt = receivedAt.String
 		row.AltitudeM = nullableFloat(altitude)
 		row.SpeedKMH = nullableFloat(speed)
 		row.DirectionDeg = nullableInt(direction)
 		row.AlarmFlag = nullableInt(alarm)
 		row.StatusFlag = nullableInt(status)
 		row.TotalMileageKM = nullableFloat(mileage)
 		out = append(out, row)
 	}
 	return out, rows.Err()
 }
 func (r *LocationRepository) Count(ctx context.Context, query LocationQuery) (int64, error) {
 	query = normalizeLocationQuery(query)
 	sqlText, args := buildLocationCountSQL(r.tableName(), query)
 	return countRows(ctx, r.db, sqlText, args...)
 }
 func (r *MileagePointRepository) Query(ctx context.Context, query MileagePointQuery) ([]MileagePointRow, error) {
 	query = normalizeMileagePointQuery(query)
 	sqlText, args := buildMileagePointSQL(r.tableName(), query)
 	rows, err := r.db.QueryContext(ctx, sqlText, args...)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
 	out := make([]MileagePointRow, 0)
 	for rows.Next() {
 		var row MileagePointRow
 		var ts scanDateTime
 		var receivedAt scanDateTime
 		var speed sql.NullFloat64
 		var longitude sql.NullFloat64
 		var latitude sql.NullFloat64
 		if err := rows.Scan(
 			&ts,
 			&row.EventID,
 			&row.FrameID,
 			&receivedAt,
 			&row.TotalMileageKM,
 			&speed,
 			&longitude,
 			&latitude,
 			&row.Protocol,
 			&row.VehicleKey,
 			&row.VIN,
 			&row.Phone,
 			&row.DeviceID,
 		); err != nil {
 			return nil, err
 		}
 		row.TS = ts.String
 		row.ReceivedAt = receivedAt.String
 		row.SpeedKMH = nullableFloat(speed)
 		row.Longitude = nullableFloat(longitude)
 		row.Latitude = nullableFloat(latitude)
 		out = append(out, row)
 	}
 	return out, rows.Err()
 }
 func (r *MileagePointRepository) Count(ctx context.Context, query MileagePointQuery) (int64, error) {
 	query = normalizeMileagePointQuery(query)
 	sqlText, args := buildMileagePointCountSQL(r.tableName(), query)
 	return countRows(ctx, r.db, sqlText, args...)
 }
 func countRows(ctx context.Context, db Queryer, sqlText string, args ...any) (int64, error) {
 	rows, err := db.QueryContext(ctx, sqlText, args...)
 	if err != nil {
 		return 0, err
 	}
 	defer rows.Close()
 	var total int64
 	if rows.Next() {
 		if err := rows.Scan(&total); err != nil {
 			return 0, err
 		}
 	}
 	return total, rows.Err()
 }
 func (r *RawFrameRepository) tableName() string {
 	if r.database == "" {
 		return "raw_frames"
 	}
 	return r.database + ".raw_frames"
 }
 func (r *LocationRepository) tableName() string {
 	if r.database == "" {
 		return "vehicle_locations"
 	}
 	return r.database + ".vehicle_locations"
 }
 func (r *MileagePointRepository) tableName() string {
 	if r.database == "" {
 		return "vehicle_mileage_points"
 	}
 	return r.database + ".vehicle_mileage_points"
 }
 func normalizeRawFrameQuery(query RawFrameQuery) RawFrameQuery {
 	query.Protocol = strings.ToUpper(strings.TrimSpace(query.Protocol))
 	query.VehicleKey = strings.TrimSpace(query.VehicleKey)
 	query.VIN = strings.TrimSpace(query.VIN)
 	query.Phone = strings.TrimSpace(query.Phone)
 	query.DeviceID = strings.TrimSpace(query.DeviceID)
 	query.MessageID = strings.TrimSpace(query.MessageID)
 	query.OrderBy = normalizeRawFrameOrderBy(query.OrderBy)
 	query.DateFrom = normalizeDateTimeLiteral(query.DateFrom)
 	query.DateTo = normalizeDateTimeLiteral(query.DateTo)
 	if query.Limit <= 0 {
 		query.Limit = 20
 	}
 	return query
 }
 func normalizeLocationQuery(query LocationQuery) LocationQuery {
 	query.Protocol = strings.ToUpper(strings.TrimSpace(query.Protocol))
 	query.VehicleKey = strings.TrimSpace(query.VehicleKey)
 	query.VIN = strings.TrimSpace(query.VIN)
 	query.Phone = strings.TrimSpace(query.Phone)
 	query.DeviceID = strings.TrimSpace(query.DeviceID)
 	query.DateFrom = normalizeDateTimeLiteral(query.DateFrom)
 	query.DateTo = normalizeDateTimeLiteral(query.DateTo)
 	if query.Limit <= 0 {
 		query.Limit = 20
 	}
 	return query
 }
 func normalizeMileagePointQuery(query MileagePointQuery) MileagePointQuery {
 	query.Protocol = strings.ToUpper(strings.TrimSpace(query.Protocol))
 	query.VehicleKey = strings.TrimSpace(query.VehicleKey)
 	query.VIN = strings.TrimSpace(query.VIN)
 	query.Phone = strings.TrimSpace(query.Phone)
 	query.DeviceID = strings.TrimSpace(query.DeviceID)
 	query.DateFrom = normalizeDateTimeLiteral(query.DateFrom)
 	query.DateTo = normalizeDateTimeLiteral(query.DateTo)
 	if query.Limit <= 0 {
 		query.Limit = 20
 	}
 	return query
 }
 func buildRawFrameSQL(table string, query RawFrameQuery) (string, []any) {
 	where := rawFrameWhere(query)
 	sqlText := `SELECT ts, frame_id, event_id, message_id, event_time, received_at, raw_size_bytes, raw_hex, raw_text, parsed_json, fields_json, parse_status, parse_error, source_endpoint, protocol, vehicle_key, vin, phone, device_id FROM ` + table
 	if len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	sqlText += " ORDER BY " + rawFrameOrderColumn(query.OrderBy) + " DESC LIMIT " + strconv.Itoa(query.Limit) + " OFFSET " + strconv.Itoa(query.Offset)
 	return sqlText, nil
 }
 func buildRawFrameCountSQL(table string, query RawFrameQuery) (string, []any) {
 	sqlText := `SELECT COUNT(*) FROM ` + table
 	if where := rawFrameWhere(query); len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	return sqlText, nil
 }
 func buildLocationSQL(table string, query LocationQuery) (string, []any) {
 	where := locationWhere(query)
 	sqlText := `SELECT ts, event_id, frame_id, received_at, longitude, latitude, altitude_m, speed_kmh, direction_deg, alarm_flag, status_flag, total_mileage_km, protocol, vehicle_key, vin, phone, device_id FROM ` + table
 	if len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	sqlText += " ORDER BY ts DESC LIMIT " + strconv.Itoa(query.Limit) + " OFFSET " + strconv.Itoa(query.Offset)
 	return sqlText, nil
 }
 func buildLocationCountSQL(table string, query LocationQuery) (string, []any) {
 	sqlText := `SELECT COUNT(*) FROM ` + table
 	if where := locationWhere(query); len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	return sqlText, nil
 }
 func buildMileagePointSQL(table string, query MileagePointQuery) (string, []any) {
 	where := mileagePointWhere(query)
 	sqlText := `SELECT ts, event_id, frame_id, received_at, total_mileage_km, speed_kmh, longitude, latitude, protocol, vehicle_key, vin, phone, device_id FROM ` + table
 	if len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	sqlText += " ORDER BY ts DESC LIMIT " + strconv.Itoa(query.Limit) + " OFFSET " + strconv.Itoa(query.Offset)
 	return sqlText, nil
 }
 func buildMileagePointCountSQL(table string, query MileagePointQuery) (string, []any) {
 	sqlText := `SELECT COUNT(*) FROM ` + table
 	if where := mileagePointWhere(query); len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	return sqlText, nil
 }
 func rawFrameWhere(query RawFrameQuery) []string {
 	var where []string
 	add := func(clause string) {
 		where = append(where, clause)
 	}
 	if query.Protocol != "" {
 		add("protocol = '" + quote(query.Protocol) + "'")
 	}
 	if query.VehicleKey != "" {
 		add("vehicle_key = '" + quote(query.VehicleKey) + "'")
 	}
 	if query.VIN != "" {
 		add("vin = '" + quote(query.VIN) + "'")
 	}
 	if query.Phone != "" {
 		add("phone = '" + quote(query.Phone) + "'")
 	}
 	if query.DeviceID != "" {
 		add("device_id = '" + quote(query.DeviceID) + "'")
 	}
 	if query.MessageID != "" {
 		if parsed, ok := parseMessageID(query.MessageID); ok {
 			add("message_id = " + strconv.FormatInt(parsed, 10))
 		}
 	}
 	if query.DateFrom != "" {
 		add("ts >= '" + quote(normalizeDateTimeLiteral(query.DateFrom)) + "'")
 	}
 	if query.DateTo != "" {
 		add("ts <= '" + quote(normalizeDateTimeLiteral(query.DateTo)) + "'")
 	}
 	return where
 }
 func normalizeRawFrameOrderBy(value string) string {
 	value = strings.ToLower(strings.TrimSpace(value))
 	switch value {
 	case "receivedat", "received_at":
 		return "receivedAt"
 	default:
 		return "ts"
 	}
 }
 func rawFrameOrderColumn(value string) string {
 	if normalizeRawFrameOrderBy(value) == "receivedAt" {
 		return "received_at"
 	}
 	return "ts"
 }
 func locationWhere(query LocationQuery) []string {
 	var where []string
 	add := func(clause string) {
 		where = append(where, clause)
 	}
 	if query.Protocol != "" {
 		add("protocol = '" + quote(query.Protocol) + "'")
 	}
 	if query.VehicleKey != "" {
 		add("vehicle_key = '" + quote(query.VehicleKey) + "'")
 	}
 	if query.VIN != "" {
 		add("vin = '" + quote(query.VIN) + "'")
 	}
 	if query.Phone != "" {
 		add("phone = '" + quote(query.Phone) + "'")
 	}
 	if query.DeviceID != "" {
 		add("device_id = '" + quote(query.DeviceID) + "'")
 	}
 	if query.DateFrom != "" {
 		add("ts >= '" + quote(normalizeDateTimeLiteral(query.DateFrom)) + "'")
 	}
 	if query.DateTo != "" {
 		add("ts <= '" + quote(normalizeDateTimeLiteral(query.DateTo)) + "'")
 	}
 	return where
 }
 func mileagePointWhere(query MileagePointQuery) []string {
 	var where []string
 	add := func(clause string) {
 		where = append(where, clause)
 	}
 	if query.Protocol != "" {
 		add("protocol = '" + quote(query.Protocol) + "'")
 	}
 	if query.VehicleKey != "" {
 		add("vehicle_key = '" + quote(query.VehicleKey) + "'")
 	}
 	if query.VIN != "" {
 		add("vin = '" + quote(query.VIN) + "'")
 	}
 	if query.Phone != "" {
 		add("phone = '" + quote(query.Phone) + "'")
 	}
 	if query.DeviceID != "" {
 		add("device_id = '" + quote(query.DeviceID) + "'")
 	}
 	if query.DateFrom != "" {
 		add("ts >= '" + quote(normalizeDateTimeLiteral(query.DateFrom)) + "'")
 	}
 	if query.DateTo != "" {
 		add("ts <= '" + quote(normalizeDateTimeLiteral(query.DateTo)) + "'")
 	}
 	return where
 }
 type RawFrameHandler struct {
 	repository *RawFrameRepository
 }
 type LocationHandler struct {
 	repository *LocationRepository
 }
 type MileagePointHandler struct {
 	repository *MileagePointRepository
 }
 func NewRawFrameHandler(repository *RawFrameRepository) *RawFrameHandler {
 	if repository == nil {
 		panic("raw frame repository must not be nil")
 	}
 	return &RawFrameHandler{repository: repository}
 }
 func NewLocationHandler(repository *LocationRepository) *LocationHandler {
 	if repository == nil {
 		panic("location repository must not be nil")
 	}
 	return &LocationHandler{repository: repository}
 }
 func NewMileagePointHandler(repository *MileagePointRepository) *MileagePointHandler {
 	if repository == nil {
 		panic("mileage point repository must not be nil")
 	}
 	return &MileagePointHandler{repository: repository}
 }
 func (h *RawFrameHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		writeHistoryError(w, http.StatusMethodNotAllowed, "method not allowed")
 		return
 	}
 	if strings.Trim(r.URL.Path, "/") != "api/history/raw-frames" {
 		writeHistoryError(w, http.StatusNotFound, "route not found")
 		return
 	}
 	query, err := parseRawFrameQuery(r)
 	if err != nil {
 		writeHistoryError(w, http.StatusBadRequest, err.Error())
 		return
 	}
 	var total int64
 	if query.IncludeTotal {
 		total, err = h.repository.Count(r.Context(), query)
 		if err != nil {
 			writeHistoryError(w, http.StatusInternalServerError, err.Error())
 			return
 		}
 	}
 	rows, err := h.repository.Query(r.Context(), query)
 	if err != nil {
 		writeHistoryError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	if !query.IncludeTotal {
 		total = int64(len(rows))
 	}
 	w.Header().Set("Content-Type", "application/json")
 	_ = json.NewEncoder(w).Encode(map[string]any{
 		"items":  rows,
 		"total":  total,
 		"limit":  query.Limit,
 		"offset": query.Offset,
 	})
 }
 func (h *LocationHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		writeHistoryError(w, http.StatusMethodNotAllowed, "method not allowed")
 		return
 	}
 	if strings.Trim(r.URL.Path, "/") != "api/history/locations" {
 		writeHistoryError(w, http.StatusNotFound, "route not found")
 		return
 	}
 	query, err := parseLocationQuery(r)
 	if err != nil {
 		writeHistoryError(w, http.StatusBadRequest, err.Error())
 		return
 	}
 	total, err := h.repository.Count(r.Context(), query)
 	if err != nil {
 		writeHistoryError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	rows, err := h.repository.Query(r.Context(), query)
 	if err != nil {
 		writeHistoryError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	w.Header().Set("Content-Type", "application/json")
 	_ = json.NewEncoder(w).Encode(map[string]any{
 		"items":  rows,
 		"total":  total,
 		"limit":  query.Limit,
 		"offset": query.Offset,
 	})
 }
 func (h *MileagePointHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		writeHistoryError(w, http.StatusMethodNotAllowed, "method not allowed")
 		return
 	}
 	if strings.Trim(r.URL.Path, "/") != "api/history/mileage-points" {
 		writeHistoryError(w, http.StatusNotFound, "route not found")
 		return
 	}
 	query, err := parseMileagePointQuery(r)
 	if err != nil {
 		writeHistoryError(w, http.StatusBadRequest, err.Error())
 		return
 	}
 	total, err := h.repository.Count(r.Context(), query)
 	if err != nil {
 		writeHistoryError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	rows, err := h.repository.Query(r.Context(), query)
 	if err != nil {
 		writeHistoryError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	w.Header().Set("Content-Type", "application/json")
 	_ = json.NewEncoder(w).Encode(map[string]any{
 		"items":  rows,
 		"total":  total,
 		"limit":  query.Limit,
 		"offset": query.Offset,
 	})
 }
 func parseRawFrameQuery(r *http.Request) (RawFrameQuery, error) {
 	values := r.URL.Query()
 	limit, err := parseBoundedInt(values.Get("limit"), 20, 1, 500, "limit")
 	if err != nil {
 		return RawFrameQuery{}, err
 	}
 	offset, err := parseBoundedInt(values.Get("offset"), 0, 0, 1_000_000, "offset")
 	if err != nil {
 		return RawFrameQuery{}, err
 	}
 	query := RawFrameQuery{
 		Protocol:     values.Get("protocol"),
 		VehicleKey:   values.Get("vehicleKey"),
 		VIN:          values.Get("vin"),
 		Phone:        values.Get("phone"),
 		DeviceID:     values.Get("deviceId"),
 		MessageID:    values.Get("messageId"),
 		OrderBy:      values.Get("orderBy"),
 		IncludeTotal: values.Get("includeTotal") != "false",
 		DateFrom:     values.Get("dateFrom"),
 		DateTo:       values.Get("dateTo"),
 		Limit:        limit,
 		Offset:       offset,
 	}
 	if !validDateTime(query.DateFrom) || !validDateTime(query.DateTo) {
 		return RawFrameQuery{}, errors.New("dateFrom/dateTo must use YYYY-MM-DD or YYYY-MM-DD HH:mm:ss")
 	}
 	if strings.TrimSpace(query.MessageID) != "" {
 		if _, ok := parseMessageID(query.MessageID); !ok {
 			return RawFrameQuery{}, errors.New("messageId must be decimal or hex like 0x0200")
 		}
 	}
 	return normalizeRawFrameQuery(query), nil
 }
 func parseMileagePointQuery(r *http.Request) (MileagePointQuery, error) {
 	values := r.URL.Query()
 	limit, err := parseBoundedInt(values.Get("limit"), 20, 1, 500, "limit")
 	if err != nil {
 		return MileagePointQuery{}, err
 	}
 	offset, err := parseBoundedInt(values.Get("offset"), 0, 0, 1_000_000, "offset")
 	if err != nil {
 		return MileagePointQuery{}, err
 	}
 	query := MileagePointQuery{
 		Protocol:   values.Get("protocol"),
 		VehicleKey: values.Get("vehicleKey"),
 		VIN:        values.Get("vin"),
 		Phone:      values.Get("phone"),
 		DeviceID:   values.Get("deviceId"),
 		DateFrom:   values.Get("dateFrom"),
 		DateTo:     values.Get("dateTo"),
 		Limit:      limit,
 		Offset:     offset,
 	}
 	if !validDateTime(query.DateFrom) || !validDateTime(query.DateTo) {
 		return MileagePointQuery{}, errors.New("dateFrom/dateTo must use YYYY-MM-DD or YYYY-MM-DD HH:mm:ss")
 	}
 	return normalizeMileagePointQuery(query), nil
 }
 func parseLocationQuery(r *http.Request) (LocationQuery, error) {
 	values := r.URL.Query()
 	limit, err := parseBoundedInt(values.Get("limit"), 20, 1, 500, "limit")
 	if err != nil {
 		return LocationQuery{}, err
 	}
 	offset, err := parseBoundedInt(values.Get("offset"), 0, 0, 1_000_000, "offset")
 	if err != nil {
 		return LocationQuery{}, err
 	}
 	query := LocationQuery{
 		Protocol:   values.Get("protocol"),
 		VehicleKey: values.Get("vehicleKey"),
 		VIN:        values.Get("vin"),
 		Phone:      values.Get("phone"),
 		DeviceID:   values.Get("deviceId"),
 		DateFrom:   values.Get("dateFrom"),
 		DateTo:     values.Get("dateTo"),
 		Limit:      limit,
 		Offset:     offset,
 	}
 	if !validDateTime(query.DateFrom) || !validDateTime(query.DateTo) {
 		return LocationQuery{}, errors.New("dateFrom/dateTo must use YYYY-MM-DD or YYYY-MM-DD HH:mm:ss")
 	}
 	return normalizeLocationQuery(query), nil
 }
 func parseBoundedInt(raw string, fallback int, min int, max int, name string) (int, error) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
 		return fallback, nil
 	}
 	value, err := strconv.Atoi(raw)
 	if err != nil || value < min || value > max {
 		return 0, fmt.Errorf("%s must be between %d and %d", name, min, max)
 	}
 	return value, nil
 }
 func parseMessageID(value string) (int64, bool) {
 	value = strings.TrimSpace(strings.ToLower(value))
 	if value == "" {
 		return 0, false
 	}
 	if strings.HasPrefix(value, "0x") {
 		parsed, err := strconv.ParseInt(strings.TrimPrefix(value, "0x"), 16, 32)
 		return parsed, err == nil
 	}
 	parsed, err := strconv.ParseInt(value, 10, 32)
 	return parsed, err == nil
 }
 func validDateTime(value string) bool {
 	value = normalizeDateTimeLiteral(value)
 	if value == "" {
 		return true
 	}
 	for _, layout := range []string{"2006-01-02", "2006-01-02 15:04:05", time.RFC3339} {
 		if _, err := time.Parse(layout, value); err == nil {
 			return true
 		}
 	}
 	return false
 }
 func normalizeDateTimeLiteral(value string) string {
 	value = strings.TrimSpace(value)
 	if value == "" {
 		return ""
 	}
 	shanghai := time.FixedZone("Asia/Shanghai", 8*3600)
 	for _, layout := range []string{"2006-01-02T15:04:05", "2006-01-02 15:04:05"} {
 		if parsed, err := time.ParseInLocation(layout, value, shanghai); err == nil {
 			return parsed.UTC().Format("2006-01-02 15:04:05")
 		}
 	}
 	if parsed, err := time.Parse(time.RFC3339, value); err == nil {
 		return parsed.UTC().Format("2006-01-02 15:04:05")
 	}
 	return value
 }
 func safeIdentifier(value string) bool {
 	if value == "" {
 		return false
 	}
 	for _, r := range value {
 		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '_' {
 			continue
 		}
 		return false
 	}
 	return true
 }
 type scanDateTime struct {
 	String string
 }
 func (s *scanDateTime) Scan(value any) error {
 	s.String = formatSQLTime(value, "2006-01-02 15:04:05")
 	return nil
 }
 func formatSQLTime(value any, layout string) string {
 	switch typed := value.(type) {
 	case nil:
 		return ""
 	case time.Time:
 		return typed.Format(layout)
 	case []byte:
 		return strings.TrimSpace(string(typed))
 	case string:
 		return strings.TrimSpace(typed)
 	default:
 		return strings.TrimSpace(fmt.Sprint(typed))
 	}
 }
 func nullableFloat(value sql.NullFloat64) *float64 {
 	if !value.Valid {
 		return nil
 	}
 	return &value.Float64
 }
 func nullableInt(value sql.NullInt64) *int64 {
 	if !value.Valid {
 		return nil
 	}
 	return &value.Int64
 }
 func writeHistoryError(w http.ResponseWriter, status int, message string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
 	_ = json.NewEncoder(w).Encode(map[string]any{"error": message})
 }
--- a/go/vehicle-gateway/internal/history/query_test.go
+++ b/go/vehicle-gateway/internal/history/query_test.go
@@ -0,0 +1,423 @@
 package history
 import (
 	"context"
 	"database/sql"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
 	"github.com/DATA-DOG/go-sqlmock"
 )
 func TestRawFrameRepositoryQueriesRawFramesWithFilters(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT ts, frame_id, event_id, message_id, event_time, received_at, raw_size_bytes, raw_hex, raw_text, parsed_json, fields_json, parse_status, parse_error, source_endpoint, protocol, vehicle_key, vin, phone, device_id FROM lingniu_vehicle_ts.raw_frames").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "frame_id", "event_id", "message_id", "event_time", "received_at", "raw_size_bytes",
 			"raw_hex", "raw_text", "parsed_json", "fields_json", "parse_status", "parse_error", "source_endpoint",
 			"protocol", "vehicle_key", "vin", "phone", "device_id",
 		}).AddRow(
 			time.Date(2026, 7, 1, 23, 25, 36, 0, time.FixedZone("Asia/Shanghai", 8*3600)),
 			"go_frame", "event-1", 0x0200,
 			time.Date(2026, 7, 1, 23, 25, 36, 0, time.FixedZone("Asia/Shanghai", 8*3600)),
 			time.Date(2026, 7, 1, 23, 25, 37, 0, time.FixedZone("Asia/Shanghai", 8*3600)),
 			64, "7E0200", "", `{"header":{"message_id":"0x0200"}}`, `{"speed_kmh":0}`,
 			"OK", "", "222.66.200.68:29646", "JT808", "013079963379", "LKLG7C4E3NA774736", "013079963379", "9963379",
 		))
 	repository := NewRawFrameRepository(db, "lingniu_vehicle_ts")
 	rows, err := repository.Query(context.Background(), RawFrameQuery{
 		Protocol: "JT808",
 		VIN:      "LKLG7C4E3NA774736",
 		DateFrom: "2026-07-01 00:00:00",
 		DateTo:   "2026-07-01 23:59:59",
 		Limit:    20,
 	})
 	if err != nil {
 		t.Fatalf("Query() error = %v", err)
 	}
 	if len(rows) != 1 {
 		t.Fatalf("row count = %d", len(rows))
 	}
 	if rows[0].MessageID != 512 || rows[0].MessageIDHex != "0x0200" || rows[0].ParsedJSON == "" {
 		t.Fatalf("unexpected row: %#v", rows[0])
 	}
 	if rows[0].TS != "2026-07-01 23:25:36" {
 		t.Fatalf("timestamp = %q", rows[0].TS)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestRawFrameHandlerReturnsRawFrames(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM lingniu_vehicle_ts.raw_frames").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(38))
 	mock.ExpectQuery("SELECT ts, frame_id, event_id, message_id, event_time, received_at, raw_size_bytes, raw_hex, raw_text, parsed_json, fields_json, parse_status, parse_error, source_endpoint, protocol, vehicle_key, vin, phone, device_id FROM lingniu_vehicle_ts.raw_frames").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "frame_id", "event_id", "message_id", "event_time", "received_at", "raw_size_bytes",
 			"raw_hex", "raw_text", "parsed_json", "fields_json", "parse_status", "parse_error", "source_endpoint",
 			"protocol", "vehicle_key", "vin", "phone", "device_id",
 		}).AddRow(
 			"2026-07-01 22:28:25", "go_frame", "event-2", 2, "2026-07-01 22:28:25", "2026-07-01 22:28:25",
 			128, "2323", "", `{"command":"REALTIME"}`, `{"total_mileage_km":53490.9}`,
 			"OK", "", "8.134.95.166:53702", "GB32960", "LB9A32A21R0LS1707", "LB9A32A21R0LS1707", "", "",
 		))
 	handler := NewRawFrameHandler(NewRawFrameRepository(db, "lingniu_vehicle_ts"))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?protocol=GB32960&vin=LB9A32A21R0LS1707&limit=5", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"vin":"LB9A32A21R0LS1707"`, `"message_id_hex":"0x0002"`, `"total":38`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestRawFrameHandlerFiltersByVehicleKey(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM lingniu_vehicle_ts.raw_frames").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(11))
 	mock.ExpectQuery("vehicle_key = 'JT808:013307811350'").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "frame_id", "event_id", "message_id", "event_time", "received_at", "raw_size_bytes",
 			"raw_hex", "raw_text", "parsed_json", "fields_json", "parse_status", "parse_error", "source_endpoint",
 			"protocol", "vehicle_key", "vin", "phone", "device_id",
 		}).AddRow(
 			"2026-07-02 00:18:22", "go_frame", "event-3", 0x0200, "2026-07-02 00:18:22", "2026-07-02 00:22:43",
 			63, "7E0200", "", `{"header":{"message_id":"0x0200"}}`, `{"total_mileage_km":8792.8}`,
 			"OK", "", "115.231.168.135:22170", "JT808", "JT808:013307811350", "", "013307811350", "",
 		))
 	handler := NewRawFrameHandler(NewRawFrameRepository(db, "lingniu_vehicle_ts"))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?vehicleKey=JT808:013307811350&protocol=JT808&limit=1", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"vehicle_key":"JT808:013307811350"`, `"phone":"013307811350"`, `"total":11`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestRawFrameHandlerCanSkipTotalCountForFreshnessProbe(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("ORDER BY received_at DESC LIMIT 1 OFFSET 0").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "frame_id", "event_id", "message_id", "event_time", "received_at", "raw_size_bytes",
 			"raw_hex", "raw_text", "parsed_json", "fields_json", "parse_status", "parse_error", "source_endpoint",
 			"protocol", "vehicle_key", "vin", "phone", "device_id",
 		}).AddRow(
 			"2026-07-02 01:26:48", "go_frame", "event-4", 0x0200, "2026-07-02 01:20:46", "2026-07-02 01:26:48",
 			63, "7E0200", "", `{"header":{"message_id":"0x0200"}}`, `{"speed_kmh":0}`,
 			"OK", "", "115.231.168.135:22170", "JT808", "JT808:013307811254", "", "013307811254", "",
 		))
 	handler := NewRawFrameHandler(NewRawFrameRepository(db, "lingniu_vehicle_ts"))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?protocol=JT808&orderBy=receivedAt&includeTotal=false&limit=1", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"total":1`, `"received_at":"2026-07-02 01:26:48"`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestRawFrameHandlerReturnsEmptyItemsArrayWhenNoRows(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM lingniu_vehicle_ts.raw_frames").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(0))
 	mock.ExpectQuery("SELECT ts, frame_id, event_id, message_id, event_time, received_at, raw_size_bytes, raw_hex, raw_text, parsed_json, fields_json, parse_status, parse_error, source_endpoint, protocol, vehicle_key, vin, phone, device_id FROM lingniu_vehicle_ts.raw_frames").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "frame_id", "event_id", "message_id", "event_time", "received_at", "raw_size_bytes",
 			"raw_hex", "raw_text", "parsed_json", "fields_json", "parse_status", "parse_error", "source_endpoint",
 			"protocol", "vehicle_key", "vin", "phone", "device_id",
 		}))
 	handler := NewRawFrameHandler(NewRawFrameRepository(db, "lingniu_vehicle_ts"))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?protocol=NOT_EXISTS&limit=1", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	if !strings.Contains(body, `"items":[]`) || strings.Contains(body, `"items":null`) {
 		t.Fatalf("expected empty items array, got: %s", body)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestLocationHandlerReturnsLocationsByVehicleKey(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM lingniu_vehicle_ts.vehicle_locations").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(17))
 	mock.ExpectQuery("vehicle_key = 'JT808:013307811350'").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "event_id", "frame_id", "received_at", "longitude", "latitude", "altitude_m", "speed_kmh",
 			"direction_deg", "alarm_flag", "status_flag", "total_mileage_km", "protocol", "vehicle_key", "vin", "phone", "device_id",
 		}).AddRow(
 			"2026-07-02 00:18:22", "event-3", "go_frame", "2026-07-02 00:22:43",
 			121.07764, 30.585928, 11.0, 8.0, 171, 0, 4718595, 8792.8,
 			"JT808", "JT808:013307811350", "", "013307811350", "",
 		))
 	handler := NewLocationHandler(NewLocationRepository(db, "lingniu_vehicle_ts"))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/locations?vehicleKey=JT808:013307811350&protocol=JT808&limit=1", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"vehicle_key":"JT808:013307811350"`, `"longitude":121.07764`, `"total_mileage_km":8792.8`, `"total":17`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMileagePointHandlerReturnsMileageByVehicleKey(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM lingniu_vehicle_ts.vehicle_mileage_points").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(19))
 	mock.ExpectQuery("vehicle_key = 'JT808:013307811350'").
 		WillReturnRows(sqlmock.NewRows([]string{
 			"ts", "event_id", "frame_id", "received_at", "total_mileage_km", "speed_kmh", "longitude", "latitude",
 			"protocol", "vehicle_key", "vin", "phone", "device_id",
 		}).AddRow(
 			"2026-07-02 00:18:22", "event-3", "go_frame", "2026-07-02 00:22:43",
 			8792.8, 8.0, 121.07764, 30.585928,
 			"JT808", "JT808:013307811350", "", "013307811350", "",
 		))
 	handler := NewMileagePointHandler(NewMileagePointRepository(db, "lingniu_vehicle_ts"))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/mileage-points?vehicleKey=JT808:013307811350&protocol=JT808&limit=1", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"vehicle_key":"JT808:013307811350"`, `"total_mileage_km":8792.8`, `"speed_kmh":8`, `"total":19`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestRawFrameHandlerRejectsInvalidLimit(t *testing.T) {
 	handler := NewRawFrameHandler(NewRawFrameRepository(&sql.DB{}, ""))
 	request := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?limit=501", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusBadRequest {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 }
 func TestParseRawFrameQueryAcceptsDatetimeLocalValues(t *testing.T) {
 	request := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?dateFrom=2026-07-01T00:00:00&dateTo=2026-07-02T00:00:00", nil)
 	query, err := parseRawFrameQuery(request)
 	if err != nil {
 		t.Fatalf("parseRawFrameQuery() error = %v", err)
 	}
 	if query.DateFrom != "2026-06-30 16:00:00" || query.DateTo != "2026-07-01 16:00:00" {
 		t.Fatalf("date range = %q -> %q", query.DateFrom, query.DateTo)
 	}
 }
 func TestNormalizeDateTimeLiteralConvertsInputToTDengineUTCTime(t *testing.T) {
 	for raw, want := range map[string]string{
 		"2026-07-01T00:00:00":       "2026-06-30 16:00:00",
 		"2026-07-01 00:00:00":       "2026-06-30 16:00:00",
 		"2026-07-01T00:00:00+08:00": "2026-06-30 16:00:00",
 		"2026-06-30T16:00:00Z":      "2026-06-30 16:00:00",
 	} {
 		if got := normalizeDateTimeLiteral(raw); got != want {
 			t.Fatalf("normalizeDateTimeLiteral(%q) = %q, want %q", raw, got, want)
 		}
 	}
 }
 func TestParseMessageIDSupportsDecimalAndHex(t *testing.T) {
 	for raw, want := range map[string]int64{
 		"512":    512,
 		"0x0200": 512,
 		"0X0100": 256,
 	} {
 		got, ok := parseMessageID(raw)
 		if !ok || got != want {
 			t.Fatalf("parseMessageID(%q) = %d,%v want %d,true", raw, got, ok, want)
 		}
 	}
 }
 func TestBuildMileagePointSQLUsesLiteralsForTDengine(t *testing.T) {
 	sqlText, args := buildMileagePointSQL("lingniu_vehicle_ts.vehicle_mileage_points", MileagePointQuery{
 		Protocol:   "JT808",
 		VehicleKey: "JT808:013307811350",
 		DateFrom:   "2026-07-02 00:00:00",
 		DateTo:     "2026-07-02 23:59:59",
 		Limit:      20,
 		Offset:     5,
 	})
 	if len(args) != 0 {
 		t.Fatalf("expected no query args for TDengine, got %#v", args)
 	}
 	for _, want := range []string{
 		"protocol = 'JT808'",
 		"vehicle_key = 'JT808:013307811350'",
 		"ts >= '2026-07-01 16:00:00'",
 		"LIMIT 20 OFFSET 5",
 	} {
 		if !strings.Contains(sqlText, want) {
 			t.Fatalf("sql missing %s: %s", want, sqlText)
 		}
 	}
 }
 func TestBuildLocationSQLUsesLiteralsForTDengine(t *testing.T) {
 	sqlText, args := buildLocationSQL("lingniu_vehicle_ts.vehicle_locations", LocationQuery{
 		Protocol:   "JT808",
 		VehicleKey: "JT808:013307811350",
 		DateFrom:   "2026-07-02 00:00:00",
 		DateTo:     "2026-07-02 23:59:59",
 		Limit:      20,
 		Offset:     5,
 	})
 	if len(args) != 0 {
 		t.Fatalf("expected no query args for TDengine, got %#v", args)
 	}
 	for _, want := range []string{
 		"protocol = 'JT808'",
 		"vehicle_key = 'JT808:013307811350'",
 		"ts >= '2026-07-01 16:00:00'",
 		"LIMIT 20 OFFSET 5",
 	} {
 		if !strings.Contains(sqlText, want) {
 			t.Fatalf("sql missing %s: %s", want, sqlText)
 		}
 	}
 }
 func TestBuildRawFrameSQLUsesLiteralsForTDengine(t *testing.T) {
 	sqlText, args := buildRawFrameSQL("lingniu_vehicle_ts.raw_frames", RawFrameQuery{
 		Protocol:   "JT808",
 		VehicleKey: "JT808:013307811350",
 		VIN:        "VIN'1",
 		MessageID:  "0x0200",
 		DateFrom:   "2026-07-01T00:00:00",
 		DateTo:     "2026-07-01T23:59:59",
 		Limit:      20,
 		Offset:     5,
 	})
 	if len(args) != 0 {
 		t.Fatalf("expected no query args for TDengine, got %#v", args)
 	}
 	for _, want := range []string{
 		"protocol = 'JT808'",
 		"vehicle_key = 'JT808:013307811350'",
 		"vin = 'VIN''1'",
 		"message_id = 512",
 		"ts >= '2026-06-30 16:00:00'",
 		"ts <= '2026-07-01 15:59:59'",
 		"LIMIT 20 OFFSET 5",
 	} {
 		if !strings.Contains(sqlText, want) {
 			t.Fatalf("sql missing %s: %s", want, sqlText)
 		}
 	}
 }
 func TestBuildRawFrameSQLCanOrderByReceivedAt(t *testing.T) {
 	sqlText, args := buildRawFrameSQL("lingniu_vehicle_ts.raw_frames", RawFrameQuery{
 		Protocol: "JT808",
 		OrderBy:  "receivedAt",
 		Limit:    1,
 	})
 	if len(args) != 0 {
 		t.Fatalf("expected no query args for TDengine, got %#v", args)
 	}
 	if !strings.Contains(sqlText, "ORDER BY received_at DESC LIMIT 1 OFFSET 0") {
 		t.Fatalf("sql should order by received_at: %s", sqlText)
 	}
 }
--- a/go/vehicle-gateway/internal/history/schema.go
+++ b/go/vehicle-gateway/internal/history/schema.go
@@ -0,0 +1,71 @@
 package history
 const DefaultDatabase = "lingniu_vehicle_ts"
 func SchemaStatements(database string) []string {
 	if database == "" {
 		database = DefaultDatabase
 	}
 	return []string{
 		"CREATE DATABASE IF NOT EXISTS " + database + " KEEP 7300 DURATION 10 BUFFER 256",
 		"USE " + database,
 		`CREATE STABLE IF NOT EXISTS raw_frames (
  ts TIMESTAMP,
  frame_id NCHAR(64),
  event_id NCHAR(64),
  message_id INT,
  event_time TIMESTAMP,
  received_at TIMESTAMP,
  raw_size_bytes INT,
  raw_hex BINARY(16374),
  raw_text BINARY(16374),
  parsed_json BINARY(16374),
  fields_json BINARY(4096),
  parse_status NCHAR(16),
  parse_error BINARY(1024),
  source_endpoint NCHAR(128)
 ) TAGS (
  protocol NCHAR(32),
  vehicle_key NCHAR(64),
  vin NCHAR(32),
  phone NCHAR(32),
  device_id NCHAR(64)
 )`,
 		`CREATE STABLE IF NOT EXISTS vehicle_locations (
  ts TIMESTAMP,
  event_id NCHAR(64),
  frame_id NCHAR(64),
  received_at TIMESTAMP,
  longitude DOUBLE,
  latitude DOUBLE,
  altitude_m DOUBLE,
  speed_kmh DOUBLE,
  direction_deg INT,
  alarm_flag BIGINT,
  status_flag BIGINT,
  total_mileage_km DOUBLE
 ) TAGS (
  protocol NCHAR(32),
  vehicle_key NCHAR(64),
  vin NCHAR(32),
  phone NCHAR(32),
  device_id NCHAR(64)
 )`,
 		`CREATE STABLE IF NOT EXISTS vehicle_mileage_points (
  ts TIMESTAMP,
  event_id NCHAR(64),
  frame_id NCHAR(64),
  received_at TIMESTAMP,
  total_mileage_km DOUBLE,
  speed_kmh DOUBLE,
  longitude DOUBLE,
  latitude DOUBLE
 ) TAGS (
  protocol NCHAR(32),
  vehicle_key NCHAR(64),
  vin NCHAR(32),
  phone NCHAR(32),
  device_id NCHAR(64)
 )`,
 	}
 }
--- a/go/vehicle-gateway/internal/history/writer.go
+++ b/go/vehicle-gateway/internal/history/writer.go
@@ -0,0 +1,339 @@
 package history
 import (
 	"context"
 	"crypto/sha1"
 	"database/sql"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"strconv"
 	"strings"
 	"sync"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Execer interface {
 	ExecContext(context.Context, string, ...any) (sql.Result, error)
 }
 type Writer struct {
 	exec  Execer
 	cache tableCache
 }
 type tableCache struct {
 	mu   sync.Mutex
 	seen map[string]struct{}
 }
 func NewWriter(exec Execer) *Writer {
 	if exec == nil {
 		panic("history execer must not be nil")
 	}
 	return &Writer{exec: exec, cache: tableCache{seen: map[string]struct{}{}}}
 }
 func (w *Writer) EnsureSchema(ctx context.Context, database string) error {
 	for _, statement := range SchemaStatements(database) {
 		if _, err := w.exec.ExecContext(ctx, statement); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 func (w *Writer) AppendAll(ctx context.Context, env envelope.FrameEnvelope) error {
 	if err := w.AppendRawFrame(ctx, env); err != nil {
 		return err
 	}
 	if err := w.AppendLocation(ctx, env); err != nil {
 		return err
 	}
 	return w.AppendMileagePoint(ctx, env)
 }
 func (w *Writer) AppendRawFrame(ctx context.Context, env envelope.FrameEnvelope) error {
 	table := tableName("raw", env)
 	if err := w.ensureChild(ctx, table, "raw_frames", env); err != nil {
 		return err
 	}
 	_, err := w.exec.ExecContext(ctx, fmt.Sprintf(`INSERT INTO %s
  (ts, frame_id, event_id, message_id, event_time, received_at, raw_size_bytes,
   raw_hex, raw_text, parsed_json, fields_json, parse_status, parse_error, source_endpoint)
 VALUES (%s)`, table, joinLiterals(rawValues(env))))
 	return err
 }
 func (w *Writer) AppendLocation(ctx context.Context, env envelope.FrameEnvelope) error {
 	longitude, okLon := floatField(env, envelope.FieldLongitude)
 	latitude, okLat := floatField(env, envelope.FieldLatitude)
 	if !okLon || !okLat {
 		return nil
 	}
 	table := tableName("loc", env)
 	if err := w.ensureChild(ctx, table, "vehicle_locations", env); err != nil {
 		return err
 	}
 	_, err := w.exec.ExecContext(ctx, fmt.Sprintf(`INSERT INTO %s
  (ts, event_id, frame_id, received_at, longitude, latitude, altitude_m, speed_kmh,
   direction_deg, alarm_flag, status_flag, total_mileage_km)
 VALUES (%s)`, table, joinLiterals(locationValues(env, longitude, latitude))))
 	return err
 }
 func (w *Writer) AppendMileagePoint(ctx context.Context, env envelope.FrameEnvelope) error {
 	totalMileage, ok := floatField(env, envelope.FieldTotalMileageKM)
 	if !ok {
 		return nil
 	}
 	table := tableName("mil", env)
 	if err := w.ensureChild(ctx, table, "vehicle_mileage_points", env); err != nil {
 		return err
 	}
 	_, err := w.exec.ExecContext(ctx, fmt.Sprintf(`INSERT INTO %s
  (ts, event_id, frame_id, received_at, total_mileage_km, speed_kmh, longitude, latitude)
 VALUES (%s)`, table, joinLiterals(mileageValues(env, totalMileage))))
 	return err
 }
 func (w *Writer) ensureChild(ctx context.Context, table string, stable string, env envelope.FrameEnvelope) error {
 	key := stable + "." + table
 	w.cache.mu.Lock()
 	_, ok := w.cache.seen[key]
 	w.cache.mu.Unlock()
 	if ok {
 		return nil
 	}
 	statement := fmt.Sprintf("CREATE TABLE IF NOT EXISTS %s USING %s TAGS ('%s', '%s', '%s', '%s', '%s')",
 		table, stable,
 		quote(string(env.Protocol)),
 		quote(env.VehicleKey()),
 		quote(env.VIN),
 		quote(env.Phone),
 		quote(env.DeviceID))
 	if _, err := w.exec.ExecContext(ctx, statement); err != nil {
 		return err
 	}
 	w.cache.mu.Lock()
 	w.cache.seen[key] = struct{}{}
 	w.cache.mu.Unlock()
 	return nil
 }
 func rawValues(env envelope.FrameEnvelope) []any {
 	received := millis(env.ReceivedAtMS)
 	eventTime := millis(env.EventTimeMS)
 	return []any{
 		received,
 		frameID(env),
 		env.StableEventID(),
 		messageIDInt(env.MessageID),
 		eventTime,
 		received,
 		rawSizeBytes(env),
 		env.RawHex,
 		env.RawText,
 		jsonString(env.Parsed),
 		jsonString(env.Fields),
 		string(env.ParseStatus),
 		env.ParseError,
 		env.SourceEndpoint,
 	}
 }
 func locationValues(env envelope.FrameEnvelope, longitude float64, latitude float64) []any {
 	received := millis(env.ReceivedAtMS)
 	return []any{
 		eventTimeOrReceived(env),
 		env.StableEventID(),
 		frameID(env),
 		received,
 		longitude,
 		latitude,
 		floatFieldOrNil(env, "altitude_m"),
 		floatFieldOrNil(env, envelope.FieldSpeedKMH),
 		intFieldOrNil(env, "direction_deg"),
 		intFieldOrNil(env, "alarm_flag"),
 		intFieldOrNil(env, "status_flag"),
 		floatFieldOrNil(env, envelope.FieldTotalMileageKM),
 	}
 }
 func mileageValues(env envelope.FrameEnvelope, totalMileage float64) []any {
 	received := millis(env.ReceivedAtMS)
 	return []any{
 		eventTimeOrReceived(env),
 		env.StableEventID(),
 		frameID(env),
 		received,
 		totalMileage,
 		floatFieldOrNil(env, envelope.FieldSpeedKMH),
 		floatFieldOrNil(env, envelope.FieldLongitude),
 		floatFieldOrNil(env, envelope.FieldLatitude),
 	}
 }
 func frameID(env envelope.FrameEnvelope) string {
 	return "go_" + env.StableEventID()
 }
 func tableName(prefix string, env envelope.FrameEnvelope) string {
 	return prefix + "_" + strings.ToLower(string(env.Protocol)) + "_" + hash16(env.VehicleKey())
 }
 func hash16(value string) string {
 	sum := sha1.Sum([]byte(value))
 	return hex.EncodeToString(sum[:8])
 }
 func messageIDInt(value string) int64 {
 	value = strings.TrimSpace(strings.ToLower(value))
 	value = strings.TrimPrefix(value, "0x")
 	parsed, err := strconv.ParseInt(value, 16, 32)
 	if err == nil {
 		return parsed
 	}
 	parsed, _ = strconv.ParseInt(value, 10, 32)
 	return parsed
 }
 func rawSizeBytes(env envelope.FrameEnvelope) int {
 	rawHex := strings.TrimSpace(env.RawHex)
 	if len(rawHex)%2 != 0 {
 		return len(rawHex) / 2
 	}
 	if rawHex != "" {
 		return len(rawHex) / 2
 	}
 	return len([]byte(env.RawText))
 }
 func jsonString(value any) string {
 	data, err := json.Marshal(value)
 	if err != nil {
 		return "{}"
 	}
 	return string(data)
 }
 func floatField(env envelope.FrameEnvelope, key string) (float64, bool) {
 	if env.Fields == nil {
 		return 0, false
 	}
 	value, ok := env.Fields[key]
 	if !ok || value == nil {
 		return 0, false
 	}
 	switch typed := value.(type) {
 	case float64:
 		return typed, true
 	case float32:
 		return float64(typed), true
 	case int:
 		return float64(typed), true
 	case int64:
 		return float64(typed), true
 	case uint16:
 		return float64(typed), true
 	case uint32:
 		return float64(typed), true
 	case string:
 		parsed, err := strconv.ParseFloat(strings.TrimSpace(typed), 64)
 		return parsed, err == nil
 	default:
 		return 0, false
 	}
 }
 func floatFieldOrNil(env envelope.FrameEnvelope, key string) any {
 	value, ok := floatField(env, key)
 	if !ok {
 		return nil
 	}
 	return value
 }
 func intFieldOrNil(env envelope.FrameEnvelope, key string) any {
 	if env.Fields == nil {
 		return nil
 	}
 	value, ok := env.Fields[key]
 	if !ok || value == nil {
 		return nil
 	}
 	switch typed := value.(type) {
 	case int:
 		return typed
 	case int64:
 		return typed
 	case uint16:
 		return int64(typed)
 	case uint32:
 		return int64(typed)
 	case float64:
 		return int64(typed)
 	case string:
 		parsed, err := strconv.ParseInt(strings.TrimSpace(typed), 10, 64)
 		if err == nil {
 			return parsed
 		}
 	}
 	return nil
 }
 func eventTimeOrReceived(env envelope.FrameEnvelope) time.Time {
 	if env.EventTimeMS > 0 {
 		return millis(env.EventTimeMS)
 	}
 	return millis(env.ReceivedAtMS)
 }
 func millis(value int64) time.Time {
 	if value <= 0 {
 		return time.UnixMilli(time.Now().UnixMilli()).UTC()
 	}
 	return time.UnixMilli(value).UTC()
 }
 func quote(value string) string {
 	return strings.ReplaceAll(value, "'", "''")
 }
 func joinLiterals(values []any) string {
 	out := make([]string, 0, len(values))
 	for _, value := range values {
 		out = append(out, literal(value))
 	}
 	return strings.Join(out, ", ")
 }
 func literal(value any) string {
 	if value == nil {
 		return "NULL"
 	}
 	switch typed := value.(type) {
 	case time.Time:
 		return "'" + typed.UTC().Format("2006-01-02 15:04:05.000") + "'"
 	case string:
 		return "'" + quote(typed) + "'"
 	case envelope.ParseStatus:
 		return "'" + quote(string(typed)) + "'"
 	case int:
 		return strconv.FormatInt(int64(typed), 10)
 	case int64:
 		return strconv.FormatInt(typed, 10)
 	case uint16:
 		return strconv.FormatUint(uint64(typed), 10)
 	case uint32:
 		return strconv.FormatUint(uint64(typed), 10)
 	case float64:
 		return strconv.FormatFloat(typed, 'f', -1, 64)
 	case float32:
 		return strconv.FormatFloat(float64(typed), 'f', -1, 64)
 	default:
 		return "'" + quote(fmt.Sprint(typed)) + "'"
 	}
 }
--- a/go/vehicle-gateway/internal/history/writer_test.go
+++ b/go/vehicle-gateway/internal/history/writer_test.go
@@ -0,0 +1,146 @@
 package history
 import (
 	"context"
 	"database/sql"
 	"strings"
 	"testing"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestSchemaStatementsCreateCoreStables(t *testing.T) {
 	statements := strings.Join(SchemaStatements("test_ts"), "\n")
 	for _, want := range []string{"CREATE DATABASE IF NOT EXISTS test_ts", "raw_frames", "vehicle_locations", "vehicle_mileage_points"} {
 		if !strings.Contains(statements, want) {
 			t.Fatalf("schema missing %q:\n%s", want, statements)
 		}
 	}
 }
 func TestWriterAppendsRawLocationAndMileage(t *testing.T) {
 	exec := &recordingExec{}
 	writer := NewWriter(exec)
 	env := sampleEnvelope()
 	if err := writer.AppendAll(context.Background(), env); err != nil {
 		t.Fatalf("AppendAll() error = %v", err)
 	}
 	if got := countSQL(exec.calls, "USING raw_frames"); got != 1 {
 		t.Fatalf("raw child create count = %d", got)
 	}
 	if got := countSQL(exec.calls, "USING vehicle_locations"); got != 1 {
 		t.Fatalf("location child create count = %d", got)
 	}
 	if got := countSQL(exec.calls, "USING vehicle_mileage_points"); got != 1 {
 		t.Fatalf("mileage child create count = %d", got)
 	}
 	if got := countSQL(exec.calls, "INSERT INTO raw_"); got != 1 {
 		t.Fatalf("raw insert count = %d", got)
 	}
 	if got := countSQL(exec.calls, "INSERT INTO loc_"); got != 1 {
 		t.Fatalf("location insert count = %d", got)
 	}
 	if got := countSQL(exec.calls, "INSERT INTO mil_"); got != 1 {
 		t.Fatalf("mileage insert count = %d", got)
 	}
 	rawInsert := findSQL(exec.calls, "INSERT INTO raw_")
 	if !strings.Contains(rawInsert, "'go_") || !strings.Contains(rawInsert, "'2e") && !strings.Contains(rawInsert, "'") {
 		t.Fatalf("raw insert should quote string literals: %s", rawInsert)
 	}
 	if strings.Contains(rawInsert, "VALUES (?,") {
 		t.Fatalf("raw insert should not use placeholders for tdengine websocket plain insert: %s", rawInsert)
 	}
 }
 func TestWriterSkipsSparseDerivedRows(t *testing.T) {
 	exec := &recordingExec{}
 	writer := NewWriter(exec)
 	env := sampleEnvelope()
 	env.Fields = map[string]any{}
 	if err := writer.AppendAll(context.Background(), env); err != nil {
 		t.Fatalf("AppendAll() error = %v", err)
 	}
 	if got := countSQL(exec.calls, "INSERT INTO raw_"); got != 1 {
 		t.Fatalf("raw insert count = %d", got)
 	}
 	if got := countSQL(exec.calls, "INSERT INTO loc_"); got != 0 {
 		t.Fatalf("location insert count = %d", got)
 	}
 	if got := countSQL(exec.calls, "INSERT INTO mil_"); got != 0 {
 		t.Fatalf("mileage insert count = %d", got)
 	}
 }
 func TestRawSizeBytesUsesRawTextWhenHexIsEmpty(t *testing.T) {
 	env := envelope.FrameEnvelope{RawText: `{"code":"0F80","data":{"speed":12}}`}
 	if got, want := rawSizeBytes(env), len([]byte(env.RawText)); got != want {
 		t.Fatalf("raw text size = %d, want %d", got, want)
 	}
 	env.RawHex = "7E0200"
 	if got, want := rawSizeBytes(env), 3; got != want {
 		t.Fatalf("raw hex size = %d, want %d", got, want)
 	}
 }
 func sampleEnvelope() envelope.FrameEnvelope {
 	return envelope.FrameEnvelope{
 		Protocol:       envelope.ProtocolJT808,
 		MessageID:      "0x0200",
 		Sequence:       1,
 		VIN:            "LNBVIN00000000001",
 		Phone:          "013307795425",
 		SourceEndpoint: "127.0.0.1:18080",
 		EventTimeMS:    1782745114000,
 		ReceivedAtMS:   1782745114999,
 		RawHex:         "7E0200",
 		Parsed:         map[string]any{"message": "location"},
 		Fields: map[string]any{
 			envelope.FieldLongitude:      121.069881,
 			envelope.FieldLatitude:       30.590151,
 			envelope.FieldSpeedKMH:       23.0,
 			envelope.FieldTotalMileageKM: 10241.2,
 			"direction_deg":              uint16(79),
 			"alarm_flag":                 uint32(0),
 			"status_flag":                uint32(72),
 		},
 		ParseStatus: envelope.ParseOK,
 	}
 }
 func countSQL(calls []execCall, pattern string) int {
 	var count int
 	for _, call := range calls {
 		if strings.Contains(call.query, pattern) {
 			count++
 		}
 	}
 	return count
 }
 func findSQL(calls []execCall, pattern string) string {
 	for _, call := range calls {
 		if strings.Contains(call.query, pattern) {
 			return call.query
 		}
 	}
 	return ""
 }
 type execCall struct {
 	query string
 	args  []any
 }
 type recordingExec struct {
 	calls []execCall
 }
 func (e *recordingExec) ExecContext(_ context.Context, query string, args ...any) (sql.Result, error) {
 	e.calls = append(e.calls, execCall{query: query, args: args})
 	return nil, nil
 }
--- a/go/vehicle-gateway/internal/identity/resolver.go
+++ b/go/vehicle-gateway/internal/identity/resolver.go
@@ -0,0 +1,237 @@
 package identity
 import (
 	"context"
 	"database/sql"
 	"errors"
 	"fmt"
 	"strings"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Resolver interface {
 	Resolve(context.Context, envelope.FrameEnvelope) (envelope.FrameEnvelope, error)
 }
 type NoopResolver struct{}
 func (NoopResolver) Resolve(_ context.Context, env envelope.FrameEnvelope) (envelope.FrameEnvelope, error) {
 	return env, nil
 }
 type MySQLResolver struct {
 	db    *sql.DB
 	table string
 }
 func NewMySQLResolver(db *sql.DB, table string) *MySQLResolver {
 	if db == nil {
 		panic("identity db must not be nil")
 	}
 	table = strings.TrimSpace(table)
 	if table == "" || !safeIdentifier(table) {
 		table = "vehicle_identity_binding"
 	}
 	return &MySQLResolver{db: db, table: table}
 }
 func safeIdentifier(value string) bool {
 	if value == "" {
 		return false
 	}
 	for _, r := range value {
 		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '_' {
 			continue
 		}
 		return false
 	}
 	return true
 }
 func (r *MySQLResolver) Resolve(ctx context.Context, env envelope.FrameEnvelope) (envelope.FrameEnvelope, error) {
 	if strings.TrimSpace(env.VIN) != "" {
 		if err := r.trackJT808(ctx, env); err != nil {
 			return env, err
 		}
 		return env, nil
 	}
 	candidates := CandidateKeys(env)
 	for _, candidate := range candidates {
 		vin, err := r.lookup(ctx, candidate.Column, candidate.Value)
 		if err != nil {
 			if errors.Is(err, sql.ErrNoRows) {
 				continue
 			}
 			return env, err
 		}
 		if strings.TrimSpace(vin) != "" {
 			env.VIN = strings.TrimSpace(vin)
 			if env.Parsed == nil {
 				env.Parsed = map[string]any{}
 			}
 			env.Parsed["identity"] = map[string]any{
 				"resolved": true,
 				"source":   candidate.Column,
 				"value":    candidate.Value,
 			}
 			env.EventID = env.StableEventID()
 			if err := r.trackJT808(ctx, env); err != nil {
 				return env, err
 			}
 			return env, nil
 		}
 	}
 	if err := r.trackJT808(ctx, env); err != nil {
 		return env, err
 	}
 	return env, nil
 }
 func (r *MySQLResolver) lookup(ctx context.Context, column string, value string) (string, error) {
 	query := "SELECT vin FROM " + r.table + " WHERE " + column + " = ? AND vin IS NOT NULL AND vin <> '' ORDER BY updated_at DESC LIMIT 1"
 	var vin string
 	err := r.db.QueryRowContext(ctx, query, value).Scan(&vin)
 	return vin, err
 }
 func (r *MySQLResolver) trackJT808(ctx context.Context, env envelope.FrameEnvelope) error {
 	if env.Protocol != envelope.ProtocolJT808 || strings.TrimSpace(env.Phone) == "" || strings.TrimSpace(env.MessageID) == "" {
 		return nil
 	}
 	registration := mapValue(env.Parsed, "registration")
 	authentication := mapValue(env.Parsed, "authentication")
 	deviceID := firstNonEmpty(env.DeviceID, textValue(registration, "device_id"))
 	plate := firstNonEmpty(env.Plate, textValue(registration, "plate"))
 	vin := strings.TrimSpace(env.VIN)
 	if vin == "" {
 		vin = "unknown"
 	}
 	firstRegisteredAt := nilTime()
 	latestRegisteredAt := nilTime()
 	if env.MessageID == "0x0100" {
 		firstRegisteredAt = "CURRENT_TIMESTAMP"
 		latestRegisteredAt = "CURRENT_TIMESTAMP"
 	}
 	latestAuthenticatedAt := nilTime()
 	if env.MessageID == "0x0102" {
 		latestAuthenticatedAt = "CURRENT_TIMESTAMP"
 	}
 	query := `INSERT INTO jt808_registration
  (phone, device_id, plate, vin, province, city, manufacturer, device_type, plate_color,
   auth_token, auth_imei, auth_software_version, source_endpoint,
   first_registered_at, latest_registered_at, latest_authenticated_at)
 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ` + firstRegisteredAt + `, ` + latestRegisteredAt + `, ` + latestAuthenticatedAt + `)
 ON DUPLICATE KEY UPDATE
  device_id = IF(VALUES(device_id) <> '', VALUES(device_id), device_id),
  plate = IF(VALUES(plate) <> '', VALUES(plate), plate),
  vin = IF(VALUES(vin) <> 'unknown', VALUES(vin), vin),
  province = IF(VALUES(province) <> '', VALUES(province), province),
  city = IF(VALUES(city) <> '', VALUES(city), city),
  manufacturer = IF(VALUES(manufacturer) <> '', VALUES(manufacturer), manufacturer),
  device_type = IF(VALUES(device_type) <> '', VALUES(device_type), device_type),
  plate_color = IF(VALUES(plate_color) <> '', VALUES(plate_color), plate_color),
  auth_token = IF(VALUES(auth_token) <> '', VALUES(auth_token), auth_token),
  auth_imei = IF(VALUES(auth_imei) <> '', VALUES(auth_imei), auth_imei),
  auth_software_version = IF(VALUES(auth_software_version) <> '', VALUES(auth_software_version), auth_software_version),
  source_endpoint = IF(VALUES(source_endpoint) <> '', VALUES(source_endpoint), source_endpoint),
  latest_seen_at = CURRENT_TIMESTAMP,
  first_registered_at = COALESCE(first_registered_at, VALUES(first_registered_at)),
  latest_registered_at = COALESCE(VALUES(latest_registered_at), latest_registered_at),
  latest_authenticated_at = COALESCE(VALUES(latest_authenticated_at), latest_authenticated_at)`
 	_, err := r.db.ExecContext(ctx, query,
 		env.Phone,
 		deviceID,
 		plate,
 		vin,
 		textValue(registration, "province"),
 		textValue(registration, "city"),
 		textValue(registration, "manufacturer"),
 		textValue(registration, "device_type"),
 		textValue(registration, "plate_color"),
 		textValue(authentication, "token"),
 		textValue(authentication, "imei"),
 		textValue(authentication, "software_version"),
 		env.SourceEndpoint,
 	)
 	if err != nil {
 		return err
 	}
 	if vin == "unknown" {
 		return nil
 	}
 	_, err = r.db.ExecContext(ctx, `UPDATE IGNORE `+r.table+`
 SET
  phone = CASE WHEN (phone IS NULL OR phone = '') AND ? <> '' THEN ? ELSE phone END,
  device_id = CASE WHEN (device_id IS NULL OR device_id = '') AND ? <> '' THEN ? ELSE device_id END,
  plate = CASE WHEN (plate IS NULL OR plate = '') AND ? <> '' THEN ? ELSE plate END
 WHERE vin = ?`, env.Phone, env.Phone, deviceID, deviceID, plate, plate, vin)
 	return err
 }
 type CandidateKey struct {
 	Column string
 	Value  string
 }
 func CandidateKeys(env envelope.FrameEnvelope) []CandidateKey {
 	var out []CandidateKey
 	add := func(column string, value string) {
 		value = strings.TrimSpace(value)
 		if value == "" || strings.EqualFold(value, "unknown") {
 			return
 		}
 		for _, existing := range out {
 			if existing.Column == column && existing.Value == value {
 				return
 			}
 		}
 		out = append(out, CandidateKey{Column: column, Value: value})
 	}
 	add("phone", env.Phone)
 	if trimmed := strings.TrimLeft(strings.TrimSpace(env.Phone), "0"); trimmed != "" {
 		add("phone", trimmed)
 	}
 	add("device_id", env.DeviceID)
 	add("plate", env.Plate)
 	add("vin", env.VehicleKeyHint)
 	return out
 }
 func mapValue(values map[string]any, key string) map[string]any {
 	if values == nil {
 		return nil
 	}
 	nested, _ := values[key].(map[string]any)
 	return nested
 }
 func textValue(values map[string]any, key string) string {
 	if values == nil {
 		return ""
 	}
 	value, ok := values[key]
 	if !ok || value == nil {
 		return ""
 	}
 	switch typed := value.(type) {
 	case string:
 		return strings.TrimSpace(typed)
 	default:
 		return strings.TrimSpace(fmt.Sprint(typed))
 	}
 }
 func firstNonEmpty(values ...string) string {
 	for _, value := range values {
 		if trimmed := strings.TrimSpace(value); trimmed != "" {
 			return trimmed
 		}
 	}
 	return ""
 }
 func nilTime() string {
 	return "NULL"
 }
--- a/go/vehicle-gateway/internal/identity/resolver_test.go
+++ b/go/vehicle-gateway/internal/identity/resolver_test.go
@@ -0,0 +1,171 @@
 package identity
 import (
 	"context"
 	"database/sql"
 	"testing"
 	"github.com/DATA-DOG/go-sqlmock"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestCandidateKeysPrioritizesPhoneDevicePlate(t *testing.T) {
 	keys := CandidateKeys(envelope.FrameEnvelope{
 		Phone:          "013307795425",
 		DeviceID:       "D1",
 		Plate:          "豫A12345",
 		VehicleKeyHint: "D1",
 	})
 	got := []string{}
 	for _, key := range keys {
 		got = append(got, key.Column+"="+key.Value)
 	}
 	want := []string{"phone=013307795425", "phone=13307795425", "device_id=D1", "plate=豫A12345", "vin=D1"}
 	if len(got) != len(want) {
 		t.Fatalf("candidate count = %d got=%#v", len(got), got)
 	}
 	for i := range want {
 		if got[i] != want[i] {
 			t.Fatalf("candidate[%d] = %q, want %q", i, got[i], want[i])
 		}
 	}
 }
 func TestCandidateKeysAddsTrimmedPhoneVariant(t *testing.T) {
 	keys := CandidateKeys(envelope.FrameEnvelope{
 		Phone: "013079963379",
 	})
 	got := []string{}
 	for _, key := range keys {
 		got = append(got, key.Column+"="+key.Value)
 	}
 	want := []string{"phone=013079963379", "phone=13079963379"}
 	if len(got) != len(want) {
 		t.Fatalf("candidate count = %d got=%#v", len(got), got)
 	}
 	for i := range want {
 		if got[i] != want[i] {
 			t.Fatalf("candidate[%d] = %q, want %q", i, got[i], want[i])
 		}
 	}
 }
 func TestMySQLResolverFillsVINFromPhone(t *testing.T) {
 	db, mock := newMockDB(t)
 	defer db.Close()
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE phone = \\?").
 		WithArgs("013307795425").
 		WillReturnRows(sqlmock.NewRows([]string{"vin"}).AddRow("LNBVIN00000000001"))
 	resolver := NewMySQLResolver(db, "vehicle_identity_binding")
 	env, err := resolver.Resolve(context.Background(), envelope.FrameEnvelope{
 		Protocol: envelope.ProtocolJT808,
 		Phone:    "013307795425",
 		Parsed:   map[string]any{},
 	})
 	if err != nil {
 		t.Fatalf("Resolve() error = %v", err)
 	}
 	if env.VIN != "LNBVIN00000000001" {
 		t.Fatalf("vin = %q", env.VIN)
 	}
 	identity, ok := env.Parsed["identity"].(map[string]any)
 	if !ok || identity["source"] != "phone" {
 		t.Fatalf("identity metadata = %#v", env.Parsed["identity"])
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMySQLResolverFallsBackToDeviceID(t *testing.T) {
 	db, mock := newMockDB(t)
 	defer db.Close()
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE phone = \\?").
 		WithArgs("013307795425").
 		WillReturnError(sql.ErrNoRows)
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE phone = \\?").
 		WithArgs("13307795425").
 		WillReturnError(sql.ErrNoRows)
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE device_id = \\?").
 		WithArgs("D1").
 		WillReturnRows(sqlmock.NewRows([]string{"vin"}).AddRow("LNBVIN00000000002"))
 	resolver := NewMySQLResolver(db, "vehicle_identity_binding")
 	env, err := resolver.Resolve(context.Background(), envelope.FrameEnvelope{
 		Protocol: envelope.ProtocolJT808,
 		Phone:    "013307795425",
 		DeviceID: "D1",
 	})
 	if err != nil {
 		t.Fatalf("Resolve() error = %v", err)
 	}
 	if env.VIN != "LNBVIN00000000002" {
 		t.Fatalf("vin = %q", env.VIN)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMySQLResolverTracksJT808RegistrationAndBackfillsBinding(t *testing.T) {
 	db, mock := newMockDB(t)
 	defer db.Close()
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE phone = \\?").
 		WithArgs("013079963379").
 		WillReturnError(sql.ErrNoRows)
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE phone = \\?").
 		WithArgs("13079963379").
 		WillReturnError(sql.ErrNoRows)
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE device_id = \\?").
 		WithArgs("DEV0001").
 		WillReturnError(sql.ErrNoRows)
 	mock.ExpectQuery("SELECT vin FROM vehicle_identity_binding WHERE plate = \\?").
 		WithArgs("TEST123").
 		WillReturnRows(sqlmock.NewRows([]string{"vin"}).AddRow("LKLG7C4E3NA774736"))
 	mock.ExpectExec("INSERT INTO jt808_registration").
 		WillReturnResult(sqlmock.NewResult(1, 1))
 	mock.ExpectExec("UPDATE IGNORE vehicle_identity_binding").
 		WithArgs("013079963379", "013079963379", "DEV0001", "DEV0001", "TEST123", "TEST123", "LKLG7C4E3NA774736").
 		WillReturnResult(sqlmock.NewResult(0, 1))
 	resolver := NewMySQLResolver(db, "vehicle_identity_binding")
 	env, err := resolver.Resolve(context.Background(), envelope.FrameEnvelope{
 		Protocol:       envelope.ProtocolJT808,
 		MessageID:      "0x0100",
 		Phone:          "013079963379",
 		DeviceID:       "DEV0001",
 		Plate:          "TEST123",
 		SourceEndpoint: "115.231.168.135:43625",
 		Parsed: map[string]any{
 			"registration": map[string]any{
 				"province":     uint16(16),
 				"city":         uint16(32),
 				"manufacturer": "YUTNG",
 				"device_type":  "ZK6105CHEVNPG4",
 				"device_id":    "DEV0001",
 				"plate_color":  uint8(2),
 				"plate":        "TEST123",
 			},
 		},
 	})
 	if err != nil {
 		t.Fatalf("Resolve() error = %v", err)
 	}
 	if env.VIN != "LKLG7C4E3NA774736" {
 		t.Fatalf("vin = %q", env.VIN)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func newMockDB(t *testing.T) (*sql.DB, sqlmock.Sqlmock) {
 	t.Helper()
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	return db, mock
 }
--- a/go/vehicle-gateway/internal/observability/logger.go
+++ b/go/vehicle-gateway/internal/observability/logger.go
@@ -0,0 +1,13 @@
 package observability
 import (
 	"log/slog"
 	"os"
 )
 // NewLogger returns a JSON logger with a stable service field so ECS logs from
 // different Go processes can be filtered without relying on container names.
 func NewLogger(service string) *slog.Logger {
 	handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{AddSource: true})
 	return slog.New(handler).With("service", service)
 }
--- a/go/vehicle-gateway/internal/protocol/gb32960/parser.go
+++ b/go/vehicle-gateway/internal/protocol/gb32960/parser.go
@@ -0,0 +1,840 @@
 package gb32960
 import (
 	"encoding/binary"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"strings"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 var (
 	ErrFrameTooShort  = errors.New("gb32960 frame too short")
 	ErrBadStartSymbol = errors.New("gb32960 bad start symbol")
 	ErrBodyLength     = errors.New("gb32960 body length mismatch")
 	ErrBCC            = errors.New("gb32960 bcc mismatch")
 )
 const (
 	minFrameLen = 25
 	headerLen   = 24
 )
 // ExtractFrames splits GB/T 32960 TCP streams using the protocol length field.
 // Returned frames include the start symbols and trailing BCC byte.
 func ExtractFrames(stream []byte) (frames [][]byte, remainder []byte, err error) {
 	offset := 0
 	for {
 		start := indexStart(stream[offset:])
 		if start < 0 {
 			return frames, nil, nil
 		}
 		offset += start
 		remaining := stream[offset:]
 		if len(remaining) < headerLen {
 			return frames, append([]byte(nil), remaining...), nil
 		}
 		bodyLen := int(binary.BigEndian.Uint16(remaining[22:24]))
 		frameLen := frameLength(remaining, bodyLen)
 		if len(remaining) < frameLen {
 			return frames, append([]byte(nil), remaining...), nil
 		}
 		frames = append(frames, append([]byte(nil), remaining[:frameLen]...))
 		offset += frameLen
 		if offset >= len(stream) {
 			return frames, nil, nil
 		}
 	}
 }
 func ParseFrame(raw []byte, receivedAtMS int64, sourceEndpoint string) (envelope.FrameEnvelope, error) {
 	if len(raw) < minFrameLen {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: len=%d", ErrFrameTooShort, len(raw))
 	}
 	version, ok := version(raw[0], raw[1])
 	if !ok {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: %s", ErrBadStartSymbol, hex.EncodeToString(raw[:2]))
 	}
 	bodyLen := int(binary.BigEndian.Uint16(raw[22:24]))
 	actualBodyLen := len(raw) - headerLen - 1
 	if len(raw) != headerLen+bodyLen+1 && !isExtendedPlatformLogin(raw[2], bodyLen, actualBodyLen) {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: declared=%d actual=%d", ErrBodyLength, bodyLen, len(raw)-headerLen-1)
 	}
 	if got, want := bcc(raw[2:len(raw)-1]), raw[len(raw)-1]; got != want {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: got=0x%02x want=0x%02x", ErrBCC, got, want)
 	}
 	command := raw[2]
 	responseFlag := raw[3]
 	vin := strings.TrimRight(string(raw[4:21]), "\x00 ")
 	body := raw[headerLen : headerLen+actualBodyLen]
 	parsed := map[string]any{
 		"header": map[string]any{
 			"version":            version,
 			"command":            fmt.Sprintf("0x%02X", command),
 			"response_flag":      fmt.Sprintf("0x%02X", responseFlag),
 			"vin":                vin,
 			"encrypt":            raw[21],
 			"body_length":        bodyLen,
 			"actual_body_length": actualBodyLen,
 		},
 	}
 	fields := map[string]any{}
 	eventTimeMS := receivedAtMS
 	if command == 0x02 || command == 0x03 {
 		eventTime, units := parseDataBody(version, body, fields)
 		if !eventTime.IsZero() {
 			eventTimeMS = eventTime.UnixMilli()
 			fields["device_time"] = eventTime.Format(time.RFC3339)
 			parsed["device_time"] = eventTime.Format(time.RFC3339)
 		}
 		parsed["data_units"] = units
 	} else if command == 0x05 {
 		login := parsePlatformLogin(body)
 		parsed["platform_login"] = login
 		if deviceTime, ok := login["login_time"].(string); ok && deviceTime != "" {
 			fields["device_time"] = deviceTime
 			parsed["device_time"] = deviceTime
 		}
 		if account, ok := login["username"].(string); ok && account != "" {
 			fields["platform_account"] = account
 		}
 	}
 	env := envelope.FrameEnvelope{
 		Protocol:       envelope.ProtocolGB32960,
 		MessageID:      fmt.Sprintf("0x%02X", command),
 		VIN:            vin,
 		SourceEndpoint: sourceEndpoint,
 		EventTimeMS:    eventTimeMS,
 		ReceivedAtMS:   receivedAtMS,
 		RawHex:         strings.ToUpper(hex.EncodeToString(raw)),
 		Parsed:         parsed,
 		Fields:         fields,
 		ParseStatus:    envelope.ParseOK,
 	}
 	env.EventID = env.StableEventID()
 	return env, nil
 }
 func parseDataBody(version string, body []byte, fields map[string]any) (time.Time, []map[string]any) {
 	if len(body) < 6 {
 		return time.Time{}, nil
 	}
 	eventTime := parseGBTime(body[:6])
 	cursor := 6
 	var units []map[string]any
 	for cursor < len(body) {
 		unitType := body[cursor]
 		cursor++
 		switch unitType {
 		case 0x01:
 			size := 20
 			if version == "V2025" {
 				size = 18
 			}
 			if len(body[cursor:]) < size {
 				units = append(units, map[string]any{"type": "0x01", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseVehicleData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x01", "name": "vehicle", "value": unit})
 			fields["vehicle_status"] = unit["vehicle_status"]
 			fields["charge_status"] = unit["charge_status"]
 			fields["running_mode"] = unit["running_mode"]
 			fields[envelope.FieldSpeedKMH] = unit["speed_kmh"]
 			fields[envelope.FieldTotalMileageKM] = unit["total_mileage_km"]
 			fields[envelope.FieldSOCPercent] = unit["soc_percent"]
 			cursor += size
 		case 0x05:
 			if len(body[cursor:]) < 9 {
 				units = append(units, map[string]any{"type": "0x05", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parsePositionData(body[cursor : cursor+9])
 			units = append(units, map[string]any{"type": "0x05", "name": "position", "value": unit})
 			fields["position_status"] = unit["position_status"]
 			fields[envelope.FieldLongitude] = unit["longitude"]
 			fields[envelope.FieldLatitude] = unit["latitude"]
 			cursor += 9
 		case 0x02:
 			if len(body[cursor:]) < 1 {
 				units = append(units, map[string]any{"type": "0x02", "error": "truncated"})
 				return eventTime, units
 			}
 			size := 1 + int(body[cursor])*12
 			if len(body[cursor:]) < size {
 				units = append(units, map[string]any{"type": "0x02", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseDriveMotorData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x02", "name": "drive_motor", "value": unit})
 			cursor += size
 		case 0x03:
 			if len(body[cursor:]) < 8 {
 				units = append(units, map[string]any{"type": "0x03", "error": "truncated"})
 				return eventTime, units
 			}
 			probeCount := int(binary.BigEndian.Uint16(body[cursor+6 : cursor+8]))
 			size := 8 + probeCount + 10
 			if len(body[cursor:]) < size {
 				units = append(units, map[string]any{"type": "0x03", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseFuelCellData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x03", "name": "fuel_cell", "value": unit})
 			fields["fuel_cell_hydrogen_consumption_kg_per_100km"] = unit["hydrogen_consumption_kg_per_100km"]
 			fields["fuel_cell_voltage_v"] = unit["fuel_cell_voltage_v"]
 			fields["fuel_cell_current_a"] = unit["fuel_cell_current_a"]
 			cursor += size
 		case 0x04:
 			if len(body[cursor:]) < 5 {
 				units = append(units, map[string]any{"type": "0x04", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseEngineData(body[cursor : cursor+5])
 			units = append(units, map[string]any{"type": "0x04", "name": "engine", "value": unit})
 			cursor += 5
 		case 0x06:
 			if len(body[cursor:]) < 14 {
 				units = append(units, map[string]any{"type": "0x06", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseExtremeData(body[cursor : cursor+14])
 			units = append(units, map[string]any{"type": "0x06", "name": "extreme", "value": unit})
 			cursor += 14
 		case 0x07:
 			size, ok := alarmDataSize(body[cursor:])
 			if !ok {
 				units = append(units, map[string]any{"type": "0x07", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseAlarmData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x07", "name": "alarm", "value": unit})
 			cursor += size
 		case 0x08:
 			size, ok := voltageDataSize(body[cursor:])
 			if !ok {
 				units = append(units, map[string]any{"type": "0x08", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseVoltageData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x08", "name": "voltage", "value": unit})
 			cursor += size
 		case 0x09:
 			size, ok := temperatureDataSize(body[cursor:])
 			if !ok {
 				units = append(units, map[string]any{"type": "0x09", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseTemperatureData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x09", "name": "temperature", "value": unit})
 			cursor += size
 		case 0x30:
 			size, ok := gdFCStackDataSize(body[cursor:])
 			if !ok {
 				units = append(units, map[string]any{"type": "0x30", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCStackData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x30", "name": "gd_fc_stack", "value": unit})
 			if summaries, ok := unit["summaries"].([]map[string]any); ok && len(summaries) > 0 {
 				fields["gd_fc_stack_hydrogen_inlet_pressure_kpa"] = summaries[0]["hydrogen_inlet_pressure_kpa"]
 				fields["gd_fc_stack_water_outlet_temp_c"] = summaries[0]["stack_water_outlet_temp_c"]
 				fields["gd_fc_stack_cell_count"] = summaries[0]["cell_count"]
 				fields["gd_fc_stack_frame_cell_count"] = summaries[0]["frame_cell_count"]
 			}
 			cursor += size
 		case 0x31:
 			size, ok := gdFCAuxiliaryDataSize(body[cursor:])
 			if !ok {
 				units = append(units, map[string]any{"type": "0x31", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCAuxiliaryData(body[cursor : cursor+size])
 			units = append(units, map[string]any{"type": "0x31", "name": "gd_fc_auxiliary", "value": unit})
 			cursor += size
 		case 0x32:
 			if len(body[cursor:]) < 9 {
 				units = append(units, map[string]any{"type": "0x32", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCDcDcData(body[cursor : cursor+9])
 			units = append(units, map[string]any{"type": "0x32", "name": "gd_fc_dcdc", "value": unit})
 			fields["gd_fc_dcdc_controller_temp_c"] = unit["controller_temp_c"]
 			cursor += 9
 		case 0x33:
 			if len(body[cursor:]) < 5 {
 				units = append(units, map[string]any{"type": "0x33", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCAirConditionerData(body[cursor : cursor+5])
 			units = append(units, map[string]any{"type": "0x33", "name": "gd_fc_air_conditioner", "value": unit})
 			cursor += 5
 		case 0x34:
 			if len(body[cursor:]) < 7 {
 				units = append(units, map[string]any{"type": "0x34", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCVehicleInfoData(body[cursor : cursor+7])
 			units = append(units, map[string]any{"type": "0x34", "name": "gd_fc_vehicle_info", "value": unit})
 			fields["gd_fc_vehicle_hydrogen_mass_kg"] = unit["hydrogen_mass_kg"]
 			cursor += 7
 		case 0x80:
 			if len(body[cursor:]) < 11 {
 				units = append(units, map[string]any{"type": "0x80", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCDemoExtensionData(body[cursor : cursor+11])
 			units = append(units, map[string]any{"type": "0x80", "name": "gd_fc_demo_extension", "value": unit})
 			fields["gd_fc_demo_stack_temp_c"] = unit["stack_temp_c"]
 			cursor += 11
 		case 0x83:
 			size, ok := gdFCVendorTLVDataSize(body[cursor:])
 			if !ok {
 				units = append(units, map[string]any{"type": "0x83", "error": "truncated"})
 				return eventTime, units
 			}
 			unit := parseGdFCVendorTLVData(0x83, body[cursor:cursor+size])
 			units = append(units, map[string]any{"type": "0x83", "name": "gd_fc_vendor_tlv", "value": unit})
 			cursor += size
 		default:
 			units = append(units, map[string]any{
 				"type":      fmt.Sprintf("0x%02X", unitType),
 				"raw_tail":  strings.ToUpper(hex.EncodeToString(body[cursor:])),
 				"parse":     "unknown_unit",
 				"byte_size": len(body) - cursor,
 			})
 			return eventTime, units
 		}
 	}
 	return eventTime, units
 }
 func frameLength(frameStart []byte, bodyLen int) int {
 	standardLen := headerLen + bodyLen + 1
 	if len(frameStart) < headerLen || frameStart[2] != 0x05 || bodyLen != 41 {
 		return standardLen
 	}
 	// Some field platform-login frames declare the standard 41-byte body but
 	// carry a 32-byte password, making the actual body 53 bytes. Only consume
 	// the extended form when its own BCC verifies so the splitter does not eat
 	// bytes from the next frame.
 	extendedLen := headerLen + 53 + 1
 	if len(frameStart) < extendedLen {
 		return standardLen
 	}
 	extended := frameStart[:extendedLen]
 	if bcc(extended[2:len(extended)-1]) == extended[len(extended)-1] {
 		return extendedLen
 	}
 	return standardLen
 }
 func isExtendedPlatformLogin(command byte, declaredBodyLen int, actualBodyLen int) bool {
 	return command == 0x05 && declaredBodyLen == 41 && actualBodyLen == 53
 }
 func parsePlatformLogin(body []byte) map[string]any {
 	login := map[string]any{
 		"raw_body_length": len(body),
 	}
 	if len(body) < 9 {
 		login["error"] = "truncated"
 		return login
 	}
 	loginTime := parseGBTime(body[:6])
 	if !loginTime.IsZero() {
 		login["login_time"] = loginTime.Format(time.RFC3339)
 	}
 	login["serial_no"] = binary.BigEndian.Uint16(body[6:8])
 	if len(body) >= 21 {
 		login["username"] = trimASCII(body[8:20])
 	}
 	if len(body) > 21 {
 		passwordEnd := len(body) - 1
 		login["password"] = trimASCII(body[20:passwordEnd])
 		login["encrypt_rule"] = body[passwordEnd]
 	}
 	return login
 }
 func parseVehicleData(data []byte) map[string]any {
 	return map[string]any{
 		"vehicle_status":   int(data[0]),
 		"charge_status":    int(data[1]),
 		"running_mode":     int(data[2]),
 		"speed_kmh":        float64(binary.BigEndian.Uint16(data[3:5])) / 10,
 		"total_mileage_km": float64(binary.BigEndian.Uint32(data[5:9])) / 10,
 		"total_voltage_v":  float64(binary.BigEndian.Uint16(data[9:11])) / 10,
 		"total_current_a":  float64(binary.BigEndian.Uint16(data[11:13]))/10 - 1000,
 		"soc_percent":      int(data[13]),
 		"dc_dc_status":     int(data[14]),
 		"gear":             int(data[15]),
 		"insulation_kohm":  binary.BigEndian.Uint16(data[16:18]),
 		"accelerator_pct":  int(data[18]),
 		"brake_pct":        int(data[19]),
 	}
 }
 func parseDriveMotorData(data []byte) map[string]any {
 	count := int(data[0])
 	motors := make([]map[string]any, 0, count)
 	cursor := 1
 	for i := 0; i < count; i++ {
 		motors = append(motors, map[string]any{
 			"serial_no":                int(data[cursor]),
 			"state":                    int(data[cursor+1]),
 			"controller_temperature_c": int(data[cursor+2]) - 40,
 			"speed_rpm":                int(binary.BigEndian.Uint16(data[cursor+3:cursor+5])) - 20000,
 			"torque_nm":                float64(int(binary.BigEndian.Uint16(data[cursor+5:cursor+7]))-20000) / 10,
 			"motor_temperature_c":      int(data[cursor+7]) - 40,
 			"controller_voltage_v":     float64(binary.BigEndian.Uint16(data[cursor+8:cursor+10])) / 10,
 			"controller_current_a":     float64(binary.BigEndian.Uint16(data[cursor+10:cursor+12]))/10 - 1000,
 		})
 		cursor += 12
 	}
 	return map[string]any{
 		"count":  count,
 		"motors": motors,
 	}
 }
 func parseFuelCellData(data []byte) map[string]any {
 	probeCount := int(binary.BigEndian.Uint16(data[6:8]))
 	probes := make([]int, 0, probeCount)
 	cursor := 8
 	for i := 0; i < probeCount; i++ {
 		probes = append(probes, int(data[cursor])-40)
 		cursor++
 	}
 	out := map[string]any{
 		"fuel_cell_voltage_v":                 float64(binary.BigEndian.Uint16(data[0:2])) / 10,
 		"fuel_cell_current_a":                 float64(binary.BigEndian.Uint16(data[2:4])) / 10,
 		"hydrogen_consumption_kg_per_100km":   float64(binary.BigEndian.Uint16(data[4:6])) / 100,
 		"temperature_probe_count":             probeCount,
 		"temperature_probe_values_c":          probes,
 		"max_hydrogen_temperature_c":          float64(binary.BigEndian.Uint16(data[cursor:cursor+2]))/10 - 40,
 		"max_hydrogen_temperature_probe_id":   int(data[cursor+2]),
 		"max_hydrogen_concentration_fraction": float64(binary.BigEndian.Uint16(data[cursor+3:cursor+5])) * 0.000001,
 		"max_hydrogen_concentration_probe_id": int(data[cursor+5]),
 		"max_hydrogen_pressure_mpa":           float64(binary.BigEndian.Uint16(data[cursor+6:cursor+8])) / 10,
 		"max_hydrogen_pressure_probe_id":      int(data[cursor+8]),
 		"dc_dc_status":                        int(data[cursor+9]),
 	}
 	return out
 }
 func parseEngineData(data []byte) map[string]any {
 	return map[string]any{
 		"engine_status":   int(data[0]),
 		"crank_speed_rpm": binary.BigEndian.Uint16(data[1:3]),
 		"fuel_rate":       binary.BigEndian.Uint16(data[3:5]),
 	}
 }
 func parseExtremeData(data []byte) map[string]any {
 	return map[string]any{
 		"max_voltage_subsystem_no": int(data[0]),
 		"max_voltage_cell_no":      int(data[1]),
 		"max_voltage_v":            float64(binary.BigEndian.Uint16(data[2:4])) / 1000,
 		"min_voltage_subsystem_no": int(data[4]),
 		"min_voltage_cell_no":      int(data[5]),
 		"min_voltage_v":            float64(binary.BigEndian.Uint16(data[6:8])) / 1000,
 		"max_temp_subsystem_no":    int(data[8]),
 		"max_temp_probe_no":        int(data[9]),
 		"max_temp_c":               int(data[10]) - 40,
 		"min_temp_subsystem_no":    int(data[11]),
 		"min_temp_probe_no":        int(data[12]),
 		"min_temp_c":               int(data[13]) - 40,
 	}
 }
 func alarmDataSize(data []byte) (int, bool) {
 	if len(data) < 5 {
 		return 0, false
 	}
 	cursor := 5
 	for i := 0; i < 4; i++ {
 		if len(data[cursor:]) < 1 {
 			return 0, false
 		}
 		count := int(data[cursor])
 		cursor++
 		cursor += count * 4
 		if cursor > len(data) {
 			return 0, false
 		}
 	}
 	return cursor, true
 }
 func parseAlarmData(data []byte) map[string]any {
 	cursor := 5
 	readList := func() []string {
 		count := int(data[cursor])
 		cursor++
 		values := make([]string, 0, count)
 		for i := 0; i < count; i++ {
 			values = append(values, fmt.Sprintf("0x%08X", binary.BigEndian.Uint32(data[cursor:cursor+4])))
 			cursor += 4
 		}
 		return values
 	}
 	return map[string]any{
 		"max_alarm_level":    int(data[0]),
 		"general_alarm_flag": fmt.Sprintf("0x%08X", binary.BigEndian.Uint32(data[1:5])),
 		"battery_faults":     readList(),
 		"motor_faults":       readList(),
 		"engine_faults":      readList(),
 		"other_faults":       readList(),
 	}
 }
 func voltageDataSize(data []byte) (int, bool) {
 	if len(data) < 1 {
 		return 0, false
 	}
 	cursor := 1
 	for i := 0; i < int(data[0]); i++ {
 		if len(data[cursor:]) < 10 {
 			return 0, false
 		}
 		frameCellCount := int(data[cursor+9])
 		cursor += 10 + frameCellCount*2
 		if cursor > len(data) {
 			return 0, false
 		}
 	}
 	return cursor, true
 }
 func parseVoltageData(data []byte) map[string]any {
 	subCount := int(data[0])
 	cursor := 1
 	totalVoltage := 0.0
 	maxCell := 0.0
 	minCell := 0.0
 	cellSeen := false
 	for i := 0; i < subCount; i++ {
 		totalVoltage += float64(binary.BigEndian.Uint16(data[cursor+1:cursor+3])) / 10
 		cellCount := int(binary.BigEndian.Uint16(data[cursor+5 : cursor+7]))
 		frameCellCount := int(data[cursor+9])
 		cursor += 10
 		for c := 0; c < frameCellCount; c++ {
 			voltage := float64(binary.BigEndian.Uint16(data[cursor:cursor+2])) / 1000
 			if !cellSeen || voltage > maxCell {
 				maxCell = voltage
 			}
 			if !cellSeen || voltage < minCell {
 				minCell = voltage
 			}
 			cellSeen = true
 			cursor += 2
 		}
 		_ = cellCount
 	}
 	return map[string]any{
 		"subsystem_count": subCount,
 		"total_voltage_v": totalVoltage,
 		"max_cell_v":      maxCell,
 		"min_cell_v":      minCell,
 	}
 }
 func temperatureDataSize(data []byte) (int, bool) {
 	if len(data) < 1 {
 		return 0, false
 	}
 	cursor := 1
 	for i := 0; i < int(data[0]); i++ {
 		if len(data[cursor:]) < 3 {
 			return 0, false
 		}
 		probeCount := int(binary.BigEndian.Uint16(data[cursor+1 : cursor+3]))
 		cursor += 3 + probeCount
 		if cursor > len(data) {
 			return 0, false
 		}
 	}
 	return cursor, true
 }
 func parseTemperatureData(data []byte) map[string]any {
 	subCount := int(data[0])
 	cursor := 1
 	maxTemp := 0
 	minTemp := 0
 	seen := false
 	for i := 0; i < subCount; i++ {
 		probeCount := int(binary.BigEndian.Uint16(data[cursor+1 : cursor+3]))
 		cursor += 3
 		for p := 0; p < probeCount; p++ {
 			temp := int(data[cursor]) - 40
 			if !seen || temp > maxTemp {
 				maxTemp = temp
 			}
 			if !seen || temp < minTemp {
 				minTemp = temp
 			}
 			seen = true
 			cursor++
 		}
 	}
 	return map[string]any{
 		"subsystem_count": subCount,
 		"max_temp_c":      maxTemp,
 		"min_temp_c":      minTemp,
 	}
 }
 func gdFCStackDataSize(data []byte) (int, bool) {
 	if len(data) < 1 {
 		return 0, false
 	}
 	cursor := 1
 	for i := 0; i < int(data[0]); i++ {
 		if len(data[cursor:]) < 22 {
 			return 0, false
 		}
 		frameCellCount := int(data[cursor+21])
 		cursor += 22 + frameCellCount*2
 		if cursor > len(data) {
 			return 0, false
 		}
 	}
 	return cursor, true
 }
 func parseGdFCStackData(data []byte) map[string]any {
 	count := int(data[0])
 	cursor := 1
 	summaries := make([]map[string]any, 0, count)
 	for i := 0; i < count; i++ {
 		frameCellCount := int(data[cursor+21])
 		summary := map[string]any{
 			"engine_work_state":           int(data[cursor]),
 			"stack_water_outlet_temp_c":   nullableTempOffset40(data[cursor+1]),
 			"hydrogen_inlet_pressure_kpa": nullableScaledU16WithOffset(data[cursor+2:cursor+4], 0.1, -100),
 			"air_inlet_pressure_kpa":      nullableScaledU16WithOffset(data[cursor+4:cursor+6], 0.1, -100),
 			"air_inlet_temp_c":            nullableTempOffset40(data[cursor+6]),
 			"max_cell_voltage_id":         nullableU16(data[cursor+7 : cursor+9]),
 			"min_cell_voltage_id":         nullableU16(data[cursor+9 : cursor+11]),
 			"max_cell_voltage_v":          nullableScaledU16(data[cursor+11:cursor+13], 0.001),
 			"min_cell_voltage_v":          nullableScaledU16(data[cursor+13:cursor+15], 0.001),
 			"avg_cell_voltage_v":          nullableScaledU16(data[cursor+15:cursor+17], 0.001),
 			"cell_count":                  nullableU16(data[cursor+17 : cursor+19]),
 			"frame_cell_start":            nullableU16(data[cursor+19 : cursor+21]),
 			"frame_cell_count":            frameCellCount,
 		}
 		cursor += 22
 		maxCell := 0.0
 		minCell := 0.0
 		seen := false
 		for c := 0; c < frameCellCount; c++ {
 			voltage := float64(binary.BigEndian.Uint16(data[cursor:cursor+2])) / 1000
 			if !seen || voltage > maxCell {
 				maxCell = voltage
 			}
 			if !seen || voltage < minCell {
 				minCell = voltage
 			}
 			seen = true
 			cursor += 2
 		}
 		if seen {
 			summary["frame_max_cell_voltage_v"] = maxCell
 			summary["frame_min_cell_voltage_v"] = minCell
 		}
 		summaries = append(summaries, summary)
 	}
 	return map[string]any{
 		"stack_count": count,
 		"summaries":   summaries,
 	}
 }
 func gdFCAuxiliaryDataSize(data []byte) (int, bool) {
 	if len(data) < 1 {
 		return 0, false
 	}
 	size := 1 + int(data[0])*16
 	return size, len(data) >= size
 }
 func parseGdFCAuxiliaryData(data []byte) map[string]any {
 	count := int(data[0])
 	cursor := 1
 	subsystems := make([]map[string]any, 0, count)
 	for i := 0; i < count; i++ {
 		subsystems = append(subsystems, map[string]any{
 			"air_compressor_motor_voltage_v": nullableScaledU16(data[cursor:cursor+2], 0.1),
 			"air_compressor_power_kw":        nullableU16WithOffset(data[cursor+2:cursor+4], -5),
 			"hydrogen_pump_motor_voltage_v":  nullableScaledU16(data[cursor+4:cursor+6], 0.2),
 			"hydrogen_pump_power_kw":         nullableU16WithOffset(data[cursor+6:cursor+8], -5),
 			"water_pump_voltage_v":           nullableScaledU16(data[cursor+8:cursor+10], 0.1),
 			"ptc_voltage_v":                  nullableScaledU16(data[cursor+10:cursor+12], 0.1),
 			"ptc_power_kw":                   nullableU16WithOffset(data[cursor+12:cursor+14], -5),
 			"low_voltage_battery_voltage_v":  nullableScaledU16(data[cursor+14:cursor+16], 0.1),
 		})
 		cursor += 16
 	}
 	return map[string]any{
 		"subsystem_count": count,
 		"subsystems":      subsystems,
 	}
 }
 func parseGdFCDcDcData(data []byte) map[string]any {
 	return map[string]any{
 		"input_voltage_v":   nullableScaledU16(data[0:2], 0.1),
 		"input_current_a":   nullableScaledU16(data[2:4], 0.1),
 		"output_voltage_v":  nullableScaledU16(data[4:6], 0.1),
 		"output_current_a":  nullableScaledU16(data[6:8], 0.1),
 		"controller_temp_c": nullableTempOffset40(data[8]),
 	}
 }
 func parseGdFCAirConditionerData(data []byte) map[string]any {
 	return map[string]any{
 		"status":                     int(data[0]),
 		"power_kw":                   nullableU16WithOffset(data[1:3], -5),
 		"compressor_input_voltage_v": nullableScaledU16(data[3:5], 0.1),
 	}
 }
 func parseGdFCVehicleInfoData(data []byte) map[string]any {
 	return map[string]any{
 		"collision_alarm":      int(data[0]),
 		"ambient_temp_c":       nullableU16WithOffset(data[1:3], -40),
 		"ambient_pressure_kpa": nullableScaledU16WithOffset(data[3:5], 0.1, -100),
 		"hydrogen_mass_kg":     nullableScaledU16(data[5:7], 0.1),
 	}
 }
 func parseGdFCDemoExtensionData(data []byte) map[string]any {
 	return map[string]any{
 		"declared_length":          int(binary.BigEndian.Uint16(data[0:2])),
 		"stack_temp_c":             nullableTempOffset40(data[2]),
 		"air_compressor_voltage_v": nullableScaledU16(data[3:5], 0.1),
 		"air_compressor_current_a": nullableScaledU16WithOffset(data[5:7], 0.1, -1000),
 		"hydrogen_pump_voltage_v":  nullableScaledU16(data[7:9], 0.1),
 		"hydrogen_pump_current_a":  nullableScaledU16WithOffset(data[9:11], 0.1, -1000),
 	}
 }
 func gdFCVendorTLVDataSize(data []byte) (int, bool) {
 	if len(data) < 2 {
 		return 0, false
 	}
 	size := 2 + int(binary.BigEndian.Uint16(data[0:2]))
 	return size, len(data) >= size
 }
 func parseGdFCVendorTLVData(typeCode byte, data []byte) map[string]any {
 	length := int(binary.BigEndian.Uint16(data[0:2]))
 	return map[string]any{
 		"type":            fmt.Sprintf("0x%02X", typeCode),
 		"declared_length": length,
 		"payload_hex":     strings.ToUpper(hex.EncodeToString(data[2:])),
 	}
 }
 func nullableU16(data []byte) any {
 	value := binary.BigEndian.Uint16(data)
 	if value == 0xfffe || value == 0xffff {
 		return nil
 	}
 	return int(value)
 }
 func nullableU16WithOffset(data []byte, offset int) any {
 	value := binary.BigEndian.Uint16(data)
 	if value == 0xfffe || value == 0xffff {
 		return nil
 	}
 	return int(value) + offset
 }
 func nullableScaledU16(data []byte, scale float64) any {
 	value := binary.BigEndian.Uint16(data)
 	if value == 0xfffe || value == 0xffff {
 		return nil
 	}
 	return float64(value) * scale
 }
 func nullableScaledU16WithOffset(data []byte, scale float64, offset float64) any {
 	value := binary.BigEndian.Uint16(data)
 	if value == 0xfffe || value == 0xffff {
 		return nil
 	}
 	return float64(value)*scale + offset
 }
 func nullableTempOffset40(value byte) any {
 	if value == 0xfe || value == 0xff {
 		return nil
 	}
 	return int(value) - 40
 }
 func parsePositionData(data []byte) map[string]any {
 	return map[string]any{
 		"position_status": int(data[0]),
 		"longitude":       float64(binary.BigEndian.Uint32(data[1:5])) / 1_000_000,
 		"latitude":        float64(binary.BigEndian.Uint32(data[5:9])) / 1_000_000,
 	}
 }
 func indexStart(data []byte) int {
 	for i := 0; i+1 < len(data); i++ {
 		if _, ok := version(data[i], data[i+1]); ok {
 			return i
 		}
 	}
 	return -1
 }
 func version(a byte, b byte) (string, bool) {
 	switch {
 	case a == '#' && b == '#':
 		return "V2016", true
 	case a == '$' && b == '$':
 		return "V2025", true
 	default:
 		return "", false
 	}
 }
 func parseGBTime(data []byte) time.Time {
 	if len(data) != 6 {
 		return time.Time{}
 	}
 	year := 2000 + int(data[0])
 	month := time.Month(data[1])
 	day := int(data[2])
 	hour := int(data[3])
 	minute := int(data[4])
 	second := int(data[5])
 	if month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59 {
 		return time.Time{}
 	}
 	return time.Date(year, month, day, hour, minute, second, 0, time.FixedZone("Asia/Shanghai", 8*3600))
 }
 func trimASCII(data []byte) string {
 	return strings.TrimRight(string(data), "\x00 ")
 }
 func bcc(data []byte) byte {
 	var out byte
 	for _, value := range data {
 		out ^= value
 	}
 	return out
 }
--- a/go/vehicle-gateway/internal/protocol/gb32960/parser_test.go
+++ b/go/vehicle-gateway/internal/protocol/gb32960/parser_test.go
@@ -0,0 +1,258 @@
 package gb32960
 import (
 	"encoding/hex"
 	"fmt"
 	"math"
 	"testing"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 const realFuelCellFrame = "232302FE4C423941333241323152304C53313730370102ED1A070116091C0102030100000008297D161F27104C020007D0000002010104564E204E205815CA271003000A000000B40002666902800200000100A101000400FFFF001205000733444601E2B5DB06013A0F6C018E0F4001014B01054A07000000000000000000080101161F271000900001900F520F530F520F640F660F650F650F650F650F660F650F650F640F640F550F550F540F560F580F570F540F570F560F550F5A0F550F580F570F5C0F5F0F5E0F610F5E0F5D0F5E0F5F0F5E0F5D0F610F5F0F610F600F600F610F610F610F600F630F630F600F610F610F610F620F620F610F6A0F6C0F6B0F6A0F6C0F6B0F6A0F6B0F6B0F6B0F6A0F610F630F630F630F640F660F640F630F630F630F580F5A0F580F5B0F550F580F5A0F5A0F590F580F5A0F620F650F650F650F660F640F640F640F640F640F660F650F640F650F660F650F670F670F670F670F630F620F680F670F650F650F670F650F610F5F0F600F620F5E0F5C0F590F4C0F490F480F440F470F480F470F420F430F450F420F450F440F440F430F530F540F520F400F410F4109010100084B4B4B4B4A4A4B4A3001026907B2FF00FF00380002002800000008006C00016C00080008000000080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008002800070007000700070007000700070007000700070007000700070007000700070007000700070007000700070007000700080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000800080008000831010E9C0005FFFFFFFF0E9CFFFFFFFF0083320E9C1B6115E212465733FFFFFFFFFF34FFFFFFFFFF002B800009690E9C2710000D000E83002402020500002700080001000000FD00000000FFFFFFFFFFFFFFFFFFFFFFFF1FFE1FF3001DBA"
 func TestExtractFramesKeepsPartialRemainderAndParsesHeader(t *testing.T) {
 	first := buildFrame(0x02, 0xfe, "LNBSCB3D4R1234567", []byte{0x1a, 0x06, 0x1e, 0x16, 0x17, 0x39})
 	second := buildFrame(0x05, 0xfe, "PLATFORM-LOGIN001", nil)
 	stream := append([]byte{0x00, 0x01}, first...)
 	stream = append(stream, second[:len(second)-3]...)
 	frames, remainder, err := ExtractFrames(stream)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 {
 		t.Fatalf("expected one complete frame, got %d", len(frames))
 	}
 	if string(remainder) != string(second[:len(second)-3]) {
 		t.Fatalf("expected partial second frame as remainder, got %s", hex.EncodeToString(remainder))
 	}
 	env, err := ParseFrame(frames[0], 1782745114999, "115.29.187.205:32960")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.Protocol != envelope.ProtocolGB32960 || env.MessageID != "0x02" {
 		t.Fatalf("unexpected envelope header: %#v", env)
 	}
 	if env.VIN != "LNBSCB3D4R1234567" {
 		t.Fatalf("unexpected vin: %q", env.VIN)
 	}
 }
 func TestParseFrameRejectsBadBCC(t *testing.T) {
 	frame := buildFrame(0x02, 0xfe, "LNBSCB3D4R1234567", nil)
 	frame[len(frame)-1] ^= 0xff
 	if _, err := ParseFrame(frame, 1782745114999, ""); err == nil {
 		t.Fatal("expected bad bcc error")
 	}
 }
 func TestExtractFramesSupportsExtendedPlatformLogin(t *testing.T) {
 	body := []byte{0x1a, 0x07, 0x02, 0x00, 0x26, 0x1f, 0x00, 0x01}
 	body = append(body, fixedASCII("Hyundai", 12)...)
 	body = append(body, fixedASCII("f2e3445d7cda409fb4f278f6fb890734", 32)...)
 	body = append(body, 0x01)
 	frame := buildFrameWithDeclaredLength(0x05, 0xfe, "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", body, 41)
 	frames, remainder, err := ExtractFrames(append(frame, []byte{0x23, 0x23, 0x05}...))
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 || len(remainder) != 3 {
 		t.Fatalf("unexpected split frames=%d remainder=%s", len(frames), hex.EncodeToString(remainder))
 	}
 	if len(frames[0]) != headerLen+53+1 {
 		t.Fatalf("extended frame len = %d", len(frames[0]))
 	}
 	env, err := ParseFrame(frames[0], 1782745114999, "8.134.95.166:39376")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.MessageID != "0x05" || env.ParseStatus != envelope.ParseOK {
 		t.Fatalf("unexpected env: %#v", env)
 	}
 	header := env.Parsed["header"].(map[string]any)
 	if header["body_length"] != 41 || header["actual_body_length"] != 53 {
 		t.Fatalf("unexpected length header: %#v", header)
 	}
 	login := env.Parsed["platform_login"].(map[string]any)
 	if login["username"] != "Hyundai" || login["password"] != "f2e3445d7cda409fb4f278f6fb890734" {
 		t.Fatalf("unexpected platform login: %#v", login)
 	}
 	if login["login_time"] != "2026-07-02T00:38:31+08:00" {
 		t.Fatalf("unexpected login time: %#v", login)
 	}
 	if env.Fields["platform_account"] != "Hyundai" {
 		t.Fatalf("platform account not exposed: %#v", env.Fields)
 	}
 }
 func TestAutoResponseEchoesRawVINAndOriginalTime(t *testing.T) {
 	body := []byte{0x1a, 0x07, 0x02, 0x00, 0x26, 0x0f, 0x00, 0x01}
 	body = append(body, fixedASCII("Hyundai", 12)...)
 	body = append(body, fixedASCII("ack-test-password", 32)...)
 	body = append(body, 0x01)
 	request := buildFrameWithDeclaredLength(0x05, 0xfe, "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", body, 41)
 	env, err := ParseFrame(request, 1782914969584, "8.134.95.166:39376")
 	if err != nil {
 		t.Fatal(err)
 	}
 	response, ok, err := AutoResponse(request, env)
 	if err != nil {
 		t.Fatalf("AutoResponse() error = %v", err)
 	}
 	if !ok {
 		t.Fatal("expected response")
 	}
 	if response[2] != 0x05 || response[3] != 0x01 {
 		t.Fatalf("unexpected response header: %x", response[:4])
 	}
 	if hex.EncodeToString(response[4:21]) != "0000000000000000000000000000000000" {
 		t.Fatalf("raw vin not echoed: %x", response[4:21])
 	}
 	if hex.EncodeToString(response[24:30]) != "1a070200260f" {
 		t.Fatalf("timestamp body not preserved: %x", response[24:30])
 	}
 	if got, want := bcc(response[2:len(response)-1]), response[len(response)-1]; got != want {
 		t.Fatalf("response bcc got=0x%02x want=0x%02x", got, want)
 	}
 }
 func TestParseFrameExtractsRealtimeVehicleMileageAndPosition(t *testing.T) {
 	body := []byte{0x1a, 0x06, 0x1e, 0x16, 0x17, 0x39}
 	body = append(body, 0x01)
 	body = append(body,
 		0x01,       // vehicle status
 		0x03,       // charge status
 		0x02,       // running mode
 		0x01, 0x2c, // speed: 30.0km/h
 		0x00, 0x01, 0x86, 0xa0, // total mileage: 10000.0km
 		0x15, 0xe5, // total voltage: 560.5V
 		0x27, 0x10, // total current: 0A after -1000 offset
 		85, 0x01, 0x00,
 		0x27, 0x10,
 		0x00, 0x00)
 	body = append(body, 0x05)
 	body = append(body,
 		0x00,
 		0x07, 0x36, 0x50, 0x40, // longitude: 121.000000
 		0x01, 0xd2, 0x4f, 0x00) // latitude: 30.560000
 	frame := buildFrame(0x02, 0xfe, "LNBSCB3D4R1234567", body)
 	env, err := ParseFrame(frame, 1782745114999, "115.29.187.205:32960")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	assertFloatField(t, env, envelope.FieldSpeedKMH, 30.0)
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 10000.0)
 	assertFloatField(t, env, envelope.FieldLongitude, 121.0)
 	assertFloatField(t, env, envelope.FieldLatitude, 30.56)
 	if env.Fields[envelope.FieldSOCPercent] != 85 {
 		t.Fatalf("unexpected soc: %#v", env.Fields[envelope.FieldSOCPercent])
 	}
 	if env.EventTimeMS == 1782745114999 {
 		t.Fatal("event time should come from GB32960 device timestamp")
 	}
 }
 func TestParseFrameKeepsParsingRealFuelCellReportUntilUnknownExtension(t *testing.T) {
 	frame, err := hex.DecodeString(realFuelCellFrame)
 	if err != nil {
 		t.Fatal(err)
 	}
 	env, err := ParseFrame(frame, 1782914969584, "115.29.187.205:32960")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.VIN != "LB9A32A21R0LS1707" {
 		t.Fatalf("vin = %q", env.VIN)
 	}
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 53490.9)
 	assertFloatField(t, env, "fuel_cell_hydrogen_consumption_kg_per_100km", 1.8)
 	assertFloatField(t, env, envelope.FieldLongitude, 120.800326)
 	assertFloatField(t, env, envelope.FieldLatitude, 31.634907)
 	assertFloatField(t, env, "gd_fc_stack_hydrogen_inlet_pressure_kpa", 97.0)
 	assertFloatField(t, env, "gd_fc_vehicle_hydrogen_mass_kg", 4.3)
 	assertIntField(t, env, "gd_fc_demo_stack_temp_c", 65)
 	units, ok := env.Parsed["data_units"].([]map[string]any)
 	if !ok {
 		t.Fatalf("data_units missing: %#v", env.Parsed["data_units"])
 	}
 	gotTypes := make([]string, 0, len(units))
 	for _, unit := range units {
 		gotTypes = append(gotTypes, fmt.Sprint(unit["type"]))
 	}
 	wantTypes := []string{"0x01", "0x02", "0x03", "0x04", "0x05", "0x06", "0x07", "0x08", "0x09", "0x30", "0x31", "0x32", "0x33", "0x34", "0x80", "0x83"}
 	if fmt.Sprint(gotTypes) != fmt.Sprint(wantTypes) {
 		t.Fatalf("unit types = %v, want %v", gotTypes, wantTypes)
 	}
 	if units[1]["name"] != "drive_motor" {
 		t.Fatalf("unexpected motor unit: %#v", units[1])
 	}
 	if units[2]["name"] != "fuel_cell" {
 		t.Fatalf("unexpected fuel cell unit: %#v", units[2])
 	}
 	if units[9]["name"] != "gd_fc_stack" {
 		t.Fatalf("unexpected gd stack unit: %#v", units[9])
 	}
 	if units[10]["name"] != "gd_fc_auxiliary" {
 		t.Fatalf("unexpected gd auxiliary unit: %#v", units[10])
 	}
 	if units[15]["name"] != "gd_fc_vendor_tlv" {
 		t.Fatalf("unexpected gd vendor tlv unit: %#v", units[15])
 	}
 	tlv := units[15]["value"].(map[string]any)
 	if tlv["declared_length"] != 36 {
 		t.Fatalf("unexpected vendor tlv: %#v", tlv)
 	}
 }
 func assertFloatField(t *testing.T, env envelope.FrameEnvelope, key string, want float64) {
 	t.Helper()
 	got, ok := env.Fields[key].(float64)
 	if !ok {
 		t.Fatalf("field %s missing or not float64: %#v", key, env.Fields[key])
 	}
 	if math.Abs(got-want) > 0.000001 {
 		t.Fatalf("field %s = %v, want %v", key, got, want)
 	}
 }
 func assertIntField(t *testing.T, env envelope.FrameEnvelope, key string, want int) {
 	t.Helper()
 	got, ok := env.Fields[key].(int)
 	if !ok {
 		t.Fatalf("field %s missing or not int: %#v", key, env.Fields[key])
 	}
 	if got != want {
 		t.Fatalf("field %s = %v, want %v", key, got, want)
 	}
 }
 func buildFrame(command byte, response byte, vin string, body []byte) []byte {
 	return buildFrameWithDeclaredLength(command, response, vin, body, len(body))
 }
 func buildFrameWithDeclaredLength(command byte, response byte, vin string, body []byte, declaredBodyLen int) []byte {
 	frame := []byte{'#', '#', command, response}
 	vinBytes := []byte(vin)
 	if len(vinBytes) < 17 {
 		vinBytes = append(vinBytes, make([]byte, 17-len(vinBytes))...)
 	}
 	frame = append(frame, vinBytes[:17]...)
 	frame = append(frame, 0x01, byte(declaredBodyLen>>8), byte(declaredBodyLen))
 	frame = append(frame, body...)
 	return append(frame, bcc(frame[2:]))
 }
 func fixedASCII(value string, size int) []byte {
 	out := make([]byte, size)
 	copy(out, []byte(value))
 	return out
 }
--- a/go/vehicle-gateway/internal/protocol/gb32960/response.go
+++ b/go/vehicle-gateway/internal/protocol/gb32960/response.go
@@ -0,0 +1,80 @@
 package gb32960
 import (
 	"encoding/binary"
 	"errors"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 var ErrResponseFrameTooShort = errors.New("gb32960 response frame too short")
 const (
 	responseSuccess = byte(0x01)
 	responseCommand = byte(0xfe)
 	encryptNone     = byte(0x01)
 )
 // AutoResponse builds the protocol ACK for accepted upstream GB/T 32960 frames.
 // The ACK is written only after the caller has durably published the frame.
 func AutoResponse(raw []byte, env envelope.FrameEnvelope) ([]byte, bool, error) {
 	if env.ParseStatus == envelope.ParseBadFrame {
 		return nil, false, nil
 	}
 	if len(raw) < headerLen+1 {
 		return nil, false, ErrResponseFrameTooShort
 	}
 	if raw[3] != responseCommand {
 		return nil, false, nil
 	}
 	command := raw[2]
 	if !shouldRespond(command) {
 		return nil, false, nil
 	}
 	body := []byte(nil)
 	if timestamp := responseTime(raw, command); !timestamp.IsZero() {
 		body = encodeGBTime(timestamp)
 	}
 	return buildResponse(raw[0], command, responseSuccess, raw[4:21], body), true, nil
 }
 func shouldRespond(command byte) bool {
 	switch command {
 	case 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08:
 		return true
 	default:
 		return false
 	}
 }
 func responseTime(raw []byte, command byte) time.Time {
 	bodyLen := len(raw) - headerLen - 1
 	if bodyLen >= 6 {
 		return parseGBTime(raw[headerLen : headerLen+6])
 	}
 	return time.Now().In(time.FixedZone("Asia/Shanghai", 8*3600))
 }
 func encodeGBTime(t time.Time) []byte {
 	local := t.In(time.FixedZone("Asia/Shanghai", 8*3600))
 	return []byte{
 		byte(local.Year() - 2000),
 		byte(local.Month()),
 		byte(local.Day()),
 		byte(local.Hour()),
 		byte(local.Minute()),
 		byte(local.Second()),
 	}
 }
 func buildResponse(start byte, command byte, responseFlag byte, vin17 []byte, body []byte) []byte {
 	out := make([]byte, 0, headerLen+len(body)+1)
 	out = append(out, start, start, command, responseFlag)
 	out = append(out, vin17[:17]...)
 	out = append(out, encryptNone, 0, 0)
 	binary.BigEndian.PutUint16(out[22:24], uint16(len(body)))
 	out = append(out, body...)
 	return append(out, bcc(out[2:]))
 }
--- a/go/vehicle-gateway/internal/protocol/jt808/parser.go
+++ b/go/vehicle-gateway/internal/protocol/jt808/parser.go
@@ -0,0 +1,600 @@
 package jt808
 import (
 	"bytes"
 	"encoding/binary"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"strings"
 	"time"
 	"unicode/utf8"
 	"golang.org/x/text/encoding/simplifiedchinese"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 var (
 	ErrFrameTooShort = errors.New("jt808 frame too short")
 	ErrChecksum      = errors.New("jt808 checksum mismatch")
 	ErrEscape        = errors.New("jt808 invalid escape sequence")
 )
 type Location struct {
 	AlarmFlag      uint32
 	StatusFlag     uint32
 	Latitude       float64
 	Longitude      float64
 	AltitudeM      uint16
 	SpeedKMH       float64
 	DirectionDeg   uint16
 	Time           time.Time
 	TotalMileageKM *float64
 	Additional     []AdditionalItem
 }
 type AdditionalItem struct {
 	ID       byte
 	Length   int
 	ValueHex string
 	Parsed   any
 }
 // ExtractFrames splits JT/T 808 TCP streams by 0x7e delimiters and unescapes
 // complete frame payloads. Returned frames exclude the leading and trailing 0x7e.
 func ExtractFrames(stream []byte) (frames [][]byte, remainder []byte, err error) {
 	start := -1
 	for i, value := range stream {
 		if value != 0x7e {
 			continue
 		}
 		if start < 0 {
 			start = i
 			continue
 		}
 		if i == start+1 {
 			start = i
 			continue
 		}
 		frame, err := unescape(stream[start+1 : i])
 		if err != nil {
 			return nil, nil, err
 		}
 		frames = append(frames, frame)
 		start = i
 	}
 	if start >= 0 && start < len(stream)-1 {
 		return frames, append([]byte(nil), stream[start:]...), nil
 	}
 	return frames, nil, nil
 }
 func ParseFrame(raw []byte, receivedAtMS int64, sourceEndpoint string) (envelope.FrameEnvelope, error) {
 	if len(raw) < 13 {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: len=%d", ErrFrameTooShort, len(raw))
 	}
 	if got, want := checksum(raw[:len(raw)-1]), raw[len(raw)-1]; got != want {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: got=0x%02x want=0x%02x", ErrChecksum, got, want)
 	}
 	messageID := binary.BigEndian.Uint16(raw[0:2])
 	props := binary.BigEndian.Uint16(raw[2:4])
 	bodySize := props & 0x03ff
 	versioned := props&0x4000 != 0
 	headerLen := 12
 	phoneStart := 4
 	phoneEnd := 10
 	serialStart := 10
 	packageInfo := map[string]any(nil)
 	protocolVersion := byte(0)
 	if versioned {
 		headerLen = 17
 		if len(raw) < headerLen {
 			return envelope.FrameEnvelope{}, fmt.Errorf("%w: versioned header len=%d", ErrFrameTooShort, len(raw))
 		}
 		protocolVersion = raw[4]
 		phoneStart = 5
 		phoneEnd = 15
 		serialStart = 15
 	}
 	subpackage := props&0x2000 != 0
 	if subpackage {
 		headerLen += 4
 	}
 	if len(raw) < headerLen+int(bodySize)+1 {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: bodySize=%d len=%d", ErrFrameTooShort, bodySize, len(raw))
 	}
 	if subpackage {
 		packageInfo = map[string]any{
 			"total": binary.BigEndian.Uint16(raw[serialStart+2 : serialStart+4]),
 			"index": binary.BigEndian.Uint16(raw[serialStart+4 : serialStart+6]),
 		}
 	}
 	phoneBCD := raw[phoneStart:phoneEnd]
 	phone := bcdString(phoneBCD)
 	phoneTrimZero := strings.TrimLeft(phone, "0")
 	if versioned && phoneTrimZero != "" {
 		phone = phoneTrimZero
 	}
 	body := raw[headerLen : headerLen+int(bodySize)]
 	parsed := map[string]any{
 		"header": map[string]any{
 			"message_id":       fmt.Sprintf("0x%04X", messageID),
 			"protocol_version": protocolVersion,
 			"versioned":        versioned,
 			"properties":       props,
 			"body_size":        bodySize,
 			"phone_bcd_hex":    strings.ToUpper(hex.EncodeToString(phoneBCD)),
 			"phone":            phone,
 			"phone_trim_zero":  phoneTrimZero,
 			"sequence":         binary.BigEndian.Uint16(raw[serialStart : serialStart+2]),
 			"subpackage":       subpackage,
 			"package_info":     packageInfo,
 			"encryption_flags": (props >> 10) & 0x07,
 		},
 	}
 	fields := map[string]any{}
 	eventTimeMS := receivedAtMS
 	if messageID == 0x0200 {
 		location, err := parseLocation(body)
 		if err != nil {
 			return envelope.FrameEnvelope{}, err
 		}
 		parsed["location"] = locationToMap(location)
 		fields[envelope.FieldLatitude] = location.Latitude
 		fields[envelope.FieldLongitude] = location.Longitude
 		fields[envelope.FieldSpeedKMH] = location.SpeedKMH
 		fields["altitude_m"] = location.AltitudeM
 		fields["direction_deg"] = location.DirectionDeg
 		fields["alarm_flag"] = location.AlarmFlag
 		fields["status_flag"] = location.StatusFlag
 		if !location.Time.IsZero() {
 			eventTimeMS = location.Time.UnixMilli()
 			fields["device_time"] = location.Time.Format(time.RFC3339)
 		}
 		if location.TotalMileageKM != nil {
 			fields[envelope.FieldTotalMileageKM] = *location.TotalMileageKM
 		}
 	} else if messageID == 0x0100 {
 		registration, err := parseRegistration(body, versioned)
 		if err != nil {
 			return envelope.FrameEnvelope{}, err
 		}
 		parsed["registration"] = registration
 		if deviceID, ok := registration["device_id"].(string); ok {
 			fields["device_id"] = deviceID
 		}
 		if plate, ok := registration["plate"].(string); ok {
 			fields["plate"] = plate
 		}
 	} else if messageID == 0x0102 {
 		authentication := parseAuthentication(body, versioned)
 		parsed["authentication"] = authentication
 		if token, ok := authentication["token"].(string); ok {
 			fields["auth_token"] = token
 		}
 	}
 	env := envelope.FrameEnvelope{
 		Protocol:       envelope.ProtocolJT808,
 		MessageID:      fmt.Sprintf("0x%04X", messageID),
 		Sequence:       binary.BigEndian.Uint16(raw[serialStart : serialStart+2]),
 		Phone:          phone,
 		SourceEndpoint: sourceEndpoint,
 		EventTimeMS:    eventTimeMS,
 		ReceivedAtMS:   receivedAtMS,
 		RawHex:         strings.ToUpper(hex.EncodeToString(raw)),
 		Parsed:         parsed,
 		Fields:         fields,
 		ParseStatus:    envelope.ParseOK,
 	}
 	if registration, ok := parsed["registration"].(map[string]any); ok {
 		env.DeviceID, _ = registration["device_id"].(string)
 		env.Plate, _ = registration["plate"].(string)
 	}
 	env.EventID = env.StableEventID()
 	return env, nil
 }
 func parseRegistration(body []byte, versioned bool) (map[string]any, error) {
 	schemaVersion := "2011_2013"
 	manufacturerSize := 5
 	deviceTypeSize := 20
 	deviceIDSize := 7
 	if versioned {
 		schemaVersion = "2019"
 		manufacturerSize = 11
 		deviceTypeSize = 30
 		deviceIDSize = 30
 	}
 	minLen := 2 + 2 + manufacturerSize + deviceTypeSize + deviceIDSize + 1
 	if len(body) < minLen {
 		return nil, fmt.Errorf("%w: registration body len=%d", ErrFrameTooShort, len(body))
 	}
 	manufacturerStart := 4
 	deviceTypeStart := manufacturerStart + manufacturerSize
 	deviceIDStart := deviceTypeStart + deviceTypeSize
 	plateColorStart := deviceIDStart + deviceIDSize
 	registration := map[string]any{
 		"schema_version": schemaVersion,
 		"province":       binary.BigEndian.Uint16(body[0:2]),
 		"city":           binary.BigEndian.Uint16(body[2:4]),
 		"manufacturer":   fixedText(body[manufacturerStart:deviceTypeStart]),
 		"device_type":    fixedText(body[deviceTypeStart:deviceIDStart]),
 		"device_id":      fixedText(body[deviceIDStart:plateColorStart]),
 		"plate_color":    body[plateColorStart],
 		"plate":          freeText(body[plateColorStart+1:]),
 	}
 	return registration, nil
 }
 func parseAuthentication(body []byte, versioned bool) map[string]any {
 	if versioned {
 		if out, ok := parseVersionedAuthentication(body); ok {
 			return out
 		}
 		if out, ok := parseDelimitedVersionedAuthentication(body); ok {
 			return out
 		}
 	}
 	return map[string]any{"token": freeText(body)}
 }
 func parseVersionedAuthentication(body []byte) (map[string]any, bool) {
 	if len(body) < 17 {
 		return nil, false
 	}
 	tokenLen := int(body[0])
 	imeiStart := 1 + tokenLen
 	softwareLenStart := imeiStart + 15
 	if tokenLen <= 0 || len(body) < softwareLenStart+1 {
 		return nil, false
 	}
 	softwareLen := int(body[softwareLenStart])
 	softwareStart := softwareLenStart + 1
 	if len(body) < softwareStart+softwareLen {
 		return nil, false
 	}
 	return map[string]any{
 		"schema_version":   "2019",
 		"token":            freeText(body[1:imeiStart]),
 		"imei":             fixedText(body[imeiStart:softwareLenStart]),
 		"software_version": freeText(body[softwareStart : softwareStart+softwareLen]),
 	}, true
 }
 func parseDelimitedVersionedAuthentication(body []byte) (map[string]any, bool) {
 	parts := bytes.Split(body, []byte{0xff, 0xff})
 	if len(parts) < 2 {
 		return nil, false
 	}
 	out := map[string]any{
 		"schema_version": "2019_delimited",
 		"token":          freeText(parts[0]),
 		"imei":           freeText(parts[1]),
 	}
 	if len(parts) > 2 {
 		out["software_version"] = freeText(parts[2])
 	}
 	return out, true
 }
 func parseLocation(body []byte) (Location, error) {
 	if len(body) < 28 {
 		return Location{}, fmt.Errorf("%w: location body len=%d", ErrFrameTooShort, len(body))
 	}
 	status := binary.BigEndian.Uint32(body[4:8])
 	latitude := float64(binary.BigEndian.Uint32(body[8:12])) / 1_000_000
 	longitude := float64(binary.BigEndian.Uint32(body[12:16])) / 1_000_000
 	if status&(1<<2) != 0 {
 		latitude = -latitude
 	}
 	if status&(1<<3) != 0 {
 		longitude = -longitude
 	}
 	location := Location{
 		AlarmFlag:    binary.BigEndian.Uint32(body[0:4]),
 		StatusFlag:   status,
 		Latitude:     latitude,
 		Longitude:    longitude,
 		AltitudeM:    binary.BigEndian.Uint16(body[16:18]),
 		SpeedKMH:     float64(binary.BigEndian.Uint16(body[18:20])) / 10,
 		DirectionDeg: binary.BigEndian.Uint16(body[20:22]),
 		Time:         parseBCDTime(body[22:28]),
 	}
 	location.Additional = parseAdditional(body[28:], &location)
 	return location, nil
 }
 func parseAdditional(data []byte, location *Location) []AdditionalItem {
 	var out []AdditionalItem
 	for len(data) >= 2 {
 		id := data[0]
 		size := int(data[1])
 		data = data[2:]
 		if len(data) < size {
 			out = append(out, AdditionalItem{
 				ID:       id,
 				Length:   size,
 				ValueHex: strings.ToUpper(hex.EncodeToString(data)),
 				Parsed:   "truncated",
 			})
 			return out
 		}
 		value := data[:size]
 		item := AdditionalItem{
 			ID:       id,
 			Length:   size,
 			ValueHex: strings.ToUpper(hex.EncodeToString(value)),
 		}
 		switch {
 		case id == 0x01 && size == 4:
 			rawMileage := binary.BigEndian.Uint32(value)
 			mileage := float64(rawMileage) / 10
 			location.TotalMileageKM = &mileage
 			item.Parsed = map[string]any{
 				"name":               envelope.FieldTotalMileageKM,
 				"raw_value_tenth_km": rawMileage,
 				"value":              mileage,
 				"unit":               "km",
 			}
 		case id == 0x02 && size == 2:
 			rawFuel := binary.BigEndian.Uint16(value)
 			item.Parsed = map[string]any{
 				"name":              "fuel_l",
 				"raw_value_tenth_l": rawFuel,
 				"value":             float64(rawFuel) / 10,
 				"unit":              "L",
 			}
 		case id == 0x03 && size == 2:
 			rawSpeed := binary.BigEndian.Uint16(value)
 			item.Parsed = map[string]any{
 				"name":                "recorder_speed_kmh",
 				"raw_value_tenth_kmh": rawSpeed,
 				"value":               float64(rawSpeed) / 10,
 				"unit":                "km/h",
 			}
 		case id == 0x04 && size == 2:
 			item.Parsed = map[string]any{
 				"name":  "manual_alarm_event_id",
 				"value": binary.BigEndian.Uint16(value),
 			}
 		case id == 0x05 && size == 30:
 			item.Parsed = map[string]any{
 				"name":   "tire_pressure",
 				"values": parseTirePressure(value),
 			}
 		case id == 0x06 && size == 2:
 			item.Parsed = map[string]any{
 				"name":  "carriage_temperature_c",
 				"value": int16(binary.BigEndian.Uint16(value)),
 				"unit":  "C",
 			}
 		case id == 0x11 && (size == 1 || size == 5):
 			parsed := map[string]any{
 				"name":          "overspeed_alarm",
 				"location_type": value[0],
 			}
 			if size == 5 {
 				parsed["area_id"] = binary.BigEndian.Uint32(value[1:5])
 			}
 			item.Parsed = parsed
 		case id == 0x12 && size == 6:
 			item.Parsed = map[string]any{
 				"name":          "area_route_alarm",
 				"location_type": value[0],
 				"area_id":       binary.BigEndian.Uint32(value[1:5]),
 				"direction":     value[5],
 			}
 		case id == 0x13 && size == 7:
 			item.Parsed = map[string]any{
 				"name":                       "road_section_driving_time_alarm",
 				"road_section_id":            binary.BigEndian.Uint32(value[0:4]),
 				"driving_time_seconds":       binary.BigEndian.Uint16(value[4:6]),
 				"result":                     value[6],
 				"result_description":         roadSectionDrivingTimeResult(value[6]),
 				"driving_time_result_source": "jt808_0x0200_additional_0x13",
 			}
 		case id == 0x25 && size == 4:
 			rawStatus := binary.BigEndian.Uint32(value)
 			item.Parsed = map[string]any{
 				"name":  "extended_vehicle_signal_status",
 				"value": rawStatus,
 				"bits":  parseExtendedVehicleSignal(rawStatus),
 			}
 		case id == 0x2a && size == 2:
 			rawStatus := binary.BigEndian.Uint16(value)
 			item.Parsed = map[string]any{
 				"name":  "io_status",
 				"value": rawStatus,
 				"bits":  parseIOStatus(rawStatus),
 			}
 		case id == 0x2b && size == 4:
 			analog := binary.BigEndian.Uint32(value)
 			item.Parsed = map[string]any{
 				"name":  "analog",
 				"ad0":   analog & 0xffff,
 				"ad1":   analog >> 16,
 				"value": analog,
 			}
 		case id == 0x30 && size == 1:
 			item.Parsed = map[string]any{
 				"name":  "network_signal_strength",
 				"value": value[0],
 			}
 		case id == 0x31 && size == 1:
 			item.Parsed = map[string]any{
 				"name":  "gnss_satellite_count",
 				"value": value[0],
 			}
 		}
 		out = append(out, item)
 		data = data[size:]
 	}
 	return out
 }
 func locationToMap(location Location) map[string]any {
 	out := map[string]any{
 		"alarm_flag":    location.AlarmFlag,
 		"status_flag":   location.StatusFlag,
 		"latitude":      location.Latitude,
 		"longitude":     location.Longitude,
 		"altitude_m":    location.AltitudeM,
 		"speed_kmh":     location.SpeedKMH,
 		"direction_deg": location.DirectionDeg,
 		"additional":    additionalToMaps(location.Additional),
 	}
 	if !location.Time.IsZero() {
 		out["device_time"] = location.Time.Format(time.RFC3339)
 	}
 	if location.TotalMileageKM != nil {
 		out[envelope.FieldTotalMileageKM] = *location.TotalMileageKM
 	}
 	return out
 }
 func additionalToMaps(items []AdditionalItem) []map[string]any {
 	out := make([]map[string]any, 0, len(items))
 	for _, item := range items {
 		value := map[string]any{
 			"id":        fmt.Sprintf("0x%02X", item.ID),
 			"length":    item.Length,
 			"value_hex": item.ValueHex,
 		}
 		if item.Parsed != nil {
 			value["parsed"] = item.Parsed
 		}
 		out = append(out, value)
 	}
 	return out
 }
 func parseTirePressure(data []byte) []map[string]any {
 	out := make([]map[string]any, 0, len(data))
 	for index, value := range data {
 		out = append(out, map[string]any{
 			"position": index,
 			"value":    value,
 			"valid":    value != 0xff,
 		})
 	}
 	return out
 }
 func parseExtendedVehicleSignal(value uint32) map[string]bool {
 	return map[string]bool{
 		"low_beam":        value&0x0001 != 0,
 		"high_beam":       value&0x0002 != 0,
 		"right_turn":      value&0x0004 != 0,
 		"left_turn":       value&0x0008 != 0,
 		"brake":           value&0x0010 != 0,
 		"reverse_gear":    value&0x0020 != 0,
 		"fog_light":       value&0x0040 != 0,
 		"clearance_light": value&0x0080 != 0,
 		"horn":            value&0x0100 != 0,
 		"air_conditioner": value&0x0200 != 0,
 		"neutral":         value&0x0400 != 0,
 		"retarder":        value&0x0800 != 0,
 		"abs":             value&0x1000 != 0,
 		"heater":          value&0x2000 != 0,
 		"clutch":          value&0x4000 != 0,
 	}
 }
 func parseIOStatus(value uint16) map[string]bool {
 	return map[string]bool{
 		"deep_sleep": value&0x0001 != 0,
 		"sleep":      value&0x0002 != 0,
 	}
 }
 func roadSectionDrivingTimeResult(value byte) string {
 	if value == 0 {
 		return "insufficient"
 	}
 	if value == 1 {
 		return "too_long"
 	}
 	return "unknown"
 }
 func bcdString(data []byte) string {
 	out := make([]byte, 0, len(data)*2)
 	for _, value := range data {
 		out = append(out, '0'+((value>>4)&0x0f), '0'+(value&0x0f))
 	}
 	return string(out)
 }
 func fixedText(data []byte) string {
 	return strings.Trim(freeText(data), "\x00 ")
 }
 func freeText(data []byte) string {
 	data = bytes.Trim(data, "\x00 ")
 	if len(data) == 0 {
 		return ""
 	}
 	if utf8.Valid(data) {
 		return string(data)
 	}
 	decoded, err := simplifiedchinese.GBK.NewDecoder().Bytes(data)
 	if err == nil && utf8.Valid(decoded) {
 		return string(decoded)
 	}
 	return strings.ToValidUTF8(string(data), "")
 }
 func parseBCDTime(data []byte) time.Time {
 	if len(data) != 6 {
 		return time.Time{}
 	}
 	year := 2000 + bcdByte(data[0])
 	month := time.Month(bcdByte(data[1]))
 	day := bcdByte(data[2])
 	hour := bcdByte(data[3])
 	minute := bcdByte(data[4])
 	second := bcdByte(data[5])
 	if month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59 {
 		return time.Time{}
 	}
 	return time.Date(year, month, day, hour, minute, second, 0, time.FixedZone("Asia/Shanghai", 8*3600))
 }
 func bcdByte(value byte) int {
 	return int(value>>4)*10 + int(value&0x0f)
 }
 func unescape(data []byte) ([]byte, error) {
 	out := make([]byte, 0, len(data))
 	for i := 0; i < len(data); i++ {
 		if data[i] != 0x7d {
 			out = append(out, data[i])
 			continue
 		}
 		if i+1 >= len(data) {
 			return nil, ErrEscape
 		}
 		i++
 		switch data[i] {
 		case 0x01:
 			out = append(out, 0x7d)
 		case 0x02:
 			out = append(out, 0x7e)
 		default:
 			return nil, ErrEscape
 		}
 	}
 	return out, nil
 }
 func checksum(data []byte) byte {
 	var out byte
 	for _, value := range data {
 		out ^= value
 	}
 	return out
 }
--- a/go/vehicle-gateway/internal/protocol/jt808/parser_test.go
+++ b/go/vehicle-gateway/internal/protocol/jt808/parser_test.go
@@ -0,0 +1,503 @@
 package jt808
 import (
 	"encoding/binary"
 	"encoding/hex"
 	"testing"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 const sampleLocationFrame = "7E020000320133077954250001000000000048000301D2C4C707376139000A00E6004F26063016235701040001900C2504000000000202000030011F31010F867E"
 const real2019LocationFrame = "7E02004046010000000001489413506007CB00000000004C000301D276AB06FBFF4B000D014E00E826070122092214040000000017020000010400013361030201402504000000012A02000030011D310112EA0402008000C57E"
 const fullAdditionalLocationFrame = "7e020000800123456789017fff000004000000080006eeb6ad02633df701380003006320070719235901040000000b02020016030200210402002c051e3737370000000000000000000000000000000000000000000000000000001105420000004212064d0000004d4d1307000000580058582504000000632a02000a2b040000001430011e31012806020001927e"
 func TestExtractFramesUnescapesAndParsesLocationWithTotalMileage(t *testing.T) {
 	stream, err := hex.DecodeString(sampleLocationFrame + "7E02000000")
 	if err != nil {
 		t.Fatal(err)
 	}
 	frames, remainder, err := ExtractFrames(stream)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 {
 		t.Fatalf("expected one complete frame, got %d", len(frames))
 	}
 	if hex.EncodeToString(remainder) != "7e02000000" {
 		t.Fatalf("expected partial remainder, got %s", hex.EncodeToString(remainder))
 	}
 	env, err := ParseFrame(frames[0], 1782745114999, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.Protocol != envelope.ProtocolJT808 {
 		t.Fatalf("protocol = %q", env.Protocol)
 	}
 	if env.MessageID != "0x0200" {
 		t.Fatalf("message id = %q", env.MessageID)
 	}
 	if env.Phone != "013307795425" {
 		t.Fatalf("phone = %q", env.Phone)
 	}
 	if env.Sequence != 1 {
 		t.Fatalf("sequence = %d", env.Sequence)
 	}
 	assertFloatField(t, env, envelope.FieldLatitude, 30.590151)
 	assertFloatField(t, env, envelope.FieldLongitude, 121.069881)
 	assertFloatField(t, env, envelope.FieldSpeedKMH, 23.0)
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 10241.2)
 	if env.Fields["direction_deg"] != uint16(79) {
 		t.Fatalf("direction = %#v", env.Fields["direction_deg"])
 	}
 	location, ok := env.Parsed["location"].(map[string]any)
 	if !ok {
 		t.Fatalf("parsed location missing: %#v", env.Parsed)
 	}
 	additional, ok := location["additional"].([]map[string]any)
 	if !ok || len(additional) == 0 {
 		t.Fatalf("additional fields missing: %#v", location["additional"])
 	}
 	if additional[0]["id"] != "0x01" || additional[0]["value_hex"] != "0001900C" {
 		t.Fatalf("unexpected first additional item: %#v", additional[0])
 	}
 	parsed, ok := additional[0]["parsed"].(map[string]any)
 	if !ok {
 		t.Fatalf("mileage parsed field missing: %#v", additional[0])
 	}
 	if parsed["raw_value_tenth_km"] != uint32(102412) || parsed["value"] != 10241.2 {
 		t.Fatalf("unexpected mileage parsed value: %#v", parsed)
 	}
 }
 func TestParseFrameSupportsJT8082019VersionedHeader(t *testing.T) {
 	stream, err := hex.DecodeString(real2019LocationFrame)
 	if err != nil {
 		t.Fatal(err)
 	}
 	frames, remainder, err := ExtractFrames(stream)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 || len(remainder) != 0 {
 		t.Fatalf("unexpected split result frames=%d remainder=%s", len(frames), hex.EncodeToString(remainder))
 	}
 	env, err := ParseFrame(frames[0], 1782914967713, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.MessageID != "0x0200" {
 		t.Fatalf("message id = %q", env.MessageID)
 	}
 	if env.Phone != "14894135060" {
 		t.Fatalf("phone = %q", env.Phone)
 	}
 	if env.Sequence != 1995 {
 		t.Fatalf("sequence = %d", env.Sequence)
 	}
 	assertFloatField(t, env, envelope.FieldLatitude, 30.570155)
 	assertFloatField(t, env, envelope.FieldLongitude, 117.178187)
 	assertFloatField(t, env, envelope.FieldSpeedKMH, 33.4)
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 7868.9)
 	if env.Fields["altitude_m"] != uint16(13) {
 		t.Fatalf("altitude = %#v", env.Fields["altitude_m"])
 	}
 	if env.Fields["direction_deg"] != uint16(232) {
 		t.Fatalf("direction = %#v", env.Fields["direction_deg"])
 	}
 	header, ok := env.Parsed["header"].(map[string]any)
 	if !ok {
 		t.Fatalf("parsed header missing: %#v", env.Parsed)
 	}
 	if header["versioned"] != true || header["protocol_version"] != byte(1) {
 		t.Fatalf("unexpected versioned header: %#v", header)
 	}
 	if header["phone_bcd_hex"] != "00000000014894135060" {
 		t.Fatalf("phone bcd = %#v", header["phone_bcd_hex"])
 	}
 }
 func TestParseFrameParsesCommonLocationAdditionalItems(t *testing.T) {
 	stream, err := hex.DecodeString(fullAdditionalLocationFrame)
 	if err != nil {
 		t.Fatal(err)
 	}
 	frames, remainder, err := ExtractFrames(stream)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 || len(remainder) != 0 {
 		t.Fatalf("unexpected split result frames=%d remainder=%s", len(frames), hex.EncodeToString(remainder))
 	}
 	env, err := ParseFrame(frames[0], 1782914967713, "127.0.0.1:808")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.Phone != "012345678901" {
 		t.Fatalf("phone = %q", env.Phone)
 	}
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 1.1)
 	location := env.Parsed["location"].(map[string]any)
 	additional := location["additional"].([]map[string]any)
 	byID := map[string]map[string]any{}
 	for _, item := range additional {
 		byID[item["id"].(string)] = item["parsed"].(map[string]any)
 	}
 	if byID["0x01"]["raw_value_tenth_km"] != uint32(11) || byID["0x01"]["value"] != 1.1 {
 		t.Fatalf("mileage parsed = %#v", byID["0x01"])
 	}
 	if byID["0x05"]["name"] != "tire_pressure" {
 		t.Fatalf("tire pressure missing: %#v", byID["0x05"])
 	}
 	tireValues := byID["0x05"]["values"].([]map[string]any)
 	if tireValues[0]["value"] != byte(0x37) || tireValues[0]["valid"] != true {
 		t.Fatalf("tire pressure first value = %#v", tireValues[0])
 	}
 	if byID["0x11"]["location_type"] != byte(0x42) || byID["0x11"]["area_id"] != uint32(0x42) {
 		t.Fatalf("overspeed parsed = %#v", byID["0x11"])
 	}
 	if byID["0x12"]["location_type"] != byte(0x4d) || byID["0x12"]["area_id"] != uint32(0x4d) || byID["0x12"]["direction"] != byte(0x4d) {
 		t.Fatalf("area route parsed = %#v", byID["0x12"])
 	}
 	if byID["0x13"]["road_section_id"] != uint32(0x58) || byID["0x13"]["driving_time_seconds"] != uint16(0x58) {
 		t.Fatalf("road section parsed = %#v", byID["0x13"])
 	}
 	ioBits := byID["0x2A"]["bits"].(map[string]bool)
 	if ioBits["deep_sleep"] || !ioBits["sleep"] {
 		t.Fatalf("io bits = %#v", ioBits)
 	}
 }
 func TestParseFrameRejectsTruncatedSubpackageHeader(t *testing.T) {
 	payload := []byte{0x02, 0x00, 0x20, 0x00}
 	payload = append(payload, encodeBCD("013307795425", 6)...)
 	payload = binary.BigEndian.AppendUint16(payload, 1)
 	payload = append(payload, checksum(payload))
 	_, err := ParseFrame(payload, 1782914967713, "115.231.168.135:43625")
 	if err == nil {
 		t.Fatal("expected truncated subpackage header to fail")
 	}
 }
 func TestParseLocationAppliesSouthWestStatusBits(t *testing.T) {
 	body := make([]byte, 28)
 	binary.BigEndian.PutUint32(body[4:8], (1<<2)|(1<<3))
 	binary.BigEndian.PutUint32(body[8:12], 12345678)
 	binary.BigEndian.PutUint32(body[12:16], 98765432)
 	location, err := parseLocation(body)
 	if err != nil {
 		t.Fatalf("parseLocation() error = %v", err)
 	}
 	if location.Latitude != -12.345678 {
 		t.Fatalf("latitude = %v", location.Latitude)
 	}
 	if location.Longitude != -98.765432 {
 		t.Fatalf("longitude = %v", location.Longitude)
 	}
 }
 func TestParseFrameParsesRegistrationIdentity(t *testing.T) {
 	body := make([]byte, 0, 46)
 	body = binary.BigEndian.AppendUint16(body, 16)
 	body = binary.BigEndian.AppendUint16(body, 32)
 	body = appendFixedASCII(body, "YUTNG", 5)
 	body = appendFixedASCII(body, "ZK6105CHEVNPG4", 20)
 	body = appendFixedASCII(body, "DEV0001", 7)
 	body = append(body, 2)
 	body = append(body, []byte("TEST123")...)
 	env, err := ParseFrame(buildFrame(0x0100, "013079963379", 7, body), 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.MessageID != "0x0100" {
 		t.Fatalf("message id = %q", env.MessageID)
 	}
 	if env.Phone != "013079963379" {
 		t.Fatalf("phone = %q", env.Phone)
 	}
 	if env.DeviceID != "DEV0001" {
 		t.Fatalf("device id = %q", env.DeviceID)
 	}
 	if env.Plate != "TEST123" {
 		t.Fatalf("plate = %q", env.Plate)
 	}
 	registration, ok := env.Parsed["registration"].(map[string]any)
 	if !ok {
 		t.Fatalf("registration missing: %#v", env.Parsed)
 	}
 	if registration["manufacturer"] != "YUTNG" || registration["device_type"] != "ZK6105CHEVNPG4" {
 		t.Fatalf("registration fields = %#v", registration)
 	}
 	if registration["plate_color"] != uint8(2) {
 		t.Fatalf("plate color = %#v", registration["plate_color"])
 	}
 }
 func TestParseFrameParsesJT8082019RegistrationIdentity(t *testing.T) {
 	body := make([]byte, 0, 84)
 	body = binary.BigEndian.AppendUint16(body, 16)
 	body = binary.BigEndian.AppendUint16(body, 32)
 	body = appendFixedASCII(body, "YUTONG00001", 11)
 	body = appendFixedASCII(body, "ZK6105CHEVNPG4-2019", 30)
 	body = appendFixedASCII(body, "DEV201900000000000000000000001", 30)
 	body = append(body, 2)
 	body = append(body, []byte("TEST2019")...)
 	env, err := ParseFrame(buildVersionedFrame(0x0100, "14894135060", 11, body), 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.Phone != "14894135060" {
 		t.Fatalf("phone = %q", env.Phone)
 	}
 	if env.DeviceID != "DEV201900000000000000000000001" {
 		t.Fatalf("device id = %q", env.DeviceID)
 	}
 	if env.Plate != "TEST2019" {
 		t.Fatalf("plate = %q", env.Plate)
 	}
 	registration, ok := env.Parsed["registration"].(map[string]any)
 	if !ok {
 		t.Fatalf("registration missing: %#v", env.Parsed)
 	}
 	if registration["schema_version"] != "2019" || registration["manufacturer"] != "YUTONG00001" {
 		t.Fatalf("registration fields = %#v", registration)
 	}
 }
 func TestParseFrameDecodesGBKRegistrationPlate(t *testing.T) {
 	body := make([]byte, 0, 46)
 	body = binary.BigEndian.AppendUint16(body, 16)
 	body = binary.BigEndian.AppendUint16(body, 32)
 	body = appendFixedASCII(body, "YUTNG", 5)
 	body = appendFixedASCII(body, "ZK6105CHEVNPG4", 20)
 	body = appendFixedASCII(body, "DEV0002", 7)
 	body = append(body, 2)
 	body = append(body, []byte{0xBB, 0xA6, 'A', '5', '3', '3', '0', '1'}...)
 	env, err := ParseFrame(buildFrame(0x0100, "013079963380", 9, body), 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.Plate != "沪A53301" {
 		t.Fatalf("plate = %q", env.Plate)
 	}
 }
 func TestParseFrameParsesJT8082019Authentication(t *testing.T) {
 	body := []byte{5}
 	body = append(body, []byte("TOKEN")...)
 	body = appendFixedASCII(body, "123456789012345", 15)
 	body = append(body, 4)
 	body = append(body, []byte("v1.2")...)
 	env, err := ParseFrame(buildVersionedFrame(0x0102, "14894135060", 12, body), 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	auth, ok := env.Parsed["authentication"].(map[string]any)
 	if !ok {
 		t.Fatalf("authentication missing: %#v", env.Parsed)
 	}
 	if auth["token"] != "TOKEN" || auth["imei"] != "123456789012345" || auth["software_version"] != "v1.2" {
 		t.Fatalf("authentication = %#v", auth)
 	}
 }
 func TestParseFrameParsesAuthenticationToken(t *testing.T) {
 	env, err := ParseFrame(buildFrame(0x0102, "064646848757", 8, []byte("g7gps")), 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatalf("ParseFrame() error = %v", err)
 	}
 	if env.MessageID != "0x0102" {
 		t.Fatalf("message id = %q", env.MessageID)
 	}
 	auth, ok := env.Parsed["authentication"].(map[string]any)
 	if !ok {
 		t.Fatalf("authentication missing: %#v", env.Parsed)
 	}
 	if auth["token"] != "g7gps" {
 		t.Fatalf("token = %#v", auth["token"])
 	}
 }
 func TestAutoResponderBuildsRegisterAck(t *testing.T) {
 	body := make([]byte, 0, 46)
 	body = binary.BigEndian.AppendUint16(body, 16)
 	body = binary.BigEndian.AppendUint16(body, 32)
 	body = appendFixedASCII(body, "YUTNG", 5)
 	body = appendFixedASCII(body, "ZK6105CHEVNPG4", 20)
 	body = appendFixedASCII(body, "DEV0001", 7)
 	body = append(body, 2)
 	body = append(body, []byte("TEST123")...)
 	request := buildFrame(0x0100, "013079963379", 9, body)
 	env, err := ParseFrame(request, 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatal(err)
 	}
 	response, ok, err := NewAutoResponder("g7gps").Respond(request, env)
 	if err != nil {
 		t.Fatalf("Respond() error = %v", err)
 	}
 	if !ok {
 		t.Fatal("expected response")
 	}
 	frames, remainder, err := ExtractFrames(response)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 || len(remainder) != 0 {
 		t.Fatalf("unexpected response split frames=%d remainder=%s", len(frames), hex.EncodeToString(remainder))
 	}
 	payload := frames[0]
 	if binary.BigEndian.Uint16(payload[0:2]) != 0x8100 {
 		t.Fatalf("message id = %04x", binary.BigEndian.Uint16(payload[0:2]))
 	}
 	if hex.EncodeToString(payload[4:10]) != "013079963379" {
 		t.Fatalf("phone bcd = %x", payload[4:10])
 	}
 	if binary.BigEndian.Uint16(payload[12:14]) != 9 || payload[14] != 0 || string(payload[15:20]) != "g7gps" {
 		t.Fatalf("unexpected register ack body: %x", payload[12:len(payload)-1])
 	}
 }
 func TestAutoResponderBuildsVersionedGeneralAck(t *testing.T) {
 	request := buildVersionedFrame(0x0200, "14894135060", 12, make([]byte, 28))
 	env, err := ParseFrame(request, 1782918600000, "115.231.168.135:43625")
 	if err != nil {
 		t.Fatal(err)
 	}
 	response, ok, err := NewAutoResponder("").Respond(request, env)
 	if err != nil {
 		t.Fatalf("Respond() error = %v", err)
 	}
 	if !ok {
 		t.Fatal("expected response")
 	}
 	frames, remainder, err := ExtractFrames(response)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 || len(remainder) != 0 {
 		t.Fatalf("unexpected response split frames=%d remainder=%s", len(frames), hex.EncodeToString(remainder))
 	}
 	payload := frames[0]
 	if binary.BigEndian.Uint16(payload[0:2]) != 0x8001 {
 		t.Fatalf("message id = %04x", binary.BigEndian.Uint16(payload[0:2]))
 	}
 	if binary.BigEndian.Uint16(payload[2:4])&0x4000 == 0 || payload[4] != 1 {
 		t.Fatalf("versioned header not preserved: %x", payload[:5])
 	}
 	if hex.EncodeToString(payload[5:15]) != "00000000014894135060" {
 		t.Fatalf("phone bcd = %x", payload[5:15])
 	}
 	bodyStart := 17
 	if binary.BigEndian.Uint16(payload[bodyStart:bodyStart+2]) != 12 ||
 		binary.BigEndian.Uint16(payload[bodyStart+2:bodyStart+4]) != 0x0200 ||
 		payload[bodyStart+4] != 0 {
 		t.Fatalf("unexpected general ack body: %x", payload[bodyStart:len(payload)-1])
 	}
 }
 func TestExtractFramesHandlesEscapedPayload(t *testing.T) {
 	payload := []byte{0x02, 0x00, 0x00, 0x02, 0x01, 0x33, 0x07, 0x79, 0x54, 0x25, 0x00, 0x01, 0x7e, 0x7d}
 	frame := append([]byte{0x7e}, escape(append(payload, checksum(payload)))...)
 	frame = append(frame, 0x7e)
 	frames, remainder, err := ExtractFrames(frame)
 	if err != nil {
 		t.Fatalf("ExtractFrames() error = %v", err)
 	}
 	if len(frames) != 1 || len(remainder) != 0 {
 		t.Fatalf("unexpected split result frames=%d remainder=%s", len(frames), hex.EncodeToString(remainder))
 	}
 	if hex.EncodeToString(frames[0][:len(payload)]) != hex.EncodeToString(payload) {
 		t.Fatalf("frame was not unescaped: %s", hex.EncodeToString(frames[0]))
 	}
 }
 func buildFrame(messageID uint16, phone string, sequence uint16, body []byte) []byte {
 	payload := make([]byte, 0, 12+len(body)+1)
 	payload = binary.BigEndian.AppendUint16(payload, messageID)
 	payload = binary.BigEndian.AppendUint16(payload, uint16(len(body)))
 	payload = append(payload, encodeBCD(phone, 6)...)
 	payload = binary.BigEndian.AppendUint16(payload, sequence)
 	payload = append(payload, body...)
 	payload = append(payload, checksum(payload))
 	return payload
 }
 func buildVersionedFrame(messageID uint16, phone string, sequence uint16, body []byte) []byte {
 	payload := make([]byte, 0, 17+len(body)+1)
 	payload = binary.BigEndian.AppendUint16(payload, messageID)
 	payload = binary.BigEndian.AppendUint16(payload, 0x4000|uint16(len(body)))
 	payload = append(payload, 1)
 	payload = append(payload, encodeBCD(phone, 10)...)
 	payload = binary.BigEndian.AppendUint16(payload, sequence)
 	payload = append(payload, body...)
 	payload = append(payload, checksum(payload))
 	return payload
 }
 func appendFixedASCII(out []byte, value string, size int) []byte {
 	start := len(out)
 	out = append(out, make([]byte, size)...)
 	copy(out[start:], []byte(value))
 	return out
 }
 func encodeBCD(value string, size int) []byte {
 	out := make([]byte, size)
 	if len(value)%2 == 1 {
 		value = "0" + value
 	}
 	if len(value) > size*2 {
 		value = value[len(value)-size*2:]
 	}
 	for len(value) < size*2 {
 		value = "0" + value
 	}
 	for i := 0; i < size; i++ {
 		out[i] = (value[i*2]-'0')<<4 | (value[i*2+1] - '0')
 	}
 	return out
 }
 func assertFloatField(t *testing.T, env envelope.FrameEnvelope, key string, want float64) {
 	t.Helper()
 	got, ok := env.Fields[key].(float64)
 	if !ok {
 		t.Fatalf("field %s missing or not float64: %#v", key, env.Fields[key])
 	}
 	if got != want {
 		t.Fatalf("field %s = %v, want %v", key, got, want)
 	}
 }
 func escape(payload []byte) []byte {
 	var out []byte
 	for _, value := range payload {
 		switch value {
 		case 0x7e:
 			out = append(out, 0x7d, 0x02)
 		case 0x7d:
 			out = append(out, 0x7d, 0x01)
 		default:
 			out = append(out, value)
 		}
 	}
 	return out
 }
--- a/go/vehicle-gateway/internal/protocol/jt808/response.go
+++ b/go/vehicle-gateway/internal/protocol/jt808/response.go
@@ -0,0 +1,130 @@
 package jt808
 import (
 	"encoding/binary"
 	"errors"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 var ErrResponseHeaderTooShort = errors.New("jt808 response header too short")
 const (
 	msgTerminalGeneralResponse = uint16(0x0001)
 	msgTerminalRegister        = uint16(0x0100)
 	msgPlatformGeneralResponse = uint16(0x8001)
 	msgPlatformRegisterAck     = uint16(0x8100)
 )
 type AutoResponder struct {
 	authCode string
 }
 func NewAutoResponder(authCode string) AutoResponder {
 	if authCode == "" {
 		authCode = "g7gps"
 	}
 	return AutoResponder{authCode: authCode}
 }
 func (r AutoResponder) Respond(raw []byte, env envelope.FrameEnvelope) ([]byte, bool, error) {
 	if env.ParseStatus == envelope.ParseBadFrame {
 		return nil, false, nil
 	}
 	header, err := parseResponseHeader(raw)
 	if err != nil {
 		return nil, false, err
 	}
 	if header.messageID == msgTerminalGeneralResponse {
 		return nil, false, nil
 	}
 	if header.messageID == msgTerminalRegister {
 		body := make([]byte, 3, 3+len(r.authCode))
 		binary.BigEndian.PutUint16(body[0:2], header.sequence)
 		body[2] = 0
 		body = append(body, []byte(r.authCode)...)
 		return encodeResponse(msgPlatformRegisterAck, header, body), true, nil
 	}
 	body := make([]byte, 5)
 	binary.BigEndian.PutUint16(body[0:2], header.sequence)
 	binary.BigEndian.PutUint16(body[2:4], header.messageID)
 	body[4] = 0
 	return encodeResponse(msgPlatformGeneralResponse, header, body), true, nil
 }
 type responseHeader struct {
 	messageID       uint16
 	versioned       bool
 	protocolVersion byte
 	phoneBCD        []byte
 	sequence        uint16
 }
 func parseResponseHeader(raw []byte) (responseHeader, error) {
 	if len(raw) < 12 {
 		return responseHeader{}, ErrResponseHeaderTooShort
 	}
 	props := binary.BigEndian.Uint16(raw[2:4])
 	versioned := props&0x4000 != 0
 	phoneStart := 4
 	phoneLen := 6
 	protocolVersion := byte(0)
 	if versioned {
 		if len(raw) < 17 {
 			return responseHeader{}, ErrResponseHeaderTooShort
 		}
 		protocolVersion = raw[4]
 		phoneStart = 5
 		phoneLen = 10
 	}
 	sequenceStart := phoneStart + phoneLen
 	if len(raw) < sequenceStart+2 {
 		return responseHeader{}, ErrResponseHeaderTooShort
 	}
 	phone := append([]byte(nil), raw[phoneStart:sequenceStart]...)
 	return responseHeader{
 		messageID:       binary.BigEndian.Uint16(raw[0:2]),
 		versioned:       versioned,
 		protocolVersion: protocolVersion,
 		phoneBCD:        phone,
 		sequence:        binary.BigEndian.Uint16(raw[sequenceStart : sequenceStart+2]),
 	}, nil
 }
 func encodeResponse(messageID uint16, header responseHeader, body []byte) []byte {
 	props := uint16(len(body)) & 0x03ff
 	if header.versioned {
 		props |= 0x4000
 	}
 	payload := make([]byte, 0, 4+1+len(header.phoneBCD)+2+len(body)+1)
 	payload = appendU16(payload, messageID)
 	payload = appendU16(payload, props)
 	if header.versioned {
 		payload = append(payload, header.protocolVersion)
 	}
 	payload = append(payload, header.phoneBCD...)
 	payload = appendU16(payload, header.sequence)
 	payload = append(payload, body...)
 	payload = append(payload, checksum(payload))
 	return frame(payload)
 }
 func appendU16(out []byte, value uint16) []byte {
 	return append(out, byte(value>>8), byte(value))
 }
 func frame(payload []byte) []byte {
 	out := []byte{0x7e}
 	for _, value := range payload {
 		switch value {
 		case 0x7e:
 			out = append(out, 0x7d, 0x02)
 		case 0x7d:
 			out = append(out, 0x7d, 0x01)
 		default:
 			out = append(out, value)
 		}
 	}
 	out = append(out, 0x7e)
 	return out
 }
--- a/go/vehicle-gateway/internal/protocol/yutongmqtt/parser.go
+++ b/go/vehicle-gateway/internal/protocol/yutongmqtt/parser.go
@@ -0,0 +1,201 @@
 package yutongmqtt
 import (
 	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"strconv"
 	"strings"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 var ErrInvalidJSON = errors.New("yutong mqtt invalid json")
 func ParseMessage(endpoint string, topic string, payload []byte, receivedAtMS int64) (envelope.FrameEnvelope, error) {
 	root := map[string]any{}
 	decoder := json.NewDecoder(bytes.NewReader(payload))
 	decoder.UseNumber()
 	if err := decoder.Decode(&root); err != nil {
 		return envelope.FrameEnvelope{}, fmt.Errorf("%w: %v", ErrInvalidJSON, err)
 	}
 	data := objectValue(root, "data")
 	if data == nil {
 		data = root
 	}
 	deviceID := firstText(root, "device", "deviceId", "terminalId", "terminalID", "imei", "IMEI", "mqttDeviceId")
 	externalVIN := firstText(root, "vin", "VIN", "externalVin", "vehicleVin")
 	vin := externalVIN
 	if vin == "" && looksLikeVIN(deviceID) {
 		vin = deviceID
 	}
 	plate := firstText(root, "plateNo", "carNo", "plate", "vehicleNo")
 	phone := firstText(root, "sim", "phone", "mobile")
 	eventTimeMS := parseTimeMS(firstText(root, "time", "deviceTime", "eventTime", "gpsTime"), receivedAtMS)
 	fields := fieldsFromData(data)
 	parsed := map[string]any{
 		"endpoint": endpoint,
 		"topic":    topic,
 		"root":     root,
 		"data":     data,
 	}
 	env := envelope.FrameEnvelope{
 		Protocol:       envelope.ProtocolYutongMQTT,
 		MessageID:      "MQTT",
 		VIN:            vin,
 		VehicleKeyHint: deviceID,
 		Phone:          phone,
 		DeviceID:       deviceID,
 		Plate:          plate,
 		SourceEndpoint: "mqtt://" + endpoint + topic,
 		EventTimeMS:    eventTimeMS,
 		ReceivedAtMS:   receivedAtMS,
 		RawText:        string(payload),
 		Parsed:         parsed,
 		Fields:         fields,
 		ParseStatus:    envelope.ParseOK,
 	}
 	env.EventID = env.StableEventID()
 	return env, nil
 }
 func fieldsFromData(data map[string]any) map[string]any {
 	fields := map[string]any{}
 	if speed, ok := firstFloat(data, "METER_SPEED", "speed", "speed_kmh"); ok {
 		fields[envelope.FieldSpeedKMH] = speed
 	}
 	if mileage, ok := firstFloat(data, "TOTAL_MILEAGE", "totalMileage", "total_mileage_km"); ok {
 		fields[envelope.FieldTotalMileageKM] = normalizeTotalMileageKM(mileage)
 	}
 	if soc, ok := firstFloat(data, "BATTERY_CAPACITY_SOC", "soc", "SOC", "soc_percent"); ok {
 		fields[envelope.FieldSOCPercent] = soc
 	}
 	if longitude, ok := firstCoord(data, "LONGITUDE", "longitude", "lng"); ok {
 		fields[envelope.FieldLongitude] = longitude
 	}
 	if latitude, ok := firstCoord(data, "LATITUDE", "latitude", "lat"); ok {
 		fields[envelope.FieldLatitude] = latitude
 	}
 	if direction, ok := firstFloat(data, "GPSDirection", "direction", "direction_deg"); ok {
 		fields["direction_deg"] = direction
 	}
 	if gear, ok := firstFloat(data, "ON_GEAR", "gear"); ok {
 		fields["gear"] = gear
 	}
 	return fields
 }
 func objectValue(root map[string]any, key string) map[string]any {
 	value, ok := root[key]
 	if !ok {
 		return nil
 	}
 	typed, ok := value.(map[string]any)
 	if !ok {
 		return nil
 	}
 	return typed
 }
 func firstText(root map[string]any, keys ...string) string {
 	for _, key := range keys {
 		if value, ok := root[key]; ok && value != nil {
 			text := strings.TrimSpace(fmt.Sprint(value))
 			if text != "" && text != "<nil>" {
 				return text
 			}
 		}
 	}
 	return ""
 }
 func firstFloat(root map[string]any, keys ...string) (float64, bool) {
 	for _, key := range keys {
 		value, ok := root[key]
 		if !ok || value == nil {
 			continue
 		}
 		if parsed, ok := toFloat(value); ok {
 			return parsed, true
 		}
 	}
 	return 0, false
 }
 func firstCoord(root map[string]any, keys ...string) (float64, bool) {
 	value, ok := firstFloat(root, keys...)
 	if !ok {
 		return 0, false
 	}
 	if value == 0 || int64(value) == 999999 {
 		return 0, false
 	}
 	if value > 1000 || value < -1000 {
 		value = value / 1_000_000
 	}
 	return value, true
 }
 func toFloat(value any) (float64, bool) {
 	switch typed := value.(type) {
 	case json.Number:
 		parsed, err := typed.Float64()
 		return parsed, err == nil
 	case float64:
 		return typed, true
 	case float32:
 		return float64(typed), true
 	case int:
 		return float64(typed), true
 	case int64:
 		return float64(typed), true
 	case string:
 		parsed, err := strconv.ParseFloat(strings.TrimSpace(typed), 64)
 		return parsed, err == nil
 	default:
 		return 0, false
 	}
 }
 func parseTimeMS(raw string, fallback int64) int64 {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
 		return fallback
 	}
 	for _, layout := range []string{
 		"2006-01-02 15:04:05.000",
 		"2006-01-02 15:04:05",
 	} {
 		if parsed, err := time.ParseInLocation(layout, raw, time.FixedZone("Asia/Shanghai", 8*3600)); err == nil {
 			return parsed.UnixMilli()
 		}
 	}
 	if len(raw) == 14 {
 		if parsed, err := time.ParseInLocation("20060102150405", raw, time.FixedZone("Asia/Shanghai", 8*3600)); err == nil {
 			return parsed.UnixMilli()
 		}
 	}
 	if parsed, err := time.Parse(time.RFC3339, raw); err == nil {
 		return parsed.UnixMilli()
 	}
 	if epoch, err := strconv.ParseInt(raw, 10, 64); err == nil {
 		if epoch > 10_000_000_000 {
 			return epoch
 		}
 		return epoch * 1000
 	}
 	return fallback
 }
 func looksLikeVIN(value string) bool {
 	value = strings.TrimSpace(value)
 	return len(value) == 17
 }
 func normalizeTotalMileageKM(value float64) float64 {
 	return value / 1000
 }
--- a/go/vehicle-gateway/internal/protocol/yutongmqtt/parser_test.go
+++ b/go/vehicle-gateway/internal/protocol/yutongmqtt/parser_test.go
@@ -0,0 +1,112 @@
 package yutongmqtt
 import (
 	"errors"
 	"testing"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestParseMessageMapsYutongPayloadToEnvelope(t *testing.T) {
 	payload := []byte(`{
 	  "device": "LTEST000000000001",
 	  "time": "20260413100000",
 	  "plateNo": "豫A12345",
 	  "data": {
 	    "METER_SPEED": 52.3,
 	    "TOTAL_MILEAGE": 123456.7,
 	    "BATTERY_CAPACITY_SOC": 70,
 	    "LONGITUDE": 116397128,
 	    "LATITUDE": 39916527,
 	    "GPSDirection": 88
 	  }
 	}`)
 	env, err := ParseMessage("endpoint-a", "/ytforward/shln/dev1", payload, 1782745114999)
 	if err != nil {
 		t.Fatalf("ParseMessage() error = %v", err)
 	}
 	if env.Protocol != envelope.ProtocolYutongMQTT {
 		t.Fatalf("protocol = %q", env.Protocol)
 	}
 	if env.VIN != "LTEST000000000001" || env.DeviceID != "LTEST000000000001" {
 		t.Fatalf("identity fields = vin:%q device:%q", env.VIN, env.DeviceID)
 	}
 	if env.Plate != "豫A12345" {
 		t.Fatalf("plate = %q", env.Plate)
 	}
 	assertFloatField(t, env, envelope.FieldSpeedKMH, 52.3)
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 123.4567)
 	assertFloatField(t, env, envelope.FieldSOCPercent, 70)
 	assertFloatField(t, env, envelope.FieldLongitude, 116.397128)
 	assertFloatField(t, env, envelope.FieldLatitude, 39.916527)
 	assertFloatField(t, env, "direction_deg", 88)
 	if env.EventTimeMS == 1782745114999 {
 		t.Fatal("event time should come from device time")
 	}
 	if env.RawText == "" || env.Parsed["data"] == nil {
 		t.Fatalf("raw/parsed missing: %#v", env)
 	}
 }
 func TestParseMessageUsesDeviceAsVehicleKeyWhenNotVIN(t *testing.T) {
 	payload := []byte(`{"device":"YT-DEVICE-001","time":"20260413100000","data":{"METER_SPEED":"12.3"}}`)
 	env, err := ParseMessage("endpoint-a", "/ytforward/shln/YT-DEVICE-001", payload, 1782745114999)
 	if err != nil {
 		t.Fatalf("ParseMessage() error = %v", err)
 	}
 	if env.VIN != "" {
 		t.Fatalf("non-vin device should not be treated as vin: %q", env.VIN)
 	}
 	if env.VehicleKey() != "YT-DEVICE-001" {
 		t.Fatalf("vehicle key = %q", env.VehicleKey())
 	}
 	assertFloatField(t, env, envelope.FieldSpeedKMH, 12.3)
 }
 func TestParseMessageNormalizesProductionMileageMeters(t *testing.T) {
 	payload := []byte(`{
 	  "device":"LMRKH9AC3R1004101",
 	  "time":"2026-07-02 01:02:04.085",
 	  "data":{"TOTAL_MILEAGE":56905000,"METER_SPEED":19}
 	}`)
 	env, err := ParseMessage("yutong", "/ytforward/shln/1", payload, 1782940000000)
 	if err != nil {
 		t.Fatalf("ParseMessage() error = %v", err)
 	}
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 56905)
 	if env.EventTimeMS != 1782925324085 {
 		t.Fatalf("event time = %d, want 1782925324085", env.EventTimeMS)
 	}
 }
 func TestParseMessageTreatsSmallYutongMileageAsMeters(t *testing.T) {
 	payload := []byte(`{
 	  "device":"LMRKH9AC3R1004101",
 	  "time":"2026-07-02 01:02:04.085",
 	  "data":{"TOTAL_MILEAGE":1024,"METER_SPEED":19}
 	}`)
 	env, err := ParseMessage("yutong", "/ytforward/shln/1", payload, 1782940000000)
 	if err != nil {
 		t.Fatalf("ParseMessage() error = %v", err)
 	}
 	assertFloatField(t, env, envelope.FieldTotalMileageKM, 1.024)
 }
 func TestParseMessageRejectsMalformedJSON(t *testing.T) {
 	_, err := ParseMessage("endpoint-a", "/bad", []byte("{bad-json"), 1782745114999)
 	if !errors.Is(err, ErrInvalidJSON) {
 		t.Fatalf("error = %v", err)
 	}
 }
 func assertFloatField(t *testing.T, env envelope.FrameEnvelope, key string, want float64) {
 	t.Helper()
 	got, ok := env.Fields[key].(float64)
 	if !ok {
 		t.Fatalf("field %s missing or not float64: %#v", key, env.Fields[key])
 	}
 	if got != want {
 		t.Fatalf("field %s = %v, want %v", key, got, want)
 	}
 }
--- a/go/vehicle-gateway/internal/realtime/http.go
+++ b/go/vehicle-gateway/internal/realtime/http.go
@@ -0,0 +1,69 @@
 package realtime
 import (
 	"encoding/json"
 	"errors"
 	"net/http"
 	"strings"
 	"github.com/redis/go-redis/v9"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Handler struct {
 	repository *Repository
 }
 func NewHandler(repository *Repository) *Handler {
 	if repository == nil {
 		panic("realtime repository must not be nil")
 	}
 	return &Handler{repository: repository}
 }
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		writeError(w, http.StatusMethodNotAllowed, "method not allowed")
 		return
 	}
 	path := strings.Trim(strings.TrimPrefix(r.URL.Path, "/api/realtime/vehicles/"), "/")
 	parts := strings.Split(path, "/")
 	if len(parts) == 0 || strings.TrimSpace(parts[0]) == "" {
 		writeError(w, http.StatusNotFound, "vehicle not found")
 		return
 	}
 	vin := parts[0]
 	switch {
 	case len(parts) == 1:
 		snapshot, err := h.repository.GetMerged(r.Context(), vin)
 		writeResult(w, snapshot, err)
 	case len(parts) == 2 && parts[1] == "online":
 		status, err := h.repository.IsOnline(r.Context(), vin)
 		writeResult(w, status, err)
 	case len(parts) == 3 && parts[1] == "protocols":
 		snapshot, err := h.repository.GetProtocol(r.Context(), vin, envelope.Protocol(strings.ToUpper(parts[2])))
 		writeResult(w, snapshot, err)
 	default:
 		writeError(w, http.StatusNotFound, "route not found")
 	}
 }
 func writeResult(w http.ResponseWriter, value any, err error) {
 	if err != nil {
 		if errors.Is(err, redis.Nil) {
 			writeError(w, http.StatusNotFound, "not found")
 			return
 		}
 		writeError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	w.Header().Set("Content-Type", "application/json")
 	_ = json.NewEncoder(w).Encode(value)
 }
 func writeError(w http.ResponseWriter, status int, message string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
 	_ = json.NewEncoder(w).Encode(map[string]any{"error": message})
 }
--- a/go/vehicle-gateway/internal/realtime/model.go
+++ b/go/vehicle-gateway/internal/realtime/model.go
@@ -0,0 +1,41 @@
 package realtime
 import (
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Snapshot struct {
 	VehicleKey     string              `json:"vehicle_key"`
 	VIN            string              `json:"vin"`
 	Protocol       envelope.Protocol   `json:"protocol,omitempty"`
 	Protocols      []envelope.Protocol `json:"protocols,omitempty"`
 	EventID        string              `json:"event_id,omitempty"`
 	EventTimeMS    int64               `json:"event_time_ms"`
 	ReceivedAtMS   int64               `json:"received_at_ms"`
 	SourceEndpoint string              `json:"source_endpoint,omitempty"`
 	Fields         map[string]any      `json:"fields,omitempty"`
 	FieldTimesMS   map[string]int64    `json:"field_times_ms,omitempty"`
 	UpdatedAtMS    int64               `json:"updated_at_ms"`
 }
 type OnlineStatus struct {
 	VehicleKey string              `json:"vehicle_key"`
 	VIN        string              `json:"vin"`
 	Online     bool                `json:"online"`
 	LastSeenMS int64               `json:"last_seen_ms"`
 	Protocols  []envelope.Protocol `json:"protocols,omitempty"`
 	TTLSeconds int64               `json:"ttl_seconds"`
 }
 type Config struct {
 	OnlineTTL time.Duration
 }
 func (c Config) ttl() time.Duration {
 	if c.OnlineTTL <= 0 {
 		return 10 * time.Minute
 	}
 	return c.OnlineTTL
 }
--- a/go/vehicle-gateway/internal/realtime/repository.go
+++ b/go/vehicle-gateway/internal/realtime/repository.go
@@ -0,0 +1,232 @@
 package realtime
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"sort"
 	"strconv"
 	"strings"
 	"time"
 	"github.com/redis/go-redis/v9"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 type Repository struct {
 	client *redis.Client
 	cfg    Config
 }
 func NewRepository(client *redis.Client, cfg Config) *Repository {
 	if client == nil {
 		panic("redis client must not be nil")
 	}
 	return &Repository{client: client, cfg: cfg}
 }
 func (r *Repository) Update(ctx context.Context, env envelope.FrameEnvelope) error {
 	vin := strings.TrimSpace(env.VIN)
 	vehicleKey := strings.TrimSpace(env.VehicleKey())
 	if vehicleKey == "" || strings.HasSuffix(vehicleKey, ":unknown") {
 		return nil
 	}
 	nowMS := time.Now().UnixMilli()
 	eventMS := env.EventTimeMS
 	if eventMS <= 0 {
 		eventMS = env.ReceivedAtMS
 	}
 	protocolSnapshot := Snapshot{
 		VehicleKey:     vehicleKey,
 		VIN:            vin,
 		Protocol:       env.Protocol,
 		EventID:        env.StableEventID(),
 		EventTimeMS:    eventMS,
 		ReceivedAtMS:   env.ReceivedAtMS,
 		SourceEndpoint: env.SourceEndpoint,
 		Fields:         cloneFields(env.Fields),
 		FieldTimesMS:   fieldTimes(env.Fields, eventMS),
 		UpdatedAtMS:    nowMS,
 	}
 	if err := r.setJSON(ctx, protocolKey(vehicleKey, env.Protocol), protocolSnapshot, r.cfg.ttl()); err != nil {
 		return err
 	}
 	protocols, err := r.addProtocol(ctx, vehicleKey, env.Protocol)
 	if err != nil {
 		return err
 	}
 	merged, err := r.GetMerged(ctx, vehicleKey)
 	if err != nil && !errors.Is(err, redis.Nil) {
 		return err
 	}
 	if merged.VehicleKey == "" {
 		merged = Snapshot{VehicleKey: vehicleKey, VIN: vin, Fields: map[string]any{}, FieldTimesMS: map[string]int64{}}
 	} else if merged.VIN == "" && vin != "" {
 		merged.VIN = vin
 	}
 	mergeFields(&merged, env.Fields, eventMS)
 	if eventMS >= merged.EventTimeMS {
 		merged.EventTimeMS = eventMS
 		merged.EventID = env.StableEventID()
 		merged.ReceivedAtMS = env.ReceivedAtMS
 		merged.SourceEndpoint = env.SourceEndpoint
 	}
 	merged.Protocols = protocols
 	merged.UpdatedAtMS = nowMS
 	if err := r.setJSON(ctx, mergedKey(vehicleKey), merged, r.cfg.ttl()); err != nil {
 		return err
 	}
 	online := OnlineStatus{
 		VehicleKey: vehicleKey,
 		VIN:        vin,
 		Online:     true,
 		LastSeenMS: env.ReceivedAtMS,
 		Protocols:  protocols,
 		TTLSeconds: int64(r.cfg.ttl().Seconds()),
 	}
 	if err := r.setJSON(ctx, onlineKey(vehicleKey), online, r.cfg.ttl()); err != nil {
 		return err
 	}
 	return r.client.ZAdd(ctx, "vehicle:last_seen", redis.Z{Score: float64(env.ReceivedAtMS), Member: vehicleKey}).Err()
 }
 func (r *Repository) GetMerged(ctx context.Context, vehicleKey string) (Snapshot, error) {
 	return r.getSnapshot(ctx, mergedKey(vehicleKey))
 }
 func (r *Repository) GetProtocol(ctx context.Context, vehicleKey string, protocol envelope.Protocol) (Snapshot, error) {
 	return r.getSnapshot(ctx, protocolKey(vehicleKey, protocol))
 }
 func (r *Repository) IsOnline(ctx context.Context, vehicleKey string) (OnlineStatus, error) {
 	vehicleKey = strings.TrimSpace(vehicleKey)
 	var status OnlineStatus
 	payload, err := r.client.Get(ctx, onlineKey(vehicleKey)).Bytes()
 	if err != nil {
 		if errors.Is(err, redis.Nil) {
 			return OnlineStatus{VehicleKey: vehicleKey, VIN: vehicleKey, Online: false}, nil
 		}
 		return status, err
 	}
 	if err := json.Unmarshal(payload, &status); err != nil {
 		return status, err
 	}
 	ttl := r.client.TTL(ctx, onlineKey(vehicleKey)).Val()
 	status.Online = ttl > 0
 	status.TTLSeconds = int64(ttl.Seconds())
 	return status, nil
 }
 func (r *Repository) getSnapshot(ctx context.Context, key string) (Snapshot, error) {
 	var snapshot Snapshot
 	payload, err := r.client.Get(ctx, key).Bytes()
 	if err != nil {
 		return snapshot, err
 	}
 	return snapshot, json.Unmarshal(payload, &snapshot)
 }
 func (r *Repository) setJSON(ctx context.Context, key string, value any, ttl time.Duration) error {
 	payload, err := json.Marshal(value)
 	if err != nil {
 		return err
 	}
 	return r.client.Set(ctx, key, payload, ttl).Err()
 }
 func (r *Repository) addProtocol(ctx context.Context, vehicleKey string, protocol envelope.Protocol) ([]envelope.Protocol, error) {
 	key := protocolsKey(vehicleKey)
 	if err := r.client.SAdd(ctx, key, string(protocol)).Err(); err != nil {
 		return nil, err
 	}
 	_ = r.client.Expire(ctx, key, r.cfg.ttl()).Err()
 	values, err := r.client.SMembers(ctx, key).Result()
 	if err != nil {
 		return nil, err
 	}
 	sort.Strings(values)
 	out := make([]envelope.Protocol, 0, len(values))
 	for _, value := range values {
 		out = append(out, envelope.Protocol(value))
 	}
 	return out, nil
 }
 func mergeFields(snapshot *Snapshot, fields map[string]any, eventMS int64) {
 	if snapshot.Fields == nil {
 		snapshot.Fields = map[string]any{}
 	}
 	if snapshot.FieldTimesMS == nil {
 		snapshot.FieldTimesMS = map[string]int64{}
 	}
 	for key, value := range fields {
 		if key == envelope.FieldTotalMileageKM && !positiveNumber(value) {
 			continue
 		}
 		if eventMS >= snapshot.FieldTimesMS[key] {
 			snapshot.Fields[key] = value
 			snapshot.FieldTimesMS[key] = eventMS
 		}
 	}
 }
 func positiveNumber(value any) bool {
 	switch typed := value.(type) {
 	case float64:
 		return typed > 0
 	case float32:
 		return typed > 0
 	case int:
 		return typed > 0
 	case int64:
 		return typed > 0
 	case uint16:
 		return typed > 0
 	case uint32:
 		return typed > 0
 	case string:
 		parsed, err := strconv.ParseFloat(strings.TrimSpace(typed), 64)
 		return err == nil && parsed > 0
 	default:
 		return false
 	}
 }
 func cloneFields(fields map[string]any) map[string]any {
 	if len(fields) == 0 {
 		return map[string]any{}
 	}
 	out := make(map[string]any, len(fields))
 	for key, value := range fields {
 		out[key] = value
 	}
 	return out
 }
 func fieldTimes(fields map[string]any, eventMS int64) map[string]int64 {
 	out := make(map[string]int64, len(fields))
 	for key := range fields {
 		out[key] = eventMS
 	}
 	return out
 }
 func mergedKey(vehicleKey string) string {
 	return "vehicle:latest:" + strings.TrimSpace(vehicleKey)
 }
 func protocolKey(vehicleKey string, protocol envelope.Protocol) string {
 	return "vehicle:latest:" + strings.TrimSpace(vehicleKey) + ":" + string(protocol)
 }
 func onlineKey(vehicleKey string) string {
 	return "vehicle:online:" + strings.TrimSpace(vehicleKey)
 }
 func protocolsKey(vehicleKey string) string {
 	return "vehicle:protocols:" + strings.TrimSpace(vehicleKey)
 }
--- a/go/vehicle-gateway/internal/realtime/repository_test.go
+++ b/go/vehicle-gateway/internal/realtime/repository_test.go
@@ -0,0 +1,250 @@
 package realtime
 import (
 	"context"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
 	"github.com/alicebob/miniredis/v2"
 	"github.com/redis/go-redis/v9"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestRepositoryUpdatesMergedAndProtocolSnapshots(t *testing.T) {
 	repo, closeFn := newTestRepository(t)
 	defer closeFn()
 	ctx := context.Background()
 	if err := repo.Update(ctx, envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		VIN:          "VIN001",
 		EventTimeMS:  1000,
 		ReceivedAtMS: 1100,
 		Fields: map[string]any{
 			envelope.FieldLongitude:      121.1,
 			envelope.FieldTotalMileageKM: 10.5,
 		},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	if err := repo.Update(ctx, envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolGB32960,
 		VIN:          "VIN001",
 		EventTimeMS:  900,
 		ReceivedAtMS: 1200,
 		Fields: map[string]any{
 			envelope.FieldLongitude: 120.0,
 			envelope.FieldLatitude:  30.5,
 		},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	merged, err := repo.GetMerged(ctx, "VIN001")
 	if err != nil {
 		t.Fatalf("GetMerged() error = %v", err)
 	}
 	if merged.Fields[envelope.FieldLongitude] != 121.1 {
 		t.Fatalf("older longitude overwrote newer value: %#v", merged.Fields)
 	}
 	if merged.Fields[envelope.FieldLatitude] != 30.5 {
 		t.Fatalf("new latitude missing: %#v", merged.Fields)
 	}
 	if got := protocolNames(merged.Protocols); strings.Join(got, ",") != "GB32960,JT808" {
 		t.Fatalf("merged protocols = %#v", got)
 	}
 	protocol, err := repo.GetProtocol(ctx, "VIN001", envelope.ProtocolJT808)
 	if err != nil {
 		t.Fatalf("GetProtocol() error = %v", err)
 	}
 	if protocol.Fields[envelope.FieldTotalMileageKM] != 10.5 {
 		t.Fatalf("protocol snapshot = %#v", protocol)
 	}
 }
 func TestRepositoryOnlineStatus(t *testing.T) {
 	repo, closeFn := newTestRepository(t)
 	defer closeFn()
 	ctx := context.Background()
 	status, err := repo.IsOnline(ctx, "VIN001")
 	if err != nil {
 		t.Fatalf("IsOnline() error = %v", err)
 	}
 	if status.Online {
 		t.Fatal("empty vin should be offline")
 	}
 	if err := repo.Update(ctx, envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		VIN:          "VIN001",
 		EventTimeMS:  1000,
 		ReceivedAtMS: 1100,
 		Fields:       map[string]any{envelope.FieldSpeedKMH: 12.3},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	status, err = repo.IsOnline(ctx, "VIN001")
 	if err != nil {
 		t.Fatalf("IsOnline() error = %v", err)
 	}
 	if !status.Online || status.LastSeenMS != 1100 {
 		t.Fatalf("online status = %#v", status)
 	}
 }
 func TestRepositoryUpdatesPhoneOnlyVehicleKey(t *testing.T) {
 	repo, closeFn := newTestRepository(t)
 	defer closeFn()
 	ctx := context.Background()
 	if err := repo.Update(ctx, envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		Phone:        "013307811170",
 		EventTimeMS:  1000,
 		ReceivedAtMS: 1100,
 		Fields: map[string]any{
 			envelope.FieldSpeedKMH:       23.0,
 			envelope.FieldTotalMileageKM: 10003.7,
 		},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	vehicleKey := "JT808:013307811170"
 	merged, err := repo.GetMerged(ctx, vehicleKey)
 	if err != nil {
 		t.Fatalf("GetMerged() error = %v", err)
 	}
 	if merged.VehicleKey != vehicleKey || merged.VIN != "" {
 		t.Fatalf("unexpected identity: %#v", merged)
 	}
 	if merged.Fields[envelope.FieldTotalMileageKM] != 10003.7 {
 		t.Fatalf("merged fields = %#v", merged.Fields)
 	}
 	status, err := repo.IsOnline(ctx, vehicleKey)
 	if err != nil {
 		t.Fatalf("IsOnline() error = %v", err)
 	}
 	if !status.Online || status.VehicleKey != vehicleKey {
 		t.Fatalf("online status = %#v", status)
 	}
 }
 func TestRepositoryDoesNotOverwritePositiveMileageWithZero(t *testing.T) {
 	repo, closeFn := newTestRepository(t)
 	defer closeFn()
 	ctx := context.Background()
 	if err := repo.Update(ctx, envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		VIN:          "VIN001",
 		EventTimeMS:  1000,
 		ReceivedAtMS: 1100,
 		Fields: map[string]any{
 			envelope.FieldTotalMileageKM: 12345.6,
 		},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	if err := repo.Update(ctx, envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		VIN:          "VIN001",
 		EventTimeMS:  2000,
 		ReceivedAtMS: 2100,
 		Fields: map[string]any{
 			envelope.FieldSpeedKMH:       22.0,
 			envelope.FieldTotalMileageKM: 0,
 		},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	merged, err := repo.GetMerged(ctx, "VIN001")
 	if err != nil {
 		t.Fatalf("GetMerged() error = %v", err)
 	}
 	if merged.Fields[envelope.FieldTotalMileageKM] != 12345.6 {
 		t.Fatalf("zero mileage overwrote positive value: %#v", merged.Fields)
 	}
 	if merged.Fields[envelope.FieldSpeedKMH] != 22.0 {
 		t.Fatalf("new speed should still merge: %#v", merged.Fields)
 	}
 }
 func TestHandlerReturnsMergedSnapshot(t *testing.T) {
 	repo, closeFn := newTestRepository(t)
 	defer closeFn()
 	if err := repo.Update(context.Background(), envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		VIN:          "VIN001",
 		EventTimeMS:  1000,
 		ReceivedAtMS: 1100,
 		Fields:       map[string]any{envelope.FieldSpeedKMH: 12.3},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	req := httptest.NewRequest(http.MethodGet, "/api/realtime/vehicles/VIN001", nil)
 	rec := httptest.NewRecorder()
 	NewHandler(repo).ServeHTTP(rec, req)
 	if rec.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", rec.Code, rec.Body.String())
 	}
 	if !stringsContains(rec.Body.String(), `"vin":"VIN001"`) {
 		t.Fatalf("unexpected body: %s", rec.Body.String())
 	}
 }
 func TestHandlerReturnsPhoneOnlyVehicleKeySnapshot(t *testing.T) {
 	repo, closeFn := newTestRepository(t)
 	defer closeFn()
 	if err := repo.Update(context.Background(), envelope.FrameEnvelope{
 		Protocol:     envelope.ProtocolJT808,
 		Phone:        "013307811170",
 		EventTimeMS:  1000,
 		ReceivedAtMS: 1100,
 		Fields:       map[string]any{envelope.FieldSpeedKMH: 12.3},
 	}); err != nil {
 		t.Fatalf("Update() error = %v", err)
 	}
 	req := httptest.NewRequest(http.MethodGet, "/api/realtime/vehicles/JT808:013307811170", nil)
 	rec := httptest.NewRecorder()
 	NewHandler(repo).ServeHTTP(rec, req)
 	if rec.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", rec.Code, rec.Body.String())
 	}
 	if !stringsContains(rec.Body.String(), `"vehicle_key":"JT808:013307811170"`) {
 		t.Fatalf("unexpected body: %s", rec.Body.String())
 	}
 }
 func newTestRepository(t *testing.T) (*Repository, func()) {
 	t.Helper()
 	server, err := miniredis.Run()
 	if err != nil {
 		t.Fatalf("miniredis.Run() error = %v", err)
 	}
 	client := redis.NewClient(&redis.Options{Addr: server.Addr()})
 	return NewRepository(client, Config{OnlineTTL: time.Minute}), func() {
 		_ = client.Close()
 		server.Close()
 	}
 }
 func stringsContains(value string, pattern string) bool {
 	return strings.Contains(value, pattern)
 }
 func protocolNames(protocols []envelope.Protocol) []string {
 	names := make([]string, 0, len(protocols))
 	for _, protocol := range protocols {
 		names = append(names, string(protocol))
 	}
 	return names
 }
--- a/go/vehicle-gateway/internal/stats/daily_metric.go
+++ b/go/vehicle-gateway/internal/stats/daily_metric.go
@@ -0,0 +1,275 @@
 package stats
 import (
 	"context"
 	"database/sql"
 	"errors"
 	"strconv"
 	"strings"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 const (
 	MetricDailyMileageKM      = "daily_mileage_km"
 	MetricDailyTotalMileageKM = "daily_total_mileage_km"
 )
 type Execer interface {
 	ExecContext(context.Context, string, ...any) (sql.Result, error)
 }
 type Writer struct {
 	exec Execer
 	loc  *time.Location
 }
 type MetricSample struct {
 	VehicleKey     string
 	VIN            string
 	Protocol       envelope.Protocol
 	StatDate       string
 	MetricKey      string
 	MetricValue    float64
 	TotalMileageKM float64
 }
 func NewWriter(exec Execer, loc *time.Location) *Writer {
 	if exec == nil {
 		panic("stats execer must not be nil")
 	}
 	if loc == nil {
 		loc = time.FixedZone("Asia/Shanghai", 8*3600)
 	}
 	return &Writer{exec: exec, loc: loc}
 }
 func (w *Writer) EnsureSchema(ctx context.Context) error {
 	if _, err := w.exec.ExecContext(ctx, DailyMetricTableSQL); err != nil {
 		return err
 	}
 	if db, ok := w.exec.(metadataDB); ok {
 		return migrateDailyMetricTable(ctx, db)
 	}
 	return nil
 }
 func (w *Writer) Append(ctx context.Context, env envelope.FrameEnvelope) error {
 	samples, err := SamplesFromEnvelope(env, w.loc)
 	if err != nil {
 		return err
 	}
 	for _, sample := range samples {
 		if _, err := w.exec.ExecContext(ctx, upsertDailyMetricSQL,
 			sample.VehicleKey,
 			sample.VIN,
 			sample.StatDate,
 			string(sample.Protocol),
 			sample.MetricKey,
 			sample.MetricValue,
 			sample.TotalMileageKM,
 			sample.TotalMileageKM); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 func SamplesFromEnvelope(env envelope.FrameEnvelope, loc *time.Location) ([]MetricSample, error) {
 	vin := strings.TrimSpace(env.VIN)
 	vehicleKey := strings.TrimSpace(env.VehicleKey())
 	if vehicleKey == "" || strings.HasSuffix(vehicleKey, ":unknown") {
 		return nil, nil
 	}
 	totalMileage, ok := floatField(env, envelope.FieldTotalMileageKM)
 	if !ok {
 		return nil, nil
 	}
 	if totalMileage <= 0 {
 		return nil, nil
 	}
 	if loc == nil {
 		loc = time.FixedZone("Asia/Shanghai", 8*3600)
 	}
 	eventMS := env.EventTimeMS
 	if eventMS <= 0 {
 		eventMS = env.ReceivedAtMS
 	}
 	if eventMS <= 0 {
 		return nil, errors.New("event or received time is required")
 	}
 	statDate := time.UnixMilli(eventMS).In(loc).Format("2006-01-02")
 	return []MetricSample{
 		{
 			VehicleKey:     vehicleKey,
 			VIN:            vin,
 			Protocol:       env.Protocol,
 			StatDate:       statDate,
 			MetricKey:      MetricDailyMileageKM,
 			MetricValue:    0,
 			TotalMileageKM: totalMileage,
 		},
 		{
 			VehicleKey:     vehicleKey,
 			VIN:            vin,
 			Protocol:       env.Protocol,
 			StatDate:       statDate,
 			MetricKey:      MetricDailyTotalMileageKM,
 			MetricValue:    totalMileage,
 			TotalMileageKM: totalMileage,
 		},
 	}, nil
 }
 const upsertDailyMetricSQL = `
 INSERT INTO vehicle_daily_metric
  (vehicle_key, vin, stat_date, protocol, metric_key, metric_value, metric_unit,
   first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method)
 VALUES (?, ?, ?, ?, ?, ?, 'km', ?, ?, 1, 'TOTAL_MILEAGE_DIFF')
 ON DUPLICATE KEY UPDATE
  vin = IF(VALUES(vin) <> '', VALUES(vin), vin),
  first_total_mileage_km = CASE
    WHEN first_total_mileage_km IS NULL OR first_total_mileage_km <= 0
      THEN VALUES(first_total_mileage_km)
    ELSE LEAST(first_total_mileage_km, VALUES(first_total_mileage_km))
  END,
  latest_total_mileage_km = CASE
    WHEN latest_total_mileage_km IS NULL OR latest_total_mileage_km <= 0
      THEN VALUES(latest_total_mileage_km)
    ELSE GREATEST(latest_total_mileage_km, VALUES(latest_total_mileage_km))
  END,
  metric_value = CASE
    WHEN metric_key = 'daily_mileage_km'
      THEN GREATEST(
             CASE
               WHEN latest_total_mileage_km IS NULL OR latest_total_mileage_km <= 0
                 THEN VALUES(latest_total_mileage_km)
               ELSE latest_total_mileage_km
             END,
             VALUES(latest_total_mileage_km)
           )
           - CASE
               WHEN first_total_mileage_km IS NULL OR first_total_mileage_km <= 0
                 THEN VALUES(first_total_mileage_km)
               ELSE LEAST(first_total_mileage_km, VALUES(first_total_mileage_km))
             END
    WHEN metric_key = 'daily_total_mileage_km'
      THEN GREATEST(
             CASE
               WHEN latest_total_mileage_km IS NULL OR latest_total_mileage_km <= 0
                 THEN VALUES(latest_total_mileage_km)
               ELSE latest_total_mileage_km
             END,
             VALUES(latest_total_mileage_km)
           )
    ELSE VALUES(metric_value)
  END,
  sample_count = sample_count + 1,
  updated_at = CURRENT_TIMESTAMP
 `
 type metadataDB interface {
 	Execer
 	QueryRowContext(context.Context, string, ...any) *sql.Row
 }
 func migrateDailyMetricTable(ctx context.Context, db metadataDB) error {
 	columnExists, err := informationSchemaExists(ctx, db, `
 SELECT COUNT(*)
 FROM information_schema.columns
 WHERE table_schema = DATABASE()
  AND table_name = 'vehicle_daily_metric'
  AND column_name = 'vehicle_key'`)
 	if err != nil {
 		return err
 	}
 	if !columnExists {
 		if _, err := db.ExecContext(ctx, `ALTER TABLE vehicle_daily_metric ADD COLUMN vehicle_key VARCHAR(96) NOT NULL DEFAULT '' AFTER id`); err != nil {
 			return err
 		}
 	}
 	if _, err := db.ExecContext(ctx, `UPDATE vehicle_daily_metric SET vehicle_key = vin WHERE vehicle_key = ''`); err != nil {
 		return err
 	}
 	vehicleIndexExists, err := informationSchemaExists(ctx, db, `
 SELECT COUNT(*)
 FROM information_schema.statistics
 WHERE table_schema = DATABASE()
  AND table_name = 'vehicle_daily_metric'
  AND index_name = 'uk_daily_metric_vehicle'`)
 	if err != nil {
 		return err
 	}
 	if !vehicleIndexExists {
 		if _, err := db.ExecContext(ctx, `ALTER TABLE vehicle_daily_metric ADD UNIQUE KEY uk_daily_metric_vehicle (vehicle_key, stat_date, protocol, metric_key)`); err != nil {
 			return err
 		}
 	}
 	oldIndexExists, err := informationSchemaExists(ctx, db, `
 SELECT COUNT(*)
 FROM information_schema.statistics
 WHERE table_schema = DATABASE()
  AND table_name = 'vehicle_daily_metric'
  AND index_name = 'uk_daily_metric'`)
 	if err != nil {
 		return err
 	}
 	if oldIndexExists {
 		if _, err := db.ExecContext(ctx, `ALTER TABLE vehicle_daily_metric DROP INDEX uk_daily_metric`); err != nil {
 			return err
 		}
 	}
 	vinIndexExists, err := informationSchemaExists(ctx, db, `
 SELECT COUNT(*)
 FROM information_schema.statistics
 WHERE table_schema = DATABASE()
  AND table_name = 'vehicle_daily_metric'
  AND index_name = 'idx_vin'`)
 	if err != nil {
 		return err
 	}
 	if !vinIndexExists {
 		if _, err := db.ExecContext(ctx, `ALTER TABLE vehicle_daily_metric ADD KEY idx_vin (vin)`); err != nil {
 			return err
 		}
 	}
 	return nil
 }
 func informationSchemaExists(ctx context.Context, db metadataDB, query string) (bool, error) {
 	var count int
 	if err := db.QueryRowContext(ctx, query).Scan(&count); err != nil {
 		return false, err
 	}
 	return count > 0, nil
 }
 func floatField(env envelope.FrameEnvelope, key string) (float64, bool) {
 	if env.Fields == nil {
 		return 0, false
 	}
 	value, ok := env.Fields[key]
 	if !ok || value == nil {
 		return 0, false
 	}
 	switch typed := value.(type) {
 	case float64:
 		return typed, true
 	case float32:
 		return float64(typed), true
 	case int:
 		return float64(typed), true
 	case int64:
 		return float64(typed), true
 	case uint16:
 		return float64(typed), true
 	case uint32:
 		return float64(typed), true
 	case string:
 		parsed, err := strconv.ParseFloat(strings.TrimSpace(typed), 64)
 		return parsed, err == nil
 	default:
 		return 0, false
 	}
 }
--- a/go/vehicle-gateway/internal/stats/daily_metric_test.go
+++ b/go/vehicle-gateway/internal/stats/daily_metric_test.go
@@ -0,0 +1,162 @@
 package stats
 import (
 	"context"
 	"database/sql"
 	"strings"
 	"testing"
 	"time"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 )
 func TestSamplesFromEnvelopeDerivesDailyMileageAndTotal(t *testing.T) {
 	loc := time.FixedZone("Asia/Shanghai", 8*3600)
 	env := envelope.FrameEnvelope{
 		Protocol:    envelope.ProtocolJT808,
 		VIN:         "LNBVIN00000000001",
 		EventTimeMS: time.Date(2026, 7, 1, 8, 30, 0, 0, loc).UnixMilli(),
 		Fields: map[string]any{
 			envelope.FieldTotalMileageKM: 10241.2,
 		},
 	}
 	samples, err := SamplesFromEnvelope(env, loc)
 	if err != nil {
 		t.Fatalf("SamplesFromEnvelope() error = %v", err)
 	}
 	if len(samples) != 2 {
 		t.Fatalf("sample count = %d", len(samples))
 	}
 	if samples[0].MetricKey != MetricDailyMileageKM || samples[0].MetricValue != 0 {
 		t.Fatalf("unexpected daily mileage sample: %#v", samples[0])
 	}
 	if samples[0].VehicleKey != "LNBVIN00000000001" {
 		t.Fatalf("vehicle key = %q", samples[0].VehicleKey)
 	}
 	if samples[1].MetricKey != MetricDailyTotalMileageKM || samples[1].MetricValue != 10241.2 {
 		t.Fatalf("unexpected daily total sample: %#v", samples[1])
 	}
 	if samples[0].StatDate != "2026-07-01" {
 		t.Fatalf("stat date = %q", samples[0].StatDate)
 	}
 }
 func TestSamplesFromEnvelopeUsesVehicleKeyWhenVINIsMissing(t *testing.T) {
 	loc := time.FixedZone("Asia/Shanghai", 8*3600)
 	samples, err := SamplesFromEnvelope(envelope.FrameEnvelope{
 		Protocol:    envelope.ProtocolJT808,
 		Phone:       "013307811254",
 		EventTimeMS: time.Date(2026, 7, 2, 0, 3, 0, 0, loc).UnixMilli(),
 		Fields: map[string]any{
 			envelope.FieldTotalMileageKM: 10985.7,
 		},
 	}, loc)
 	if err != nil {
 		t.Fatalf("SamplesFromEnvelope() error = %v", err)
 	}
 	if len(samples) != 2 {
 		t.Fatalf("sample count = %d", len(samples))
 	}
 	if samples[0].VehicleKey != "JT808:013307811254" {
 		t.Fatalf("vehicle key = %q", samples[0].VehicleKey)
 	}
 	if samples[0].VIN != "" {
 		t.Fatalf("vin should stay empty for unresolved JT808 identity, got %q", samples[0].VIN)
 	}
 }
 func TestSamplesFromEnvelopeSkipsMissingVehicleKeyOrMileage(t *testing.T) {
 	samples, err := SamplesFromEnvelope(envelope.FrameEnvelope{
 		Protocol: envelope.ProtocolJT808,
 		Fields:   map[string]any{envelope.FieldTotalMileageKM: 1.2},
 	}, nil)
 	if err != nil {
 		t.Fatalf("SamplesFromEnvelope() error = %v", err)
 	}
 	if len(samples) != 0 {
 		t.Fatalf("expected no samples without vehicle key, got %#v", samples)
 	}
 	samples, err = SamplesFromEnvelope(envelope.FrameEnvelope{
 		Protocol: envelope.ProtocolGB32960,
 		VIN:      "LNBVIN00000000002",
 		Fields:   map[string]any{},
 	}, nil)
 	if err != nil {
 		t.Fatalf("SamplesFromEnvelope() error = %v", err)
 	}
 	if len(samples) != 0 {
 		t.Fatalf("expected no samples without mileage, got %#v", samples)
 	}
 }
 func TestSamplesFromEnvelopeSkipsNonPositiveMileage(t *testing.T) {
 	for _, value := range []any{0, 0.0, -1.0, "0"} {
 		samples, err := SamplesFromEnvelope(envelope.FrameEnvelope{
 			Protocol:    envelope.ProtocolJT808,
 			VIN:         "LNBVIN00000000001",
 			EventTimeMS: time.Date(2026, 7, 1, 9, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*3600)).UnixMilli(),
 			Fields: map[string]any{
 				envelope.FieldTotalMileageKM: value,
 			},
 		}, nil)
 		if err != nil {
 			t.Fatalf("SamplesFromEnvelope(%#v) error = %v", value, err)
 		}
 		if len(samples) != 0 {
 			t.Fatalf("expected no samples for non-positive mileage %#v, got %#v", value, samples)
 		}
 	}
 }
 func TestWriterEnsuresSchemaAndUpsertsTwoMetrics(t *testing.T) {
 	exec := &recordingExec{}
 	writer := NewWriter(exec, time.FixedZone("Asia/Shanghai", 8*3600))
 	if err := writer.EnsureSchema(context.Background()); err != nil {
 		t.Fatalf("EnsureSchema() error = %v", err)
 	}
 	if err := writer.Append(context.Background(), envelope.FrameEnvelope{
 		Protocol:    envelope.ProtocolGB32960,
 		VIN:         "LNBVIN00000000002",
 		EventTimeMS: time.Date(2026, 7, 1, 9, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*3600)).UnixMilli(),
 		Fields: map[string]any{
 			envelope.FieldTotalMileageKM: "10000.0",
 		},
 	}); err != nil {
 		t.Fatalf("Append() error = %v", err)
 	}
 	if !strings.Contains(exec.calls[0].query, "CREATE TABLE IF NOT EXISTS vehicle_daily_metric") {
 		t.Fatalf("unexpected schema sql: %s", exec.calls[0].query)
 	}
 	if !strings.Contains(exec.calls[0].query, "vehicle_key") {
 		t.Fatalf("schema should include vehicle_key: %s", exec.calls[0].query)
 	}
 	if len(exec.calls) != 3 {
 		t.Fatalf("exec calls = %d", len(exec.calls))
 	}
 	if !strings.Contains(exec.calls[1].query, "ON DUPLICATE KEY UPDATE") {
 		t.Fatalf("unexpected upsert sql: %s", exec.calls[1].query)
 	}
 	if !strings.Contains(exec.calls[1].query, "first_total_mileage_km <= 0") {
 		t.Fatalf("upsert should ignore legacy zero first mileage: %s", exec.calls[1].query)
 	}
 	if got := exec.calls[1].args[0]; got != "LNBVIN00000000002" {
 		t.Fatalf("first upsert arg should be vehicle_key, got %#v", got)
 	}
 }
 type execCall struct {
 	query string
 	args  []any
 }
 type recordingExec struct {
 	calls []execCall
 }
 func (e *recordingExec) ExecContext(_ context.Context, query string, args ...any) (sql.Result, error) {
 	e.calls = append(e.calls, execCall{query: query, args: args})
 	return nil, nil
 }
--- a/go/vehicle-gateway/internal/stats/query.go
+++ b/go/vehicle-gateway/internal/stats/query.go
@@ -0,0 +1,326 @@
 package stats
 import (
 	"context"
 	"database/sql"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
 	"time"
 )
 type Queryer interface {
 	QueryContext(context.Context, string, ...any) (*sql.Rows, error)
 }
 type MetricQuery struct {
 	VehicleKey string
 	VIN        string
 	Protocol   string
 	MetricKey  string
 	DateFrom   string
 	DateTo     string
 	Limit      int
 	Offset     int
 }
 type MetricRow struct {
 	VehicleKey           string   `json:"vehicle_key"`
 	VIN                  string   `json:"vin"`
 	StatDate             string   `json:"stat_date"`
 	Protocol             string   `json:"protocol"`
 	MetricKey            string   `json:"metric_key"`
 	MetricValue          float64  `json:"metric_value"`
 	MetricUnit           string   `json:"metric_unit"`
 	FirstTotalMileageKM  *float64 `json:"first_total_mileage_km,omitempty"`
 	LatestTotalMileageKM *float64 `json:"latest_total_mileage_km,omitempty"`
 	SampleCount          int64    `json:"sample_count"`
 	CalculationMethod    string   `json:"calculation_method"`
 	CreatedAt            string   `json:"created_at"`
 	UpdatedAt            string   `json:"updated_at"`
 }
 type MetricRepository struct {
 	db Queryer
 }
 func NewMetricRepository(db Queryer) *MetricRepository {
 	if db == nil {
 		panic("metric query db must not be nil")
 	}
 	return &MetricRepository{db: db}
 }
 func (r *MetricRepository) Query(ctx context.Context, query MetricQuery) ([]MetricRow, error) {
 	query = normalizeMetricQuery(query)
 	sqlText, args := buildMetricSQL(query)
 	rows, err := r.db.QueryContext(ctx, sqlText, args...)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
 	out := make([]MetricRow, 0)
 	for rows.Next() {
 		var row MetricRow
 		var statDate scanDate
 		var createdAt scanDateTime
 		var updatedAt scanDateTime
 		var first sql.NullFloat64
 		var latest sql.NullFloat64
 		if err := rows.Scan(
 			&row.VehicleKey,
 			&row.VIN,
 			&statDate,
 			&row.Protocol,
 			&row.MetricKey,
 			&row.MetricValue,
 			&row.MetricUnit,
 			&first,
 			&latest,
 			&row.SampleCount,
 			&row.CalculationMethod,
 			&createdAt,
 			&updatedAt,
 		); err != nil {
 			return nil, err
 		}
 		row.StatDate = statDate.String
 		row.CreatedAt = createdAt.String
 		row.UpdatedAt = updatedAt.String
 		if first.Valid {
 			row.FirstTotalMileageKM = &first.Float64
 		}
 		if latest.Valid {
 			row.LatestTotalMileageKM = &latest.Float64
 		}
 		out = append(out, row)
 	}
 	return out, rows.Err()
 }
 func (r *MetricRepository) Count(ctx context.Context, query MetricQuery) (int64, error) {
 	query = normalizeMetricQuery(query)
 	sqlText, args := buildMetricCountSQL(query)
 	rows, err := r.db.QueryContext(ctx, sqlText, args...)
 	if err != nil {
 		return 0, err
 	}
 	defer rows.Close()
 	var total int64
 	if rows.Next() {
 		if err := rows.Scan(&total); err != nil {
 			return 0, err
 		}
 	}
 	return total, rows.Err()
 }
 func normalizeMetricQuery(query MetricQuery) MetricQuery {
 	query.VehicleKey = strings.TrimSpace(query.VehicleKey)
 	query.VIN = strings.TrimSpace(query.VIN)
 	query.Protocol = strings.ToUpper(strings.TrimSpace(query.Protocol))
 	query.MetricKey = strings.TrimSpace(query.MetricKey)
 	query.DateFrom = strings.TrimSpace(query.DateFrom)
 	query.DateTo = strings.TrimSpace(query.DateTo)
 	if query.Limit <= 0 {
 		query.Limit = 50
 	}
 	return query
 }
 func buildMetricSQL(query MetricQuery) (string, []any) {
 	where, args := buildMetricWhere(query)
 	sqlText := `SELECT vehicle_key, vin, stat_date, protocol, metric_key, metric_value, metric_unit, first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method, created_at, updated_at FROM vehicle_daily_metric`
 	if len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	sqlText += " ORDER BY stat_date DESC, vehicle_key ASC, protocol ASC, metric_key ASC LIMIT ? OFFSET ?"
 	args = append(args, query.Limit, query.Offset)
 	return sqlText, args
 }
 func buildMetricCountSQL(query MetricQuery) (string, []any) {
 	where, args := buildMetricWhere(query)
 	sqlText := `SELECT COUNT(*) FROM vehicle_daily_metric`
 	if len(where) > 0 {
 		sqlText += " WHERE " + strings.Join(where, " AND ")
 	}
 	return sqlText, args
 }
 func buildMetricWhere(query MetricQuery) ([]string, []any) {
 	var where []string
 	var args []any
 	add := func(clause string, value any) {
 		where = append(where, clause)
 		args = append(args, value)
 	}
 	if query.VIN != "" {
 		add("vin = ?", query.VIN)
 	}
 	if query.VehicleKey != "" {
 		add("vehicle_key = ?", query.VehicleKey)
 	}
 	if query.Protocol != "" {
 		add("protocol = ?", query.Protocol)
 	}
 	if query.MetricKey != "" {
 		add("metric_key = ?", query.MetricKey)
 	}
 	if query.DateFrom != "" {
 		add("stat_date >= ?", query.DateFrom)
 	}
 	if query.DateTo != "" {
 		add("stat_date <= ?", query.DateTo)
 	}
 	return where, args
 }
 type MetricHandler struct {
 	repository *MetricRepository
 }
 func NewMetricHandler(repository *MetricRepository) *MetricHandler {
 	if repository == nil {
 		panic("metric repository must not be nil")
 	}
 	return &MetricHandler{repository: repository}
 }
 func (h *MetricHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodGet {
 		writeMetricError(w, http.StatusMethodNotAllowed, "method not allowed")
 		return
 	}
 	if strings.Trim(r.URL.Path, "/") != "api/stats/daily-metrics" {
 		writeMetricError(w, http.StatusNotFound, "route not found")
 		return
 	}
 	query, err := parseMetricQuery(r)
 	if err != nil {
 		writeMetricError(w, http.StatusBadRequest, err.Error())
 		return
 	}
 	total, err := h.repository.Count(r.Context(), query)
 	if err != nil {
 		writeMetricError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	rows, err := h.repository.Query(r.Context(), query)
 	if err != nil {
 		writeMetricError(w, http.StatusInternalServerError, err.Error())
 		return
 	}
 	w.Header().Set("Content-Type", "application/json")
 	_ = json.NewEncoder(w).Encode(map[string]any{
 		"items":  rows,
 		"total":  total,
 		"limit":  query.Limit,
 		"offset": query.Offset,
 	})
 }
 func parseMetricQuery(r *http.Request) (MetricQuery, error) {
 	values := r.URL.Query()
 	limit, err := parseBoundedInt(values.Get("limit"), 50, 1, 1000, "limit")
 	if err != nil {
 		return MetricQuery{}, err
 	}
 	offset, err := parseBoundedInt(values.Get("offset"), 0, 0, 1_000_000, "offset")
 	if err != nil {
 		return MetricQuery{}, err
 	}
 	query := MetricQuery{
 		VehicleKey: values.Get("vehicleKey"),
 		VIN:        values.Get("vin"),
 		Protocol:   values.Get("protocol"),
 		MetricKey:  values.Get("metricKey"),
 		DateFrom:   values.Get("dateFrom"),
 		DateTo:     values.Get("dateTo"),
 		Limit:      limit,
 		Offset:     offset,
 	}
 	if !validDate(query.DateFrom) || !validDate(query.DateTo) {
 		return MetricQuery{}, errors.New("dateFrom/dateTo must use YYYY-MM-DD")
 	}
 	return normalizeMetricQuery(query), nil
 }
 func parseBoundedInt(raw string, fallback int, min int, max int, name string) (int, error) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
 		return fallback, nil
 	}
 	value, err := strconv.Atoi(raw)
 	if err != nil || value < min || value > max {
 		return 0, fmt.Errorf("%s must be between %d and %d", name, min, max)
 	}
 	return value, nil
 }
 func validDate(value string) bool {
 	value = strings.TrimSpace(value)
 	if value == "" {
 		return true
 	}
 	if len(value) != len("2006-01-02") {
 		return false
 	}
 	for i, r := range value {
 		switch i {
 		case 4, 7:
 			if r != '-' {
 				return false
 			}
 		default:
 			if r < '0' || r > '9' {
 				return false
 			}
 		}
 	}
 	return true
 }
 func writeMetricError(w http.ResponseWriter, status int, message string) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
 	_ = json.NewEncoder(w).Encode(map[string]any{"error": message})
 }
 type scanDate struct {
 	String string
 }
 func (s *scanDate) Scan(value any) error {
 	s.String = formatSQLTime(value, "2006-01-02")
 	return nil
 }
 type scanDateTime struct {
 	String string
 }
 func (s *scanDateTime) Scan(value any) error {
 	s.String = formatSQLTime(value, "2006-01-02 15:04:05")
 	return nil
 }
 func formatSQLTime(value any, layout string) string {
 	switch typed := value.(type) {
 	case nil:
 		return ""
 	case time.Time:
 		return typed.Format(layout)
 	case []byte:
 		return strings.TrimSpace(string(typed))
 	case string:
 		return strings.TrimSpace(typed)
 	default:
 		return strings.TrimSpace(fmt.Sprint(typed))
 	}
 }
--- a/go/vehicle-gateway/internal/stats/query_test.go
+++ b/go/vehicle-gateway/internal/stats/query_test.go
@@ -0,0 +1,185 @@
 package stats
 import (
 	"context"
 	"database/sql"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"time"
 	"github.com/DATA-DOG/go-sqlmock"
 )
 func TestMetricRepositoryQueriesDailyMetricsWithFilters(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT vehicle_key, vin, stat_date, protocol, metric_key, metric_value, metric_unit, first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method, created_at, updated_at FROM vehicle_daily_metric").
 		WithArgs("LKLG7C4E3NA774736", "JT808", "2026-07-01", "2026-07-01", 20, 0).
 		WillReturnRows(sqlmock.NewRows([]string{
 			"vehicle_key", "vin", "stat_date", "protocol", "metric_key", "metric_value", "metric_unit",
 			"first_total_mileage_km", "latest_total_mileage_km", "sample_count", "calculation_method",
 			"created_at", "updated_at",
 		}).AddRow(
 			"LKLG7C4E3NA774736", "LKLG7C4E3NA774736", time.Date(2026, 7, 1, 0, 0, 0, 0, time.FixedZone("Asia/Shanghai", 8*3600)), "JT808", MetricDailyTotalMileageKM, 12345.6, "km",
 			12345.6, 12345.6, 13, "TOTAL_MILEAGE_DIFF", time.Date(2026, 7, 1, 22, 49, 11, 0, time.FixedZone("Asia/Shanghai", 8*3600)), time.Date(2026, 7, 1, 23, 9, 36, 0, time.FixedZone("Asia/Shanghai", 8*3600)),
 		))
 	repository := NewMetricRepository(db)
 	rows, err := repository.Query(context.Background(), MetricQuery{
 		VIN:      "LKLG7C4E3NA774736",
 		Protocol: "JT808",
 		DateFrom: "2026-07-01",
 		DateTo:   "2026-07-01",
 		Limit:    20,
 	})
 	if err != nil {
 		t.Fatalf("Query() error = %v", err)
 	}
 	if len(rows) != 1 {
 		t.Fatalf("row count = %d", len(rows))
 	}
 	if rows[0].MetricKey != MetricDailyTotalMileageKM || rows[0].MetricValue != 12345.6 {
 		t.Fatalf("unexpected row: %#v", rows[0])
 	}
 	if rows[0].VehicleKey != "LKLG7C4E3NA774736" {
 		t.Fatalf("vehicle key = %q", rows[0].VehicleKey)
 	}
 	if rows[0].StatDate != "2026-07-01" || rows[0].UpdatedAt != "2026-07-01 23:09:36" {
 		t.Fatalf("unexpected time formatting: %#v", rows[0])
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMetricHandlerReturnsDailyMetrics(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM vehicle_daily_metric").
 		WithArgs("LB9A32A21R0LS1707", "GB32960", "2020-07-01", "2020-07-01").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(42))
 	mock.ExpectQuery("SELECT vehicle_key, vin, stat_date, protocol, metric_key, metric_value, metric_unit, first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method, created_at, updated_at FROM vehicle_daily_metric").
 		WithArgs("LB9A32A21R0LS1707", "GB32960", "2020-07-01", "2020-07-01", 50, 0).
 		WillReturnRows(sqlmock.NewRows([]string{
 			"vehicle_key", "vin", "stat_date", "protocol", "metric_key", "metric_value", "metric_unit",
 			"first_total_mileage_km", "latest_total_mileage_km", "sample_count", "calculation_method",
 			"created_at", "updated_at",
 		}).AddRow(
 			"LB9A32A21R0LS1707", "LB9A32A21R0LS1707", "2020-07-01", "GB32960", MetricDailyMileageKM, 0.0, "km",
 			53490.9, 53490.9, 3, "TOTAL_MILEAGE_DIFF", "2026-07-01 22:07:58", "2026-07-01 22:28:25",
 		))
 	handler := NewMetricHandler(NewMetricRepository(db))
 	request := httptest.NewRequest(http.MethodGet, "/api/stats/daily-metrics?vin=LB9A32A21R0LS1707&protocol=GB32960&dateFrom=2020-07-01&dateTo=2020-07-01", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"vin":"LB9A32A21R0LS1707"`, `"metric_key":"daily_mileage_km"`, `"total":42`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMetricHandlerFiltersByVehicleKey(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM vehicle_daily_metric").
 		WithArgs("JT808:013307811254", "JT808").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(12))
 	mock.ExpectQuery("SELECT vehicle_key, vin, stat_date, protocol, metric_key, metric_value, metric_unit, first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method, created_at, updated_at FROM vehicle_daily_metric").
 		WithArgs("JT808:013307811254", "JT808", 50, 0).
 		WillReturnRows(sqlmock.NewRows([]string{
 			"vehicle_key", "vin", "stat_date", "protocol", "metric_key", "metric_value", "metric_unit",
 			"first_total_mileage_km", "latest_total_mileage_km", "sample_count", "calculation_method",
 			"created_at", "updated_at",
 		}).AddRow(
 			"JT808:013307811254", "", "2026-07-02", "JT808", MetricDailyTotalMileageKM, 10985.7, "km",
 			10985.7, 10985.7, 1, "TOTAL_MILEAGE_DIFF", "2026-07-02 00:03:00", "2026-07-02 00:03:00",
 		))
 	handler := NewMetricHandler(NewMetricRepository(db))
 	request := httptest.NewRequest(http.MethodGet, "/api/stats/daily-metrics?vehicleKey=JT808:013307811254&protocol=JT808", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	for _, want := range []string{`"vehicle_key":"JT808:013307811254"`, `"vin":""`, `"metric_value":10985.7`} {
 		if !strings.Contains(body, want) {
 			t.Fatalf("response missing %s: %s", want, body)
 		}
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMetricHandlerReturnsEmptyItemsArrayWhenNoRows(t *testing.T) {
 	db, mock, err := sqlmock.New()
 	if err != nil {
 		t.Fatalf("sqlmock.New() error = %v", err)
 	}
 	defer db.Close()
 	mock.ExpectQuery("SELECT COUNT\\(\\*\\) FROM vehicle_daily_metric").
 		WithArgs("YUTONG_MQTT").
 		WillReturnRows(sqlmock.NewRows([]string{"total"}).AddRow(0))
 	mock.ExpectQuery("SELECT vehicle_key, vin, stat_date, protocol, metric_key, metric_value, metric_unit, first_total_mileage_km, latest_total_mileage_km, sample_count, calculation_method, created_at, updated_at FROM vehicle_daily_metric").
 		WithArgs("YUTONG_MQTT", 50, 0).
 		WillReturnRows(sqlmock.NewRows([]string{
 			"vehicle_key", "vin", "stat_date", "protocol", "metric_key", "metric_value", "metric_unit",
 			"first_total_mileage_km", "latest_total_mileage_km", "sample_count", "calculation_method",
 			"created_at", "updated_at",
 		}))
 	handler := NewMetricHandler(NewMetricRepository(db))
 	request := httptest.NewRequest(http.MethodGet, "/api/stats/daily-metrics?protocol=YUTONG_MQTT", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusOK {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 	body := response.Body.String()
 	if !strings.Contains(body, `"items":[]`) || strings.Contains(body, `"items":null`) {
 		t.Fatalf("expected empty items array, got: %s", body)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Fatalf("sql expectations: %v", err)
 	}
 }
 func TestMetricHandlerRejectsInvalidPagination(t *testing.T) {
 	handler := NewMetricHandler(NewMetricRepository(&sql.DB{}))
 	request := httptest.NewRequest(http.MethodGet, "/api/stats/daily-metrics?limit=2001", nil)
 	response := httptest.NewRecorder()
 	handler.ServeHTTP(response, request)
 	if response.Code != http.StatusBadRequest {
 		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
 	}
 }
--- a/go/vehicle-gateway/internal/stats/schema.go
+++ b/go/vehicle-gateway/internal/stats/schema.go
@@ -0,0 +1,22 @@
 package stats
 const DailyMetricTableSQL = `CREATE TABLE IF NOT EXISTS vehicle_daily_metric (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  vehicle_key VARCHAR(96) NOT NULL,
  vin VARCHAR(32) NOT NULL DEFAULT '',
  stat_date DATE NOT NULL,
  protocol VARCHAR(32) NOT NULL,
  metric_key VARCHAR(64) NOT NULL,
  metric_value DECIMAL(18,3) NOT NULL,
  metric_unit VARCHAR(16) NOT NULL,
  first_total_mileage_km DECIMAL(18,3) NULL,
  latest_total_mileage_km DECIMAL(18,3) NULL,
  sample_count BIGINT NOT NULL DEFAULT 0,
  calculation_method VARCHAR(64) NOT NULL,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_daily_metric_vehicle (vehicle_key, stat_date, protocol, metric_key),
  KEY idx_vin (vin),
  KEY idx_stat_date (stat_date),
  KEY idx_protocol_metric (protocol, metric_key)
 )`
--- a/tools/go_kafka_prod_smoke.py
+++ b/tools/go_kafka_prod_smoke.py
@@ -0,0 +1,162 @@
 #!/usr/bin/env python3
 """Kafka topic and consumer lag smoke checks for the Go native production stack."""
 from __future__ import annotations
 import argparse
 import json
 import subprocess
 import sys
 from dataclasses import asdict, dataclass
 DEFAULT_HOST = "114.55.58.251"
 DEFAULT_USER = "root"
 DEFAULT_BOOTSTRAP = "127.0.0.1:9092"
 DEFAULT_KAFKA_BIN = "/opt/kafka/current/bin"
 DEFAULT_TOPICS = [
    "vehicle.raw.go.gb32960.v1",
    "vehicle.raw.go.jt808.v1",
    "vehicle.raw.go.yutong-mqtt.v1",
    "vehicle.event.go.unified.v1",
 ]
 DEFAULT_GROUPS = [
    "go-history-writer",
    "go-stat-writer",
    "go-realtime-api",
 ]
@dataclass(frozen=True)
 class Check:
    name: str
    status: str
    message: str
@dataclass(frozen=True)
 class ConsumerLag:
    group: str
    topic: str
    partition: int
    current_offset: int | None
    log_end_offset: int
    lag: int | None
 def parse_topic_list(output: str) -> set[str]:
    return {line.strip() for line in output.splitlines() if line.strip()}
 def topic_checks(existing: set[str], required: list[str]) -> list[Check]:
    checks: list[Check] = []
    for topic in required:
        if topic in existing:
            checks.append(Check("topic." + topic, "pass", "present"))
        else:
            checks.append(Check("topic." + topic, "fail", "missing"))
    return checks
 def parse_consumer_group_describe(output: str) -> list[ConsumerLag]:
    rows: list[ConsumerLag] = []
    for line in output.splitlines():
        parts = line.split()
        if len(parts) < 6 or parts[0] == "GROUP":
            continue
        group, topic = parts[0], parts[1]
        try:
            partition = int(parts[2])
            current = parse_optional_int(parts[3])
            log_end = int(parts[4])
            lag = parse_optional_int(parts[5])
        except ValueError:
            continue
        rows.append(ConsumerLag(group, topic, partition, current, log_end, lag))
    return rows
 def parse_optional_int(value: str) -> int | None:
    value = value.strip()
    if value == "-":
        return None
    return int(value)
 def group_lag_check(group: str, rows: list[ConsumerLag], max_lag: int) -> Check:
    group_rows = [row for row in rows if row.group == group]
    if not group_rows:
        return Check("group." + group, "fail", "no rows")
    concrete_lags = [row.lag for row in group_rows if row.lag is not None]
    if not concrete_lags:
        return Check("group." + group, "fail", "no concrete lag rows")
    max_seen = max(concrete_lags)
    topics = sorted({row.topic for row in group_rows})
    status = "pass" if max_seen <= max_lag else "fail"
    return Check(
        "group." + group,
        status,
        "max_lag=" + str(max_seen) + "; threshold=" + str(max_lag) + "; topics=" + ",".join(topics),
    )
 def ssh(host: str, user: str, command: str, timeout: float) -> str:
    target = user + "@" + host if user else host
    completed = subprocess.run(
        ["ssh", "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", target, command],
        check=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        timeout=timeout,
    )
    return completed.stdout
 def remote_topic_command(kafka_bin: str, bootstrap: str) -> str:
    return kafka_bin.rstrip("/") + "/kafka-topics.sh --bootstrap-server " + bootstrap + " --list"
 def remote_group_command(kafka_bin: str, bootstrap: str, group: str) -> str:
    return kafka_bin.rstrip("/") + "/kafka-consumer-groups.sh --bootstrap-server " + bootstrap + " --describe --group " + group
 def run(args: argparse.Namespace) -> tuple[str, list[Check]]:
    topic_output = ssh(args.host, args.user, remote_topic_command(args.kafka_bin, args.bootstrap), args.timeout)
    checks = topic_checks(parse_topic_list(topic_output), DEFAULT_TOPICS)
    for group in DEFAULT_GROUPS:
        group_output = ssh(args.host, args.user, remote_group_command(args.kafka_bin, args.bootstrap, group), args.timeout)
        checks.append(group_lag_check(group, parse_consumer_group_describe(group_output), args.max_lag))
    status = "fail" if any(check.status == "fail" for check in checks) else "pass"
    return status, checks
 def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--host", default=DEFAULT_HOST)
    parser.add_argument("--user", default=DEFAULT_USER)
    parser.add_argument("--bootstrap", default=DEFAULT_BOOTSTRAP)
    parser.add_argument("--kafka-bin", default=DEFAULT_KAFKA_BIN)
    parser.add_argument("--max-lag", type=int, default=100)
    parser.add_argument("--timeout", type=float, default=20.0)
    return parser.parse_args(argv)
 def main(argv: list[str]) -> int:
    args = parse_args(argv)
    try:
        status, checks = run(args)
    except Exception as exc:
        status = "fail"
        checks = [Check("kafka.ssh", "fail", str(exc))]
    print(json.dumps({
        "status": status,
        "host": args.host,
        "bootstrap": args.bootstrap,
        "checks": [asdict(check) for check in checks],
    }, ensure_ascii=False, indent=2))
    return 0 if status == "pass" else 1
 if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))
--- a/tools/go_native_deploy.py
+++ b/tools/go_native_deploy.py
@@ -0,0 +1,253 @@
 #!/usr/bin/env python3
 """Build and deploy the Go native vehicle gateway release to ECS."""
 from __future__ import annotations
 import argparse
 import os
 import pathlib
 import shutil
 import subprocess
 import sys
 import tarfile
 import tempfile
 import time
 from dataclasses import dataclass
 DEFAULT_APP_HOST = "115.29.187.205"
 DEFAULT_KAFKA_HOST = "114.55.58.251"
 DEFAULT_USER = "root"
 DEFAULT_RELEASE_ROOT = "/opt/lingniu-go-native"
 DEFAULT_GO_DIR = "go/vehicle-gateway"
 BINARIES = [
    ("gateway", "./cmd/gateway"),
    ("history-writer", "./cmd/history-writer"),
    ("stat-writer", "./cmd/stat-writer"),
    ("realtime-api", "./cmd/realtime-api"),
 ]
 SERVICES = [
    "lingniu-go-gateway",
    "lingniu-go-history-writer",
    "lingniu-go-stat-writer",
    "lingniu-go-realtime-api",
 ]
@dataclass(frozen=True)
 class BuildCommand:
    output_name: str
    argv: list[str]
    env: list[str]
    cwd: str
@dataclass(frozen=True)
 class SpoolStatus:
    files: int
    recent: int
 def git_short_sha(cwd: str) -> str:
    return run_capture(["git", "rev-parse", "--short=7", "HEAD"], cwd=cwd).strip()
 def build_commands(go_dir: str, output_dir: str) -> list[BuildCommand]:
    commands: list[BuildCommand] = []
    env = ["CGO_ENABLED=0", "GOOS=linux", "GOARCH=amd64"]
    for output_name, package in BINARIES:
        commands.append(BuildCommand(
            output_name=output_name,
            argv=[
                "go",
                "build",
                "-trimpath",
                "-ldflags=-s -w",
                "-o",
                str(pathlib.Path(output_dir) / output_name),
                package,
            ],
            env=env,
            cwd=go_dir,
        ))
    return commands
 def build_release(go_dir: str, output_dir: str) -> None:
    for command in build_commands(go_dir, output_dir):
        env = os.environ.copy()
        for item in command.env:
            key, value = item.split("=", 1)
            env[key] = value
        run(command.argv, cwd=command.cwd, env=env)
 def create_archive(source_dir: str, archive_path: str) -> None:
    with tarfile.open(archive_path, "w:gz") as archive:
        for binary, _ in BINARIES:
            archive.add(pathlib.Path(source_dir) / binary, arcname=binary)
 def remote_switch_command(release: str, release_root: str, remote_archive: str) -> str:
    if not safe_release_name(release):
        raise ValueError("release must contain only letters, numbers, dot, underscore, or dash")
    release_dir = release_root.rstrip("/") + "/releases/" + release
    root = release_root.rstrip("/")
    commands = [
        "set -euo pipefail",
        "mkdir -p " + shell_quote(release_dir),
        "tar -xzf " + shell_quote(remote_archive) + " -C " + shell_quote(release_dir),
        "chmod +x " + shell_quote(release_dir) + "/*",
        "ln -sfn " + shell_quote(release_dir) + " " + shell_quote(root + "/current"),
        "systemctl daemon-reload",
    ]
    commands.extend("systemctl restart " + service for service in SERVICES)
    commands.append("rm -f " + shell_quote(remote_archive))
    return " && ".join(commands)
 def acceptance_command(app_host: str, kafka_host: str, date: str, timeout: float) -> list[str]:
    command = [
        "python3",
        "tools/go_prod_acceptance.py",
        "--app-host",
        app_host,
        "--kafka-host",
        kafka_host,
        "--timeout",
        str(int(timeout) if timeout == int(timeout) else timeout),
    ]
    if date:
        command.extend(["--date", date])
    return command
 def deploy(args: argparse.Namespace) -> None:
    repo = pathlib.Path(args.repo).resolve()
    go_dir = str(repo / args.go_dir)
    release = args.release or git_short_sha(str(repo))
    with tempfile.TemporaryDirectory(prefix="lingniu-go-native-") as tmp:
        output_dir = pathlib.Path(tmp) / "out"
        output_dir.mkdir()
        archive_path = pathlib.Path(tmp) / ("lingniu-go-native-" + release + ".tar.gz")
        build_release(go_dir, str(output_dir))
        create_archive(str(output_dir), str(archive_path))
        remote_archive = "/tmp/" + archive_path.name
        target = ssh_target(args.user, args.app_host)
        run(["scp", "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", str(archive_path), target + ":" + remote_archive])
        run([
            "ssh",
            "-o",
            "StrictHostKeyChecking=no",
            "-o",
            "UserKnownHostsFile=/dev/null",
            target,
            remote_switch_command(release, args.release_root, remote_archive),
        ])
        wait_for_spool_drain(target, args.release_root, args.spool_drain_timeout, args.spool_poll_interval)
    if not args.skip_acceptance:
        run(acceptance_command(args.app_host, args.kafka_host, args.date, args.timeout), cwd=str(repo))
 def wait_for_spool_drain(target: str, release_root: str, timeout: float, poll_interval: float) -> None:
    deadline = time.monotonic() + timeout
    last = SpoolStatus(files=-1, recent=-1)
    while time.monotonic() <= deadline:
        output = run_capture([
            "ssh",
            "-o",
            "StrictHostKeyChecking=no",
            "-o",
            "UserKnownHostsFile=/dev/null",
            target,
            spool_status_command(release_root),
        ])
        last = parse_spool_status(output)
        print(f"spool files={last.files} recent={last.recent}", flush=True)
        if last.files == 0:
            return
        time.sleep(max(1.0, poll_interval))
    raise RuntimeError(f"gateway spool did not drain: files={last.files} recent={last.recent}")
 def spool_status_command(release_root: str) -> str:
    spool_dir = release_root.rstrip("/") + "/spool/gateway"
    return (
        "spool=" + shell_quote(spool_dir) + "; "
        "files=$(find \"$spool\" -type f 2>/dev/null | wc -l); "
        "recent=$(find \"$spool\" -type f -mmin -5 2>/dev/null | wc -l); "
        "printf 'files=%s recent=%s\\n' \"$files\" \"$recent\""
    )
 def parse_spool_status(output: str) -> SpoolStatus:
    values: dict[str, int] = {}
    for part in output.split():
        if "=" not in part:
            continue
        key, value = part.split("=", 1)
        try:
            values[key] = int(value)
        except ValueError:
            continue
    return SpoolStatus(files=values.get("files", -1), recent=values.get("recent", -1))
 def ssh_target(user: str, host: str) -> str:
    return user + "@" + host if user else host
 def shell_quote(value: str) -> str:
    return "'" + value.replace("'", "'\"'\"'") + "'"
 def safe_release_name(value: str) -> bool:
    value = value.strip()
    if not value:
        return False
    return all(r.isalnum() or r in "._-" for r in value)
 def run(argv: list[str], cwd: str | None = None, env: dict[str, str] | None = None) -> None:
    subprocess.run(argv, cwd=cwd, env=env, check=True)
 def run_capture(argv: list[str], cwd: str | None = None) -> str:
    return subprocess.run(argv, cwd=cwd, check=True, stdout=subprocess.PIPE, text=True).stdout
 def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--repo", default=".")
    parser.add_argument("--go-dir", default=DEFAULT_GO_DIR)
    parser.add_argument("--app-host", default=DEFAULT_APP_HOST)
    parser.add_argument("--kafka-host", default=DEFAULT_KAFKA_HOST)
    parser.add_argument("--user", default=DEFAULT_USER)
    parser.add_argument("--release-root", default=DEFAULT_RELEASE_ROOT)
    parser.add_argument("--release", default="")
    parser.add_argument("--date", default="")
    parser.add_argument("--timeout", type=float, default=20.0)
    parser.add_argument("--spool-drain-timeout", type=float, default=900.0)
    parser.add_argument("--spool-poll-interval", type=float, default=10.0)
    parser.add_argument("--skip-acceptance", action="store_true")
    return parser.parse_args(argv)
 def main(argv: list[str]) -> int:
    args = parse_args(argv)
    try:
        deploy(args)
    except subprocess.CalledProcessError as exc:
        print("command failed: " + " ".join(exc.cmd), file=sys.stderr)
        return exc.returncode or 1
    except (OSError, shutil.Error) as exc:
        print("deploy failed: " + str(exc), file=sys.stderr)
        return 1
    except RuntimeError as exc:
        print("deploy failed: " + str(exc), file=sys.stderr)
        return 1
    return 0
 if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))
--- a/tools/go_native_prod_smoke.py
+++ b/tools/go_native_prod_smoke.py
@@ -0,0 +1,544 @@
 #!/usr/bin/env python3
 """HTTP smoke checks for the Go native production vehicle ingest stack."""
 from __future__ import annotations
 import argparse
 import datetime as dt
 import json
 import sys
 import urllib.parse
 import urllib.request
 from dataclasses import asdict, dataclass
 from typing import Any
 SHANGHAI = dt.timezone(dt.timedelta(hours=8))
 DEFAULT_BASE_URL = "http://115.29.187.205:20210"
 DEFAULT_REALTIME_MAX_AGE_MINUTES = 15.0
@dataclass(frozen=True)
 class CheckSpec:
    name: str
    path: str
    params: dict[str, Any]
    minimum: int
    kind: str = "total"
    max_age_minutes: float | None = None
    require_parsed_json: bool = False
    require_frame_id: bool = False
    require_metric_formula: bool = False
@dataclass(frozen=True)
 class Check:
    name: str
    status: str
    count: int
    minimum: int
    message: str
@dataclass(frozen=True)
 class CheckWindow:
    date_from: str
    date_to: str
    stat_date: str
    max_raw_age_minutes: float | None
 def shanghai_day_window(now: dt.datetime | None = None) -> tuple[str, str]:
    now = now or dt.datetime.now(tz=SHANGHAI)
    local = now.astimezone(SHANGHAI)
    start = dt.datetime(local.year, local.month, local.day, tzinfo=SHANGHAI)
    end = start + dt.timedelta(days=1)
    return start.isoformat(timespec="seconds"), end.isoformat(timespec="seconds")
 def resolve_check_window(
    raw_date: str | None,
    max_raw_age_minutes: float,
    now: dt.datetime | None = None,
 ) -> CheckWindow:
    current = (now or dt.datetime.now(tz=SHANGHAI)).astimezone(SHANGHAI)
    today = current.date()
    if raw_date:
        day = dt.date.fromisoformat(raw_date)
        start = dt.datetime(day.year, day.month, day.day, tzinfo=SHANGHAI)
        date_from, date_to = shanghai_day_window(start)
        freshness = max_raw_age_minutes if day == today else None
        return CheckWindow(date_from, date_to, raw_date, freshness)
    date_from, date_to = shanghai_day_window(current)
    return CheckWindow(date_from, date_to, date_from[:10], max_raw_age_minutes)
 def api_url(base_url: str, path: str, params: dict[str, Any]) -> str:
    url = base_url.rstrip("/") + path
    if not params:
        return url
    return url + "?" + urllib.parse.urlencode(params)
 def query_json(base_url: str, path: str, params: dict[str, Any], timeout: float) -> dict[str, Any]:
    request = urllib.request.Request(
        api_url(base_url, path, params),
        headers={"Accept": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))
 def check_total(
    name: str,
    payload: dict[str, Any],
    minimum: int,
    max_age_minutes: float | None = None,
    now: dt.datetime | None = None,
    require_parsed_json: bool = False,
    require_frame_id: bool = False,
    require_metric_formula: bool = False,
 ) -> Check:
    count = int(payload.get("total") or 0)
    items = payload.get("items") or []
    sample = sample_summary(items)
    age_message = latest_age_message(items, now)
    if count >= minimum:
        parsed_message = ""
        if max_age_minutes is not None:
            latest_age = latest_age_minutes(items, now)
            if latest_age is None:
                return Check(name, "fail", count, minimum, f"count={count}; missing latest ts; sample={sample}")
            if latest_age > max_age_minutes:
                return Check(
                    name,
                    "fail",
                    count,
                    minimum,
                    f"count={count}; latest_age_minutes={latest_age:.1f}; "
                    f"expected <= {max_age_minutes:.1f}; sample={sample}",
                )
        if require_parsed_json:
            parsed_message = parsed_json_message(items)
            if not parsed_message.startswith("parsed_json=ok"):
                return Check(name, "fail", count, minimum, f"count={count}; {parsed_message}; sample={sample}")
        frame_message = ""
        if require_frame_id:
            frame_message = frame_id_message(items)
            if not frame_message.startswith("frame_id=ok"):
                return Check(name, "fail", count, minimum, f"count={count}; {frame_message}; sample={sample}")
        metric_message = ""
        if require_metric_formula:
            metric_message = metric_formula_message(items)
            if not metric_message.startswith("metric_formula=ok"):
                return Check(name, "fail", count, minimum, f"count={count}; {metric_message}; sample={sample}")
        details = [f"count={count}", age_message]
        if parsed_message:
            details.append(parsed_message)
        if frame_message:
            details.append(frame_message)
        if metric_message:
            details.append(metric_message)
        return Check(name, "pass", count, minimum, "; ".join(details) + f"; sample={sample}")
    return Check(name, "fail", count, minimum, f"count={count}; expected >= {minimum}; {age_message}; sample={sample}")
 def parse_tdengine_utc_timestamp(value: str) -> dt.datetime:
    value = str(value or "").strip()
    for layout in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S"):
        try:
            return dt.datetime.strptime(value[:19], layout).replace(tzinfo=dt.timezone.utc)
        except ValueError:
            continue
    raise ValueError(f"unsupported timestamp: {value}")
 def latest_age_minutes(items: list[Any], now: dt.datetime | None = None) -> float | None:
    if not items or not isinstance(items[0], dict):
        return None
    timestamp = items[0].get("received_at") or items[0].get("ts")
    if not timestamp:
        return None
    current = now or dt.datetime.now(tz=dt.timezone.utc)
    if current.tzinfo is None:
        current = current.replace(tzinfo=dt.timezone.utc)
    latest = parse_tdengine_utc_timestamp(str(timestamp))
    return max(0.0, (current.astimezone(dt.timezone.utc) - latest).total_seconds() / 60)
 def latest_age_message(items: list[Any], now: dt.datetime | None = None) -> str:
    latest_age = latest_age_minutes(items, now)
    if latest_age is None:
        return "latest_age_minutes=unknown"
    return f"latest_age_minutes={latest_age:.1f}"
 def parsed_json_message(items: list[Any]) -> str:
    if not items or not isinstance(items[0], dict):
        return "missing parsed_json"
    raw = items[0].get("parsed_json")
    if isinstance(raw, dict) and raw:
        return "parsed_json=ok"
    if not isinstance(raw, str) or not raw.strip() or raw.strip().lower() == "null":
        return "missing parsed_json"
    try:
        parsed = json.loads(raw)
    except json.JSONDecodeError:
        return "invalid parsed_json"
    if isinstance(parsed, dict) and parsed:
        return "parsed_json=ok"
    return "invalid parsed_json"
 def frame_id_message(items: list[Any]) -> str:
    if not items or not isinstance(items[0], dict):
        return "missing frame_id"
    frame_id = str(items[0].get("frame_id") or "").strip()
    if frame_id:
        return "frame_id=ok"
    return "missing frame_id"
 def metric_formula_message(items: list[Any]) -> str:
    if not items or not isinstance(items[0], dict):
        return "missing metric row"
    row = items[0]
    try:
        metric_value = float(row.get("metric_value"))
        first_total = float(row.get("first_total_mileage_km"))
        latest_total = float(row.get("latest_total_mileage_km"))
    except (TypeError, ValueError):
        return "missing metric formula fields"
    metric_key = str(row.get("metric_key") or "")
    if metric_key == "daily_mileage_km":
        expected = max(0.0, latest_total - first_total)
    elif metric_key == "daily_total_mileage_km":
        expected = latest_total
    else:
        return "unsupported metric_key=" + metric_key
    if abs(metric_value - expected) <= 0.001:
        return "metric_formula=ok"
    return f"metric_formula mismatch value={metric_value:.3f} expected={expected:.3f}"
 def check_realtime(
    name: str,
    payload: dict[str, Any],
    max_age_minutes: float | None = None,
    now: dt.datetime | None = None,
 ) -> Check:
    if payload.get("online") is False:
        return Check(name, "fail", 0, 1, "online=false")
    updated_message = ""
    if max_age_minutes is not None:
        updated_age = realtime_updated_age_minutes(payload, now)
        if updated_age is None:
            return Check(name, "fail", 0, 1, "missing updated_at_ms")
        updated_message = f"updated_age_minutes={updated_age:.1f}"
        if updated_age > max_age_minutes:
            return Check(
                name,
                "fail",
                0,
                1,
                updated_message + f"; expected <= {max_age_minutes:.1f}",
            )
    identifier = payload.get("vin") or payload.get("vehicle_key") or ""
    protocols = payload.get("protocols") or []
    protocol = payload.get("protocol") or ""
    fields = payload.get("fields") or {}
    message = json.dumps(
        {
            key: value
            for key, value in {
                "identifier": identifier,
                "protocol": protocol,
                "protocols": protocols,
                "field_count": len(fields) if isinstance(fields, dict) else 0,
                "online": payload.get("online"),
            }.items()
            if value not in (None, "", [])
        },
        ensure_ascii=False,
        sort_keys=True,
    )
    if updated_message:
        message = updated_message + "; " + message
    return Check(name, "pass", 1, 1, message)
 def realtime_updated_age_minutes(payload: dict[str, Any], now: dt.datetime | None = None) -> float | None:
    try:
        updated_ms = int(payload.get("updated_at_ms"))
    except (TypeError, ValueError):
        return None
    current = now or dt.datetime.now(tz=dt.timezone.utc)
    if current.tzinfo is None:
        current = current.replace(tzinfo=dt.timezone.utc)
    updated = dt.datetime.fromtimestamp(updated_ms / 1000, tz=dt.timezone.utc)
    return max(0.0, (current.astimezone(dt.timezone.utc) - updated).total_seconds() / 60)
 def sample_summary(items: list[Any]) -> str:
    if not items:
        return "{}"
    first = items[0]
    if not isinstance(first, dict):
        return json.dumps(first, ensure_ascii=False, sort_keys=True)
    keep = {
        key: first.get(key)
        for key in (
            "ts",
            "stat_date",
            "protocol",
            "vehicle_key",
            "vin",
            "phone",
            "message_id_hex",
            "metric_key",
            "metric_value",
            "total_mileage_km",
            "latest_total_mileage_km",
        )
        if first.get(key) not in (None, "")
    }
    return json.dumps(keep, ensure_ascii=False, sort_keys=True)
 def overall_status(checks: list[Check]) -> str:
    return "fail" if any(check.status == "fail" for check in checks) else "pass"
 def build_check_specs(
    *,
    date_from: str,
    date_to: str,
    stat_date: str,
    min_raw: int,
    min_history: int,
    min_stat: int,
    max_raw_age_minutes: float | None = None,
 ) -> list[CheckSpec]:
    raw_params = {"limit": 1, "orderBy": "receivedAt", "includeTotal": "false"}
    gb32960_history_params = {"protocol": "GB32960", "dateFrom": date_from, "dateTo": date_to, "limit": 1}
    jt808_history_params = {"protocol": "JT808", "dateFrom": date_from, "dateTo": date_to, "limit": 1}
    yutong_mqtt_history_params = {"protocol": "YUTONG_MQTT", "dateFrom": date_from, "dateTo": date_to, "limit": 1}
    return [
        CheckSpec(
            "gb32960.raw",
            "/api/history/raw-frames",
            {**raw_params, "protocol": "GB32960"},
            min_raw,
            max_age_minutes=max_raw_age_minutes,
            require_parsed_json=True,
        ),
        CheckSpec(
            "jt808.raw",
            "/api/history/raw-frames",
            {**raw_params, "protocol": "JT808"},
            min_raw,
            max_age_minutes=max_raw_age_minutes,
            require_parsed_json=True,
        ),
        CheckSpec(
            "yutong_mqtt.raw",
            "/api/history/raw-frames",
            {**raw_params, "protocol": "YUTONG_MQTT"},
            min_raw,
            max_age_minutes=max_raw_age_minutes,
            require_parsed_json=True,
        ),
        CheckSpec("gb32960.locations", "/api/history/locations", gb32960_history_params, min_history, require_frame_id=True),
        CheckSpec("gb32960.mileage_points", "/api/history/mileage-points", gb32960_history_params, min_history, require_frame_id=True),
        CheckSpec("jt808.locations", "/api/history/locations", jt808_history_params, min_history, require_frame_id=True),
        CheckSpec("jt808.mileage_points", "/api/history/mileage-points", jt808_history_params, min_history, require_frame_id=True),
        CheckSpec("yutong_mqtt.locations", "/api/history/locations", yutong_mqtt_history_params, min_history, require_frame_id=True),
        CheckSpec("yutong_mqtt.mileage_points", "/api/history/mileage-points", yutong_mqtt_history_params, min_history, require_frame_id=True),
        CheckSpec(
            "gb32960.daily_mileage",
            "/api/stats/daily-metrics",
            {
                "protocol": "GB32960",
                "metricKey": "daily_mileage_km",
                "dateFrom": stat_date,
                "dateTo": stat_date,
                "limit": 1,
            },
            min_stat,
            require_metric_formula=True,
        ),
        CheckSpec(
            "gb32960.daily_total_mileage",
            "/api/stats/daily-metrics",
            {
                "protocol": "GB32960",
                "metricKey": "daily_total_mileage_km",
                "dateFrom": stat_date,
                "dateTo": stat_date,
                "limit": 1,
            },
            min_stat,
            require_metric_formula=True,
        ),
        CheckSpec(
            "jt808.daily_mileage",
            "/api/stats/daily-metrics",
            {
                "protocol": "JT808",
                "metricKey": "daily_mileage_km",
                "dateFrom": stat_date,
                "dateTo": stat_date,
                "limit": 1,
            },
            min_stat,
            require_metric_formula=True,
        ),
        CheckSpec(
            "jt808.daily_total_mileage",
            "/api/stats/daily-metrics",
            {
                "protocol": "JT808",
                "metricKey": "daily_total_mileage_km",
                "dateFrom": stat_date,
                "dateTo": stat_date,
                "limit": 1,
            },
            min_stat,
            require_metric_formula=True,
        ),
    ]
 def vehicle_identifier(item: dict[str, Any]) -> str:
    for key in ("vin", "vehicle_key"):
        value = str(item.get(key) or "").strip()
        if value and value.lower() != "unknown":
            return value
    return ""
 def build_realtime_specs(payloads: dict[str, dict[str, Any]]) -> list[CheckSpec]:
    configs = [
        ("gb32960", "gb32960.raw", "GB32960"),
        ("jt808", "jt808.raw", "JT808"),
        ("yutong_mqtt", "yutong_mqtt.raw", "YUTONG_MQTT"),
    ]
    specs: list[CheckSpec] = []
    for prefix, source_name, protocol in configs:
        items = payloads.get(source_name, {}).get("items") or []
        if not items or not isinstance(items[0], dict):
            continue
        identifier = vehicle_identifier(items[0])
        if not identifier:
            continue
        encoded = urllib.parse.quote(identifier, safe="")
        base_path = "/api/realtime/vehicles/" + encoded
        specs.extend([
            CheckSpec(
                prefix + ".realtime",
                base_path,
                {},
                1,
                "realtime",
                max_age_minutes=DEFAULT_REALTIME_MAX_AGE_MINUTES,
            ),
            CheckSpec(prefix + ".realtime_online", base_path + "/online", {}, 1, "realtime"),
            CheckSpec(
                prefix + ".realtime_protocol",
                base_path + "/protocols/" + protocol,
                {},
                1,
                "realtime",
                max_age_minutes=DEFAULT_REALTIME_MAX_AGE_MINUTES,
            ),
        ])
    return specs
 def run_checks(base_url: str, specs: list[CheckSpec], timeout: float) -> list[Check]:
    checks: list[Check] = []
    for spec in specs:
        try:
            payload = query_json(base_url, spec.path, spec.params, timeout)
            if spec.kind == "realtime":
                checks.append(check_realtime(spec.name, payload, spec.max_age_minutes))
            else:
                checks.append(check_total(
                    spec.name,
                    payload,
                    spec.minimum,
                    spec.max_age_minutes,
                    require_parsed_json=spec.require_parsed_json,
                    require_frame_id=spec.require_frame_id,
                    require_metric_formula=spec.require_metric_formula,
                ))
        except Exception as exc:  # pragma: no cover - exercised by live failures.
            checks.append(Check(spec.name, "fail", 0, spec.minimum, f"request failed: {exc}"))
    return checks
 def query_payloads(base_url: str, specs: list[CheckSpec], timeout: float) -> tuple[list[Check], dict[str, dict[str, Any]]]:
    checks: list[Check] = []
    payloads: dict[str, dict[str, Any]] = {}
    for spec in specs:
        try:
            payload = query_json(base_url, spec.path, spec.params, timeout)
            payloads[spec.name] = payload
            checks.append(check_total(
                spec.name,
                payload,
                spec.minimum,
                spec.max_age_minutes,
                require_parsed_json=spec.require_parsed_json,
                require_frame_id=spec.require_frame_id,
                require_metric_formula=spec.require_metric_formula,
            ))
        except Exception as exc:
            checks.append(Check(spec.name, "fail", 0, spec.minimum, f"request failed: {exc}"))
    return checks, payloads
 def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
    parser.add_argument("--date", help="Shanghai local date, YYYY-MM-DD. Defaults to today.")
    parser.add_argument("--timeout", type=float, default=5.0)
    parser.add_argument("--min-raw", type=int, default=1)
    parser.add_argument("--min-history", type=int, default=1)
    parser.add_argument("--min-stat", type=int, default=1)
    parser.add_argument(
        "--max-raw-age-minutes",
        type=float,
        default=15.0,
        help="Require latest RAW sample age to be at most this many minutes when checking today's date.",
    )
    return parser.parse_args(argv)
 def main(argv: list[str]) -> int:
    args = parse_args(argv)
    window = resolve_check_window(args.date, args.max_raw_age_minutes)
    specs = build_check_specs(
        date_from=window.date_from,
        date_to=window.date_to,
        stat_date=window.stat_date,
        min_raw=args.min_raw,
        min_history=args.min_history,
        min_stat=args.min_stat,
        max_raw_age_minutes=window.max_raw_age_minutes,
    )
    checks, payloads = query_payloads(args.base_url, specs, args.timeout)
    checks.extend(run_checks(args.base_url, build_realtime_specs(payloads), args.timeout))
    status = overall_status(checks)
    print(json.dumps({
        "status": status,
        "baseUrl": args.base_url,
        "dateFrom": window.date_from,
        "dateTo": window.date_to,
        "checks": [asdict(check) for check in checks],
    }, ensure_ascii=False, indent=2))
    return 0 if status == "pass" else 1
 if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))
--- a/tools/go_prod_acceptance.py
+++ b/tools/go_prod_acceptance.py
@@ -0,0 +1,136 @@
 #!/usr/bin/env python3
 """Run the Go native production acceptance smoke suite."""
 from __future__ import annotations
 import argparse
 import json
 import subprocess
 import sys
 from dataclasses import asdict, dataclass
 from typing import Any
 DEFAULT_APP_HOST = "115.29.187.205"
 DEFAULT_KAFKA_HOST = "114.55.58.251"
 DEFAULT_USER = "root"
 DEFAULT_BASE_URL = "http://115.29.187.205:20210"
@dataclass(frozen=True)
 class ChildCommand:
    name: str
    argv: list[str]
@dataclass(frozen=True)
 class ChildResult:
    name: str
    status: str
    exit_code: int
    payload: dict[str, Any]
 def build_commands(args: argparse.Namespace) -> list[ChildCommand]:
    timeout = str(args.timeout)
    return [
        ChildCommand("systemd", [
            sys.executable,
            "tools/go_systemd_prod_smoke.py",
            "--host",
            args.app_host,
            "--user",
            args.ssh_user,
            "--timeout",
            timeout,
        ]),
        ChildCommand("kafka", [
            sys.executable,
            "tools/go_kafka_prod_smoke.py",
            "--host",
            args.kafka_host,
            "--user",
            args.ssh_user,
            "--max-lag",
            str(args.max_lag),
            "--timeout",
            timeout,
        ]),
        ChildCommand("http", [
            sys.executable,
            "tools/go_native_prod_smoke.py",
            "--base-url",
            args.base_url,
            "--timeout",
            timeout,
        ] + (["--date", args.date] if args.date else [])),
    ]
 def run_child(command: ChildCommand, timeout: float) -> ChildResult:
    completed = subprocess.run(
        command.argv,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        timeout=timeout,
    )
    payload = parse_json_output(completed.stdout)
    if completed.stderr.strip():
        payload.setdefault("stderr", completed.stderr.strip())
    status = payload.get("status")
    if status not in {"pass", "fail"}:
        status = "pass" if completed.returncode == 0 else "fail"
    return ChildResult(command.name, status, completed.returncode, payload)
 def parse_json_output(output: str) -> dict[str, Any]:
    output = output.strip()
    if not output:
        return {}
    start = output.find("{")
    end = output.rfind("}")
    if start < 0 or end < start:
        return {"rawOutput": output}
    try:
        return json.loads(output[start:end + 1])
    except json.JSONDecodeError:
        return {"rawOutput": output}
 def overall_status(results: list[ChildResult]) -> str:
    if not results:
        return "fail"
    return "fail" if any(result.status != "pass" or result.exit_code != 0 for result in results) else "pass"
 def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--app-host", default=DEFAULT_APP_HOST)
    parser.add_argument("--kafka-host", default=DEFAULT_KAFKA_HOST)
    parser.add_argument("--ssh-user", default=DEFAULT_USER)
    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
    parser.add_argument("--date", help="Shanghai local date, YYYY-MM-DD. Defaults to today in go_native_prod_smoke.py.")
    parser.add_argument("--timeout", type=float, default=20.0)
    parser.add_argument("--max-lag", type=int, default=100)
    return parser.parse_args(argv)
 def main(argv: list[str]) -> int:
    args = parse_args(argv)
    results: list[ChildResult] = []
    for command in build_commands(args):
        try:
            results.append(run_child(command, args.timeout + 10))
        except Exception as exc:
            results.append(ChildResult(command.name, "fail", 1, {"status": "fail", "error": str(exc)}))
    status = overall_status(results)
    print(json.dumps({
        "status": status,
        "checks": [asdict(result) for result in results],
    }, ensure_ascii=False, indent=2))
    return 0 if status == "pass" else 1
 if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))
--- a/tools/go_systemd_prod_smoke.py
+++ b/tools/go_systemd_prod_smoke.py
@@ -0,0 +1,210 @@
 #!/usr/bin/env python3
 """Systemd and port smoke checks for the Go native production ECS."""
 from __future__ import annotations
 import argparse
 import json
 import subprocess
 import sys
 from dataclasses import asdict, dataclass
 DEFAULT_HOST = "115.29.187.205"
 DEFAULT_USER = "root"
 DEFAULT_SERVICES = [
    "lingniu-go-gateway.service",
    "lingniu-go-history-writer.service",
    "lingniu-go-stat-writer.service",
    "lingniu-go-realtime-api.service",
 ]
 DEFAULT_PORTS = {
    808: "gateway",
    32960: "gateway",
    20210: "realtime-api",
 }
 DEFAULT_RELEASE_ROOT = "/opt/lingniu-go-native"
 DEFAULT_SPOOL_DIR = "/opt/lingniu-go-native/spool/gateway"
 DEFAULT_BINARIES = ["gateway", "history-writer", "stat-writer", "realtime-api"]
@dataclass(frozen=True)
 class Check:
    name: str
    status: str
    message: str
@dataclass(frozen=True)
 class ServiceState:
    active: str
    enabled: str
 def parse_service_states(output: str) -> dict[str, ServiceState]:
    states: dict[str, ServiceState] = {}
    for line in output.splitlines():
        parts = line.split()
        if len(parts) >= 2:
            enabled = parts[2] if len(parts) >= 3 else "enabled"
            states[parts[0]] = ServiceState(parts[1], enabled)
    return states
 def service_checks(output: str, services: list[str]) -> list[Check]:
    states = parse_service_states(output)
    checks: list[Check] = []
    for service in services:
        state = states.get(service, ServiceState("missing", "missing"))
        status = "pass" if state.active == "active" and state.enabled == "enabled" else "fail"
        checks.append(Check(
            "service." + service,
            status,
            "state=" + state.active + "; enabled=" + state.enabled,
        ))
    return checks
 def port_checks(output: str, ports: dict[int, str]) -> list[Check]:
    lines = output.splitlines()
    checks: list[Check] = []
    for port, process in sorted(ports.items()):
        matching = [line.strip() for line in lines if has_port(line, port)]
        if not matching:
            checks.append(Check("port." + str(port), "fail", "not listening"))
            continue
        owned = [line for line in matching if process in line]
        if owned:
            checks.append(Check("port." + str(port), "pass", owned[0]))
        else:
            checks.append(Check("port." + str(port), "fail", matching[0]))
    return checks
 def has_port(line: str, port: int) -> bool:
    needle = ":" + str(port)
    return needle + " " in line or needle + "\t" in line
 def spool_check(output: str) -> Check:
    values = parse_key_values(output)
    files = int(values.get("files", "-1"))
    recent = int(values.get("recent", "-1"))
    status = "pass" if files == 0 and recent == 0 else "fail"
    return Check("spool.gateway", status, output.strip() or "missing")
 def release_check(output: str) -> Check:
    values = parse_key_values(output)
    current = values.get("current", "")
    binaries_present = [values.get(binary, "0") == "1" for binary in DEFAULT_BINARIES]
    status = "pass" if current and all(binaries_present) else "fail"
    return Check("release.current", status, output.strip() or "missing")
 def parse_key_values(output: str) -> dict[str, str]:
    values: dict[str, str] = {}
    for part in output.split():
        if "=" not in part:
            continue
        key, value = part.split("=", 1)
        values[key] = value
    return values
 def ssh(host: str, user: str, command: str, timeout: float) -> str:
    target = user + "@" + host if user else host
    completed = subprocess.run(
        ["ssh", "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", target, command],
        check=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        timeout=timeout,
    )
    return completed.stdout
 def remote_command(services: list[str]) -> str:
    quoted = " ".join(services)
    return (
        "for svc in " + quoted + "; do "
        "printf '%s ' \"$svc\"; "
        "printf '%s ' \"$(systemctl is-active \"$svc\" 2>/dev/null || true)\"; "
        "systemctl is-enabled \"$svc\" 2>/dev/null || true; "
        "done; "
        "printf '\\n--PORTS--\\n'; "
        "ss -lntp; "
        "printf '\\n--SPOOL--\\n'; "
        "spool='" + DEFAULT_SPOOL_DIR + "'; "
        "if test -d \"$spool\"; then "
        "files=$(find \"$spool\" -type f | wc -l); "
        "bytes=$(du -sb \"$spool\" 2>/dev/null | awk '{print $1}'); "
        "recent=$(find \"$spool\" -type f -mmin -5 | wc -l); "
        "printf 'files=%s bytes=%s recent=%s\\n' \"$files\" \"${bytes:-0}\" \"$recent\"; "
        "else printf 'files=-1 bytes=0 recent=-1 missing=%s\\n' \"$spool\"; fi; "
        "printf '\\n--RELEASE--\\n'; "
        "root='" + DEFAULT_RELEASE_ROOT + "'; "
        "current=$(readlink -f \"$root/current\" 2>/dev/null || true); "
        "printf 'current=%s' \"$current\"; "
        "for bin in " + " ".join(DEFAULT_BINARIES) + "; do "
        "if test -x \"$root/current/$bin\"; then present=1; else present=0; fi; "
        "printf ' %s=%s' \"$bin\" \"$present\"; "
        "done; printf '\\n'"
    )
 def split_remote_output(output: str) -> tuple[str, str, str, str]:
    ports_marker = "\n--PORTS--\n"
    spool_marker = "\n--SPOOL--\n"
    release_marker = "\n--RELEASE--\n"
    if ports_marker not in output:
        return output, "", "", ""
    service_output, rest = output.split(ports_marker, 1)
    if spool_marker not in rest:
        return service_output, rest, "", ""
    port_output, spool_output = rest.split(spool_marker, 1)
    if release_marker not in spool_output:
        return service_output, port_output, spool_output, ""
    spool_output, release_output = spool_output.split(release_marker, 1)
    return service_output, port_output, spool_output, release_output
 def run(args: argparse.Namespace) -> tuple[str, list[Check]]:
    output = ssh(args.host, args.user, remote_command(DEFAULT_SERVICES), args.timeout)
    service_output, port_output, spool_output, release_output = split_remote_output(output)
    checks = (
        service_checks(service_output, DEFAULT_SERVICES)
        + port_checks(port_output, DEFAULT_PORTS)
        + [spool_check(spool_output)]
        + [release_check(release_output)]
    )
    status = "fail" if any(check.status == "fail" for check in checks) else "pass"
    return status, checks
 def parse_args(argv: list[str]) -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--host", default=DEFAULT_HOST)
    parser.add_argument("--user", default=DEFAULT_USER)
    parser.add_argument("--timeout", type=float, default=20.0)
    return parser.parse_args(argv)
 def main(argv: list[str]) -> int:
    args = parse_args(argv)
    try:
        status, checks = run(args)
    except Exception as exc:
        status = "fail"
        checks = [Check("systemd.ssh", "fail", str(exc))]
    print(json.dumps({
        "status": status,
        "host": args.host,
        "checks": [asdict(check) for check in checks],
    }, ensure_ascii=False, indent=2))
    return 0 if status == "pass" else 1
 if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))
--- a/tools/test_go_kafka_prod_smoke.py
+++ b/tools/test_go_kafka_prod_smoke.py
@@ -0,0 +1,62 @@
 import unittest
 from tools import go_kafka_prod_smoke as smoke
 class GoKafkaProdSmokeTest(unittest.TestCase):
    def test_parse_topic_list_marks_required_topics_present(self):
        topics = smoke.parse_topic_list("""
 vehicle.raw.go.gb32960.v1
 vehicle.raw.go.jt808.v1
 vehicle.raw.go.yutong-mqtt.v1
 vehicle.event.go.unified.v1
 """)
        checks = smoke.topic_checks(topics, smoke.DEFAULT_TOPICS)
        self.assertTrue(all(check.status == "pass" for check in checks))
    def test_topic_checks_fail_when_required_topic_missing(self):
        topics = {"vehicle.raw.go.gb32960.v1"}
        checks = smoke.topic_checks(topics, ["vehicle.raw.go.gb32960.v1", "vehicle.event.go.unified.v1"])
        by_name = {check.name: check for check in checks}
        self.assertEqual(by_name["topic.vehicle.event.go.unified.v1"].status, "fail")
    def test_parse_consumer_group_describe_reads_lag_rows(self):
        rows = smoke.parse_consumer_group_describe("""
 GROUP           TOPIC                       PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
 go-realtime-api vehicle.event.go.unified.v1 0          15992           15992           0
 go-realtime-api vehicle.event.go.unified.v1 1          2036            2036            3
 """)
        self.assertEqual(rows[0].group, "go-realtime-api")
        self.assertEqual(rows[1].topic, "vehicle.event.go.unified.v1")
        self.assertEqual(rows[1].lag, 3)
    def test_lag_checks_fail_when_lag_exceeds_threshold(self):
        rows = [
            smoke.ConsumerLag("go-history-writer", "vehicle.raw.go.jt808.v1", 0, 100, 100, 0),
            smoke.ConsumerLag("go-history-writer", "vehicle.raw.go.jt808.v1", 1, 100, 110, 10),
        ]
        check = smoke.group_lag_check("go-history-writer", rows, max_lag=5)
        self.assertEqual(check.status, "fail")
        self.assertIn("max_lag=10", check.message)
    def test_lag_checks_pass_when_group_has_rows_and_lag_is_small(self):
        rows = [
            smoke.ConsumerLag("go-stat-writer", "vehicle.raw.go.gb32960.v1", 0, 100, 100, 0),
            smoke.ConsumerLag("go-stat-writer", "vehicle.raw.go.jt808.v1", 1, 100, 101, 1),
        ]
        check = smoke.group_lag_check("go-stat-writer", rows, max_lag=5)
        self.assertEqual(check.status, "pass")
        self.assertIn("max_lag=1", check.message)
 if __name__ == "__main__":
    unittest.main()
--- a/tools/test_go_native_deploy.py
+++ b/tools/test_go_native_deploy.py
@@ -0,0 +1,63 @@
 import unittest
 from tools import go_native_deploy as deploy
 class GoNativeDeployTest(unittest.TestCase):
    def test_build_commands_cover_four_production_binaries(self):
        commands = deploy.build_commands("/repo/go/vehicle-gateway", "/tmp/out")
        self.assertEqual([command.output_name for command in commands], [
            "gateway",
            "history-writer",
            "stat-writer",
            "realtime-api",
        ])
        for command in commands:
            self.assertEqual(command.argv[:3], ["go", "build", "-trimpath"])
            self.assertIn("GOOS=linux", command.env)
            self.assertIn("GOARCH=amd64", command.env)
            self.assertIn("CGO_ENABLED=0", command.env)
    def test_remote_switch_command_creates_release_and_restarts_all_services(self):
        command = deploy.remote_switch_command("409f55b", "/opt/lingniu-go-native", "/tmp/lingniu-go-native-409f55b.tar.gz")
        self.assertIn("/opt/lingniu-go-native/releases/409f55b", command)
        self.assertIn("ln -sfn", command)
        self.assertIn("systemctl restart lingniu-go-gateway", command)
        self.assertIn("systemctl restart lingniu-go-history-writer", command)
        self.assertIn("systemctl restart lingniu-go-stat-writer", command)
        self.assertIn("systemctl restart lingniu-go-realtime-api", command)
    def test_acceptance_command_uses_deployed_hosts_and_date(self):
        command = deploy.acceptance_command(
            app_host="115.29.187.205",
            kafka_host="114.55.58.251",
            date="2026-07-02",
            timeout=20,
        )
        self.assertEqual(command[:2], ["python3", "tools/go_prod_acceptance.py"])
        self.assertIn("--app-host", command)
        self.assertIn("115.29.187.205", command)
        self.assertIn("--kafka-host", command)
        self.assertIn("114.55.58.251", command)
        self.assertIn("--date", command)
        self.assertIn("2026-07-02", command)
    def test_parse_spool_status_reads_file_and_recent_counts(self):
        status = deploy.parse_spool_status("files=42 recent=3")
        self.assertEqual(status.files, 42)
        self.assertEqual(status.recent, 3)
    def test_spool_status_command_targets_gateway_spool_directory(self):
        command = deploy.spool_status_command("/opt/lingniu-go-native")
        self.assertIn("/opt/lingniu-go-native/spool/gateway", command)
        self.assertIn("files=", command)
        self.assertIn("recent=", command)
 if __name__ == "__main__":
    unittest.main()
--- a/tools/test_go_native_prod_smoke.py
+++ b/tools/test_go_native_prod_smoke.py
@@ -0,0 +1,358 @@
 import datetime as dt
 import unittest
 from tools import go_native_prod_smoke as smoke
 class GoNativeProdSmokeTest(unittest.TestCase):
    def test_shanghai_day_window_uses_plus_eight_bounds(self):
        now = dt.datetime(2026, 7, 2, 1, 35, tzinfo=smoke.SHANGHAI)
        date_from, date_to = smoke.shanghai_day_window(now)
        self.assertEqual(date_from, "2026-07-02T00:00:00+08:00")
        self.assertEqual(date_to, "2026-07-03T00:00:00+08:00")
    def test_api_url_encodes_plus_eight_date_range(self):
        url = smoke.api_url(
            "http://example.test/base/",
            "/api/history/raw-frames",
            {
                "protocol": "JT808",
                "dateFrom": "2026-07-02T00:00:00+08:00",
                "dateTo": "2026-07-03T00:00:00+08:00",
                "limit": 1,
            },
        )
        self.assertEqual(
            url,
            "http://example.test/base/api/history/raw-frames?"
            "protocol=JT808&dateFrom=2026-07-02T00%3A00%3A00%2B08%3A00"
            "&dateTo=2026-07-03T00%3A00%3A00%2B08%3A00&limit=1",
        )
    def test_explicit_today_date_still_enforces_raw_freshness(self):
        now = dt.datetime(2026, 7, 2, 9, 30, tzinfo=smoke.SHANGHAI)
        window = smoke.resolve_check_window("2026-07-02", 15.0, now)
        self.assertEqual(window.date_from, "2026-07-02T00:00:00+08:00")
        self.assertEqual(window.date_to, "2026-07-03T00:00:00+08:00")
        self.assertEqual(window.stat_date, "2026-07-02")
        self.assertEqual(window.max_raw_age_minutes, 15.0)
    def test_explicit_historical_date_disables_raw_freshness(self):
        now = dt.datetime(2026, 7, 2, 9, 30, tzinfo=smoke.SHANGHAI)
        window = smoke.resolve_check_window("2026-07-01", 15.0, now)
        self.assertEqual(window.date_from, "2026-07-01T00:00:00+08:00")
        self.assertEqual(window.date_to, "2026-07-02T00:00:00+08:00")
        self.assertEqual(window.stat_date, "2026-07-01")
        self.assertIsNone(window.max_raw_age_minutes)
    def test_total_check_passes_when_total_reaches_minimum(self):
        check = smoke.check_total(
            "jt808.raw",
            {"total": 2, "items": [{"vehicle_key": "JT808:013307811170"}]},
            minimum=1,
        )
        self.assertEqual(check.status, "pass")
        self.assertEqual(check.count, 2)
        self.assertIn("JT808:013307811170", check.message)
    def test_total_check_fails_when_total_is_below_minimum(self):
        check = smoke.check_total("gb32960.raw", {"total": 0, "items": []}, minimum=1)
        self.assertEqual(check.status, "fail")
        self.assertEqual(check.count, 0)
        self.assertIn("expected >= 1", check.message)
    def test_overall_status_fails_if_any_check_fails(self):
        checks = [
            smoke.Check("a", "pass", 1, 1, "ok"),
            smoke.Check("b", "fail", 0, 1, "bad"),
        ]
        self.assertEqual(smoke.overall_status(checks), "fail")
    def test_build_checks_cover_three_raw_protocols_and_two_daily_metric_protocols(self):
        specs = smoke.build_check_specs(
            date_from="2026-07-02T00:00:00+08:00",
            date_to="2026-07-03T00:00:00+08:00",
            stat_date="2026-07-02",
            min_raw=1,
            min_history=1,
            min_stat=1,
        )
        names = [spec.name for spec in specs]
        self.assertIn("gb32960.raw", names)
        self.assertIn("jt808.raw", names)
        self.assertIn("yutong_mqtt.raw", names)
        self.assertIn("gb32960.locations", names)
        self.assertIn("gb32960.mileage_points", names)
        self.assertIn("jt808.locations", names)
        self.assertIn("jt808.mileage_points", names)
        self.assertIn("yutong_mqtt.locations", names)
        self.assertIn("yutong_mqtt.mileage_points", names)
        self.assertIn("gb32960.daily_mileage", names)
        self.assertIn("jt808.daily_total_mileage", names)
    def test_raw_checks_order_by_received_at_for_ingest_freshness(self):
        specs = smoke.build_check_specs(
            date_from="2026-07-02T00:00:00+08:00",
            date_to="2026-07-03T00:00:00+08:00",
            stat_date="2026-07-02",
            min_raw=1,
            min_history=1,
            min_stat=1,
            max_raw_age_minutes=15,
        )
        raw_specs = [spec for spec in specs if spec.name.endswith(".raw")]
        self.assertTrue(raw_specs)
        for spec in raw_specs:
            self.assertEqual(spec.params.get("orderBy"), "receivedAt")
            self.assertEqual(spec.params.get("includeTotal"), "false")
            self.assertNotIn("dateFrom", spec.params)
            self.assertNotIn("dateTo", spec.params)
    def test_vehicle_identifier_prefers_vin_over_vehicle_key(self):
        identifier = smoke.vehicle_identifier({
            "vin": "LB9A32A20R0LS1343",
            "vehicle_key": "GB32960:ignored",
        })
        self.assertEqual(identifier, "LB9A32A20R0LS1343")
    def test_vehicle_identifier_falls_back_to_vehicle_key(self):
        identifier = smoke.vehicle_identifier({
            "vin": "",
            "vehicle_key": "JT808:013307811170",
        })
        self.assertEqual(identifier, "JT808:013307811170")
    def test_realtime_specs_are_built_from_raw_samples_with_vin(self):
        payloads = {
            "gb32960.raw": {"items": [{"vin": "LB9A32A20R0LS1343", "vehicle_key": "LB9A32A20R0LS1343"}]},
            "jt808.raw": {"items": [{"vin": "", "vehicle_key": "JT808:013307811170"}]},
            "yutong_mqtt.raw": {"items": [{"vin": "LMRKH9AC6R1004108"}]},
        }
        specs = smoke.build_realtime_specs(payloads)
        self.assertEqual(
            [(spec.name, spec.path) for spec in specs],
            [
                ("gb32960.realtime", "/api/realtime/vehicles/LB9A32A20R0LS1343"),
                ("gb32960.realtime_online", "/api/realtime/vehicles/LB9A32A20R0LS1343/online"),
                ("gb32960.realtime_protocol", "/api/realtime/vehicles/LB9A32A20R0LS1343/protocols/GB32960"),
                ("jt808.realtime", "/api/realtime/vehicles/JT808%3A013307811170"),
                ("jt808.realtime_online", "/api/realtime/vehicles/JT808%3A013307811170/online"),
                ("jt808.realtime_protocol", "/api/realtime/vehicles/JT808%3A013307811170/protocols/JT808"),
                ("yutong_mqtt.realtime", "/api/realtime/vehicles/LMRKH9AC6R1004108"),
                ("yutong_mqtt.realtime_online", "/api/realtime/vehicles/LMRKH9AC6R1004108/online"),
                ("yutong_mqtt.realtime_protocol", "/api/realtime/vehicles/LMRKH9AC6R1004108/protocols/YUTONG_MQTT"),
            ],
        )
    def test_realtime_check_requires_online_true_when_field_exists(self):
        check = smoke.check_realtime(
            "gb32960.realtime_online",
            {"vin": "LB9A32A20R0LS1343", "online": True, "protocols": ["GB32960"]},
        )
        self.assertEqual(check.status, "pass")
        self.assertEqual(check.count, 1)
    def test_realtime_check_fails_when_online_false(self):
        check = smoke.check_realtime(
            "gb32960.realtime_online",
            {"vin": "LB9A32A20R0LS1343", "online": False},
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("online=false", check.message)
    def test_realtime_check_fails_when_snapshot_is_stale(self):
        now = dt.datetime(2026, 7, 2, 0, 30, 0, tzinfo=dt.timezone.utc)
        check = smoke.check_realtime(
            "jt808.realtime",
            {"vehicle_key": "JT808:013307811170", "updated_at_ms": 1782950400000},
            max_age_minutes=15,
            now=now,
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("updated_age_minutes=30.0", check.message)
    def test_realtime_check_passes_when_snapshot_is_fresh(self):
        now = dt.datetime(2026, 7, 2, 0, 30, 0, tzinfo=dt.timezone.utc)
        check = smoke.check_realtime(
            "jt808.realtime",
            {"vehicle_key": "JT808:013307811170", "updated_at_ms": 1782951600000},
            max_age_minutes=15,
            now=now,
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("updated_age_minutes=10.0", check.message)
    def test_parse_tdengine_utc_timestamp_as_aware_utc(self):
        parsed = smoke.parse_tdengine_utc_timestamp("2026-07-01 17:36:02")
        self.assertEqual(parsed, dt.datetime(2026, 7, 1, 17, 36, 2, tzinfo=dt.timezone.utc))
    def test_total_check_fails_when_latest_sample_is_stale(self):
        now = dt.datetime(2026, 7, 1, 18, 0, 0, tzinfo=dt.timezone.utc)
        check = smoke.check_total(
            "gb32960.raw",
            {"total": 1, "items": [{"ts": "2026-07-01 17:00:00"}]},
            minimum=1,
            max_age_minutes=30,
            now=now,
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("latest_age_minutes=60.0", check.message)
    def test_total_check_uses_received_at_for_raw_freshness_when_present(self):
        now = dt.datetime(2026, 7, 1, 18, 0, 0, tzinfo=dt.timezone.utc)
        check = smoke.check_total(
            "gb32960.raw",
            {
                "total": 1,
                "items": [{
                    "ts": "2026-07-01 17:00:00",
                    "received_at": "2026-07-01 17:58:00",
                }],
            },
            minimum=1,
            max_age_minutes=15,
            now=now,
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("latest_age_minutes=2.0", check.message)
    def test_total_check_passes_when_latest_sample_is_fresh(self):
        now = dt.datetime(2026, 7, 1, 18, 0, 0, tzinfo=dt.timezone.utc)
        check = smoke.check_total(
            "gb32960.raw",
            {"total": 1, "items": [{"ts": "2026-07-01 17:45:00"}]},
            minimum=1,
            max_age_minutes=30,
            now=now,
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("latest_age_minutes=15.0", check.message)
    def test_raw_check_requires_structured_parsed_json(self):
        check = smoke.check_total(
            "jt808.raw",
            {
                "total": 1,
                "items": [{
                    "ts": "2026-07-01 17:45:00",
                    "parsed_json": "",
                }],
            },
            minimum=1,
            require_parsed_json=True,
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("missing parsed_json", check.message)
    def test_raw_check_accepts_structured_parsed_json(self):
        check = smoke.check_total(
            "gb32960.raw",
            {
                "total": 1,
                "items": [{
                    "ts": "2026-07-01 17:45:00",
                    "parsed_json": "{\"header\":{\"vin\":\"LTEST\"}}",
                }],
            },
            minimum=1,
            require_parsed_json=True,
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("parsed_json=ok", check.message)
    def test_history_check_requires_frame_id_backlink(self):
        check = smoke.check_total(
            "jt808.locations",
            {"total": 1, "items": [{"ts": "2026-07-01 17:45:00", "frame_id": ""}]},
            minimum=1,
            require_frame_id=True,
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("missing frame_id", check.message)
    def test_history_check_accepts_frame_id_backlink(self):
        check = smoke.check_total(
            "jt808.mileage_points",
            {"total": 1, "items": [{"ts": "2026-07-01 17:45:00", "frame_id": "go_abc"}]},
            minimum=1,
            require_frame_id=True,
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("frame_id=ok", check.message)
    def test_daily_mileage_formula_requires_latest_minus_first(self):
        check = smoke.check_total(
            "jt808.daily_mileage",
            {
                "total": 1,
                "items": [{
                    "metric_key": "daily_mileage_km",
                    "metric_value": 40.0,
                    "first_total_mileage_km": 4434.9,
                    "latest_total_mileage_km": 4481.0,
                }],
            },
            minimum=1,
            require_metric_formula=True,
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("metric_formula mismatch", check.message)
    def test_daily_total_formula_requires_latest_total(self):
        check = smoke.check_total(
            "jt808.daily_total_mileage",
            {
                "total": 1,
                "items": [{
                    "metric_key": "daily_total_mileage_km",
                    "metric_value": 4481.0,
                    "first_total_mileage_km": 4434.9,
                    "latest_total_mileage_km": 4481.0,
                }],
            },
            minimum=1,
            require_metric_formula=True,
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("metric_formula=ok", check.message)
 if __name__ == "__main__":
    unittest.main()
--- a/tools/test_go_prod_acceptance.py
+++ b/tools/test_go_prod_acceptance.py
@@ -0,0 +1,53 @@
 import argparse
 import sys
 import unittest
 from tools import go_prod_acceptance as acceptance
 class GoProdAcceptanceTest(unittest.TestCase):
    def test_build_commands_runs_systemd_kafka_and_http_smokes(self):
        args = argparse.Namespace(
            app_host="115.29.187.205",
            kafka_host="114.55.58.251",
            ssh_user="root",
            base_url="http://115.29.187.205:20210",
            date="2026-07-02",
            timeout=8.0,
            max_lag=100,
        )
        commands = acceptance.build_commands(args)
        self.assertEqual(len(commands), 3)
        self.assertEqual(commands[0].name, "systemd")
        self.assertEqual(commands[0].argv[:2], [sys.executable, "tools/go_systemd_prod_smoke.py"])
        self.assertIn("--host", commands[0].argv)
        self.assertIn("115.29.187.205", commands[0].argv)
        self.assertEqual(commands[1].name, "kafka")
        self.assertIn("tools/go_kafka_prod_smoke.py", commands[1].argv)
        self.assertIn("--max-lag", commands[1].argv)
        self.assertEqual(commands[2].name, "http")
        self.assertIn("tools/go_native_prod_smoke.py", commands[2].argv)
        self.assertIn("--base-url", commands[2].argv)
    def test_overall_status_fails_when_any_child_fails(self):
        results = [
            acceptance.ChildResult("systemd", "pass", 0, {"status": "pass"}),
            acceptance.ChildResult("kafka", "fail", 1, {"status": "fail"}),
        ]
        self.assertEqual(acceptance.overall_status(results), "fail")
    def test_overall_status_passes_when_all_children_pass(self):
        results = [
            acceptance.ChildResult("systemd", "pass", 0, {"status": "pass"}),
            acceptance.ChildResult("kafka", "pass", 0, {"status": "pass"}),
            acceptance.ChildResult("http", "pass", 0, {"status": "pass"}),
        ]
        self.assertEqual(acceptance.overall_status(results), "pass")
 if __name__ == "__main__":
    unittest.main()
--- a/tools/test_go_systemd_prod_smoke.py
+++ b/tools/test_go_systemd_prod_smoke.py
@@ -0,0 +1,101 @@
 import unittest
 from tools import go_systemd_prod_smoke as smoke
 class GoSystemdProdSmokeTest(unittest.TestCase):
    def test_service_checks_require_all_go_units_active(self):
        output = """
 lingniu-go-gateway.service active enabled
 lingniu-go-history-writer.service active enabled
 lingniu-go-stat-writer.service active enabled
 lingniu-go-realtime-api.service active enabled
 """
        checks = smoke.service_checks(output, smoke.DEFAULT_SERVICES)
        self.assertTrue(all(check.status == "pass" for check in checks))
    def test_service_checks_fail_when_unit_is_missing_or_inactive(self):
        output = """
 lingniu-go-gateway.service active enabled
 lingniu-go-history-writer.service failed enabled
 """
        checks = smoke.service_checks(output, smoke.DEFAULT_SERVICES)
        by_name = {check.name: check for check in checks}
        self.assertEqual(by_name["service.lingniu-go-history-writer.service"].status, "fail")
        self.assertEqual(by_name["service.lingniu-go-stat-writer.service"].status, "fail")
    def test_service_checks_fail_when_unit_is_not_enabled(self):
        output = """
 lingniu-go-gateway.service active disabled
 lingniu-go-history-writer.service active enabled
 lingniu-go-stat-writer.service active enabled
 lingniu-go-realtime-api.service active enabled
 """
        checks = smoke.service_checks(output, smoke.DEFAULT_SERVICES)
        by_name = {check.name: check for check in checks}
        self.assertEqual(by_name["service.lingniu-go-gateway.service"].status, "fail")
        self.assertIn("enabled=disabled", by_name["service.lingniu-go-gateway.service"].message)
    def test_port_checks_require_expected_go_processes(self):
        output = """
 LISTEN 0 4096 *:32960 *:* users:(("gateway",pid=10,fd=3))
 LISTEN 0 4096 *:808 *:* users:(("gateway",pid=10,fd=4))
 LISTEN 0 4096 *:20210 *:* users:(("realtime-api",pid=11,fd=3))
 """
        checks = smoke.port_checks(output, smoke.DEFAULT_PORTS)
        self.assertTrue(all(check.status == "pass" for check in checks))
    def test_port_checks_fail_when_java_owns_ingest_port(self):
        output = """
 LISTEN 0 4096 *:808 *:* users:(("java",pid=20,fd=4))
 LISTEN 0 4096 *:32960 *:* users:(("gateway",pid=10,fd=3))
 LISTEN 0 4096 *:20210 *:* users:(("realtime-api",pid=11,fd=3))
 """
        checks = smoke.port_checks(output, smoke.DEFAULT_PORTS)
        by_name = {check.name: check for check in checks}
        self.assertEqual(by_name["port.808"].status, "fail")
        self.assertIn("java", by_name["port.808"].message)
    def test_spool_check_passes_when_no_pending_files(self):
        check = smoke.spool_check("files=0 bytes=208896 recent=0")
        self.assertEqual(check.status, "pass")
        self.assertIn("files=0", check.message)
    def test_spool_check_fails_when_pending_or_recent_files_exist(self):
        for output in ["files=2 bytes=300 recent=0", "files=0 bytes=208896 recent=1"]:
            check = smoke.spool_check(output)
            self.assertEqual(check.status, "fail")
    def test_release_check_passes_when_current_release_has_all_binaries(self):
        check = smoke.release_check(
            "current=/opt/lingniu-go-native/releases/8def635 "
            "gateway=1 history-writer=1 stat-writer=1 realtime-api=1"
        )
        self.assertEqual(check.status, "pass")
        self.assertIn("8def635", check.message)
    def test_release_check_fails_when_binary_is_missing(self):
        check = smoke.release_check(
            "current=/opt/lingniu-go-native/releases/8def635 "
            "gateway=1 history-writer=0 stat-writer=1 realtime-api=1"
        )
        self.assertEqual(check.status, "fail")
        self.assertIn("history-writer=0", check.message)
 if __name__ == "__main__":
    unittest.main()
Author	SHA1	Message	Date
lingniu	cbb6f3b741	perf: skip raw freshness count scan	2026-07-02 09:30:15 +08:00
lingniu	42de422935	test: check raw freshness without event date filter	2026-07-02 09:27:22 +08:00
lingniu	318486b1e9	fix: verify raw freshness by received time	2026-07-02 09:16:45 +08:00
lingniu	0a024f9a76	chore: wait for gateway spool before acceptance	2026-07-02 09:11:50 +08:00
lingniu	ea9d9f5d35	chore: add go native ecs deploy script	2026-07-02 08:50:19 +08:00
lingniu	409f55b5ae	test: verify go native release layout	2026-07-02 08:47:05 +08:00
lingniu	8def635bf5	test: verify realtime snapshots are fresh	2026-07-02 08:43:27 +08:00
lingniu	c211447747	test: verify daily metric formulas	2026-07-02 08:38:32 +08:00
lingniu	1741aacaaa	test: verify history rows link raw frames	2026-07-02 08:35:34 +08:00
lingniu	27f4ad3468	test: verify raw parsed json in production smoke	2026-07-02 02:00:50 +08:00
lingniu	601150b364	test: verify gateway spool is drained	2026-07-02 01:57:53 +08:00
lingniu	5b7f386c5a	test: verify go services are enabled	2026-07-02 01:55:39 +08:00
lingniu	f4d9c9ef5a	test: add go production acceptance smoke	2026-07-02 01:53:43 +08:00
lingniu	96514898eb	test: add go systemd production smoke	2026-07-02 01:51:41 +08:00
lingniu	0ef88e1a4c	test: add kafka production smoke	2026-07-02 01:49:02 +08:00
lingniu	0fd4d319f9	docs: record go kafka production topics	2026-07-02 01:44:27 +08:00
lingniu	4e8434c511	test: verify mqtt history tables in production smoke	2026-07-02 01:41:08 +08:00
lingniu	576644eb65	test: verify gb32960 history tables in production smoke	2026-07-02 01:39:45 +08:00
lingniu	9bd48c5781	test: require fresh raw data in production smoke	2026-07-02 01:38:16 +08:00
lingniu	2214abe9c5	test: include realtime in production smoke	2026-07-02 01:36:14 +08:00
lingniu	1477b997c9	test: add go native production smoke	2026-07-02 01:34:28 +08:00
lingniu	4ea8d18972	docs: document go native ecs deployment	2026-07-02 01:31:58 +08:00
lingniu	947e645090	fix: query history with utc tdengine filters	2026-07-02 01:28:45 +08:00
lingniu	78b805e3a2	fix: normalize timezone history filters	2026-07-02 01:24:51 +08:00
lingniu	a7b24f4c0b	feat: expose realtime snapshot protocols	2026-07-02 01:23:03 +08:00
lingniu	eb124d929b	fix: accept datetime-local history filters	2026-07-02 01:19:19 +08:00
lingniu	4711287655	fix: return empty arrays for query APIs	2026-07-02 01:16:48 +08:00
lingniu	2c224396c9	fix: return real pagination totals	2026-07-02 01:14:06 +08:00
lingniu	4f2cded760	fix: treat yutong mqtt mileage as meters	2026-07-02 01:08:59 +08:00
lingniu	7ad1a25e8e	fix: normalize yutong mqtt mileage units	2026-07-02 01:04:14 +08:00
lingniu	3ee1d6f52b	fix: stabilize yutong mqtt ingestion	2026-07-02 01:01:33 +08:00
lingniu	6d1d0aa85e	feat: write protocol acknowledgements from go gateway	2026-07-02 00:54:31 +08:00
lingniu	055373c405	fix: support extended gb32960 platform login	2026-07-02 00:47:01 +08:00
lingniu	e37dd39c89	fix: enrich jt808 location additional parsing	2026-07-02 00:36:51 +08:00
lingniu	dd73fdbb5b	feat: add vehicle mileage history query	2026-07-02 00:29:49 +08:00
lingniu	fb9ab8525a	feat: add vehicle location history query	2026-07-02 00:27:20 +08:00
lingniu	cc89e0d537	fix: filter raw frames by vehicle key	2026-07-02 00:24:53 +08:00
lingniu	f3ecf430cc	fix: cache realtime snapshots by vehicle key	2026-07-02 00:21:50 +08:00
lingniu	bcf7cdae2e	fix: key daily metrics by vehicle identity	2026-07-02 00:18:35 +08:00
lingniu	9045b871d6	fix: align jt808 parser with protocol variants	2026-07-02 00:14:02 +08:00
lingniu	b0150a5503	docs: record yutong mqtt eof diagnosis	2026-07-02 00:04:23 +08:00
lingniu	8f3b337fd6	docs: add native go deployment runbook	2026-07-02 00:02:21 +08:00
lingniu	594ab2d9c7	feat: support yutong mqtt tls config	2026-07-01 23:50:30 +08:00
lingniu	229ffcf61f	docs: record go production port verification	2026-07-01 23:46:33 +08:00
lingniu	593713283c	fix: query tdengine raw frames with literals	2026-07-01 23:42:09 +08:00
lingniu	6bee0499ae	feat: expose raw frame query api	2026-07-01 23:39:10 +08:00
lingniu	59c1c9df0f	docs: record daily metric api verification	2026-07-01 23:35:50 +08:00
lingniu	56f4811c68	fix: format daily metric query timestamps	2026-07-01 23:33:03 +08:00
lingniu	1a53011408	feat: expose daily metric query api	2026-07-01 23:30:54 +08:00
lingniu	c2d70dad86	docs: record production chain verification	2026-07-01 23:28:27 +08:00
lingniu	91db6c959e	docs: record jt808 identity tracking verification	2026-07-01 23:23:59 +08:00
lingniu	7b44f97ddb	fix: decode jt808 registration plate text	2026-07-01 23:21:53 +08:00
lingniu	a72977cd79	feat: track jt808 registration identity	2026-07-01 23:17:29 +08:00
lingniu	dd95101499	docs: record mileage metric guard verification	2026-07-01 23:11:35 +08:00
lingniu	d347525a75	fix: keep valid realtime mileage	2026-07-01 23:08:31 +08:00
lingniu	19008e840c	fix: ignore invalid zero mileage metrics	2026-07-01 23:06:06 +08:00
lingniu	c803a19bf5	docs: record go production port switch	2026-07-01 23:03:33 +08:00
lingniu	243de5c2b2	feat: spool gateway publishes to disk	2026-07-01 23:00:06 +08:00
lingniu	4a32e2181a	docs: record gateway publish retry deployment	2026-07-01 22:56:55 +08:00
lingniu	7e7066dd86	feat: retry gateway kafka publishes	2026-07-01 22:54:47 +08:00
lingniu	e7c8c57296	docs: record jt808 identity verification	2026-07-01 22:51:18 +08:00
lingniu	6b55694c43	fix: resolve jt808 phone without leading zero	2026-07-01 22:34:47 +08:00
lingniu	eb48d16181	docs: record gb32960 vendor verification	2026-07-01 22:29:46 +08:00
lingniu	a15de91912	feat: parse gb32960 guangdong fuel cell blocks	2026-07-01 22:27:34 +08:00
lingniu	796d79dd30	docs: record go gateway real frame verification	2026-07-01 22:23:44 +08:00
lingniu	5f4f4fd124	feat: parse gb32960 realtime data units	2026-07-01 22:21:21 +08:00
lingniu	e0068a750d	fix: support jt808 versioned header	2026-07-01 22:12:47 +08:00
lingniu	665122b23b	docs: record go gateway ecs verification	2026-07-01 22:08:45 +08:00
lingniu	60ca42e5d5	fix: quote tdengine history inserts	2026-07-01 22:06:12 +08:00
lingniu	80474eeccb	feat: add go vehicle identity resolver	2026-07-01 21:57:18 +08:00
lingniu	17024651c8	chore: add go gateway deployment stack	2026-07-01 21:55:27 +08:00
lingniu	d8c77d7882	feat: add yutong mqtt ingestion	2026-07-01 21:53:39 +08:00
lingniu	b55b075a97	feat: add go realtime redis api	2026-07-01 21:51:13 +08:00
lingniu	bac8864e79	feat: add go daily metric writer	2026-07-01 21:48:52 +08:00
lingniu	5d844701ff	feat: add go tdengine history writer	2026-07-01 21:47:38 +08:00
lingniu	967981c040	feat: add go tcp gateway runtime	2026-07-01 21:45:28 +08:00
lingniu	1fdbc29e27	feat: scaffold go vehicle gateway core	2026-07-01 21:43:16 +08:00
lingniu	d148a4e3af	docs: design go ingest redesign phase one	2026-07-01 21:36:07 +08:00