优化

firstleg/src/main/resources/openapi/phase3-loading-delivery-v1.yaml

@@ -6,11 +6,13 @@ paths:
   /api/platform/v1/inbounds/{inboundId}/loading/evidence/pda:
     get:
       summary: List loading evidence for the active PDA worker
+      description: Requires the associated inbound to have entered the loading stage. PDA workflowStatus AWAITING_REVIEW does not bypass this gate; canonical claim or picking advances WAIT_SPLIT to LOADING.
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
       responses:
         '200': {description: Business envelope; requires platform:firstleg:pda:work}
     post:
       summary: Append one PDA-captured loading evidence photo
+      description: Requires the associated inbound process status to be LOADING. PDA workflowStatus AWAITING_REVIEW is a review projection and does not replace the inbound loading-stage gate.
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true

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

@@ -38,6 +38,7 @@ paths:
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/claim:
     post:
       summary: Atomically claim an unassigned task for the authenticated operator
+      description: Claiming the canonical PDA task idempotently starts its plan and advances every associated inbound from WAIT_SPLIT to LOADING with optimistic locking; workflowStatus may later become AWAITING_REVIEW while the task remains LOADING until manual completion.
       parameters: [{$ref: '#/components/parameters/TaskId'}]
       requestBody:
         required: true
@@ -66,6 +67,7 @@ paths:
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/pick:
     post:
       summary: Increment a picked item owned by the authenticated assignee
+      description: The first successful pick also repairs the same WAIT_SPLIT to LOADING transition when the plan was already started, without using containerNo as an association key.
       parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
       responses: {'200': {description: Updated task}}
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/partial:
@@ -81,6 +83,7 @@ paths:
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/batch:
     post:
       summary: Atomically submit the complete online PDA draft once
+      description: A batch containing PICK or PARTIAL idempotently advances associated inbound process status to LOADING before evidence operations become available.
       parameters:
         - {$ref: '#/components/parameters/TaskId'}
         - {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}