feat(firstleg): add compliant carrier schedule queries

2026-08-10 12:20:05 +08:00
parent 5c1c6a1a07
commit edd5108625
21 changed files with 1654 additions and 0 deletions
@@ -0,0 +1,113 @@
+openapi: 3.0.3
+info:
+  title: Carrier Schedule Query API
+  version: 1.0.0
+  description: Six-carrier query tasks with a three-day window, at most three attempts, and explicit manual fallback.
+paths:
+  /api/platform/v1/carrier-schedule-queries/carriers:
+    get:
+      summary: List official carrier sources and compliant access modes
+      responses:
+        '200': {description: MATSON, SML, ZIM, COSCO, EMC and HEDE descriptors}
+  /api/platform/v1/carrier-schedule-queries:
+    get:
+      summary: Query carrier schedule tasks
+      parameters:
+        - {name: customerId, in: query, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: oceanBookingId, in: query, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: containerBookingId, in: query, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: carrierCode, in: query, schema: {$ref: '#/components/schemas/CarrierCode'}}
+        - {name: status, in: query, schema: {$ref: '#/components/schemas/QueryStatus'}}
+        - {name: expired, in: query, schema: {type: boolean}}
+        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
+        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
+        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
+      responses:
+        '200': {description: Query tasks with source, freshness and rate-limit fields}
+    post:
+      summary: Create a query task linked to a real booking and allocated container
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/CreateRequest'}
+      responses:
+        '200': {description: Created task or idempotent replay}
+  /api/platform/v1/carrier-schedule-queries/{queryId}:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    get:
+      summary: Get task, immutable attempts and history
+      responses:
+        '200': {description: Stable task detail}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/history:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    get:
+      summary: Get immutable task history
+      responses:
+        '200': {description: CREATE, ATTEMPT and MANUAL_RESULT history}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/attempts:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    post:
+      summary: Execute the compliant carrier strategy; never bypass captcha or dynamic pages
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AttemptRequest'}
+      responses:
+        '200': {description: MANUAL_REQUIRED with coverageGap when no public structured API is available}
+  /api/platform/v1/carrier-schedule-queries/{queryId}/manual-results:
+    parameters: [{$ref: '#/components/parameters/QueryId'}]
+    post:
+      summary: Link a validated manual port-schedule observation without pretending automated success
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ManualResultRequest'}
+      responses:
+        '200': {description: Successful manual fallback and next query time}
+components:
+  parameters:
+    QueryId: {name: queryId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+  schemas:
+    CarrierCode: {type: string, enum: [MATSON, SML, ZIM, COSCO, EMC, HEDE]}
+    TrackingType: {type: string, enum: [BOOKING_NO, BILL_OF_LADING, CONTAINER_NO]}
+    QueryStatus: {type: string, enum: [READY, MANUAL_REQUIRED, SUCCESS]}
+    CreateRequest:
+      type: object
+      required: [expectedVersion, customerId, oceanBookingId, carrierCode, trackingType, trackingNo]
+      properties:
+        expectedVersion: {type: integer, minimum: 0, maximum: 0}
+        customerId: {type: integer, format: int64, minimum: 1}
+        oceanBookingId: {type: integer, format: int64, minimum: 1}
+        containerBookingId: {type: integer, format: int64, minimum: 1, nullable: true}
+        carrierCode: {$ref: '#/components/schemas/CarrierCode'}
+        trackingType: {$ref: '#/components/schemas/TrackingType'}
+        trackingNo: {type: string, minLength: 1, maxLength: 128}
+        remark: {type: string, nullable: true, maxLength: 1000}
+    AttemptRequest:
+      type: object
+      required: [expectedVersion]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, nullable: true, maxLength: 1000}
+    ManualResultRequest:
+      type: object
+      required: [expectedVersion, portScheduleId, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        portScheduleId: {type: integer, format: int64, minimum: 1}
+        reason: {type: string, minLength: 1, maxLength: 1000}
+    QueryView:
+      type: object
+      required: [query, expired, maxAttempts, nextAllowedAt]
+      properties:
+        query: {type: object, description: Includes source, attemptCount, lastAttemptAt, lastSuccessAt, sourceUpdatedAt and manualReason}
+        expired: {type: boolean}
+        maxAttempts: {type: integer, enum: [3]}
+        nextAllowedAt: {type: string, format: date-time}