openapi: 3.0.3
info:
  title: 一件代发国内清点组托 API
  version: 3.0.0
  description: 测量环节录入预计托数，审核通过后预生成全部 DP 托盘码并可立即打印。PDA 支持先扫箱或先扫托，逐托封托后完成入库。
paths:
  /api/platform/v1/first-leg/pda-dropship/tasks/pending:
    get:
      summary: 查询待领取或本人已领取任务
      x-required-authority: platform:firstleg:pda:view
      parameters: [{$ref: '#/components/parameters/WarehouseId'}, {name: keyword, in: query, required: false, schema: {type: string, maxLength: 64}}]
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}:
    get:
      summary: 查询任务、已清点待绑箱及托盘结果
      x-required-authority: platform:firstleg:pda:view
      parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/cartons/resolve:
    get:
      summary: 扫箱码解析入仓码、SKU 和应收数量，不返回全部未清点箱
      x-required-authority: platform:firstleg:pda:view
      parameters:
        - {$ref: '#/components/parameters/TaskId'}
        - {$ref: '#/components/parameters/WarehouseId'}
        - {name: boxCode, in: query, required: true, schema: {type: string, maxLength: 80}}
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/claim:
    post:
      summary: 领取任务
      x-required-authority: platform:firstleg:pda:work
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ClaimRequest'}}}}
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/cartons/count:
    post:
      summary: 逐箱确认 SKU 实收数量
      description: 未传 palletNo 时进入待归托区；传入本任务预生成的 OPEN 托盘码时直接归托。数量不一致必须 ACCEPT_VARIANCE 且填写说明。
      x-required-authority: platform:firstleg:pda:work
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CountCartonRequest'}}}}
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/pallets/bind-pending:
    post:
      summary: 扫托盘码并把当前任务全部待绑箱绑定到该托盘
      x-required-authority: platform:firstleg:pda:work
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/BindPendingRequest'}}}}
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/cartons/{cartonId}/move:
    post:
      summary: 换托，targetPalletNo 为空时退回待绑区
      x-required-authority: platform:firstleg:pda:work
      parameters:
        - {$ref: '#/components/parameters/TaskId'}
        - {name: cartonId, in: path, required: true, schema: {type: integer, format: int64}}
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/MoveCartonRequest'}}}}
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/pallets/{palletId}/seal:
    post:
      summary: 封托；禁止空托、版本冲突和重复归托
      x-required-authority: platform:firstleg:pda:work
      parameters:
        - {$ref: '#/components/parameters/TaskId'}
        - {name: palletId, in: path, required: true, schema: {type: integer, format: int64}}
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/SealPalletRequest'}}}}
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/tasks/{taskId}/pallets/{palletId}/print:
    get:
      summary: PDA 获取预生成托盘码的 A4 托盘信息单
      description: 测量审核通过并生成托盘码后即可获取；每个托盘固定一页 A4，包含托盘号及其 Code 128 一维码、入仓码、箱数以及已归托 SKU、商品名称和实点数量，不展示作业状态。空托显示暂无已归托 SKU。仅当前仓库、当前操作员可访问。
      x-required-authority: platform:firstleg:pda:view
      parameters:
        - {$ref: '#/components/parameters/TaskId'}
        - {name: palletId, in: path, required: true, schema: {type: integer, format: int64}}
        - {$ref: '#/components/parameters/WarehouseId'}
      responses:
        '200': {description: A4 托盘信息单 PDF, content: {application/pdf: {schema: {type: string, format: binary}}}}
  /api/platform/v1/first-leg/pda-dropship/inbound-orders/{inboundId}/pallets:
    get:
      summary: Admin 查询入仓单权威托盘结果
      x-required-authority: firstleg:inbound:list
      responses: {'200': {description: OK}}
  /api/platform/v1/first-leg/pda-dropship/inbound-orders/{inboundId}/pallets/{palletId}/print:
    get:
      summary: 获取包含托盘码、入仓码和 SKU 实收汇总的 A4 托盘信息单
      x-required-authority: firstleg:inbound:list
      responses: {'200': {description: PDF}}
