docs: add detailed 32960 pipeline comments

modules/inbound/inbound-xinda-push/src/main/java/com/lingniu/ingest/inbound/xinda/XindaPushClient.java

@@ -116,6 +116,7 @@ public class XindaPushClient extends PushClient {
         String cmd = msg.getCmd();
         if (cmd == null) return;
         try {
+            // 信达只把业务消息派发到 Dispatcher；登录/心跳/订阅 ACK 只影响连接状态和日志。
             switch (cmd) {
                 case "8001" -> handleLoginAck(msg);
                 case "8002" -> log.debug("[xinda-push] heartbeat ack");
@@ -128,6 +129,7 @@ public class XindaPushClient extends PushClient {
             }
         } catch (Exception e) {
             log.warn("[xinda-push] dispatch failed cmd={} json={}", cmd, msg.getJson(), e);
+            // 推送回调异常也生成错误 RawFrame，保证原始 JSON 不丢。
             publishMessageError(msg, e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage());
         }
     }
@@ -193,6 +195,7 @@ public class XindaPushClient extends PushClient {
         JSONObject identityFields = parsed.json();
         IdentityResolution identity = resolveIdentity(identityFields);
         Map<String, String> meta = new HashMap<>();
+        // 保留外部字段和内部 VIN 的双轨元数据，方便定位绑定错误或第三方字段变更。
         meta.put("source", "xinda-push");
         meta.put("cmd", payload.command());
         meta.put("vin", identity.identity().vin());

modules/inbound/inbound-xinda-push/src/main/java/com/lingniu/ingest/inbound/xinda/XindaPushEventMapper.java

@@ -41,10 +41,12 @@ public final class XindaPushEventMapper implements EventMapper<XindaPushMessage>
         try {
             json = parse(message.json());
         } catch (Exception e) {
+            // JSON 解析失败不丢弃，转 passthrough 保留 rawJson，后续可通过历史库回查。
             return List.of(passthrough(message, new JSONObject(), true, false,
                     e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()));
         }
         if (json.getBooleanValue("operationalError")) {
+            // 接入侧运行错误也统一作为 passthrough 事件进入管线，便于监控和审计。
             return List.of(passthrough(message, json, false, false));
         }
         return switch (message.command()) {

modules/inbound/inbound-xinda-push/src/main/java/com/lingniu/ingest/inbound/xinda/config/XindaPushProperties.java

@@ -7,16 +7,21 @@ import java.util.List;
 
 /**
  * 信达 Push 接入配置。所有敏感字段均可通过环境变量注入，彻底取代旧代码里的硬编码。
+ *
+ * <p>该入口属于第三方推送协议，与 GB32960 TCP 接收链路并列。生产排查 32960 时，
+ * 应先确认本开关是否关闭，避免把信达推送事件误认为 32960 原始包。
  */
 @ConfigurationProperties(prefix = "lingniu.ingest.xinda-push")
 public class XindaPushProperties {
 
+    /** 总开关。关闭时不会向信达平台建连/订阅。 */
     private boolean enabled = false;
     private String host;
     private int port = 10100;
     private String username;
     private String password;
     private String clientDesc = "lingniu-ingest";
+    /** 默认订阅常见定位/轨迹类消息，新增业务消息需要先在 mapper 中确认字段映射。 */
     private List<String> subscribeMsgIds = new ArrayList<>(List.of("0200", "0300", "0401"));
     /** 断线重连间隔（秒）。 */
     private int reconnectIntervalSec = 5;