feat(lastleg): connect appointment followups and fleet intake
This commit is contained in:
@@ -0,0 +1,230 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: 美国预约筹划货源
|
||||
version: 1.0.0
|
||||
description: 读取真实已开船头程货物，不要求预先创建入仓计划，不生成库存、车次或对外确认。
|
||||
security:
|
||||
- bearerAuth: []
|
||||
paths:
|
||||
/api/platform/v1/last-leg/appointment-planning/cargo:
|
||||
get:
|
||||
operationId: appointmentPlanningCargo
|
||||
summary: 分页读取美国FBA筹划货源
|
||||
description: >-
|
||||
仅平台身份；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
|
||||
从公共仓库目录核对美国接仓点与美国FBA目的仓；目录失败返回错误，不冒充空结果。
|
||||
当前读取FIRST_LEG货物与已确认开船或更晚的实际船节点，未建计划可见；已有计划不重复计数。
|
||||
预计时间来自尾程订单保存的来源快照，不代表实时船司ETA；shippingObservedAt仅是实际节点观察时间。
|
||||
sourcePalletCount是头程预报托数，不是海外实测托位。其他货源由后续正式合同接入，不能从本接口推断已支持。
|
||||
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}}
|
||||
- {name: warehouseId, in: query, schema: {type: string}, description: 美国接仓点主档ID，仅用于关联}
|
||||
- {name: destination, in: query, schema: {type: string}, description: 美国FBA仓编码}
|
||||
- {name: keyword, in: query, schema: {type: string, maxLength: 128}, description: 入仓码、柜号或客户名称}
|
||||
responses:
|
||||
'200':
|
||||
description: 业务响应，必须核对code
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {type: string}
|
||||
message: {type: string}
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
records: {type: array, items: {$ref: '#/components/schemas/Cargo'}}
|
||||
page: {type: integer}
|
||||
size: {type: integer}
|
||||
total: {type: integer}
|
||||
pages: {type: integer}
|
||||
'400': {description: 查询参数或美国范围无效}
|
||||
'403': {description: 无来源读取权限或非平台身份}
|
||||
'503': {description: 仓库目录暂不可用，不能证明美国货源范围}
|
||||
/api/platform/v1/last-leg/appointment-planning/sources/resolve:
|
||||
get:
|
||||
operationId: resolveAppointmentPlanningSource
|
||||
summary: 核对深链来源并读取预约覆盖
|
||||
description: >-
|
||||
仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
|
||||
依据真实客户、货源与美国仓目录核对来源，URL参数不能授予预约资格。
|
||||
ORDER仅接受已开船头程FBA货；BOOKING保留原登记身份，确认承运后尚未生成入仓单也能跟进。
|
||||
此查询不建单、不确认预约。当前覆盖读取已有FBA预约，尚未生成货物时返回SOURCE_NOT_MATERIALIZED。
|
||||
parameters:
|
||||
- {name: sourceKey, in: query, required: true, schema: {type: string, maxLength: 160}, description: 'ORDER:<内部关联ID>或BOOKING:<登记号>，非用户展示编号'}
|
||||
- {name: customerId, in: query, required: true, schema: {type: string, maxLength: 128}}
|
||||
- {name: destinationKey, in: query, schema: {type: string}, description: 'FBA:<仓编码>，传入后必须与真实来源一致'}
|
||||
responses:
|
||||
'200':
|
||||
description: code=200时data包含已核实来源和预约覆盖
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {type: string}
|
||||
message: {type: string}
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
source: {$ref: '#/components/schemas/PlanningSource'}
|
||||
coverage: {$ref: '#/components/schemas/Coverage'}
|
||||
'400': {description: 非美国FBA来源、尚未开船或目的地变化}
|
||||
'403': {description: 无读取权限或非平台身份}
|
||||
'404': {description: 客户与来源不匹配或来源不存在}
|
||||
'503': {description: 仓库目录不可用}
|
||||
/api/platform/v1/last-leg/appointment-planning/sources/{sourceKey}/follow-ups:
|
||||
parameters:
|
||||
- {name: sourceKey, in: path, required: true, schema: {type: string, maxLength: 160}, description: 'ORDER或BOOKING稳定来源键，路径须URL编码'}
|
||||
- {name: customerId, in: query, required: true, schema: {type: string, maxLength: 128}}
|
||||
get:
|
||||
summary: 分页读取分事项跟进历史与最新版本
|
||||
description: 仅平台；同时要求platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。已有跟进历史在货物完成后仍可读取。
|
||||
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含history分页和按stage排列的versions；createdAt为UTC时间点，followupDate为业务地点当地日期。
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {type: string}
|
||||
message: {type: string}
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
history:
|
||||
type: object
|
||||
properties:
|
||||
records: {type: array, items: {$ref: '#/components/schemas/FollowupRecord'}}
|
||||
page: {type: integer}
|
||||
size: {type: integer}
|
||||
total: {type: integer}
|
||||
pages: {type: integer}
|
||||
versions: {type: object, additionalProperties: {type: integer, minimum: 0}, description: 四个事项各自的最新版本}
|
||||
'403': {description: 无读取权限或非平台身份}
|
||||
'404': {description: 无历史且来源不具备美国筹划资格}
|
||||
post:
|
||||
summary: 追加人工联系结果与下次跟进
|
||||
description: >-
|
||||
仅平台；除读取权限外要求platform:appointment:followup。
|
||||
跟进人来自登录主体，不接受客户端操作者ID。核实来源后按stage版本追加，以持久化唯一约束防止并发覆盖；幂等键持久化，同键同操作者同内容返回原记录，异内容拒绝。
|
||||
不要求已创建入仓计划、外部预约号或司机，不更新正式预约、库存和车次。设置followupDate时nextAction必填。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [stage, expectedVersion, idempotencyKey, result]
|
||||
properties:
|
||||
stage: {type: string, enum: [DRAYAGE_CONTACT, TERMINAL_APPOINTMENT, WAREHOUSE_RECEIVING, FBA_RECEIVING]}
|
||||
expectedVersion: {type: integer, minimum: 0, description: 初次为0，后续取history.versions中对应事项版本}
|
||||
idempotencyKey: {type: string, maxLength: 64}
|
||||
contactedParty: {type: string, maxLength: 200, nullable: true}
|
||||
result: {type: string, minLength: 1, maxLength: 1000}
|
||||
nextAction: {type: string, maxLength: 500, nullable: true}
|
||||
followupDate: {type: string, format: date, nullable: true}
|
||||
responses:
|
||||
'200':
|
||||
description: data为原记录或新增记录
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: {type: string}
|
||||
message: {type: string}
|
||||
data: {$ref: '#/components/schemas/FollowupRecord'}
|
||||
'400': {description: 无效事项或缺少下一步安排}
|
||||
'403': {description: 无写权限或非平台身份}
|
||||
'404': {description: 来源不存在或不可筹划}
|
||||
'409': {description: 版本冲突或同键异内容}
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
|
||||
schemas:
|
||||
FollowupRecord:
|
||||
type: object
|
||||
properties:
|
||||
stage: {type: string, enum: [DRAYAGE_CONTACT, TERMINAL_APPOINTMENT, WAREHOUSE_RECEIVING, FBA_RECEIVING]}
|
||||
version: {type: integer, minimum: 1}
|
||||
contactedParty: {type: string, nullable: true}
|
||||
result: {type: string}
|
||||
nextAction: {type: string, nullable: true}
|
||||
followupDate: {type: string, format: date, nullable: true}
|
||||
operatorName: {type: string, nullable: true}
|
||||
createdAt: {type: string, format: date-time, description: UTC时间点}
|
||||
PlanningSource:
|
||||
type: object
|
||||
properties:
|
||||
sourceKey: {type: string}
|
||||
customerId: {type: string}
|
||||
orderId: {type: string, nullable: true}
|
||||
inboundCode: {type: string, nullable: true}
|
||||
bookingNo: {type: string, nullable: true}
|
||||
containerNo: {type: string, nullable: true}
|
||||
originWarehouseId: {type: string}
|
||||
originWarehouseName: {type: string}
|
||||
destinationKey: {type: string}
|
||||
destinationWarehouseCode: {type: string}
|
||||
packages: {type: integer, nullable: true, description: 未知数量保持空值，不能替换为0}
|
||||
sourceVersion: {type: string, nullable: true}
|
||||
canFollowup: {type: boolean}
|
||||
blockReasons: {type: array, items: {type: string}}
|
||||
Coverage:
|
||||
type: object
|
||||
properties:
|
||||
customerId: {type: string}
|
||||
sourceKey: {type: string}
|
||||
destinationKey: {type: string}
|
||||
status: {type: string, enum: [SOURCE_NOT_FOUND, SOURCE_NOT_MATERIALIZED, SOURCE_NOT_READY, DESTINATION_MISMATCH, UNASSIGNED, PARTIAL, PENDING, CONFIRMED, REVIEW_REQUIRED]}
|
||||
sourceVersion: {type: string, nullable: true}
|
||||
changeReviewRequired: {type: boolean}
|
||||
missingFields: {type: array, items: {type: string}, description: 缺项或待核实原因代码，客户端需显示业务文案}
|
||||
appointments:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
appointmentNo: {type: string}
|
||||
confirmationNo: {type: string, nullable: true}
|
||||
status: {type: string}
|
||||
confirmedAt: {type: string, nullable: true}
|
||||
confirmedEndAt: {type: string, nullable: true}
|
||||
timezone: {type: string, nullable: true, description: 旧预约未记录时区时为空并返回缺项，不能按浏览器时区推定}
|
||||
Cargo:
|
||||
type: object
|
||||
properties:
|
||||
sourceKey: {type: string, description: 稳定ORDER来源键，不因生成入仓计划而变化；非展示编号}
|
||||
orderId: {type: string}
|
||||
customerId: {type: string}
|
||||
customerName: {type: string, nullable: true}
|
||||
inboundCode: {type: string, nullable: true}
|
||||
containerBookingId: {type: string}
|
||||
containerNo: {type: string, nullable: true}
|
||||
originWarehouseId: {type: string}
|
||||
originWarehouseCode: {type: string}
|
||||
originWarehouseName: {type: string}
|
||||
destinationWarehouseCode: {type: string}
|
||||
packages: {type: integer, nullable: true}
|
||||
receivedPackages: {type: integer, nullable: true}
|
||||
shippedPackages: {type: integer, nullable: true}
|
||||
sourcePalletCount: {type: integer, nullable: true}
|
||||
volumeCbm: {type: number, nullable: true}
|
||||
estimatedArrivalAt: {type: string, nullable: true, description: 来源预计到港快照，保留原业务当地时间；不得按浏览器时区转换}
|
||||
estimatedWarehouseAt: {type: string, nullable: true, description: 已保存预计到仓，不因本查询改变}
|
||||
orderVersion: {type: integer}
|
||||
standardNode: {type: string}
|
||||
shippingVersion: {type: string, nullable: true}
|
||||
shippingObservedAt: {type: string, nullable: true}
|
||||
shippingProvider: {type: string, nullable: true}
|
||||
hasInboundPlan: {type: boolean}
|
||||
hasActiveAppointment: {type: boolean}
|
||||
detained: {type: boolean}
|
||||
mixedDestinations: {type: boolean, description: 存在其他目的地明细时，不能按整票默认为同仓货物}
|
||||
Reference in New Issue
Block a user