feat(firstleg): converge phase3 loading models and pda

2026-08-09 11:21:38 +08:00
parent 9b88fb4b9e
commit ed5b9fe77f
46 changed files with 2028 additions and 96 deletions
@@ -0,0 +1,87 @@
+openapi: 3.0.3
+info:
+  title: Phase 3 Container PDA Picking API
+  version: 1.0.0
+paths:
+  /api/platform/v1/first-leg/pda-loading/tasks:
+    get:
+      summary: Find the active container picking task in one platform warehouse
+      parameters:
+        - {name: containerNo, in: query, required: true, schema: {type: string}}
+        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
+      responses:
+        '200': {description: Task with assignment, review and item-level versions}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/claim:
+    post:
+      summary: Atomically claim an unassigned task for the authenticated operator
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/ClaimRequest'}}}
+      responses:
+        '200': {description: Claimed task or A0409 when another operator owns it}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/assign:
+    post:
+      summary: Assign or reassign a task with optimistic locking
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/AssignRequest'}}}
+      responses:
+        '200': {description: Assigned task or A0409 on assignment version conflict}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/pick:
+    post:
+      summary: Increment a picked item owned by the authenticated assignee
+      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:
+    post:
+      summary: Record the final partial quantity for one assigned item
+      parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
+      responses: {'200': {description: Task awaiting review when every item is resolved}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/skip:
+    post:
+      summary: Resolve an untouched assigned item as skipped
+      parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
+      responses: {'200': {description: Task awaiting review when every item is resolved}}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/review:
+    post:
+      summary: Review all resolved items, settle partial and skipped quantities, then complete the plan
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/ReviewRequest'}}}
+      responses:
+        '200': {description: Completed task or A0409 when items or task version changed}
+  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/operations:
+    get:
+      summary: Read immutable task-level claim, assignment and review audit records
+      parameters: [{$ref: '#/components/parameters/TaskId'}]
+      responses:
+        '200': {description: Ordered operation history}
+components:
+  parameters:
+    TaskId: {name: taskId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    ItemId: {name: itemId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+  schemas:
+    ClaimRequest:
+      type: object
+      required: [expectedAssignmentVersion, operationId]
+      properties:
+        expectedAssignmentVersion: {type: integer, minimum: 0}
+        operationId: {type: string, maxLength: 128}
+    AssignRequest:
+      type: object
+      required: [assigneeId, assigneeName, expectedAssignmentVersion, operationId]
+      properties:
+        assigneeId: {type: integer, format: int64, minimum: 1}
+        assigneeName: {type: string, maxLength: 64}
+        expectedAssignmentVersion: {type: integer, minimum: 0}
+        operationId: {type: string, maxLength: 128}
+    ReviewRequest:
+      type: object
+      required: [expectedTaskVersion, operationId]
+      properties:
+        expectedTaskVersion: {type: integer, minimum: 0}
+        operationId: {type: string, maxLength: 128}
+        remark: {type: string, maxLength: 500}