125 lines
5.9 KiB
YAML
125 lines
5.9 KiB
YAML
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}/batch:
|
|
post:
|
|
summary: Atomically submit the complete online PDA draft once
|
|
parameters:
|
|
- {$ref: '#/components/parameters/TaskId'}
|
|
- {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
|
|
requestBody:
|
|
required: true
|
|
content: {application/json: {schema: {$ref: '#/components/schemas/BatchRequest'}}}
|
|
responses:
|
|
'200': {description: Completed task, identical replay result, or A0409 when any snapshot changed}
|
|
/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}
|
|
BatchRequest:
|
|
type: object
|
|
required: [warehouseId, containerNo, expectedVersion, items]
|
|
properties:
|
|
warehouseId: {type: integer, format: int64, minimum: 1}
|
|
containerNo: {type: string, maxLength: 64}
|
|
expectedVersion: {type: integer, minimum: 0}
|
|
items:
|
|
type: array
|
|
minItems: 1
|
|
maxItems: 500
|
|
items: {$ref: '#/components/schemas/BatchItemRequest'}
|
|
BatchItemRequest:
|
|
type: object
|
|
required: [itemId, action, version]
|
|
properties:
|
|
itemId: {type: integer, format: int64, minimum: 1}
|
|
action: {type: string, enum: [PICK, PARTIAL, SKIP]}
|
|
pickedPackageCount: {type: integer, minimum: 1, description: Incremental count required by PICK}
|
|
finalPickedPackageCount: {type: integer, minimum: 1, description: Final actual count required by PARTIAL}
|
|
releaseMode: {type: string, enum: [AUTO, MANUAL]}
|
|
reservationIds:
|
|
type: array
|
|
items: {type: integer, format: int64, minimum: 1}
|
|
version: {type: integer, minimum: 0}
|
|
reason: {type: string, maxLength: 500, description: Required by SKIP}
|
|
ReviewRequest:
|
|
type: object
|
|
required: [expectedTaskVersion, operationId]
|
|
properties:
|
|
expectedTaskVersion: {type: integer, minimum: 0}
|
|
operationId: {type: string, maxLength: 128}
|
|
remark: {type: string, maxLength: 500}
|