优化

firstleg/src/main/resources/openapi/carrier-schedule-internal-v1.yaml

@@ -0,0 +1,23 @@
+openapi: 3.0.3
+info:
+  title: Carrier Schedule Internal Handoff API
+  version: 1.0.0
+  description: Internal-only handoff contract; it is not a platform or merchant frontend API.
+paths:
+  /internal/firstleg/v1/carrier-schedule-queries/{queryId}/stop:
+    post:
+      summary: Stop tracking after the overseas pickup handoff has completed
+      parameters:
+        - {name: queryId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: X-Internal-Service-Token, in: header, required: true, schema: {type: string}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [reason]
+              properties:
+                reason: {type: string, minLength: 1, maxLength: 500}
+      responses:
+        '200': {description: Idempotent STOPPED task detail}

firstleg/src/main/resources/openapi/carrier-schedule-query-v1.yaml

@@ -2,7 +2,7 @@ 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.
+  description: Phase-4 carrier tracking from domestic outbound confirmation through destination pickup readiness.
 paths:
   /api/platform/v1/carrier-schedule-queries/carriers:
     get:
@@ -40,7 +40,7 @@ paths:
   /api/platform/v1/carrier-schedule-queries/{queryId}:
     parameters: [{$ref: '#/components/parameters/QueryId'}]
     get:
-      summary: Get task, immutable attempts and history
+      summary: Get task, standardized node facts and immutable business history
       x-permission: platform:firstleg:port-schedule-query:list
       responses:
         '200': {description: Stable task detail}
@@ -51,19 +51,6 @@ paths:
       x-permission: platform:firstleg:port-schedule-query:list
       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
-      x-permission: platform:firstleg:port-schedule-query:attempt
-      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:
@@ -84,7 +71,8 @@ components:
   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]}
+    QueryStatus: {type: string, enum: [READY, MANUAL_REQUIRED, ARRIVED, PICKUP_READY, STOPPED]}
+    StandardNode: {type: string, enum: [DEPARTED_WAREHOUSE, AT_ORIGIN_PORT, DEPARTED_ORIGIN_PORT, IN_TRANSIT, ARRIVED, PICKUP_READY]}
     CreateRequest:
       type: object
       required: [expectedVersion, customerId, oceanBookingId, carrierCode, trackingType, trackingNo]
@@ -97,12 +85,6 @@ components:
         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]
@@ -112,9 +94,7 @@ components:
         reason: {type: string, minLength: 1, maxLength: 1000}
     QueryView:
       type: object
-      required: [query, expired, maxAttempts, nextAllowedAt]
+      required: [query, expired]
       properties:
-        query: {type: object, description: Includes source, attemptCount, lastAttemptAt, lastSuccessAt, sourceUpdatedAt and manualReason}
+        query: {type: object, description: Includes triggerSource, latestStandardNode, latestNodeObservedAt, source freshness and stop fields; scheduler leases and raw attempts are never exposed}
         expired: {type: boolean}
-        maxAttempts: {type: integer, enum: [3]}
-        nextAllowedAt: {type: string, format: date-time}