优化

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -953,6 +953,10 @@ components:
         bookingNo: {type: string, maxLength: 40}
         containerNo: {type: string, maxLength: 64, nullable: true}
         cabinetNo: {type: string, maxLength: 64}
+        channelCode: {type: string, maxLength: 64, nullable: true, description: Missing legacy snapshots are blocked from loading until explicitly backfilled}
+        channelName: {type: string, maxLength: 128, nullable: true}
+        oceanBookingId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
+        oceanBookingRequirementId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
         warehouseId: {type: string, pattern: '^[1-9][0-9]*$'}
         warehouseName: {type: string, maxLength: 128}
         billOfLadingNo: {type: string, maxLength: 128, nullable: true}
@@ -1017,11 +1021,12 @@ components:
         data: {$ref: '#/components/schemas/ContainerSaveRequest'}
     ContainerTransportUpdateRequest:
       type: object
-      required: [version]
+      required: [version, reason]
       properties:
         containerNo: {type: string, maxLength: 64, nullable: true}
         voyageNo: {type: string, maxLength: 64, nullable: true}
         version: {type: integer, minimum: 0}
+        reason: {type: string, maxLength: 500}
     MerchantInboundBillingEnvelope:
       type: object
       properties:

firstleg/src/main/resources/openapi/loading-lists-v1.yaml

@@ -208,9 +208,10 @@ components:
         customerName: {type: string, nullable: true, description: 客户名称}
     PreloadSummary:
       type: object
-      required: [planId, preloadNo, customers, status, skuCount, totalPackageCount, totalVolumeCbm, totalGrossWeightKg, createdAt, version]
+      required: [planId, containerBookingId, preloadNo, customers, status, skuCount, totalPackageCount, totalVolumeCbm, totalGrossWeightKg, createdAt, version]
       properties:
         planId: {$ref: '#/components/schemas/LongId'}
+        containerBookingId: {$ref: '#/components/schemas/LongId'}
         preloadNo: {type: string, description: 预装单号}
         containerNo: {type: string, nullable: true, description: 集装箱号}
         internalContainerNo: {type: string, nullable: true, description: 内部柜号}
@@ -229,9 +230,10 @@ components:
         version: {type: integer, format: int32, minimum: 0, description: 乐观锁版本}
     ConfirmedSummary:
       type: object
-      required: [planId, loadingListNo, status, totalPackageCount, totalGrossWeightKg, totalNetWeightKg, totalVolumeCbm, totalQuantity, createdAt, version]
+      required: [planId, containerBookingId, loadingListNo, status, totalPackageCount, totalGrossWeightKg, totalNetWeightKg, totalVolumeCbm, totalQuantity, createdAt, version]
       properties:
         planId: {$ref: '#/components/schemas/LongId'}
+        containerBookingId: {$ref: '#/components/schemas/LongId'}
         loadingListNo: {type: string, description: 装柜清单号}
         warehouseId: {$ref: '#/components/schemas/NullableLongId'}
         warehouseName: {type: string, nullable: true, description: 仓库名称}

firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml

@@ -0,0 +1,74 @@
+openapi: 3.0.3
+info: {title: Phase 3 Ocean Booking API, version: 1.1.0}
+paths:
+  /api/platform/v1/ocean-bookings:
+    post:
+      summary: Create an ocean booking draft with immutable channel and warehouse snapshots
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateRequest'}}}}
+      responses: {'200': {description: Draft detail}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/confirm:
+    post:
+      summary: Confirm booking and atomically create one stable cabinet and editing loading plan per requested quantity
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
+      responses: {'200': {description: CONFIRMED detail; no real container number required}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
+    post:
+      summary: Confirm released transport data and synchronize associated cabinet transport snapshots
+      description: Does not create cabinets, change channels, replace cabinetNo, or recreate loading plans.
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
+      responses: {'200': {description: RELEASED detail}}
+components:
+  parameters:
+    OceanBookingId: {name: oceanBookingId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+  schemas:
+    CreateRequest:
+      type: object
+      required: [expectedVersion, data]
+      properties:
+        expectedVersion: {type: integer, enum: [0]}
+        data: {$ref: '#/components/schemas/DraftData'}
+    DraftData:
+      type: object
+      required: [customerId, customerName, channelCode, channelName, warehouseId, warehouseName, parties, containerRequirements]
+      properties:
+        customerId: {type: integer, format: int64, minimum: 1}
+        customerName: {type: string, maxLength: 128}
+        channelCode: {type: string, maxLength: 64}
+        channelName: {type: string, maxLength: 128}
+        warehouseId: {type: integer, format: int64, minimum: 1}
+        warehouseName: {type: string, maxLength: 128}
+        billOfLadingNo: {type: string, nullable: true, deprecated: true, description: Must be omitted until release}
+        vesselName: {type: string, nullable: true, deprecated: true, description: Must be omitted until release}
+        voyageNo: {type: string, nullable: true, deprecated: true, description: Must be omitted until release}
+        estimatedSailingAt: {type: string, format: date-time, nullable: true, deprecated: true, description: Must be omitted until release}
+        estimatedArrivalAt: {type: string, format: date-time, nullable: true, deprecated: true, description: Must be omitted until release}
+        parties: {type: array, minItems: 3, items: {type: object}}
+        containerRequirements: {type: array, minItems: 1, maxItems: 20, items: {$ref: '#/components/schemas/ContainerRequirement'}}
+    ContainerRequirement:
+      type: object
+      required: [containerType, containerKind, capacityCbm, maxWeightKg, quantity]
+      properties:
+        containerType: {type: string, maxLength: 32}
+        containerKind: {type: string, maxLength: 32}
+        capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0}
+        maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0}
+        quantity: {type: integer, minimum: 1}
+    ActionRequest:
+      type: object
+      required: [expectedVersion]
+      properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, maxLength: 1000}}
+    ReleaseRequest:
+      type: object
+      required: [expectedVersion, billOfLadingNo, vesselName, voyageNo, estimatedSailingAt, estimatedArrivalAt]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        billOfLadingNo: {type: string, maxLength: 128}
+        vesselName: {type: string, maxLength: 128}
+        voyageNo: {type: string, maxLength: 64}
+        estimatedSailingAt: {type: string, format: date-time}
+        estimatedArrivalAt: {type: string, format: date-time}
+        reason: {type: string, maxLength: 1000}

