feat(appointments): unify pre-inbound planning and confirmed FBA bookings
This commit is contained in:
@@ -6,6 +6,134 @@ info:
|
||||
security:
|
||||
- bearerAuth: []
|
||||
paths:
|
||||
/api/platform/v1/last-leg/appointment-planning/appointments:
|
||||
post:
|
||||
operationId: createAppointmentFromSources
|
||||
summary: 在入仓前按稳定货源保存跨客户预约安排
|
||||
description: >-
|
||||
仅平台；同时需要platform:appointment:list、platform:overseas-warehouse:last-mile-order:list及platform:overseas-warehouse:inbound-order:fba-appointment。
|
||||
与入仓明细入口共用同一FBA预约聚合；系统生成AP单号，不创建入仓计划、库存或车次。
|
||||
PENDING允许日期、时段、外部约号及箱数暂缺。SUCCESS必须有权威目的仓时区、真实货件材料、确定箱数及外部约号和确认时段。
|
||||
实际客户、起运仓、目的仓及原BOOKING由服务端核对；活动来源与已形成订单均唯一占用，取消后释放并保留历史。
|
||||
命令与主单、明细同事务；同键同操作人同内容重试返回原快照，不受后来编辑影响。异内容或来源占用冲突拒绝。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [sources, originWarehouseId, fbaWarehouseCode, details, idempotencyKey]
|
||||
properties:
|
||||
originWarehouseId: {type: string, minLength: 1, description: 选择货源时的接仓点，保存时重新核对}
|
||||
fbaWarehouseCode: {type: string, minLength: 1, maxLength: 64, description: 选择货源时的目的仓编码，变化则拒绝保存}
|
||||
sources:
|
||||
type: array
|
||||
minItems: 1
|
||||
maxItems: 100
|
||||
items:
|
||||
type: object
|
||||
required: [sourceKey, customerId]
|
||||
properties:
|
||||
sourceKey: {type: string, maxLength: 160}
|
||||
customerId: {type: string, maxLength: 128}
|
||||
destinationKey: {type: string}
|
||||
details: {$ref: './fba-appointment-calendar-v1.yaml#/components/schemas/AppointmentDetails'}
|
||||
idempotencyKey: {type: string, minLength: 1, maxLength: 64}
|
||||
responses:
|
||||
'200': {$ref: './fba-appointment-calendar-v1.yaml#/components/responses/AppointmentResult'}
|
||||
'400': {description: 来源、时段或正式确认材料无效}
|
||||
'403': {description: 权限不足或非平台身份}
|
||||
'404': {description: 来源不存在或客户不匹配}
|
||||
'409': {description: 同键异内容、版本或活动货物占用冲突}
|
||||
'503': {description: 权威仓库目录或时区暂不可用}
|
||||
/api/platform/v1/last-leg/appointment-planning/appointments/unscheduled:
|
||||
get:
|
||||
operationId: listUnscheduledAppointments
|
||||
summary: 分页读取没有日期或时段的预约安排
|
||||
description: 仅平台，权限platform:appointment:list；排除取消/失败，不用09点或零点占位。
|
||||
parameters:
|
||||
- {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
|
||||
- {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
|
||||
responses:
|
||||
'200':
|
||||
description: code=200时data为分页
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {type: string}
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
records: {type: array, items: {$ref: './fba-appointment-calendar-v1.yaml#/components/schemas/Appointment'}}
|
||||
total: {type: integer}
|
||||
page: {type: integer}
|
||||
size: {type: integer}
|
||||
pages: {type: integer}
|
||||
'403': {description: 无列表权限或非平台身份}
|
||||
/api/platform/v1/last-leg/appointment-planning/batches/preview:
|
||||
post:
|
||||
operationId: previewAppointmentBatch
|
||||
summary: 核对跨客户同仓货源合批资格
|
||||
description: >-
|
||||
只读核对，不保存预约安排、不占货、不确认预约。仅平台，同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
|
||||
最多100票，批量查询货源、实际开船节点和美国仓目录，支持ORDER与已确认承运BOOKING混合；同一订单重复别名拒绝。
|
||||
必须同美国起运仓及同美国FBA目的仓；暂扣、多目的地、已有有效预约或已取消完成货源拒绝；未知箱数保留待核实，不填0。
|
||||
未建入仓计划及尚未来货的已确认BOOKING不伪造计划、库存或入仓码；正式确认前必须核实箱数。
|
||||
未接入权威备妥窗口时返回readinessIncomplete及READY_WINDOW_UNVERIFIED，不拿到港/到仓预测代替。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [sources]
|
||||
properties:
|
||||
sources:
|
||||
type: array
|
||||
minItems: 1
|
||||
maxItems: 100
|
||||
items:
|
||||
type: object
|
||||
required: [sourceKey, customerId]
|
||||
properties:
|
||||
sourceKey: {type: string, maxLength: 160}
|
||||
customerId: {type: string, maxLength: 128}
|
||||
destinationKey: {type: string, description: 可选预期目的地；存在时必须与来源一致}
|
||||
responses:
|
||||
'200':
|
||||
description: code=200时data为本次核对结果，不是已保存单据
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {type: string}
|
||||
message: {type: string}
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
originWarehouseName: {type: string}
|
||||
destinationWarehouseCode: {type: string}
|
||||
sources: {type: array, items: {$ref: '#/components/schemas/PlanningSource'}}
|
||||
missingFields: {type: array, items: {type: string}}
|
||||
group:
|
||||
type: object
|
||||
properties:
|
||||
originWarehouseId: {type: string}
|
||||
destinationKey: {type: string}
|
||||
packages: {type: integer, nullable: true}
|
||||
unknownQuantitySources: {type: integer}
|
||||
sourceCount: {type: integer}
|
||||
customerCount: {type: integer}
|
||||
readyFrom: {type: string, format: date-time, nullable: true}
|
||||
readyTo: {type: string, format: date-time, nullable: true}
|
||||
readinessIncomplete: {type: boolean}
|
||||
'400': {description: 来源重复、跨仓、数量不明或不满足合批资格}
|
||||
'403': {description: 权限不足或非平台身份}
|
||||
'404': {description: 来源与客户不匹配}
|
||||
'503': {description: 美国仓目录不可用}
|
||||
/api/platform/v1/last-leg/appointment-planning/containers:
|
||||
get:
|
||||
operationId: appointmentPlanningContainers
|
||||
@@ -152,7 +280,7 @@ paths:
|
||||
description: >-
|
||||
仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
|
||||
依据真实客户、货源与美国仓目录核对来源，URL参数不能授予预约资格。
|
||||
ORDER仅接受已开船头程FBA货；BOOKING保留原登记身份，确认承运后尚未生成入仓单也能跟进。
|
||||
ORDER接受已开船头程FBA货和没有外接登记的真实仓储转运；有原登记必须使用BOOKING稳定身份，确认承运后尚未生成入仓单也能跟进。
|
||||
此查询不建单、不确认预约。当前覆盖读取已有FBA预约，尚未生成货物时返回SOURCE_NOT_MATERIALIZED。
|
||||
parameters:
|
||||
- {name: sourceKey, in: query, required: true, schema: {type: string, maxLength: 160}, description: 'ORDER:<内部关联ID>或BOOKING:<登记号>，非用户展示编号'}
|
||||
|
||||
Reference in New Issue
Block a user