# 车辆定位源仲裁运维说明

## 目标

同一车辆可能同时接入 GB32960、宇通 MQTT、多个 JT808 终端。全局监控不能简单选择最后上报的数据，否则不同设备的定位误差会让车辆在地图上来回跳动。

当前生产规则如下：

- 跨协议默认优先级：GB32960、YUTONG_MQTT、JT808；候选数据在 10 分钟内有效。
- JT808 按终端保存独立快照，不再由同 VIN 的多个终端互相覆盖。
- JT808 默认优先级：直连终端 20、平台转发 30、未知来源 40；数值越小越优先。
- 当前终端有 5 分的黏性权重，新终端连续 3 个有效点后才允许接管。
- 两个新鲜 JT808 来源相差超过 200 米时标记冲突并保持当前来源，避免自动跳点。
- 单终端相邻点超过 `max(500 米, 间隔秒数 × 70 米)` 时拒绝该点。
- 前端仅在定位来源未变化时执行平滑移动；来源切换时直接重置动画，避免绘制虚假轨迹。

## 数据表

- `vehicle_realtime_location_source`：JT808 终端级实时位置和质量状态。
- `vehicle_location_source_policy`：车辆、协议、终端级启停和优先级。
- `vehicle_realtime_location`：仲裁后的协议级位置；`source_key` 表示当前终端，`location_conflict` 和 `location_conflict_distance_m` 表示冲突状态。

查看某辆车的 JT808 候选来源：

```sql
SELECT source_key, phone, device_id, source_kind, source_endpoint,
       quality_status, quality_reason, consecutive_good_samples,
       latitude, longitude, received_at
FROM vehicle_realtime_location_source
WHERE vin = ? AND protocol = 'JT808'
ORDER BY received_at DESC;
```

## 指定权威终端

先从候选表复制完整 `source_key`。将权威终端设置为较小优先级；建议保留其他终端作为备用，而不是直接禁用。

```sql
INSERT INTO vehicle_location_source_policy
  (vin, protocol, source_key, enabled, priority, remark)
VALUES
  (?, 'JT808', ?, 1, 1, '人工确认的权威定位终端')
ON DUPLICATE KEY UPDATE
  enabled = VALUES(enabled),
  priority = VALUES(priority),
  remark = VALUES(remark);
```

禁用确认异常的终端：

```sql
INSERT INTO vehicle_location_source_policy
  (vin, protocol, source_key, enabled, priority, remark)
VALUES
  (?, 'JT808', ?, 0, 100, '异常终端，停止参与定位仲裁')
ON DUPLICATE KEY UPDATE
  enabled = VALUES(enabled),
  remark = VALUES(remark);
```

恢复默认策略时删除对应配置：

```sql
DELETE FROM vehicle_location_source_policy
WHERE vin = ? AND protocol = 'JT808' AND source_key = ?;
```

配置在下一条该车辆 JT808 定位消息到达时生效，不需要重启服务。

## 监控与排查

主要观察指标：

- `vehicle_realtime_store_updates_total{protocol="JT808",status="ok",store="mysql"}`
- `vehicle_realtime_store_update_duration_ms_histogram{protocol="JT808",status="ok",store="mysql"}`
- `vehicle_process_heap_alloc_bytes`

冲突车辆查询：

```sql
SELECT vin, source_key, location_conflict, location_conflict_distance_m,
       latitude, longitude, received_at
FROM vehicle_realtime_location
WHERE protocol = 'JT808' AND location_conflict = 1
ORDER BY location_conflict_distance_m DESC;
```

冲突期间保留当前来源是预期行为。人工确认哪个终端可信后，再写入策略表；不要通过删除实时快照或修改业务资产数据解决定位冲突。