feat: make gb32960 archive history query production ready

docs/vehicle-telemetry-internal-fields.md

@@ -0,0 +1,146 @@
+# Vehicle Telemetry Internal Fields
+
+This document defines the internal telemetry field model for Lingniu hydrogen
+vehicle operations. Protocol fields such as GB/T 32960, JT808, MQTT, and vendor
+extensions must be mapped into these fields before storage, statistics, or
+business reporting.
+
+## Design Rules
+
+- Business statistics use internal fields, not protocol field names.
+- Every internal field has one stable unit and one business meaning.
+- Protocol-specific raw values remain traceable through `source_protocol`,
+  `protocol_version`, `metadata`, and raw archive references.
+- Core operational fields are stored as typed columns or typed payload fields.
+- Unstable vendor-specific fields can stay in extension metadata until promoted.
+- Hydrogen leak safety is a first-class critical safety event, not a generic
+  alarm count.
+
+## Identity And Time
+
+| Internal field | Type | Unit | Meaning | GB/T 32960 source |
+|---|---:|---|---|---|
+| `vin` | string | - | Vehicle VIN and partition key | header VIN |
+| `event_time` | instant | - | Device collection time | command body timestamp |
+| `ingest_time` | instant | - | Platform receive time | ingest server clock |
+| `source_protocol` | enum | - | Source adapter | `GB32960` |
+| `protocol_version` | string | - | Source protocol version | `V2016` / `V2025` |
+
+## Real-Time Vehicle State
+
+| Internal field | Type | Unit | Meaning | GB/T 32960 source |
+|---|---:|---|---|---|
+| `vehicle_state` | enum | - | Started, shutdown, other, invalid | vehicle block `vehicleState` |
+| `charging_state` | enum | - | Charging state | vehicle block `chargingState` |
+| `running_mode` | enum | - | Electric, hybrid, fuel, other | vehicle block `runningMode` |
+| `speed_kmh` | double | km/h | Current speed | vehicle block `speedKmh` |
+| `total_mileage_km` | double | km | Odometer mileage | vehicle block `totalMileageKm` |
+| `gear_level` | integer | - | Gear value | vehicle block `gearRaw` low 4 bits |
+| `accelerator_pedal` | double | % | Accelerator pedal opening | V2016 vehicle block |
+| `brake_pedal` | double | % | Brake pedal opening | V2016 vehicle block |
+
+## Location
+
+| Internal field | Type | Unit | Meaning | GB/T 32960 source |
+|---|---:|---|---|---|
+| `longitude` | double | deg | Longitude | position block |
+| `latitude` | double | deg | Latitude | position block |
+| `altitude_m` | double | m | Altitude when available | extension or other protocol |
+| `direction_deg` | double | deg | Direction when available | extension or other protocol |
+| `location_status_raw` | long | - | Raw location status bits | position block `statusFlag` |
+
+## Battery And Electricity
+
+| Internal field | Type | Unit | Meaning | GB/T 32960 source |
+|---|---:|---|---|---|
+| `battery_soc` | double | % | Battery SOC | vehicle block `socPercent` |
+| `battery_voltage_v` | double | V | Battery total voltage | vehicle block `totalVoltageV` |
+| `battery_current_a` | double | A | Battery total current | vehicle block `totalCurrentA` |
+| `battery_power_kw` | double | kW | Derived instantaneous battery power | `voltage * current / 1000` in statistics |
+| `battery_temperature_max_c` | integer | C | Max battery temperature | temperature or extreme blocks |
+| `battery_temperature_min_c` | integer | C | Min battery temperature | temperature or extreme blocks |
+| `daily_electricity_kwh` | double | kWh | Daily electricity usage | statistics time integral |
+
+Daily electricity must be computed in the statistics layer from typed telemetry
+points. Do not accumulate protocol raw values directly.
+
+## Hydrogen And Fuel Cell
+
+| Internal field | Type | Unit | Meaning | GB/T 32960 source |
+|---|---:|---|---|---|
+| `fc_voltage_v` | double | V | Fuel cell voltage | fuel cell block |
+| `fc_current_a` | double | A | Fuel cell current | fuel cell block |
+| `fc_temp_c` | double | C | Fuel cell or hydrogen system temperature | fuel cell block |
+| `hydrogen_remaining_kg` | double | kg | Remaining hydrogen mass | vendor extension or capacity conversion |
+| `hydrogen_remaining_percent` | double | % | Remaining hydrogen percent | V2025 fuel cell block |
+| `hydrogen_high_pressure_mpa` | double | MPa | Hydrogen high pressure | fuel cell block |
+| `hydrogen_low_pressure_mpa` | double | MPa | Hydrogen low pressure when available | extension or other protocol |
+| `daily_hydrogen_kg` | double | kg | Daily hydrogen consumed | statistics layer |
+| `hydrogen_mileage_efficiency` | double | km/kg | Mileage per kg hydrogen | statistics layer |
+
+Daily hydrogen usage should be calculated from adjacent hydrogen remaining
+values. A rising value indicates refueling and must not be counted as negative
+consumption.
+
+## Hydrogen Tank Safety
+
+| Internal field | Type | Unit | Meaning | GB/T 32960 source |
+|---|---:|---|---|---|
+| `safety_category` | enum | - | `GENERAL`, `TANK_PRESSURE`, `TANK_TEMPERATURE`, `HYDROGEN_LEAK` | alarm bit classification |
+| `hydrogen_leak_detected` | boolean | - | Whether hydrogen leak is detected | general alarm bit `HYDROGEN_LEAK` |
+| `hydrogen_leak_level` | enum | - | `NONE`, `WARNING`, `CRITICAL`, `UNKNOWN` | internal rule |
+| `hydrogen_leak_action_required` | boolean | - | Whether immediate handling is required | internal rule |
+| `tank_pressure_status` | enum | - | Normal, warning, critical | hydrogen pressure bit or threshold rule |
+| `tank_temperature_status` | enum | - | Normal, warning, critical | hydrogen temp bit or threshold rule |
+
+Safety rule:
+
+```text
+If HYDROGEN_LEAK is present:
+  alarm.level = CRITICAL
+  safety_category = HYDROGEN_LEAK
+  hydrogen_leak_detected = true
+  hydrogen_leak_level = CRITICAL
+  hydrogen_leak_action_required = true
+```
+
+Hydrogen leak overrides otherwise normal vehicle, speed, battery, or hydrogen
+state. It must be counted independently from generic alarms.
+
+## Daily Operation Statistics
+
+Daily statistics are generated by `stat_date + vin`.
+
+| Internal field | Type | Unit | Meaning |
+|---|---:|---|---|
+| `stat_date` | date | - | Statistics date |
+| `vin` | string | - | Vehicle VIN |
+| `first_event_time` | instant | - | First valid telemetry time |
+| `last_event_time` | instant | - | Last valid telemetry time |
+| `online_minutes` | double | min | Online duration |
+| `running_minutes` | double | min | Running duration |
+| `daily_mileage_km` | double | km | Daily mileage |
+| `daily_electricity_kwh` | double | kWh | Daily electricity usage |
+| `daily_hydrogen_kg` | double | kg | Daily hydrogen usage |
+| `hydrogen_added_kg` | double | kg | Refueled hydrogen |
+| `km_per_kg_hydrogen` | double | km/kg | Hydrogen efficiency |
+| `kwh_per_100km` | double | kWh/100km | Electricity efficiency |
+| `alarm_count` | integer | - | Generic alarm count |
+| `tank_safety_alarm_count` | integer | - | Tank safety alarm count |
+| `hydrogen_leak_alarm_count` | integer | - | Hydrogen leak alarm count |
+| `hydrogen_leak_duration_seconds` | long | s | Hydrogen leak duration |
+| `data_quality_level` | enum | - | Good, partial, bad |
+
+## Implementation Status
+
+- `RealtimePayload` already uses internal operational field names for state,
+  location, battery, fuel cell, and hydrogen fields.
+- `AlarmPayload` carries internal hydrogen safety fields.
+- `Gb32960EventMapper` maps GB/T 32960 alarm bits into internal safety fields.
+- `TelemetrySnapshot` publishes full-field internal telemetry values through the
+  Kafka protobuf envelope.
+- `event-history-service`, `vehicle-state-service`, and `vehicle-stat-service`
+  consume the same full-field telemetry snapshot contract.
+- `event-history-service` CSV export can flatten selected internal fields with
+  `fields=field_a,field_b`; media archive references are exposed through
+  `rawArchiveUri` by falling back to `MediaMeta.archiveRef`.