优化

2026-08-20 18:02:38 +08:00
parent b55b049e77
commit 1cd8b6a473
210 changed files with 6974 additions and 825 deletions
@@ -0,0 +1,55 @@
+openapi: 3.0.3
+info:
+  title: Carrier Schedule Provider Internal API
+  version: 1.0.0
+  description: Internal provider adapter contract. It owns normalization, timeout, rate-limit and provider errors, not business tasks.
+paths:
+  /internal/integrations/carrier-schedules/query:
+    post:
+      summary: Query one carrier tracking identifier through the configured provider adapter
+      parameters:
+        - name: X-Internal-Service-Token
+          in: header
+          required: true
+          schema: {type: string}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/QueryRequest'}
+      responses:
+        '200': {description: Standard observations or an explicit normalized failure/manual outcome}
+components:
+  schemas:
+    QueryRequest:
+      type: object
+      required: [carrierCode, trackingType, trackingNo]
+      properties:
+        carrierCode: {type: string, enum: [MATSON, SML, ZIM, COSCO, EMC, HEDE]}
+        trackingType: {type: string, enum: [BOOKING_NO, BILL_OF_LADING, CONTAINER_NO]}
+        trackingNo: {type: string, minLength: 1, maxLength: 128}
+    StandardNode:
+      type: string
+      enum: [DEPARTED_WAREHOUSE, AT_ORIGIN_PORT, DEPARTED_ORIGIN_PORT, IN_TRANSIT, ARRIVED, PICKUP_READY]
+    QueryResult:
+      type: object
+      required: [providerCode, outcome, observations]
+      properties:
+        providerCode: {type: string}
+        outcome: {type: string, enum: [SUCCESS, NO_CHANGE, RETRYABLE_FAILURE, PERMANENT_FAILURE, MANUAL_REQUIRED]}
+        observations:
+          type: array
+          items:
+            type: object
+            required: [providerEventId, providerNodeCode, standardNode, observedAt, rawPayloadHash]
+            properties:
+              providerEventId: {type: string}
+              providerNodeCode: {type: string}
+              standardNode: {$ref: '#/components/schemas/StandardNode'}
+              observedAt: {type: string, format: date-time}
+              estimatedAt: {type: string, format: date-time, nullable: true}
+              actualAt: {type: string, format: date-time, nullable: true}
+              locationCode: {type: string, nullable: true}
+              locationName: {type: string, nullable: true}
+              sourceReference: {type: string, nullable: true}
+              rawPayloadHash: {type: string, pattern: '^[0-9a-f]{64}$'}