docs: document local ingest deployment verification

docs/operations/vehicle-ingest-tdengine-verification.md

@@ -93,6 +93,36 @@ curl -sS http://127.0.0.1:20200/v3/api-docs \
 
 预期：健康检查为 `UP`，OpenAPI 中包含这两个 TDengine 查询接口。
 
+## 本机 launchctl 部署
+
+当前本机生产验证建议使用仓库模板生成 plist：
+
+```bash
+deploy/local/launchctl/
+```
+
+关键约束：
+
+- `jt808-ingest-app` 监听 TCP `808`，HTTP `20482`。
+- `gb32960-ingest-app` 监听 TCP `32960`，HTTP `20100`。
+- `vehicle-history-app` 监听 HTTP `20200`。
+- 三个服务必须共用同一个 `SINK_ARCHIVE_PATH`，否则 TDengine 中的 `raw_uri` 能入库，但 history API 无法按 `archive://...` 读取原始帧。
+- 替换 jar 前先 `launchctl bootout`，再复制 jar 和 `launchctl bootstrap`，避免 KeepAlive 在 jar 拷贝中途重启。
+
+健康检查：
+
+```bash
+curl -sS http://127.0.0.1:20482/actuator/health
+curl -sS http://127.0.0.1:20100/actuator/health
+curl -sS http://127.0.0.1:20200/actuator/health
+```
+
+Swagger：
+
+- JT808 ingest: `http://127.0.0.1:20482/swagger-ui/index.html`
+- GB32960 ingest: `http://127.0.0.1:20100/swagger-ui/index.html`
+- History query: `http://127.0.0.1:20200/swagger-ui/index.html`
+
 ## Kafka Topic 验证
 
 历史服务必须消费事件 topic 和 raw topic：
@@ -161,6 +191,78 @@ SELECT COUNT(*) FROM telemetry_fields;
 - TDengine 未启用时，TDengine 专属接口不应该出现在 OpenAPI 中。
 - 路径不存在时，API 层应该返回 HTTP `404`，而不是泛化的存储失败。
 
-## 当前本地缺口
+## 2026-06-29 本机实时链路验证结果
 
-本次实现验证环境中，Kafka `114.55.58.251:9092` 可连通，但本机 `127.0.0.1:6041` 不可连通。完整 TDengine 写入和查询验收需要提供真实可用的 `TDENGINE_JDBC_URL`。
+运行服务：
+
+- `com.lingniu.jt808.808`: `jt808-ingest-app`，TCP `808`，HTTP `20482`
+- `com.lingniu.gb32960.32960`: `gb32960-ingest-app`，TCP `32960`，HTTP `20100`
+- `com.lingniu.vehicle-history.jt808`: `vehicle-history-app`，HTTP `20200`
+
+健康检查已确认三个服务均返回 `{"status":"UP"}`。
+
+JT808 真实转发链路已验证：
+
+- 本机 TCP `808` 有外部平台持续发送 JT808 报文。
+- `vehicle.raw.jt808.v1` 和 `vehicle.event.jt808.v1` 被 history 消费。
+- `raw_frames` 中 `protocol='JT808'` 的真实行数已超过 `6000`。
+- `vehicle_locations` 中 `protocol='JT808'` 的位置行数已超过 `1900`。
+- `telemetry_fields` 中 `protocol='JT808'` 的字段行数已超过 `15000`。
+- 最新样例包含终端号 `13079963310`、消息 ID `512`、`archive://2026/06/29/JT808/...` 原始帧引用。
+
+复查 SQL：
+
+```sql
+USE vehicle_ts;
+SELECT COUNT(*) FROM raw_frames WHERE protocol = 'JT808';
+SELECT COUNT(*) FROM vehicle_locations WHERE protocol = 'JT808';
+SELECT COUNT(*) FROM telemetry_fields WHERE protocol = 'JT808';
+SELECT event_time, vehicle_key, phone, message_id, raw_uri
+  FROM raw_frames
+  WHERE protocol = 'JT808'
+  ORDER BY event_time DESC
+  LIMIT 5;
+```
+
+复查 API：
+
+```bash
+curl -sS 'http://127.0.0.1:20200/api/event-history/jt808/locations?phone=13079963296&dateFrom=2026-06-29T00:00:00%2B08:00&dateTo=2026-06-29T23:59:59%2B08:00&limit=10'
+```
+
+GB32960 链路已用合成实时帧验证：
+
+- TCP `32960` 返回 GB32960 `2323` ACK。
+- `raw_frames` 中测试 VIN `LTEST202606290001` 已有 `2` 条 raw 记录。
+- `telemetry_fields` 中测试 VIN `LTEST202606290001` 已有 `34` 条字段记录。
+- latest raw 包含 `archive://2026/06/29/GB32960/LTEST202606290001/...`。
+- snapshots API 可查到 `speedKmh=62.4`、`totalMileageKm=223456.7`、`longitude=116.397128`、`latitude=39.916527`。
+
+复查 SQL：
+
+```sql
+USE vehicle_ts;
+SELECT COUNT(*) FROM raw_frames
+  WHERE protocol = 'GB32960' AND vin = 'LTEST202606290001';
+SELECT COUNT(*) FROM telemetry_fields
+  WHERE protocol = 'GB32960' AND vin = 'LTEST202606290001';
+SELECT event_time, vin, raw_uri, raw_id
+  FROM raw_frames
+  WHERE protocol = 'GB32960' AND vin = 'LTEST202606290001'
+  ORDER BY event_time DESC
+  LIMIT 5;
+```
+
+复查 API：
+
+```bash
+curl -sS 'http://127.0.0.1:20200/api/event-history/gb32960/snapshots?vin=LTEST202606290001&dateFrom=2026-06-29T00:00:00%2B08:00&dateTo=2026-06-29T23:59:59%2B08:00&limit=10'
+curl -sS 'http://127.0.0.1:20200/api/event-history/gb32960/snapshots/fields?vin=LTEST202606290001&fields=VEHICLE.speedKmh,VEHICLE.totalMileageKm,POSITION_V2016.longitude,POSITION_V2016.latitude&dateFrom=2026-06-29T00:00:00%2B08:00&dateTo=2026-06-29T23:59:59%2B08:00&limit=10'
+```
+
+## 当前注意事项
+
+- 当前本机使用 TDengine WebSocket JDBC，例如 `jdbc:TAOS-WS://<tdengine-host>:6041/vehicle_ts`。
+- `KAFKA_CONSUMER_AUTO_OFFSET_RESET=latest` 适合生产接入新流量；如果要回放历史 Kafka 数据，需要切换 consumer group 或重置 offset。
+- `vehicle-history-app` raw 和 event 使用不同 consumer binding；raw consumer 必须开启，否则 `raw_frames` 不会持续增长。
+- JT808 设备没有 VIN 映射时，`vehicle_key` 使用 `jt808:<phone>`，后续维护注册/VIN 映射后再反写 VIN。