248 lines
14 KiB
YAML
248 lines
14 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 一件代发国内清点组托 API
|
|
version: 3.0.0
|
|
description: 测量环节录入预计托数，审核通过后预生成全部 DP 托盘码并可合并打印。PDA 支持先扫箱或先扫托，同一国内作业仓可跨票共用开放托盘，实物装满后再封托。
|
|
paths:
|
|
/api/platform/v1/first-leg/pda-dropship/cartons/resolve:
|
|
get:
|
|
summary: 同仓跨客户识别箱码并预览原任务
|
|
description: 只读，不领取或清点；返回 task 与 carton，确认时仍须领取原任务后按原 taskId 清点。拒绝其他作业员已领取任务及箱码歧义。
|
|
x-required-authority: platform:firstleg:pda:view
|
|
parameters:
|
|
- {$ref: '#/components/parameters/WarehouseId'}
|
|
- {name: boxCode, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 80}}
|
|
responses:
|
|
'200': {description: 原任务和箱内 SKU 预览}
|
|
/api/platform/v1/first-leg/pda-dropship/pallets/resolve:
|
|
get:
|
|
summary: 查询当前仓库真实托盘状态与逐客户逐票组成
|
|
description: 扫描不产生归托；返回 pallet 与 members，成员保留 taskId、inboundId、inboundCode、customerId、customerName、cartonCount。不存在或跨仓的托盘拒绝，已封托返回真实状态。
|
|
x-required-authority: platform:firstleg:pda:view
|
|
parameters:
|
|
- {$ref: '#/components/parameters/WarehouseId'}
|
|
- {name: palletNo, in: query, required: true, schema: {type: string, pattern: 'DP-[0-9]{6}-[0-9]{4}'}}
|
|
responses:
|
|
'200': {description: 实物托盘状态和成员汇总}
|
|
/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}/unseal:
|
|
post:
|
|
summary: 解除封托，恢复为可继续组托的开放托盘
|
|
description: 仅允许尚未进入有效装柜计划或后续履约的已封托托盘；合托时原子恢复所有参与任务和入仓单的待组托状态。
|
|
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/UnsealPalletRequest'}}}}
|
|
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/tasks/{taskId}/pallets/print:
|
|
get:
|
|
summary: 合并获取本票全部预生成托盘码的多页 A4 PDF
|
|
description: 每个预生成托盘固定一页，PDA 无需展开托盘列表或逐个下载，最多按本票预计托数生成。
|
|
x-required-authority: platform:firstleg:pda:view
|
|
parameters: [{$ref: '#/components/parameters/TaskId'}, {$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: platform:firstleg:inbound:list
|
|
responses: {'200': {description: OK}}
|
|
/api/platform/v1/first-leg/pda-dropship/inbound-orders/{inboundId}/pallets/print:
|
|
get:
|
|
summary: Admin 合并打印入仓单关联的全部一件代发托盘
|
|
description: 测量审核预生成托盘码后即可打印；每托一页，空托也保留托盘码和当前入仓单信息，供电脑连接打印机后在 PDA 作业前贴码。
|
|
x-required-authority: platform:firstleg:inbound:list
|
|
responses:
|
|
'200': {description: 多页 A4 托盘信息单 PDF, content: {application/pdf: {schema: {type: string, format: binary}}}}
|
|
/api/platform/v1/first-leg/pda-dropship/inbound-orders/{inboundId}/pallets/{palletId}/print:
|
|
get:
|
|
summary: 获取包含托盘码、目的仓、入仓码和 SKU 汇总的 A4 托盘信息单
|
|
x-required-authority: platform: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, description: '整托按 SKU 编码去重的种类数，包含合托全部入仓码，不是商品件数或入仓明细数'}
|
|
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}
|
|
UnsealPalletRequest:
|
|
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}
|