feat(appointment): integrate work calendar and stable cargo batches
This commit is contained in:
@@ -0,0 +1,114 @@
|
||||
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}}
|
||||
Reference in New Issue
Block a user