115 lines
6.4 KiB
YAML
115 lines
6.4 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 预约货物核实资料
|
|
version: 1.0.0
|
|
description: >-
|
|
按原ORDER或BOOKING货源保存独立核实资料，不修改订单、登记、库存或预约确认状态。
|
|
未取得预约确认也可保存箱数和各票货件号。核实记录逐版本追加，取消预约不删除资料。
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/api/platform/v1/last-leg/appointment-planning/sources/{sourceKey}/cargo-verification:
|
|
parameters:
|
|
- {name: sourceKey, in: path, required: true, schema: {type: string, maxLength: 160}, description: 原稳定货源键；外接货来货前后均使用BOOKING键}
|
|
- {name: customerId, in: query, required: true, schema: {type: string, maxLength: 128}, description: 服务端核对的原客户归属}
|
|
get:
|
|
operationId: getAppointmentCargoVerification
|
|
summary: 读取本票独立核实资料和分配总量
|
|
description: >-
|
|
仅平台，需platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
|
|
source为权威原来源，verification为空表示尚无独立核实记录。
|
|
原版本、目的地或原箱数变化后sourceChanged为true，可分配量返回null，重新核实前不得采用旧资料。
|
|
allocatedPackages合计当前活动预约明细；未知分配单独计数，不当作零。
|
|
availablePackages为当前有效总量减已分配量，未知、超量或待复核时为空，不虚构可用量。
|
|
allowedActions表示业务资格；前端仍须与当前用户写权限取交集。
|
|
parameters:
|
|
- {name: destinationKey, in: query, schema: {type: string, maxLength: 160}, description: 可传选择时的目的地；与原来源不符则拒绝}
|
|
responses:
|
|
'200':
|
|
description: 业务响应，data为核实上下文
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code: {type: string}
|
|
data: {$ref: '#/components/schemas/CargoContext'}
|
|
'400': {description: 来源格式或目的地不符}
|
|
'403': {description: 非平台身份或权限不足}
|
|
'404': {description: 原来源不存在或客户不匹配}
|
|
'503': {description: 权威仓库目录不可用}
|
|
post:
|
|
operationId: saveAppointmentCargoVerification
|
|
summary: 独立保存箱数和本票货件或追踪号
|
|
description: >-
|
|
仅平台，需两个读取权限及platform:overseas-warehouse:inbound-order:fba-appointment。
|
|
操作人取登录身份。原货源锁与预约写命令共用，锁后重读来源和版本；expectedVersion首次为0。
|
|
原来源已知箱数时，核实量不得超过原来源；任何情况下不得低于活动预约已分配量。
|
|
原来源箱数未知时允许独立核实总量，原来源仍为空。
|
|
可以暂缺箱数或货件，保存不会自动确认预约；正式确认仍需完整材料。
|
|
同来源客户内的同幂等键、同操作人、同请求返回原核实版本，即使此后又有新版本。
|
|
同键异内容、并发版本冲突或原来源变化返回409；记录与业务写入处于同一事务。
|
|
后续预约写入采用核实版本及货件快照；单独再次核实不会改写已保存预约快照。
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema: {$ref: '#/components/schemas/SaveCargoVerification'}
|
|
responses:
|
|
'200':
|
|
description: 保存或重试原命令的核实资料快照
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code: {type: string}
|
|
data: {$ref: '#/components/schemas/CargoVerification'}
|
|
'400': {description: 请求字段无效}
|
|
'403': {description: 非平台身份或缺少独立写权限}
|
|
'404': {description: 原来源不存在或客户不匹配}
|
|
'409': {description: 原来源或核实版本变化、幂等冲突、箱数越界或来源不可安排}
|
|
'503': {description: 权威仓库目录不可用}
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
|
|
schemas:
|
|
SaveCargoVerification:
|
|
type: object
|
|
required: [destinationKey, expectedVersion, shipmentReferences, idempotencyKey]
|
|
properties:
|
|
destinationKey: {type: string, minLength: 1, maxLength: 160}
|
|
expectedSourceVersion: {type: string, maxLength: 160, nullable: true, description: 读取上下文中的原来源版本，空值也须一致}
|
|
expectedVersion: {type: integer, minimum: 0}
|
|
packageCount: {type: integer, minimum: 1, nullable: true}
|
|
shipmentReferences: {type: array, maxItems: 100, items: {type: string, minLength: 1, maxLength: 128}, description: 本票货件号或追踪号，允许暂时空列表；保存时去首尾空格并去重}
|
|
remark: {type: string, maxLength: 1000, nullable: true}
|
|
idempotencyKey: {type: string, minLength: 1, maxLength: 64}
|
|
CargoVerification:
|
|
type: object
|
|
required: [version, destinationKey, shipmentReferences, verifiedAt]
|
|
properties:
|
|
version: {type: integer, minimum: 1}
|
|
sourceVersion: {type: string, nullable: true}
|
|
destinationKey: {type: string}
|
|
sourcePackages: {type: integer, nullable: true}
|
|
packageCount: {type: integer, nullable: true}
|
|
shipmentReferences: {type: array, items: {type: string}}
|
|
remark: {type: string, nullable: true}
|
|
operatorName: {type: string, nullable: true}
|
|
verifiedAt: {type: string, format: date-time, description: UTC时间}
|
|
CargoContext:
|
|
type: object
|
|
properties:
|
|
source: {$ref: './appointment-planning-v1.yaml#/components/schemas/PlanningSource'}
|
|
verification:
|
|
allOf: [{$ref: '#/components/schemas/CargoVerification'}]
|
|
nullable: true
|
|
allocatedPackages: {type: integer, format: int64}
|
|
unknownAllocationCount: {type: integer, format: int64}
|
|
effectivePackages: {type: integer, nullable: true, description: 独立核实箱数；没有核实记录时采用原来源箱数}
|
|
availablePackages: {type: integer, format: int64, nullable: true}
|
|
sourceChanged: {type: boolean}
|
|
allowedActions: {type: array, items: {type: string, enum: [VERIFY_CARGO]}}
|
|
blockReasons: {type: array, items: {type: string}}
|