docs: add detailed 32960 pipeline comments

modules/inbound/inbound-mqtt/src/main/java/com/lingniu/ingest/inbound/mqtt/client/MqttEndpointManager.java

@@ -64,6 +64,7 @@ public final class MqttEndpointManager implements AutoCloseable {
     public void start() {
         for (MqttInboundProperties.Endpoint ep : props.getEndpoints()) {
             try {
+                // 多 endpoint 互不影响：单个连接初始化失败会派发 operationalError，但不会阻止其他 endpoint。
                 Mqtt3AsyncClient client = buildClient(ep);
                 clients.add(client);
                 connectAndSubscribe(client, ep);
@@ -146,6 +147,7 @@ public final class MqttEndpointManager implements AutoCloseable {
             String externalDeviceId = firstNonBlank(parsed.deviceId(), parsed.vin());
             IdentityResolution identity = resolveIdentity(parsed);
             Map<String, String> meta = new HashMap<>(4);
+            // metadata 同时保留外部设备号和内部 VIN，便于排查绑定表错误导致的车辆归属问题。
             meta.put("vin", identity.identity().vin());
             meta.put("externalVin", parsed.externalVin() == null ? "" : parsed.externalVin());
             meta.put("phone", parsed.phone() == null ? "" : parsed.phone());
@@ -173,6 +175,7 @@ public final class MqttEndpointManager implements AutoCloseable {
         } catch (Exception e) {
             log.warn("mqtt endpoint [{}] message handling failed topic={} len={}",
                     ep.getName(), topic, payload.length, e);
+            // 单条消息异常也转成 RawFrame 错误事件，避免 MQTT 回调线程吞掉现场。
             publishMessageError(ep, topic, payload, e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage());
         }
     }
@@ -215,6 +218,7 @@ public final class MqttEndpointManager implements AutoCloseable {
     }
 
     private void publishOperationalError(MqttInboundProperties.Endpoint ep, String phase, String reason) {
+        // 连接/订阅级别错误也进入 Dispatcher，这样监控和历史查询能看到接入端本身的问题。
         String endpointName = ep == null ? "" : ep.getName();
         String profile = ep == null ? "" : ep.getProfile();
         String topic = ep == null ? "" : ep.getTopic();

modules/inbound/inbound-mqtt/src/main/java/com/lingniu/ingest/inbound/mqtt/config/MqttInboundProperties.java

@@ -7,11 +7,16 @@ import java.util.List;
 
 /**
  * MQTT 接入配置。支持多 endpoint（每个 endpoint 可对应一个车厂 / 一个 broker）。
+ *
+ * <p>这是 JSON/MQTT 厂商入口，不参与 GB32960 TCP 32960 端口接入；如果同一辆车同时存在
+ * MQTT 和 32960 数据，需要在下游按 protocol/source 做归因。
  */
 @ConfigurationProperties(prefix = "lingniu.ingest.mqtt")
 public class MqttInboundProperties {
 
+    /** 总开关。关闭时不会创建任何 MQTT 客户端连接。 */
     private boolean enabled = false;
+    /** 多 broker/多 topic 配置；每个 endpoint 独立重连、订阅并转成内部 VehicleEvent。 */
     private List<Endpoint> endpoints = new ArrayList<>();
 
     public boolean isEnabled() { return enabled; }
@@ -31,6 +36,7 @@ public class MqttInboundProperties {
         private String clientId;
         private String username;
         private String password;
+        /** false 表示保留 broker 会话，重连后可继续接收离线期间的 QoS1/2 消息。 */
         private boolean cleanSession = false;
         private int keepAliveSeconds = 20;
         private int connectionTimeoutSeconds = 10;