feat(firstleg): converge phase3 loading models and pda

2026-08-09 11:21:38 +08:00
parent 9b88fb4b9e
commit ed5b9fe77f
46 changed files with 2028 additions and 96 deletions
@@ -0,0 +1,58 @@
+openapi: 3.0.3
+info:
+  title: Phase 3 Preload and Container Loading Bridge API
+  version: 1.0.0
+paths:
+  /api/platform/v1/inbounds/{inboundId}/preload/loading-plans:
+    get:
+      summary: Query all container loading plans linked to one inbound preload
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
+      responses:
+        '200': {description: Business envelope containing zero or more stable links}
+  /api/platform/v1/inbounds/{inboundId}/preload/loading-plans/{loadingPlanId}:
+    post:
+      summary: Atomically link an inbound preload and a container loading plan
+      description: Both optimistic-lock versions must match; either conflict rolls back the whole link operation.
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/LoadingPlanId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/BindRequest'}}
+      responses:
+        '200': {description: Business envelope containing the persisted link or a business conflict}
+  /api/platform/v1/first-leg/smart-loading/plans/{loadingPlanId}/preloads:
+    get:
+      summary: Query all inbound preloads linked to one container loading plan
+      parameters: [{$ref: '#/components/parameters/LoadingPlanId'}]
+      responses:
+        '200': {description: Business envelope containing links across authorized customers}
+components:
+  parameters:
+    InboundId: {name: inboundId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    LoadingPlanId: {name: loadingPlanId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    TenantId: {name: tenantId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+  schemas:
+    BindRequest:
+      type: object
+      required: [expectedPreloadVersion, expectedLoadingPlanVersion]
+      properties:
+        expectedPreloadVersion: {type: integer, minimum: 0}
+        expectedLoadingPlanVersion: {type: integer, minimum: 0}
+    Link:
+      type: object
+      required: [id, tenantId, inboundId, preloadPlanId, preloadStatus, preloadVersion, loadingPlanId, containerBookingId, loadingPlanStatus, loadingPlanVersion, allocatedPackageCount, linkedAt]
+      properties:
+        id: {type: integer, format: int64}
+        tenantId: {type: integer, format: int64}
+        inboundId: {type: integer, format: int64}
+        preloadPlanId: {type: integer, format: int64}
+        preloadStatus: {type: string, enum: [PENDING, CONFIRMING, CONFIRMED]}
+        preloadVersion: {type: integer, minimum: 0}
+        loadingPlanId: {type: integer, format: int64}
+        containerBookingId: {type: integer, format: int64}
+        containerNo: {type: string, nullable: true}
+        loadingPlanStatus: {type: string, enum: [EDITING, LOADING, COMPLETED]}
+        loadingPlanVersion: {type: integer, minimum: 0}
+        allocatedPackageCount: {type: integer, minimum: 1}
+        linkedAt: {type: string, format: date-time}