firstleg/src/main/resources/openapi/phase3-pda-convergence-v1.yaml

@@ -7,7 +7,7 @@ paths:
     get:
       summary: Find the active container picking task in one platform warehouse
       parameters:
-        - {name: containerNo, in: query, required: true, schema: {type: string}}
+        - {name: containerNo, in: query, required: true, deprecated: true, description: Compatibility lookup only; taskId is the stable identity, schema: {type: string}}
         - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
       responses:
         '200':
@@ -26,6 +26,14 @@ paths:
               schema:
                 type: array
                 items: {$ref: '#/components/schemas/PendingTask'}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}:
+    get:
+      summary: Read one PDA task by stable task identity
+      parameters:
+        - {$ref: '#/components/parameters/TaskId'}
+        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      responses:
+        '200': {description: Task with current transport display fields}
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/claim:
     post:
       summary: Atomically claim an unassigned task for the authenticated operator
@@ -112,11 +120,13 @@ components:
   schemas:
     Task:
       type: object
-      required: [id, loadingPlanId, containerNo, taskStatus, workflowStatus, version, items]
+      required: [id, loadingPlanId, containerBookingId, cabinetNo, taskStatus, workflowStatus, version, items]
       properties:
         id: {type: integer, format: int64}
         loadingPlanId: {type: integer, format: int64}
-        containerNo: {type: string}
+        containerBookingId: {type: integer, format: int64}
+        cabinetNo: {type: string}
+        currentContainerNo: {type: string, nullable: true, description: Mutable transport display field; never task identity}
         taskStatus: {type: string, enum: [LOADING, COMPLETED]}
         workflowStatus: {type: string, enum: [UNASSIGNED, IN_PROGRESS, AWAITING_REVIEW, COMPLETED]}
         version: {type: integer, minimum: 0}
@@ -147,11 +157,13 @@ components:
         version: {type: integer, minimum: 0}
     PendingTask:
       type: object
-      required: [taskId, loadingPlanId, containerNo, warehouseId, taskStatus, workflowStatus, version, assignmentVersion, itemCount, pendingItemCount]
+      required: [taskId, loadingPlanId, containerBookingId, cabinetNo, warehouseId, taskStatus, workflowStatus, version, assignmentVersion, itemCount, pendingItemCount]
       properties:
         taskId: {type: integer, format: int64}
         loadingPlanId: {type: integer, format: int64}
-        containerNo: {type: string}
+        containerBookingId: {type: integer, format: int64}
+        cabinetNo: {type: string}
+        currentContainerNo: {type: string, nullable: true}
         warehouseId: {type: integer, format: int64}
         warehouseName: {type: string, nullable: true}
         taskStatus: {type: string, enum: [LOADING]}
@@ -176,10 +188,12 @@ components:
         operationId: {type: string, maxLength: 128}
     BatchRequest:
       type: object
-      required: [warehouseId, containerNo, expectedVersion, inventorySnapshotToken, items]
+      required: [warehouseId, loadingPlanId, containerBookingId, expectedVersion, inventorySnapshotToken, items]
       properties:
         warehouseId: {type: integer, format: int64, minimum: 1}
-        containerNo: {type: string, maxLength: 64}
+        loadingPlanId: {type: integer, format: int64, minimum: 1}
+        containerBookingId: {type: integer, format: int64, minimum: 1}
+        containerNo: {type: string, maxLength: 64, nullable: true, deprecated: true, description: Accepted during compatibility period but ignored for identity and idempotency}
         expectedVersion: {type: integer, minimum: 0}
         inventorySnapshotToken: {type: string, minLength: 64, maxLength: 64}
         items:
@@ -217,11 +231,14 @@ components:
         remark: {type: string, maxLength: 500}
     InventorySnapshot:
       type: object
-      required: [taskId, taskVersion, containerNo, warehouseId, capturedAt, snapshotToken, inbounds]
+      required: [taskId, loadingPlanId, containerBookingId, cabinetNo, taskVersion, warehouseId, capturedAt, snapshotToken, inbounds]
       properties:
         taskId: {type: integer, format: int64}
+        loadingPlanId: {type: integer, format: int64}
+        containerBookingId: {type: integer, format: int64}
+        cabinetNo: {type: string}
         taskVersion: {type: integer, minimum: 0}
-        containerNo: {type: string}
+        currentContainerNo: {type: string, nullable: true}
         warehouseId: {type: integer, format: int64}
         capturedAt: {type: string, format: date-time}
         snapshotToken: {type: string, minLength: 64, maxLength: 64}