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}