feat(appointments): unify pre-inbound planning and confirmed FBA bookings

This commit is contained in:
2026-10-10 10:38:06 +08:00
parent 24f5ccf7ff
commit c4c1bddeec
54 changed files with 1623 additions and 744 deletions
@@ -1651,39 +1651,65 @@ CREATE TABLE IF NOT EXISTS ll_appointment_followup (
CREATE TABLE IF NOT EXISTS ll_inbound_fba_appointment (
id BIGINT NOT NULL COMMENT '主键ID',
appointment_no VARCHAR(64) NOT NULL COMMENT '预约单号',
appointment_at DATETIME(3) NOT NULL COMMENT '预约时间',
appointment_end_at DATETIME(3) NULL COMMENT '预约结束时间,未明确时为空',
appointment_no VARCHAR(64) NOT NULL COMMENT '系统预约业务单号,不是外部约号',
confirmation_no VARCHAR(128) NULL COMMENT '收货方正式外部确认号',
planned_date DATE NULL COMMENT '计划当地日期,可只有日期而无时段',
planned_at DATETIME(3) NULL COMMENT '计划开始当地时间,待定可空',
planned_end_at DATETIME(3) NULL COMMENT '计划结束当地时间',
appointment_at DATETIME(3) NULL COMMENT '对方确认开始当地时间',
appointment_end_at DATETIME(3) NULL COMMENT '对方确认结束当地时间',
appointment_start_utc DATETIME(3) NULL COMMENT '确认开始UTC时间点',
appointment_end_utc DATETIME(3) NULL COMMENT '确认结束UTC时间点',
timezone VARCHAR(64) NULL COMMENT '目的仓权威IANA时区,未维护不得确认',
origin_warehouse_id VARCHAR(64) NOT NULL COMMENT '实际起运仓',
version INT NOT NULL DEFAULT 0 COMMENT '并发版本',
expected_loading_at DATETIME(3) NOT NULL COMMENT '预计装车时间',
appointment_status VARCHAR(32) NOT NULL DEFAULT 'PENDING' COMMENT '预约状态',
appointment_remark VARCHAR(1000) NULL COMMENT '预约备注',
fba_warehouse_code VARCHAR(128) NOT NULL COMMENT 'FBA仓库编码',
selected_count INT NOT NULL DEFAULT 0 COMMENT '已选明细数量',
created_by VARCHAR(128) NULL COMMENT '创建人ID',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
appointment_status VARCHAR(32) NOT NULL DEFAULT 'PENDING' COMMENT 'PENDING安排/SUCCESS对方确认/FAILED/CANCELLED',
appointment_remark VARCHAR(1000) NULL COMMENT '备注或取消原因',
fba_warehouse_code VARCHAR(128) NOT NULL COMMENT 'FBA目的仓编码',
selected_count INT NOT NULL DEFAULT 0 COMMENT '真实货源票数',
created_by VARCHAR(128) NOT NULL COMMENT '登录操作人',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建UTC时间',
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '更新UTC时间',
PRIMARY KEY (id),
UNIQUE KEY uk_ll_fba_appointment_no (appointment_no),
KEY idx_ll_fba_appointment_list (appointment_at, appointment_status, fba_warehouse_code)
) ENGINE=InnoDB COMMENT='FBA入仓预约单';
UNIQUE KEY uk_ll_fba_external_confirmation (fba_warehouse_code,confirmation_no),
KEY idx_ll_fba_appointment_list (appointment_at,appointment_status,fba_warehouse_code),
KEY idx_ll_fba_appointment_planned (planned_at,appointment_status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='FBA预约安排与正式确认唯一主记录';
CREATE TABLE IF NOT EXISTS ll_inbound_fba_appointment_item (
id BIGINT NOT NULL COMMENT '主键ID',
appointment_id BIGINT NOT NULL COMMENT '预约单ID',
customer_id VARCHAR(128) NOT NULL COMMENT '本票货物客户ID',
plan_id BIGINT NOT NULL COMMENT '入仓计划ID',
line_id BIGINT NOT NULL COMMENT '入仓计划明细ID',
order_id BIGINT NOT NULL COMMENT '订单ID',
inbound_code VARCHAR(128) NOT NULL COMMENT '入仓单号快照',
fba_warehouse_code VARCHAR(128) NOT NULL COMMENT 'FBA仓库编码',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
id BIGINT NOT NULL COMMENT '记录主键',
appointment_id BIGINT NOT NULL COMMENT '预约主记录标识',
source_key VARCHAR(160) NOT NULL COMMENT '稳定ORDER或BOOKING货源键',
source_version VARCHAR(160) NULL COMMENT '保存时核实的来源版本',
customer_id VARCHAR(128) NOT NULL COMMENT '本票所属客户',
order_id BIGINT NULL COMMENT '尚未形成尾程订单时为空',
inbound_code VARCHAR(128) NULL COMMENT '真实入仓码,不伪造',
fba_warehouse_code VARCHAR(128) NOT NULL COMMENT '目的FBA仓编码',
package_count INT NULL COMMENT '所选整票预报箱数,未知保持空',
active TINYINT(1) NOT NULL DEFAULT 1 COMMENT '取消或失败后释放货源占用',
active_source_key VARCHAR(160) GENERATED ALWAYS AS (CASE WHEN active=1 THEN source_key ELSE NULL END) STORED COMMENT '有效货源唯一占用键',
active_order_id BIGINT GENERATED ALWAYS AS (CASE WHEN active=1 THEN order_id ELSE NULL END) STORED COMMENT '有效订单唯一占用键',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建UTC时间',
PRIMARY KEY (id),
UNIQUE KEY uk_ll_fba_appointment_item_line (appointment_id, line_id),
KEY idx_ll_fba_appointment_item_cargo (line_id,appointment_id),
KEY idx_ll_fba_appointment_item_plan (plan_id),
KEY idx_ll_fba_appointment_item_order (order_id)
) ENGINE=InnoDB COMMENT='FBA入仓预约明细';
UNIQUE KEY uk_ll_fba_item_source (appointment_id,source_key),
UNIQUE KEY uk_ll_fba_active_source (active_source_key),
UNIQUE KEY uk_ll_fba_active_order (active_order_id),
KEY idx_ll_fba_item_source_lookup (source_key,customer_id),
KEY idx_ll_fba_item_customer_order (customer_id,order_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='入仓前后共用的预约真实货源';
CREATE TABLE IF NOT EXISTS ll_fba_appointment_command (
command_key VARCHAR(128) NOT NULL COMMENT '持久化幂等键',
request_hash CHAR(64) NOT NULL COMMENT '操作、操作者和请求摘要',
operation VARCHAR(96) NOT NULL COMMENT '操作类型及目标业务号',
operator_id VARCHAR(128) NOT NULL COMMENT '登录操作人',
appointment_no VARCHAR(64) NULL COMMENT '系统预约业务单号',
response_json LONGTEXT NULL COMMENT '原命令返回快照,与业务写入同事务',
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建UTC时间',
PRIMARY KEY(command_key),
KEY idx_ll_fba_command_appointment(appointment_no,created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='预约命令与变更历史';
ALTER TABLE ll_loading_order_status_history
MODIFY COLUMN id BIGINT NOT NULL AUTO_INCREMENT COMMENT '状态历史主键',
@@ -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:<登记号>,非用户展示编号'}
@@ -1,15 +1,15 @@
openapi: 3.0.3
info:
title: 跨客户 FBA 预约与日历
version: 1.0.0
description: 按同一目的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。平台身份限定。客户归属由服务端入仓计划确定,不接受预约主单customerId;同号同内容重放返回原预约,异内容拒绝。已有有效预约的货物不能重复建约。'
description: '权限:platform:overseas-warehouse:inbound-order:fba-appointment。平台身份限定。入仓明细仅作选择入口,服务端转成原ORDER/BOOKING整票来源,不另建别名。系统生成appointmentNo,不接受主单客户或外部号冒充系统单号。同键、同操作者、同内容返回原命令快照;异内容拒绝。与入仓前货源入口共用同一主表及唯一占用约束。'
requestBody:
required: true
content:
@@ -18,10 +18,11 @@ paths:
allOf:
- {$ref: '#/components/schemas/AppointmentWrite'}
- type: object
required: [lineIds, appointmentNo]
required: [lineIds, originWarehouseId, fbaWarehouseCode]
properties:
lineIds: {type: array, minItems: 1, maxItems: 500, items: {type: string}}
appointmentNo: {type: string, maxLength: 64}
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: 非平台身份或无写权限}
@@ -32,8 +33,8 @@ paths:
required: true
schema: {type: string}
delete:
summary: 删除未关联有效排车的预约
description: '平台专用,权限platform:appointment:delete。校验当前版本后原子删除预约及预约明细,不删除客户货物。已有关联有效排车时拒绝。'
summary: 取消未关联有效排车的预约并释放占用
description: '平台专用,权限platform:appointment:delete。校验版本后保留主单、确认事实及明细历史,设置CANCELLED并释放货源占用;不删除客户货物或回退库存。已有关联有效排车时拒绝。取消命令按系统单号、版本和操作者幂等。'
parameters:
- {name: version, in: query, required: true, schema: {type: integer, minimum: 0}}
responses:
@@ -47,7 +48,7 @@ paths:
'403': {description: 无读取权限}
put:
summary: 按版本更新预约
description: '权限:platform:overseas-warehouse:inbound-order:fba-appointment。平台限定,版本冲突拒绝;取消不删除货物。恢复时重新校验货物是否已被其他有效预约占用。'
description: '权限:platform:overseas-warehouse:inbound-order:fba-appointment。平台限定,版本及持久化幂等校验;已有有效排车时先处理运输安排。取消/失败必须写原因并保留原确认时间。恢复时重新核对来源、目的仓和占用;不能直接将SUCCESS退回PENDING。'
requestBody:
required: true
content:
@@ -66,7 +67,7 @@ paths:
get:
operationId: fbaAppointmentCalendar
summary: 按日期范围查询 FBA 预约
description: '权限:platform:appointment:list。仅平台身份可读取跨客户预约。固定批量查询预约及关联明细,不逐预约查详情。'
description: '权限:platform:appointment:list。按确认当地时间、计划时段或仅计划日期选取,排除取消/失败。仅有日期时不补造零点时段;无日期记录走未定时分页入口。固定批量查询预约及明细,不逐预约查详情。跨时区总览仍需按地点标注,不将当地值当成浏览器时区。'
parameters:
- name: from
in: query
@@ -110,22 +111,40 @@ components:
schemas:
AppointmentWrite:
type: object
required: [appointmentAt, expectedLoadingAt, appointmentStatus]
required: [details, idempotencyKey]
properties:
appointmentAt: {type: string, description: 预约开始日期时间}
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: 明确结束时间时必须晚于开始时间;未知留空,不推算}
expectedLoadingAt: {type: string}
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}
appointmentAt: {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}
expectedLoadingAt: {type: string}
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}
@@ -140,8 +159,9 @@ components:
properties:
id: {type: string}
customerId: {type: string, description: 本票货物客户归属,不在预约主单指定客户}
planId: {type: string}
lineId: {type: string}
orderId: {type: string}
inboundCode: {type: string}
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}