168 lines
9.2 KiB
YAML
168 lines
9.2 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 跨客户 FBA 预约与日历
|
|
version: 2.0.0
|
|
description: 同一美国起运仓和目的FBA仓的跨客户安排。系统单号与外部约号分开；入仓前后共用稳定货源，只有平台可维护完整预约，不推进库存或现场作业。
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/api/platform/v1/last-leg/inbound-plans/fba-appointments/batch:
|
|
post:
|
|
summary: 为同一目的仓的跨客户入仓明细创建预约
|
|
description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台身份限定。入仓明细仅作选择入口，服务端转成原ORDER/BOOKING整票来源，不另建别名。系统生成appointmentNo，不接受主单客户或外部号冒充系统单号。同键、同操作者、同内容返回原命令快照；异内容拒绝。与入仓前货源入口共用同一主表及唯一占用约束。'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/AppointmentWrite'}
|
|
- type: object
|
|
required: [lineIds, originWarehouseId, fbaWarehouseCode]
|
|
properties:
|
|
originWarehouseId: {type: string, minLength: 1, description: 选择时的接仓点，保存时核对}
|
|
fbaWarehouseCode: {type: string, minLength: 1, maxLength: 64, description: 选择时的目的仓，变化则拒绝}
|
|
lineIds: {type: array, minItems: 1, maxItems: 100, items: {type: string}}
|
|
responses:
|
|
'200': {$ref: '#/components/responses/AppointmentResult'}
|
|
'403': {description: 非平台身份或无写权限}
|
|
/api/platform/v1/last-leg/inbound-plans/fba-appointments/{appointmentNo}:
|
|
parameters:
|
|
- name: appointmentNo
|
|
in: path
|
|
required: true
|
|
schema: {type: string}
|
|
delete:
|
|
summary: 取消未关联有效排车的预约并释放占用
|
|
description: '平台专用，权限platform:appointment:delete。校验版本后保留主单、确认事实及明细历史，设置CANCELLED并释放货源占用；不删除客户货物或回退库存。已有关联有效排车时拒绝。取消命令按系统单号、版本和操作者幂等。'
|
|
parameters:
|
|
- {name: version, in: query, required: true, schema: {type: integer, minimum: 0}}
|
|
responses:
|
|
'200': {description: 业务响应，成功code为字符串200；版本冲突或已关联排车返回业务错误}
|
|
'403': {description: 无删除权限}
|
|
get:
|
|
summary: 读取完整跨客户预约
|
|
description: '仅平台，权限：platform:appointment:list 或 platform:overseas-warehouse:inbound-order:list。客户只能经原订单/入仓单接口读取自己的货物，不开放整张预约。'
|
|
responses:
|
|
'200': {$ref: '#/components/responses/AppointmentResult'}
|
|
'403': {description: 无读取权限}
|
|
put:
|
|
summary: 按版本更新预约
|
|
description: '权限：platform:overseas-warehouse:inbound-order:fba-appointment。平台限定，版本及持久化幂等校验；已有有效排车时先处理运输安排。取消/失败必须写原因并保留原确认时间。恢复时重新核对来源、目的仓和占用；不能直接将SUCCESS退回PENDING。'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- {$ref: '#/components/schemas/AppointmentWrite'}
|
|
- type: object
|
|
required: [version]
|
|
properties:
|
|
version: {type: integer, minimum: 0}
|
|
responses:
|
|
'200': {$ref: '#/components/responses/AppointmentResult'}
|
|
'403': {description: 无写权限}
|
|
/api/platform/v1/last-leg/inbound-plans/fba-appointments/calendar:
|
|
get:
|
|
operationId: fbaAppointmentCalendar
|
|
summary: 按日期范围查询 FBA 预约
|
|
description: '权限：platform:appointment:list。按确认当地时间、计划时段或仅计划日期选取，排除取消/失败。跨日时段只要与查询区间相交即返回，结束时间为不包含的边界；已有确认开始时间时只使用对应确认结束时间，不借用计划结束时间。仅有日期时不补造零点时段；无日期记录走未定时分页入口。固定批量查询预约及明细，不逐预约查详情。跨时区总览仍需按地点标注，不将当地值当成浏览器时区。'
|
|
parameters:
|
|
- name: from
|
|
in: query
|
|
required: true
|
|
description: 包含该日期零点，以现有预约业务日期为准。
|
|
schema: {type: string, format: date}
|
|
- name: to
|
|
in: query
|
|
required: true
|
|
description: 不包含该日期零点；必须晚于from，间隔不超过42天。
|
|
schema: {type: string, format: date}
|
|
responses:
|
|
'200':
|
|
description: 业务响应；成功code为字符串200，空区间返回空数组。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code: {type: string}
|
|
message: {type: string}
|
|
data:
|
|
type: array
|
|
items: {$ref: '#/components/schemas/Appointment'}
|
|
'401': {description: 未登录或会话失效}
|
|
'403': {description: 无列表权限}
|
|
components:
|
|
responses:
|
|
AppointmentResult:
|
|
description: 业务响应，成功code为字符串200，业务冲突返回对应业务错误码。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
code: {type: string}
|
|
message: {type: string}
|
|
data: {$ref: '#/components/schemas/Appointment'}
|
|
securitySchemes:
|
|
bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
|
|
schemas:
|
|
AppointmentWrite:
|
|
type: object
|
|
required: [details, idempotencyKey]
|
|
properties:
|
|
details: {$ref: '#/components/schemas/AppointmentDetails'}
|
|
idempotencyKey: {type: string, minLength: 1, maxLength: 64}
|
|
AppointmentDetails:
|
|
type: object
|
|
required: [appointmentStatus]
|
|
properties:
|
|
plannedDate: {type: string, format: date, nullable: true, description: 计划当地日期，允许未定}
|
|
plannedAt: {type: string, nullable: true, description: 已知的计划开始当地时段，日期必须与plannedDate一致}
|
|
plannedEndAt: {type: string, nullable: true}
|
|
confirmationNo: {type: string, maxLength: 128, nullable: true, description: 仅SUCCESS登记收货方的外部约号；同一FBA仓不得重复}
|
|
appointmentAt: {type: string, nullable: true, description: 对方确认开始当地时间；SUCCESS必填，PENDING不能当作计划填写}
|
|
appointmentEndAt: {type: string, nullable: true, description: 明确结束时间时必须晚于开始时间；未知留空，不推算}
|
|
appointmentStatus: {type: string, enum: [PENDING, SUCCESS, FAILED, CANCELLED]}
|
|
appointmentRemark: {type: string, maxLength: 1000, nullable: true}
|
|
startOffset: {type: string, maxLength: 6, nullable: true, description: 当地重叠时刻的明确时差；必须符合目的仓IANA时区}
|
|
endOffset: {type: string, maxLength: 6, nullable: true}
|
|
Appointment:
|
|
type: object
|
|
properties:
|
|
id: {type: string, description: 内部标识，不作为展示编号}
|
|
appointmentNo: {type: string, description: 系统生成AP业务单号}
|
|
confirmationNo: {type: string, nullable: true, description: 对方正式外部确认号}
|
|
plannedDate: {type: string, format: date, nullable: true}
|
|
plannedAt: {type: string, nullable: true}
|
|
plannedEndAt: {type: string, nullable: true}
|
|
appointmentAt: {type: string, nullable: true, description: 对方确认的地点当地时间}
|
|
appointmentEndAt: {type: string, nullable: true}
|
|
version: {type: integer, minimum: 0}
|
|
appointmentStartUtc: {type: string, format: date-time, nullable: true}
|
|
appointmentEndUtc: {type: string, format: date-time, nullable: true}
|
|
timezone: {type: string, nullable: true, description: 来自美国FBA仓主档的IANA时区；缺失不得正式确认}
|
|
originWarehouseId: {type: string}
|
|
appointmentStatus: {type: string, enum: [PENDING, SUCCESS, FAILED, CANCELLED]}
|
|
appointmentRemark: {type: string, nullable: true}
|
|
fbaWarehouseCode: {type: string}
|
|
selectedCount: {type: integer}
|
|
createdBy: {type: string, nullable: true}
|
|
createdAt: {type: string}
|
|
updatedAt: {type: string}
|
|
items:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id: {type: string}
|
|
customerId: {type: string, description: 本票货物客户归属，不在预约主单指定客户}
|
|
sourceKey: {type: string}
|
|
sourceVersion: {type: string, nullable: true}
|
|
orderId: {type: string, nullable: true}
|
|
inboundCode: {type: string, nullable: true}
|
|
packageCount: {type: integer, nullable: true}
|
|
fbaWarehouseCode: {type: string}
|