docs(ops): document location source arbitration

docs/ops/vehicle-location-source-arbitration.md

@@ -0,0 +1,88 @@
+# 车辆定位源仲裁运维说明
+
+## 目标
+
+同一车辆可能同时接入 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;
+```
+
+冲突期间保留当前来源是预期行为。人工确认哪个终端可信后，再写入策略表；不要通过删除实时快照或修改业务资产数据解决定位冲突。