优化

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

@@ -10,7 +10,7 @@ paths:
       responses:
         '200': {description: Business envelope containing the stable evidence array}
     post:
-      summary: Bind one real File service object to a loading evidence slot
+      summary: Append one real File service object to a loading evidence type
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -18,6 +18,16 @@ paths:
           application/json: {schema: {$ref: '#/components/schemas/UpsertEvidenceRequest'}}
       responses:
         '200': {description: Business envelope; ownership, type and version failures use business error codes}
+  /api/platform/v1/inbounds/{inboundId}/loading/evidence/{evidenceId}/void:
+    post:
+      summary: Void an incorrect loading evidence photo without hard deletion
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/EvidenceId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/VoidEvidenceRequest'}}
+      responses:
+        '200': {description: Business envelope containing the voided record and audit fields}
   /api/platform/v1/inbounds/{inboundId}/loading/picking/start:
     post:
       summary: Refresh the compatibility projection from canonical container PDA tasks
@@ -50,7 +60,7 @@ paths:
         '200': {description: Business envelope containing task or null}
   /api/platform/v1/inbounds/{inboundId}/loading/complete:
     post:
-      summary: Complete loading only after picking and PHOTO_STEP_1..4 plus SEAL evidence are complete
+      summary: Complete loading only after picking and five evidence types each have an active photo
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true
@@ -62,6 +72,7 @@ components:
   parameters:
     InboundId: {name: inboundId, 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}}
+    EvidenceId: {name: evidenceId, 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:
     UpsertEvidenceRequest:
@@ -69,11 +80,17 @@ components:
       required: [expectedVersion, evidenceType, fileId]
       properties:
         expectedVersion: {type: integer, minimum: 0}
-        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL]}
+        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL], description: PHOTO_STEP_1=空仓，PHOTO_STEP_2=半仓，PHOTO_STEP_3=满仓，PHOTO_STEP_4=锁仓，SEAL=带锁码照；同类型可多次追加}
         fileId: {type: integer, format: int64, minimum: 1}
         fileName: {type: string, maxLength: 255, deprecated: true, description: Ignored; server uses File metadata}
         sealNo: {type: string, maxLength: 64, description: Required when evidenceType is SEAL}
         remark: {type: string, maxLength: 1000}
+    VoidEvidenceRequest:
+      type: object
+      required: [expectedVersion, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, minLength: 1, maxLength: 500, description: 作废原因，记录操作人和时间}
     PickingRequest:
       type: object
       required: [expectedVersion, expectedCount, pickedCount]