fix(events): allow manual nodes without tracking query

common-event-contract/src/main/java/com/baiyue/common/event/FirstLegContainerShippingNodeRecordedV1.java

@@ -28,7 +28,10 @@ public record FirstLegContainerShippingNodeRecordedV1(
         "EMPTY_RETURNED", 100);
 
     public FirstLegContainerShippingNodeRecordedV1 {
-        if (queryId == null || queryId.isBlank() || oceanBookingId == null || oceanBookingId.isBlank()
+        if (queryId != null && queryId.isBlank()) {
+            throw new IllegalArgumentException("船节点跟踪任务标识不能为空字符串");
+        }
+        if (oceanBookingId == null || oceanBookingId.isBlank()
             || containerBookingId == null || containerBookingId.isBlank()
             || containerNo == null || containerNo.isBlank()) {
             throw new IllegalArgumentException("船节点交接业务标识不能为空");

common-event-contract/src/main/resources/openapi/cross-region-events-v1.yaml

@@ -42,10 +42,9 @@ components:
         destinationType: {type: string, enum: [FBA, OVERSEAS]}
     FirstLegContainerShippingNodeRecordedV1:
       type: object
-      required: [queryId, customerId, oceanBookingId, sourceContainerBookingId, containerNo, standardNode, nodeSequence, observedAt, actualAt, providerCode, providerEventId, providerNodeCode, rawPayloadHash]
+      required: [oceanBookingId, sourceContainerBookingId, containerNo, standardNode, nodeSequence, observedAt, actualAt, providerCode, providerEventId, providerNodeCode, rawPayloadHash]
       properties:
-        queryId: {type: string}
-        customerId: {type: string}
+        queryId: {type: [string, 'null'], description: Automatic tracking task ID; null for a direct platform manual node.}
         oceanBookingId: {type: string}
         sourceContainerBookingId: {type: string, minLength: 1}
         containerNo: {type: string, minLength: 1, description: Uppercase normalized physical container number; never cabinetNo or a technical identity}

common-event-contract/src/test/java/com/baiyue/common/event/FirstLegContainerShippingNodeRecordedV1Test.java

@@ -35,6 +35,18 @@ class FirstLegContainerShippingNodeRecordedV1Test {
             .hasMessageContaining("normalized");
     }
 
+    @Test
+    void acceptsDirectManualNodeWithoutTrackingQuery() {
+        var payload = payload();
+        var manual = new FirstLegContainerShippingNodeRecordedV1(
+            null, payload.oceanBookingId(), payload.containerBookingId(), payload.containerNo(),
+            payload.standardNode(), payload.nodeSequence(), payload.observedAt(), payload.actualAt(),
+            payload.locationCode(), payload.locationName(), "MANUAL", "manual-event", payload.providerNodeCode(),
+            "MANUAL:7", payload.rawPayloadHash());
+
+        assertThat(manual.queryId()).isNull();
+    }
+
     @Test
     void rejectsEstimatedOnlyOrIncompleteProviderFacts() {
         assertThatThrownBy(() -> new FirstLegContainerShippingNodeRecordedV1(

firstleg/src/test/java/com/baiyue/firstleg/portschedule/service/CarrierScheduleNodeOutboxServiceTest.java

@@ -93,6 +93,23 @@ class CarrierScheduleNodeOutboxServiceTest {
         verify(mapper, never()).insert(org.mockito.ArgumentMatchers.any(InboundOutboxEntity.class));
     }
 
+    @Test
+    void directManualActualFactDoesNotRequireTrackingQuery() throws Exception {
+        CarrierScheduleNodeFactEntity fact = fact();
+        fact.setProviderCode("MANUAL"); fact.setProviderEventId("manual-event");
+        fact.setSourceReference("MANUAL:7");
+
+        service.publishContainerNode(2088000000000000004L, 2088000000000000003L,
+            fact, "ZCSU7881970");
+
+        ArgumentCaptor<InboundOutboxEntity> captor = ArgumentCaptor.forClass(InboundOutboxEntity.class);
+        verify(mapper).insert(captor.capture());
+        EventEnvelope envelope = objectMapper.readValue(captor.getValue().getPayloadJson(), EventEnvelope.class);
+        assertThat(envelope.payload().path("queryId").isNull()).isTrue();
+        assertThat(envelope.payload().path("sourceContainerBookingId").asText())
+            .isEqualTo("2088000000000000003");
+    }
+
     @Test
     void initialOutboundDepartureUsesVersionZeroWithoutEnvelopeFailure() throws Exception {
         CarrierScheduleQueryEntity query = query();