fix(firstleg): scope loading evidence to cabinet tasks

2026-08-31 18:14:36 +08:00
parent 4795ab958c
commit df0fbc1c7f
31 changed files with 695 additions and 1314 deletions
@@ -1,67 +1,8 @@
 openapi: 3.0.3
 info:
-  title: Phase 3 Loading Evidence and Picking API
+  title: Phase 3 Loading and Picking API
  version: 1.0.0
 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
-        content:
-          application/json: {schema: {$ref: '#/components/schemas/UpsertEvidenceRequest'}}
-      responses:
-        '200': {description: Business envelope; requires platform:firstleg:pda:work}
-  /api/platform/v1/inbounds/{inboundId}/loading/evidence:
-    get:
-      summary: List loading evidence bound to one customer inbound
-      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
-      responses:
-        '200': {description: Business envelope containing the stable evidence array}
-    post:
-      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
-        content:
-          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}/content/pda:
-    get:
-      summary: Download one loading evidence photo for the active PDA worker
-      description: Uses the existing platform:firstleg:pda:work authority and validates customer, inbound and evidence ownership before proxying File service content.
-      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/EvidenceId'}, {$ref: '#/components/parameters/TenantId'}]
-      responses:
-        '200': {description: Authenticated image bytes}
-  /api/platform/v1/inbounds/{inboundId}/loading/evidence/{evidenceId}/void/pda:
-    post:
-      summary: Void an incorrect PDA loading evidence photo
-      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; requires platform:firstleg:pda:work}
-  /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
@@ -107,38 +48,8 @@ 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:
-    EvidenceResponse:
-      type: object
-      required: [id, inboundId, tenantId, evidenceType, fileId, previewUrl, version, status]
-      properties:
-        id: {type: integer, format: int64}
-        inboundId: {type: integer, format: int64}
-        tenantId: {type: integer, format: int64}
-        evidenceType: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL]}
-        fileId: {type: integer, format: int64}
-        fileName: {type: string}
-        previewUrl: {type: string, description: Authenticated PDA image-content path; request with the current bearer token}
-        version: {type: integer}
-        status: {type: string}
-    UpsertEvidenceRequest:
-      type: object
-      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], 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]
@@ -119,6 +119,57 @@ paths:
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      responses:
        '200': {description: Ordered operation history}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/evidence:
+    get:
+      summary: 查询当前领取人的柜次装柜证据
+      parameters:
+        - {$ref: '#/components/parameters/TaskId'}
+        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      responses: {'200': {description: 仅platform:firstleg:pda:work且任务必须由当前用户领取}}
+    post:
+      summary: 通过Firstleg代理上传并登记当前柜次装柜证据
+      parameters:
+        - {$ref: '#/components/parameters/TaskId'}
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: expectedVersion, in: query, required: true, schema: {type: integer, minimum: 0}}
+        - {name: evidenceType, in: query, required: true, schema: {type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL]}}
+        - {name: sealNo, in: query, required: false, schema: {type: string, maxLength: 64}}
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [file]
+              properties: {file: {type: string, format: binary}}
+      responses: {'200': {description: 柜级证据列表}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/evidence/{evidenceId}/content:
+    get:
+      summary: 下载当前柜次有效装柜证据
+      parameters:
+        - {$ref: '#/components/parameters/TaskId'}
+        - {name: evidenceId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      responses: {'200': {description: 图片字节}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/evidence/{evidenceId}/void:
+    post:
+      summary: 作废当前柜次错误证据
+      parameters:
+        - {$ref: '#/components/parameters/TaskId'}
+        - {name: evidenceId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [warehouseId, expectedVersion, reason]
+              properties:
+                warehouseId: {type: integer, format: int64, minimum: 1}
+                expectedVersion: {type: integer, minimum: 0}
+                reason: {type: string, minLength: 1, maxLength: 500}
+      responses: {'200': {description: 作废后柜级证据列表}}
 components:
  parameters:
    TaskId: {name: taskId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}