feat: build vehicle data platform and production pipeline

docs/architecture/storage-minimal-contract.md

@@ -12,21 +12,22 @@
 4. TDengine 只承担高写入时间序列：raw、位置历史。
 5. MySQL 只承担低基数业务状态：身份映射、实时快照、日指标。
 6. 同一个事实只落一个主表，其他表只存查询必要的投影。
-7. 新字段先进入 `parsed_json`，只有稳定查询需求出现后才提升为列。
+7. 新字段先由 Gateway 一次扁平化后进入 `parsed_fields`；TDengine 物理列仍名为 `parsed_json`，只有稳定查询需求出现后才提升为列。
 
 ## 目标表边界
 
 | 存储 | 表/Key | 保留内容 | 不保留内容 |
 | --- | --- | --- | --- |
-| TDengine | `raw_frames` | raw hex/text、完整 `parsed_json`、解析状态、协议标签、车辆标识标签 | `fields_json` 这类可从 `parsed_json`/业务表再得到的重复字段 |
+| TDengine | `raw_frames` | raw hex/text、扁平 `parsed_fields` JSON（物理列 `parsed_json`）、解析状态、协议标签、车辆标识标签 | 原始嵌套解析树、`fields_json` 等重复字段 |
 | TDengine | `raw_frame_payload_chunks` | 超长 raw/parsed payload 分片 | 业务查询字段 |
 | TDengine | `vehicle_locations` | 时间、VIN/协议标签、经纬度、速度、方向、SOC、总里程等位置核心字段 | 完整协议 JSON、注册鉴权信息、phone/device_id/vehicle_key 兜底标识 |
-| MySQL | `vehicle_realtime_snapshot` | 每个协议+VIN 的最新事件时间、接收时间、车牌、事件 ID | phone、device、source endpoint、完整 JSON |
+| MySQL | `vehicle_realtime_snapshot` | 每个协议+VIN 的最新事件态、合并扁平字段，以及独立的首次/前次/最新接收时间、连续间隔、样本数和证据来源 | phone、device、原始嵌套解析树、raw 报文、无限接收历史 |
 | MySQL | `vehicle_realtime_location` | 每个协议+VIN 的最新位置核心字段 | raw、parsed JSON、消息头内部字段 |
 | MySQL | `vehicle_daily_mileage` | 日期、VIN、协议、日里程、首末总里程、样本数 | 临时 vehicle key、泛化 metric key/value、自增 id、created_at、每帧细节、位置点列表 |
 | MySQL | `vehicle_identity_binding` | 人工维护或导入的 VIN、车牌、phone、oem 映射 | 注册历史、协议状态、device_id、自增 id、created_at |
 | MySQL | `jt808_registration` | JT808 phone 主键下的注册、鉴权、VIN 匹配状态、来源端点 | GB32960/MQTT 注册信息、位置历史、created_at |
 | Redis | `vehicle:realtime-raw:{protocol}:{vin}` | 每协议每 VIN 最新完整 parsed 状态 | 无 VIN 临时身份、历史数据、统计结果 |
+| Redis | `vehicle:rt-kv:{protocol}:{vin}:values/types/times/meta` | 每协议每 VIN 最新扁平实时字段、类型、字段级事件时间和投影元信息 | 历史字段值、统计结果、无 VIN 临时身份 |
 
 ## 当前应收敛的重复点
 
@@ -60,6 +61,7 @@
 
 6. MySQL realtime 当前态表不保留代理主键和创建时间。
    - 原因：`vehicle_realtime_snapshot`、`vehicle_realtime_location` 都是每协议每 VIN 一行的当前态投影，业务主键就是 `(protocol, vin)`。
+   - 接入证据按接收时间单调推进，不受设备事件时间乱序影响；重复事件 ID 或回退接收时间不能增加样本数。`access_first_seen_source=snapshot_backfill` 仅表示部署时基线，只有 `live_writer` 新行能证明 writer 上线后的首次观测。
    - 状态：schema 使用 `PRIMARY KEY (protocol, vin)`，不保留自增 `id` 和 `created_at`，对外只暴露最新 `updated_at`。
    - 索引：不在 `vehicle_realtime_location` 维护经纬度组合索引；实时表只回答当前态，地理范围和轨迹类查询走 TDengine 历史位置。
    - 查询：`/api/realtime/snapshots`、`/api/realtime/locations` 默认不执行 `COUNT(*)`，`total` 表示本页返回条数；只有需要精确总数时传 `includeTotal=true`。
@@ -83,9 +85,9 @@
 
 ## 字段提升规则
 
-协议字段进入系统后分三层：
+协议字段只在 Gateway 解析、映射和扁平化一次，进入系统后分三层。`vehicle.fields.*` 事件中的所有字段名必须位于对应协议命名空间：`gb32960.*`、`jt808.*` 或 `yutong_mqtt.*`；统计层不读取内部标准化核心字段作为兼容兜底。
 
-1. `parsed_json`：默认入口，保存完整结构化解析。
+1. `parsed_fields`：默认入口，保存全量扁平协议字段；TDengine 继续使用兼容物理列名 `parsed_json`。
 2. 核心列：只有跨协议稳定查询需要时才提升，例如经纬度、速度、SOC、总里程。
 3. 指标表：只有聚合口径稳定、产品需要分页/排序/报表时才持久化。