baiyue-firstleg/firstleg/src/main/resources/openapi/dropship-palletization-v1.yaml

openapi: 3.0.3
info:
  title: 一件代发国内清点组托 API
  version: 2.0.0
  description: 测量、计费后独立下发。先逐箱确认 SKU 实收数量；全部箱码清点完成后才原子生成、绑定并封存正式 DP 托盘码，随后可打印托盘标签。
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: 清点阶段只记录箱级实收并进入 COUNTED_UNBOUND，不得提前生成或绑定托盘码。数量不一致必须 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}/pallets/create-and-bind:
    post:
      summary: 完成一件代发入库并生成正式 DP 托盘码
      description: 仅全部箱码已经清点的本人任务可执行；同一事务内生成 DP 托盘码、绑定全部箱、封托并把入仓单推进到待分柜。未完成清点或没有待绑箱时不发码、不建空托。operationId 重放不重复创建；返回已完成 Task。
      x-required-authority: platform:firstleg:pda:work
      parameters: [{$ref: '#/components/parameters/TaskId'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateAndBindRequest'}}}}
      responses: {'200': {description: Task}}
  /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 打印已封托的一件代发托盘码
      description: 仅当前仓库、当前操作员可访问；未封托托盘拒绝打印。返回 100mm × 100mm PDF。
      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: 托盘码 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 实收汇总
      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:
    Carton:
      type: object
      properties:
        cartonId: {type: integer, format: int64, nullable: true}
        boxCode: {type: string}
        inboundId: {type: integer, format: int64}
        inboundCode: {type: string}
        inboundDetailId: {type: integer, format: int64}
        skuCode: {type: string}
        cargoName: {type: string, nullable: true}
        expectedSkuQuantity: {type: integer, minimum: 1}
        actualSkuQuantity: {type: integer, minimum: 1, nullable: true}
        discrepancyStatus: {type: string, enum: [MATCH, ACCEPTED_VARIANCE], nullable: true}
        discrepancyRemark: {type: string, nullable: true}
        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}
    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, actualSkuQuantity, discrepancyAction, operationId]
      properties:
        warehouseId: {type: integer, format: int64}
        boxCode: {type: string, maxLength: 80}
        actualSkuQuantity: {type: integer, minimum: 1}
        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}$'}
    CreateAndBindRequest:
      type: object
      required: [warehouseId, operationId]
      properties:
        warehouseId: {type: integer, format: int64, minimum: 1}
        operationId: {type: string, minLength: 1, maxLength: 128}
    NullablePalletNo: {type: string, pattern: '^DP-[0-9]{6}-[0-9]{4}$', nullable: true}