docs: add detailed 32960 pipeline comments

modules/services/vehicle-state-service/src/main/java/com/lingniu/ingest/vehiclestate/RedisVehicleStateRepository.java

@@ -17,6 +17,7 @@ public final class RedisVehicleStateRepository implements VehicleStateRepository
 
     @Override
     public void putState(String vin, String json) {
+        // 每辆车一个 Redis key，读最新状态时不需要扫描或 join 历史表。
         put(key("vehicle:state:", vin), json);
     }
 

modules/services/vehicle-state-service/src/main/java/com/lingniu/ingest/vehiclestate/VehicleStateController.java

@@ -28,6 +28,7 @@ public final class VehicleStateController {
 
     @GetMapping("/{vin}")
     public ResponseEntity<String> state(@PathVariable String vin) {
+        // 查询的是 Redis 最新状态快照，不是 event-file-store 的历史 snapshot。
         return json(repository.getState(vin));
     }
 

modules/services/vehicle-state-service/src/main/java/com/lingniu/ingest/vehiclestate/VehicleStateEnvelopeIngestor.java

@@ -25,6 +25,7 @@ public final class VehicleStateEnvelopeIngestor implements EnvelopeIngestor {
         VehicleEnvelope envelope = null;
         try {
             envelope = parse(kafkaValue);
+            // Kafka 消费路径只接受标准 VehicleEnvelope；坏消息返回明确结果给处理器写 DLQ。
             updater.update(envelope);
             return EnvelopeIngestResult.processed(envelope.getEventId(), envelope.getVin());
         } catch (IllegalArgumentException ex) {

modules/services/vehicle-state-service/src/main/java/com/lingniu/ingest/vehiclestate/VehicleStateUpdater.java

@@ -27,6 +27,7 @@ public final class VehicleStateUpdater {
         Map<String, String> fields = fields(envelope);
         String vin = envelope.getVin();
 
+        // vehicle-state 只维护“最新状态”缓存，覆盖写 Redis，不承担历史查询或 RAW 回放职责。
         repository.putState(vin, json(base(envelope, fields)));
         repository.putLastEvent(vin, json(lastEvent(envelope)));
 
@@ -41,6 +42,7 @@ public final class VehicleStateUpdater {
     private static Map<String, String> fields(VehicleEnvelope envelope) {
         Map<String, String> fields = new LinkedHashMap<>();
         for (TelemetryField field : envelope.getTelemetrySnapshot().getFieldsList()) {
+            // 同名字段以后到者为准，和最新状态语义一致。
             fields.put(field.getKey(), field.getValue());
         }
         return fields;
@@ -89,6 +91,7 @@ public final class VehicleStateUpdater {
     }
 
     private static boolean hasSafetyFields(Map<String, String> fields) {
+        // safety 是从标准字段中筛出来的窄视图，字段缺失时不写对应 Redis key。
         return fields.containsKey("safety_category")
                 || fields.containsKey("hydrogen_leak_detected")
                 || fields.containsKey("hydrogen_leak_level")

modules/services/vehicle-state-service/src/main/java/com/lingniu/ingest/vehiclestate/config/VehicleStateAutoConfiguration.java

@@ -22,6 +22,7 @@ public class VehicleStateAutoConfiguration {
     @ConditionalOnBean(StringRedisTemplate.class)
     @ConditionalOnMissingBean
     public VehicleStateRepository vehicleStateRepository(StringRedisTemplate redis) {
+        // 车辆状态模块依赖 Redis；没有 Redis Bean 时不自动启用，避免误以为它是历史库。
         return new RedisVehicleStateRepository(redis);
     }
 
@@ -44,6 +45,7 @@ public class VehicleStateAutoConfiguration {
     @ConditionalOnMissingBean(name = "vehicleStateEnvelopeConsumerProcessor")
     public EnvelopeConsumerProcessor vehicleStateEnvelopeConsumerProcessor(VehicleStateEnvelopeIngestor ingestor,
                                                                           EnvelopeDeadLetterSink deadLetterSink) {
+        // Bean 名必须和 sink-mq 默认 binding 对齐，KafkaEnvelopeConsumerFactory 才能自动创建 worker。
         return new EnvelopeConsumerProcessor("vehicle-state", ingestor, deadLetterSink);
     }