feat(firstleg): close phase3 outbound customs and schedule gates

2026-08-08 22:36:41 +08:00
parent 789d97675b
commit 66d1aa0d3d
81 changed files with 5196 additions and 36 deletions
@@ -0,0 +1,86 @@
+openapi: 3.0.3
+info:
+  title: Phase 3 Loading Evidence and Picking API
+  version: 1.0.0
+paths:
+  /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: Bind one real File service object to a loading evidence slot
+      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/picking/start:
+    post:
+      summary: Start the inbound-level PDA picking review task
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/PickingRequest'}}
+      responses:
+        '200': {description: Business envelope containing IN_PROGRESS task}
+  /api/platform/v1/inbounds/{inboundId}/loading/picking/complete:
+    post:
+      summary: Complete a started PDA picking task when planned and picked counts match
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/PickingRequest'}}
+      responses:
+        '200': {description: Business envelope containing COMPLETED task}
+  /api/platform/v1/inbounds/{inboundId}/loading/picking:
+    get:
+      summary: Read the inbound-level PDA picking task
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
+      responses:
+        '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
+      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json: {schema: {$ref: '#/components/schemas/CompleteLoadingRequest'}}
+      responses:
+        '200': {description: Business envelope containing LOADED status}
+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}}
+    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
+  schemas:
+    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]}
+        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}
+    PickingRequest:
+      type: object
+      required: [expectedVersion, expectedCount, pickedCount]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        expectedCount: {type: integer, minimum: 1}
+        pickedCount: {type: integer, minimum: 0}
+        remark: {type: string, maxLength: 1000}
+    CompleteLoadingRequest:
+      type: object
+      required: [expectedVersion]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        remark: {type: string, maxLength: 1000}