components:
  parameters:
    TaskId: {name: taskId, in: path, required: true, schema: {type: integer, format: int64}}
    WarehouseId: {name: warehouseId, in: query, required: true, schema: {type: integer, format: int64}}
  schemas:
    Task:
      type: object
      description: 一件代发清点组托任务；palletSetupReady=false 时禁止领取、解析箱码和提交清点。
      required: [taskId, totalCartons, countedCartons, boundCartons, unboundCartons, expectedPalletCount, generatedPalletCount, palletSetupReady, taskStatus, pallets]
      properties:
        taskId: {type: integer, format: int64}
        totalCartons: {type: integer, minimum: 1}
        countedCartons: {type: integer, minimum: 0}
        boundCartons: {type: integer, minimum: 0}
        unboundCartons: {type: integer, minimum: 0}
        expectedPalletCount: {type: integer, minimum: 1}
        generatedPalletCount: {type: integer, minimum: 0}
        palletSetupReady: {type: boolean}
        palletSetupMessage: {type: string, nullable: true}
        taskStatus: {type: string, enum: [PENDING, CLAIMED, COMPLETED]}
        pallets: {type: array, items: {$ref: '#/components/schemas/Pallet'}}
    Carton:
      type: object
      properties:
        cartonId: {type: integer, format: int64, nullable: true}
        boxCode: {type: string}
        inboundId: {type: integer, format: int64}
        inboundCode: {type: string}
        skuLines: {type: array, minItems: 1, items: {$ref: '#/components/schemas/CartonSkuLine'}, description: 当前物理箱内全部SKU清点行}
        countStatus: {type: string, enum: [UNCOUNTED, COUNTED_UNBOUND, BOUND]}
        palletId: {type: integer, format: int64, nullable: true}
        palletNo: {$ref: '#/components/schemas/NullablePalletNo'}
        canCount: {type: boolean}
        blockReason: {type: string, nullable: true}
    CartonSkuLine:
      type: object
      required: [inboundDetailId, skuCode, expectedQuantity]
      properties:
        inboundDetailId: {type: integer, format: int64}
        skuCode: {type: string}
        cargoName: {type: string, nullable: true}
        expectedQuantity: {type: integer, minimum: 1}
        actualQuantity: {type: integer, minimum: 0, nullable: true}
        discrepancyStatus: {type: string, enum: [MATCH, ACCEPTED_VARIANCE], nullable: true}
        discrepancyRemark: {type: string, nullable: true}
    Pallet:
      type: object
      properties:
        palletId: {type: integer, format: int64}
        palletNo: {$ref: '#/components/schemas/PalletNo'}
        status: {type: string, enum: [OPEN, SEALED]}
        cartonCount: {type: integer, minimum: 0}
        skuCount: {type: integer, minimum: 0}
        discrepancyCartons: {type: integer, minimum: 0}
        weightKg: {type: number, minimum: 0}
        volumeCbm: {type: number, minimum: 0}
        version: {type: integer, minimum: 1}
        items: {type: array, items: {type: object}}
        cartons: {type: array, items: {$ref: '#/components/schemas/Carton'}, description: 含稳定 cartonId，换托必须使用该 ID}
        sealedAt: {type: string, format: date-time, nullable: true}
    ClaimRequest:
      type: object
      required: [warehouseId]
      properties: {warehouseId: {type: integer, format: int64}}
    CountCartonRequest:
      type: object
      required: [warehouseId, boxCode, skuLines, operationId]
      properties:
        warehouseId: {type: integer, format: int64}
        boxCode: {type: string, maxLength: 80}
        palletNo: {$ref: '#/components/schemas/NullablePalletNo'}
        skuLines:
          type: array
          minItems: 1
          items:
            type: object
            required: [inboundDetailId, skuCode, actualQuantity, discrepancyAction]
            properties:
              inboundDetailId: {type: integer, format: int64}
              skuCode: {type: string, maxLength: 128}
              actualQuantity: {type: integer, minimum: 0}
              discrepancyAction: {type: string, enum: [MATCH, ACCEPT_VARIANCE]}
              discrepancyRemark: {type: string, maxLength: 500, nullable: true}
        operationId: {type: string, maxLength: 128}
    BindPendingRequest:
      type: object
      required: [warehouseId, palletNo, operationId]
      properties:
        warehouseId: {type: integer, format: int64}
        palletNo: {$ref: '#/components/schemas/PalletNo'}
        operationId: {type: string, maxLength: 128}
    MoveCartonRequest:
      type: object
      required: [warehouseId, operationId]
      properties:
        warehouseId: {type: integer, format: int64}
        targetPalletNo: {$ref: '#/components/schemas/NullablePalletNo'}
        operationId: {type: string, maxLength: 128}
    SealPalletRequest:
      type: object
      required: [warehouseId, expectedVersion, operationId]
      properties:
        warehouseId: {type: integer, format: int64}
        expectedVersion: {type: integer, minimum: 1}
        operationId: {type: string, maxLength: 128}
    PalletNo: {type: string, pattern: '^DP-[0-9]{6}-[0-9]{4}$'}
    NullablePalletNo: {type: string, pattern: '^DP-[0-9]{6}-[0-9]{4}$', nullable: true}