优化

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}