docs: add detailed 32960 pipeline comments

modules/core/vehicle-identity/src/main/java/com/lingniu/ingest/identity/FileVehicleIdentityService.java

@@ -46,6 +46,7 @@ public final class FileVehicleIdentityService implements VehicleIdentityResolver
                 Files.createDirectories(path.getParent());
                 try (BufferedWriter writer = Files.newBufferedWriter(path, StandardCharsets.UTF_8,
                         StandardOpenOption.CREATE, StandardOpenOption.APPEND, StandardOpenOption.WRITE)) {
+                    // append-only 允许运行时新增绑定；重启时按文件顺序 replay，后写覆盖内存索引中的旧映射。
                     writer.write(mapper.writeValueAsString(BindingLine.from(binding)));
                     writer.newLine();
                 }
@@ -72,6 +73,7 @@ public final class FileVehicleIdentityService implements VehicleIdentityResolver
                 }
                 try {
                     BindingLine binding = mapper.readValue(line, BindingLine.class);
+                    // 单行损坏不影响其它绑定加载，避免一个坏配置拖垮全部接入。
                     delegate.bind(binding.toBinding());
                 } catch (Exception e) {
                     log.warn("skip invalid vehicle identity binding line path={} line={}", path, line, e);

modules/core/vehicle-identity/src/main/java/com/lingniu/ingest/identity/InMemoryVehicleIdentityService.java

@@ -31,8 +31,10 @@ public final class InMemoryVehicleIdentityService implements VehicleIdentityReso
             return new VehicleIdentity("unknown", false, VehicleIdentitySource.UNKNOWN);
         }
         if (!lookup.vin().isBlank()) {
+            // 协议报文已经携带可信 VIN 时直接采用；绑定表主要服务 JT808/MQTT/信达这类外部 ID。
             return new VehicleIdentity(lookup.vin(), true, VehicleIdentitySource.EXPLICIT_VIN);
         }
+        // 绑定优先级：phone > deviceId > plate。顺序要稳定，否则同一车辆多外部号会产生不同内部 VIN。
         VehicleIdentity phone = resolveBound(phoneToVin, lookup.protocol(), lookup.phone(), VehicleIdentitySource.BOUND_PHONE);
         if (phone != null) return phone;
 
@@ -43,6 +45,7 @@ public final class InMemoryVehicleIdentityService implements VehicleIdentityReso
         if (plate != null) return plate;
 
         if (!lookup.deviceId().isBlank()) {
+            // fallback 不是已确认绑定，只用于不中断接收和冷存；metadata.identityResolved=false 会保留这个事实。
             return new VehicleIdentity(lookup.deviceId(), false, VehicleIdentitySource.FALLBACK_DEVICE_ID);
         }
         if (!lookup.phone().isBlank()) {
@@ -70,6 +73,7 @@ public final class InMemoryVehicleIdentityService implements VehicleIdentityReso
 
     private static String key(ProtocolId protocol, String value) {
         String p = protocol == null ? "UNKNOWN" : protocol.name();
+        // 绑定 key 带协议前缀，避免 JT808 phone 与 MQTT deviceId 数值相同时互相覆盖。
         return p + ":" + value.trim().toUpperCase(Locale.ROOT);
     }
 }

modules/core/vehicle-identity/src/main/java/com/lingniu/ingest/identity/config/VehicleIdentityAutoConfiguration.java

@@ -28,6 +28,7 @@ public class VehicleIdentityAutoConfiguration {
     @ConditionalOnProperty(prefix = "lingniu.ingest.identity", name = "store", havingValue = "file")
     public FileVehicleIdentityService fileVehicleIdentityService(VehicleIdentityProperties properties,
                                                                  ObjectMapper objectMapper) {
+        // 文件实现同时提供 resolver 和 registry，协议层既能查绑定，也能在注册/鉴权时补写绑定。
         return new FileVehicleIdentityService(Path.of(properties.getFile().getPath()), objectMapper);
     }