baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-pda-convergence-v1.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: cabinetNo, in: query, required: false, schema: {type: string}}
        - {name: loadingPlanId, in: query, required: false, schema: {type: integer, format: int64}}
        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
      responses:
        '200':
          description: Task with assignment, review, stable carton codes and item-level versions
          content: {application/json: {schema: {$ref: '#/components/schemas/Task'}}}
  /api/platform/v1/first-leg/pda-loading/tasks/pending:
    get:
      summary: List active tasks available to the authenticated PDA operator
      parameters:
        - {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}}
      responses:
        '200':
          description: Unassigned tasks and tasks assigned to the current operator, including AWAITING_REVIEW tasks with zero unresolved items so PDA can enter evidence and final completion; no customer selector required
          content:
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/PendingTask'}
  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}:
    get:
      summary: Read one PDA task by stable task identity
      parameters:
        - {$ref: '#/components/parameters/TaskId'}
        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
      responses:
        '200':
          description: Task with current transport display and ACTIVE container lifecycle fields
          content: {application/json: {schema: {$ref: '#/components/schemas/Task'}}}
  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/claim:
    post:
      summary: Atomically claim an unassigned task for the authenticated operator
      description: Claiming the canonical PDA task idempotently starts its plan and advances every associated inbound from WAIT_SPLIT to LOADING with optimistic locking; workflowStatus may later become AWAITING_REVIEW while the task remains LOADING until manual completion.
      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}/inventory-snapshot:
    get:
      summary: Read the current Warehouse inventory snapshot before atomic submission
      parameters:
        - {$ref: '#/components/parameters/TaskId'}
        - {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
      responses:
        '200':
          description: Current occupied resources grouped by inbound order with a stable snapshot token
          content: {application/json: {schema: {$ref: '#/components/schemas/InventorySnapshot'}}}
  /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
      description: The first successful pick also repairs the same WAIT_SPLIT to LOADING transition when the plan was already started, without using containerNo as an association key.
      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
      description: A batch containing PICK or PARTIAL idempotently advances associated inbound process status to LOADING before evidence operations become available.
      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: 人工确认装柜完成的兼容入口
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/ReviewRequest'}}}
      responses:
        '200': {description: 操作员明确确认后完成装柜}
  /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/complete:
    post:
      summary: PDA拣货全部处理后人工确认装柜完成
      description: 短事务校验任务版本、全部明细和operationId请求摘要，持久化可靠完成命令并将任务置为COMPLETING后立即返回PROCESSING事实。后台worker按稳定入库单顺序以checkpoint恢复Order、Warehouse、入库状态、计划和事件；请求事务内不调用任何远程服务。同operationId重放立即返回相同PROCESSING或最终结果；不同operationId在处理期间返回A0409。
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      requestBody:
        required: true
        content: {application/json: {schema: {$ref: '#/components/schemas/CompleteLoadingRequest'}}}
      responses:
        '200': {description: 已可靠受理；taskStatus=COMPLETING且workflowStatus=PROCESSING，或幂等返回最终COMPLETED结果；冲突返回A0409}
  /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}
  /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}}
    ItemId: {name: itemId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
  schemas:
    Task:
      type: object
      required: [id, loadingPlanId, containerBookingId, inboundId, inboundVersion, loadingVersion, cabinetNo, sourceType, recordStatus, taskStatus, workflowStatus, version, items]
      properties:
        id: {type: integer, format: int64}
        loadingPlanId: {type: integer, format: int64}
        containerBookingId: {type: integer, format: int64}
        inboundId: {type: integer, format: int64, description: Stable inbound identity selected from the task item; evidence identity is taskId+inboundId+loadingPlanId+containerBookingId}
        inboundVersion: {type: integer, minimum: 0, description: Current fl_inbound_order.version for inboundId; never inferred from PDA task version}
        loadingVersion: {type: integer, minimum: 0, description: Compatibility alias of inboundVersion from the same fl_inbound_order row; /loading/complete uses this inbound loading-stage version}
        cabinetNo: {type: string}
        currentContainerNo: {type: string, nullable: true, description: Mutable transport display field; changing it never resynchronizes the task or item versions and it is never task identity}
        sourceType: {type: string, enum: [SIMULATION, OCEAN_BOOKING], description: Source of the surviving stable container identity}
        recordStatus: {type: string, enum: [ACTIVE], description: Task detail is served only from the ACTIVE container booking currently owned by the loading plan}
        mergedIntoContainerBookingId: {type: integer, format: int64, nullable: true, description: Always null for the surviving ACTIVE operational container; populated only on hidden MERGED source history}
        taskStatus: {type: string, enum: [LOADING, COMPLETING, COMPLETION_FAILED, COMPLETED]}
        workflowStatus: {type: string, enum: [UNASSIGNED, IN_PROGRESS, AWAITING_REVIEW, PROCESSING, COMPLETION_FAILED, COMPLETED]}
        completionCommand: {$ref: '#/components/schemas/CompletionCommand', nullable: true}
        version: {type: integer, minimum: 0}
        assignment: {type: object, nullable: true}
        review: {type: object, nullable: true}
        items:
          type: array
          items: {$ref: '#/components/schemas/PickItem'}
    PickItem:
      type: object
      required: [id, loadingPlanItemId, tenantId, inboundId, inboundDetailId, boxCodes, plannedPackageCount, pickedPackageCount, itemStatus, version]
      properties:
        id: {type: integer, format: int64}
        loadingPlanItemId: {type: integer, format: int64}
        tenantId: {type: integer, format: int64, description: Hidden isolation key for subsequent PDA evidence calls}
        inboundId: {type: integer, format: int64}
        inboundDetailId: {type: integer, format: int64}
        orderNo: {type: string, nullable: true}
        inboundCode: {type: string, nullable: true}
        cargoName: {type: string, nullable: true}
        boxCodes:
          type: array
          description: Stable carton label codes; one successful scan represents one carton
          items: {type: string}
        plannedPackageCount: {type: integer, minimum: 1}
        pickedPackageCount: {type: integer, minimum: 0}
        itemStatus: {type: string, enum: [PENDING, PICKING, PICKED, PARTIAL, SKIPPED]}
        version: {type: integer, minimum: 0}
    PendingTask:
      type: object
      required: [taskId, loadingPlanId, containerBookingId, cabinetNo, sourceType, recordStatus, warehouseId, taskStatus, workflowStatus, version, assignmentVersion, itemCount, pendingItemCount]
      properties:
        taskId: {type: integer, format: int64}
        loadingPlanId: {type: integer, format: int64}
        containerBookingId: {type: integer, format: int64}
        cabinetNo: {type: string}
        currentContainerNo: {type: string, nullable: true}
        sourceType: {type: string, enum: [SIMULATION, OCEAN_BOOKING]}
        recordStatus: {type: string, enum: [ACTIVE], description: Enforced by the server-side pending-task query; PDA clients must not infer or relax this filter}
        mergedIntoContainerBookingId: {type: integer, format: int64, nullable: true, description: Always null for an ACTIVE pending task}
        warehouseId: {type: integer, format: int64}
        warehouseName: {type: string, nullable: true}
        taskStatus: {type: string, enum: [LOADING, COMPLETING, COMPLETION_FAILED]}
        workflowStatus: {type: string, enum: [UNASSIGNED, IN_PROGRESS, AWAITING_REVIEW, PROCESSING, COMPLETION_FAILED], description: Server projection aligned with task detail; completion acceptance is returned immediately as PROCESSING}
        version: {type: integer, minimum: 0}
        assignmentVersion: {type: integer, minimum: 0}
        itemCount: {type: integer, minimum: 1}
        pendingItemCount: {type: integer, minimum: 0}
    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, loadingPlanId, containerBookingId, expectedVersion, inventorySnapshotToken, items]
      properties:
        warehouseId: {type: integer, format: int64, minimum: 1}
        loadingPlanId: {type: integer, format: int64, minimum: 1}
        containerBookingId: {type: integer, format: int64, minimum: 1}
        expectedVersion: {type: integer, minimum: 0}
        inventorySnapshotToken: {type: string, minLength: 64, maxLength: 64}
        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}
    CompletionCommand:
      type: object
      required: [id, operationId, status, expectedTaskVersion, attemptCount]
      properties:
        id: {type: integer, format: int64}
        operationId: {type: string, maxLength: 128, description: Retry must reuse this exact identity}
        status: {type: string, enum: [PROCESSING, RETRYABLE, FAILED, COMPLETED]}
        expectedTaskVersion: {type: integer, minimum: 0, description: Retry must preserve this request-hashed version}
        remark: {type: string, maxLength: 500, nullable: true, description: Retry must preserve this request-hashed remark}
        attemptCount: {type: integer, minimum: 0}
        nextRetryAt: {type: string, format: date-time, nullable: true}
        failureStage: {type: string, nullable: true}
        failureCode: {type: string, nullable: true}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        completedAt: {type: string, format: date-time, nullable: true}
    CompleteLoadingRequest:
      type: object
      required: [expectedTaskVersion, operationId]
      properties:
        expectedTaskVersion: {type: integer, minimum: 0}
        operationId: {type: string, maxLength: 128}
        remark: {type: string, maxLength: 500}
    InventorySnapshot:
      type: object
      required: [taskId, loadingPlanId, containerBookingId, cabinetNo, taskVersion, warehouseId, capturedAt, snapshotToken, inbounds]
      properties:
        taskId: {type: integer, format: int64}
        loadingPlanId: {type: integer, format: int64}
        containerBookingId: {type: integer, format: int64}
        cabinetNo: {type: string}
        taskVersion: {type: integer, minimum: 0}
        currentContainerNo: {type: string, nullable: true}
        warehouseId: {type: integer, format: int64}
        capturedAt: {type: string, format: date-time}
        snapshotToken: {type: string, minLength: 64, maxLength: 64}
        inbounds:
          type: array
          items: {$ref: '#/components/schemas/InboundInventory'}
    InboundInventory:
      type: object
      required: [inboundId, availablePackageCount, resources]
      properties:
        inboundId: {type: integer, format: int64}
        availablePackageCount: {type: integer, minimum: 0}
        resources:
          type: array
          items: {$ref: '#/components/schemas/InventoryResource'}
    InventoryResource:
      type: object
      required: [reservationId, occupancyId, palletId, locationId, sharedOverflow, availablePackageCount]
      properties:
        reservationId: {type: integer, format: int64}
        occupancyId: {type: integer, format: int64}
        palletId: {type: integer, format: int64}
        locationId: {type: integer, format: int64}
        locationCode: {type: string, nullable: true}
        sharedOverflow: {type: boolean}
        availablePackageCount: {type: integer, minimum: 1}