Merge origin/dev and resolve backend conflicts

lastleg-service/src/main/resources/db/lastleg.sql

@@ -48,7 +48,7 @@ CREATE TABLE IF NOT EXISTS ll_order (
   order_type VARCHAR(32) NOT NULL DEFAULT 'FIRST_LEG' COMMENT '订单类型：FIRST_LEG头程订单、RELABEL_APPLICATION换标下单、WAREHOUSE_TRANSFER仓储转运、LOCAL_LOOSEBOARD本土散板、RETURN_RELABEL退货换标、ONE_CLICK_DROPSHIP一件代发',
   lx_code VARCHAR(128) NULL COMMENT '一件代发领星入库单代码',
   destination_type VARCHAR(32) NULL COMMENT '目的类型：FBA按箱数接收、OVERSEAS逐箱扫码',
-  inbound_code VARCHAR(128) NOT NULL COMMENT '入仓码',
+  inbound_code VARCHAR(128) NULL COMMENT '真实来源入仓码；无入仓关系的海外本土业务为空',
   source_region VARCHAR(32) NOT NULL COMMENT '来源区域/系统',
   source_inbound_id VARCHAR(128) NOT NULL COMMENT '最终实装 LOADED 分片 ID，建单幂等键',
   root_inbound_id VARCHAR(128) COMMENT '根入仓单 ID',
@@ -58,8 +58,10 @@ CREATE TABLE IF NOT EXISTS ll_order (
   customer_name VARCHAR(255) COMMENT '货主名称',
   source_warehouse_id VARCHAR(128) COMMENT '来源国内装柜仓 ID 快照',
   source_warehouse_name VARCHAR(255) COMMENT '来源国内装柜仓名称快照',
-  overseas_warehouse_id VARCHAR(128) COMMENT '海外实际收货仓 ID，由绑定仓库的PDA操作员认领柜号时冻结',
-  overseas_warehouse_name VARCHAR(255) COMMENT '海外仓名称',
+  overseas_warehouse_id VARCHAR(128) NOT NULL DEFAULT '193000000000200003' COMMENT '海外接柜仓ID，新产生普通尾程整柜默认洛杉矶仓',
+  overseas_warehouse_code VARCHAR(128) NOT NULL DEFAULT 'US-LAX-01' COMMENT '海外接柜仓业务编码快照',
+  overseas_warehouse_name VARCHAR(255) NOT NULL DEFAULT '洛杉矶仓' COMMENT '海外接柜仓名称快照',
+  receiving_warehouse_version INT NOT NULL DEFAULT 0 COMMENT '柜级接柜仓分配乐观锁版本',
   transfer_warehouse_id VARCHAR(128) COMMENT '转入目的仓 ID',
   transfer_warehouse_code VARCHAR(128) COMMENT '转入目的仓编码',
   transfer_warehouse_name VARCHAR(255) COMMENT '转入目的仓名称',
@@ -68,6 +70,10 @@ CREATE TABLE IF NOT EXISTS ll_order (
   container_status VARCHAR(32) DEFAULT '待转柜' COMMENT '货柜状态',
   abnormal TINYINT NOT NULL DEFAULT 0 COMMENT '是否异常：0否1是',
   detained TINYINT NOT NULL DEFAULT 0 COMMENT '是否暂扣：0否1是',
+  hold_chargeable TINYINT NOT NULL DEFAULT 0 COMMENT '当前暂扣是否计费：0否1是',
+  hold_reason VARCHAR(500) NULL COMMENT '当前暂扣原因；解除后为空',
+  manual_node_override TINYINT NOT NULL DEFAULT 0 COMMENT '是否启用单票人工计划节点覆盖：0否1是，启用后不再继承柜级节点',
+  version INT NOT NULL DEFAULT 0 COMMENT '尾程订单命令乐观锁版本',
   pallet_count INT NOT NULL DEFAULT 0 COMMENT '托数',
   package_count INT NOT NULL DEFAULT 0 COMMENT '箱数',
   picked_package_count INT NOT NULL DEFAULT 0 COMMENT '累计已拣箱数',
@@ -108,6 +114,14 @@ CREATE TABLE IF NOT EXISTS ll_order (
 
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='pallet_merge_batch_id'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN pallet_merge_batch_id VARCHAR(64) NULL COMMENT ''平台预标记合托分组号'' AFTER pallet_merge_flag'));
 PREPARE ll_order_merge_batch_ddl FROM @ddl; EXECUTE ll_order_merge_batch_ddl; DEALLOCATE PREPARE ll_order_merge_batch_ddl;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='hold_chargeable'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN hold_chargeable TINYINT NOT NULL DEFAULT 0 COMMENT ''当前暂扣是否计费：0否1是'' AFTER detained'));
+PREPARE ll_order_command_ddl FROM @ddl; EXECUTE ll_order_command_ddl; DEALLOCATE PREPARE ll_order_command_ddl;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='hold_reason'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN hold_reason VARCHAR(500) NULL COMMENT ''当前暂扣原因；解除后为空'' AFTER hold_chargeable'));
+PREPARE ll_order_command_ddl FROM @ddl; EXECUTE ll_order_command_ddl; DEALLOCATE PREPARE ll_order_command_ddl;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='manual_node_override'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN manual_node_override TINYINT NOT NULL DEFAULT 0 COMMENT ''是否启用单票人工计划节点覆盖：0否1是'' AFTER hold_reason'));
+PREPARE ll_order_command_ddl FROM @ddl; EXECUTE ll_order_command_ddl; DEALLOCATE PREPARE ll_order_command_ddl;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='version'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN version INT NOT NULL DEFAULT 0 COMMENT ''尾程订单命令乐观锁版本'' AFTER manual_node_override'));
+PREPARE ll_order_command_ddl FROM @ddl; EXECUTE ll_order_command_ddl; DEALLOCATE PREPARE ll_order_command_ddl;
 
 CREATE TABLE IF NOT EXISTS ll_order_detail (
   id BIGINT NOT NULL AUTO_INCREMENT COMMENT '订单明细主键',
@@ -177,6 +191,61 @@ CREATE TABLE IF NOT EXISTS ll_order_operation_log (
   KEY idx_ll_order_operation_customer_order(customer_id,order_id,created_at)
 ) ENGINE=InnoDB COMMENT='尾程订单操作记录';
 
+CREATE TABLE IF NOT EXISTS ll_order_command_record (
+  id BIGINT NOT NULL COMMENT '尾程订单命令幂等记录ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',
+  order_id BIGINT NOT NULL COMMENT '尾程订单ID', action VARCHAR(32) NOT NULL COMMENT '命令动作：MANUAL_PLAN、HOLD、MANUAL_NODES',
+  operator_id VARCHAR(128) NOT NULL COMMENT '平台操作人ID', idempotency_key VARCHAR(128) NOT NULL COMMENT '客户端幂等键',
+  request_hash VARCHAR(64) NOT NULL COMMENT '规范化请求SHA-256摘要', result_ref VARCHAR(128) NULL COMMENT '结果业务引用',
+  result_json LONGTEXT NOT NULL COMMENT '首次成功响应JSON快照', result_version INT NOT NULL COMMENT '命令成功后的订单版本',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '首次成功时间', PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_order_command_key(customer_id,order_id,action,operator_id,idempotency_key),
+  KEY idx_ll_order_command_history(customer_id,order_id,created_at)
+) ENGINE=InnoDB COMMENT='尾程订单写命令幂等与结果审计记录';
+
+CREATE TABLE IF NOT EXISTS ll_order_hold_history (
+  id BIGINT NOT NULL COMMENT '尾程订单暂扣历史ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',
+  order_id BIGINT NOT NULL COMMENT '尾程订单ID', held TINYINT NOT NULL COMMENT '操作后是否暂扣：0否1是',
+  chargeable TINYINT NOT NULL COMMENT '本次暂扣是否计费：0否1是', reason VARCHAR(500) NOT NULL COMMENT '暂扣或解除原因',
+  order_version INT NOT NULL COMMENT '操作成功后的订单版本', operator_id VARCHAR(128) NOT NULL COMMENT '操作人ID',
+  operator_name VARCHAR(128) NOT NULL COMMENT '操作人名称', idempotency_key VARCHAR(128) NOT NULL COMMENT '客户端幂等键',
+  created_at DATETIME(3) NOT NULL COMMENT '操作时间', PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_order_hold_key(customer_id,order_id,operator_id,idempotency_key),
+  KEY idx_ll_order_hold_history(customer_id,order_id,created_at)
+) ENGINE=InnoDB COMMENT='尾程订单暂扣与解除不可变历史';
+
+CREATE TABLE IF NOT EXISTS ll_order_manual_node (
+  id BIGINT NOT NULL COMMENT '尾程订单人工节点ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',
+  order_id BIGINT NOT NULL COMMENT '尾程订单ID', node_code VARCHAR(32) NOT NULL COMMENT '八行人工展示节点稳定代码，与Carrier标准节点隔离',
+  node_at DATETIME(3) NULL COMMENT '人工填写节点时间，允许为空', source VARCHAR(16) NOT NULL DEFAULT 'MANUAL' COMMENT '节点来源，固定MANUAL',
+  order_version INT NOT NULL COMMENT '最近编辑后的订单版本', updated_by VARCHAR(128) NOT NULL COMMENT '最近操作人ID',
+  updated_at DATETIME(3) NOT NULL COMMENT '最近编辑时间', PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_order_manual_node(customer_id,order_id,node_code), KEY idx_ll_order_manual_node_order(customer_id,order_id,node_at)
+) ENGINE=InnoDB COMMENT='尾程订单当前人工节点覆盖事实';
+
+CREATE TABLE IF NOT EXISTS ll_order_manual_node_history (
+  id BIGINT NOT NULL COMMENT '尾程订单人工节点历史ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',
+  order_id BIGINT NOT NULL COMMENT '尾程订单ID', nodes_json LONGTEXT NOT NULL COMMENT '本次全量人工节点JSON快照',
+  order_version INT NOT NULL COMMENT '操作成功后的订单版本', operator_id VARCHAR(128) NOT NULL COMMENT '操作人ID',
+  operator_name VARCHAR(128) NOT NULL COMMENT '操作人名称', idempotency_key VARCHAR(128) NOT NULL COMMENT '客户端幂等键',
+  created_at DATETIME(3) NOT NULL COMMENT '操作时间', PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_order_manual_node_history_key(customer_id,order_id,operator_id,idempotency_key),
+  KEY idx_ll_order_manual_node_history(customer_id,order_id,created_at)
+) ENGINE=InnoDB COMMENT='尾程订单人工节点覆盖不可变历史';
+
+CREATE TABLE IF NOT EXISTS ll_receiving_warehouse_operation (
+  id BIGINT NOT NULL COMMENT '柜级接柜仓修改操作ID',
+  source_container_booking_id VARCHAR(128) NOT NULL COMMENT '稳定来源柜预订ID',
+  idempotency_key VARCHAR(255) NOT NULL COMMENT '平台请求幂等键',
+  request_hash VARCHAR(64) NOT NULL COMMENT '规范化修改请求SHA-256摘要',
+  result_version INT NOT NULL COMMENT '修改成功后的柜级分配版本',
+  operator_name VARCHAR(128) NOT NULL COMMENT '平台操作人名称',
+  remark VARCHAR(500) NULL COMMENT '接柜仓修改备注',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '操作时间',
+  PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_receiving_warehouse_idempotency(idempotency_key),
+  KEY idx_ll_receiving_warehouse_container(source_container_booking_id,created_at)
+) ENGINE=InnoDB COMMENT='柜级海外接柜仓修改幂等审计记录';
+
 -- 派送单列表与详情快照、转派送费用及操作记录。
 CREATE TABLE IF NOT EXISTS ll_delivery_order (
   id BIGINT NOT NULL COMMENT '派送单主键ID',
@@ -213,6 +282,7 @@ CREATE TABLE IF NOT EXISTS ll_delivery_order (
   remark VARCHAR(1000) NULL COMMENT '派送备注',
   idempotency_key VARCHAR(255) NOT NULL COMMENT '业务幂等键',
   created_by VARCHAR(128) NULL COMMENT '创建人ID',
+  version BIGINT NOT NULL DEFAULT 0 COMMENT '派送单乐观锁版本',
   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 '更新时间',
   PRIMARY KEY (id),
@@ -349,7 +419,7 @@ ALTER TABLE ll_order
   MODIFY COLUMN order_no VARCHAR(32) NOT NULL COMMENT '尾程单号',
   MODIFY COLUMN customer_id VARCHAR(128) NOT NULL COMMENT '租户/客户账号标识',
   MODIFY COLUMN order_type VARCHAR(32) NOT NULL DEFAULT 'FIRST_LEG' COMMENT '订单类型',
-  MODIFY COLUMN inbound_code VARCHAR(128) NOT NULL COMMENT '入仓码',
+  MODIFY COLUMN inbound_code VARCHAR(128) NULL COMMENT '真实来源入仓码；无入仓关系的海外本土业务为空',
   MODIFY COLUMN source_region VARCHAR(32) NOT NULL COMMENT '来源区域/系统',
   MODIFY COLUMN source_inbound_id VARCHAR(128) NOT NULL COMMENT '最终实装 LOADED 分片 ID，建单幂等键',
   MODIFY COLUMN root_inbound_id VARCHAR(128) NULL COMMENT '根入仓单 ID',
@@ -357,8 +427,10 @@ ALTER TABLE ll_order
   MODIFY COLUMN source_order_no VARCHAR(128) NULL COMMENT '来源订单号',
   MODIFY COLUMN root_order_id VARCHAR(128) NULL COMMENT '根订单 ID',
   MODIFY COLUMN customer_name VARCHAR(255) NULL COMMENT '货主名称',
-  MODIFY COLUMN overseas_warehouse_id VARCHAR(128) NULL COMMENT '海外仓 ID',
-  MODIFY COLUMN overseas_warehouse_name VARCHAR(255) NULL COMMENT '海外仓名称',
+  MODIFY COLUMN overseas_warehouse_id VARCHAR(128) NOT NULL DEFAULT '193000000000200003' COMMENT '海外接柜仓ID，新产生普通尾程整柜默认洛杉矶仓',
+  MODIFY COLUMN overseas_warehouse_code VARCHAR(128) NOT NULL DEFAULT 'US-LAX-01' COMMENT '海外接柜仓业务编码快照',
+  MODIFY COLUMN overseas_warehouse_name VARCHAR(255) NOT NULL DEFAULT '洛杉矶仓' COMMENT '海外接柜仓名称快照',
+  MODIFY COLUMN receiving_warehouse_version INT NOT NULL DEFAULT 0 COMMENT '柜级接柜仓分配乐观锁版本',
   MODIFY COLUMN fba_warehouse_code VARCHAR(128) NULL COMMENT 'FBA 仓库编码',
   MODIFY COLUMN container_no VARCHAR(64) NULL COMMENT '集装箱号',
   MODIFY COLUMN container_status VARCHAR(32) NULL DEFAULT '待转柜' COMMENT '货柜状态',
@@ -485,7 +557,14 @@ CREATE TABLE IF NOT EXISTS ll_inbound_plan (
   customer_id VARCHAR(128) NOT NULL COMMENT '租户/客户账号标识',
   source_order_id BIGINT NOT NULL COMMENT '来源尾程订单ID，一张入仓单对应一张入库计划',
   container_no VARCHAR(64) NOT NULL COMMENT '集装箱号',
-  overseas_warehouse_id BIGINT NULL COMMENT '海外实际收货共享物理仓ID，由PDA认领柜号时冻结',
+  overseas_warehouse_id BIGINT NOT NULL DEFAULT 193000000000200003 COMMENT '平台预分配的海外实际收货共享物理仓ID',
+  planned_arrival_date DATE NULL COMMENT '人工计划预计到仓日期',
+  pallet_type VARCHAR(32) NULL COMMENT '人工计划托盘类型',
+  assigned_flag TINYINT NOT NULL DEFAULT 0 COMMENT '人工计划是否已分配：0否1是',
+  merge_required TINYINT NOT NULL DEFAULT 0 COMMENT '人工计划是否要求合托：0否1是',
+  urgent_flag TINYINT NOT NULL DEFAULT 0 COMMENT '人工计划是否加急：0否1是',
+  creation_mode VARCHAR(16) NOT NULL DEFAULT 'AUTO' COMMENT '计划生成方式：AUTO柜级自动、MANUAL单票人工',
+  plan_remark VARCHAR(1000) NULL COMMENT '入仓计划备注',
   status VARCHAR(32) NOT NULL DEFAULT 'PLANNED' COMMENT '入库计划状态',
   line_count INT NOT NULL DEFAULT 0 COMMENT '入仓码明细数量',
   pallet_count INT NOT NULL DEFAULT 0 COMMENT '系统自动分配托盘数量',
@@ -537,7 +616,9 @@ CREATE TABLE IF NOT EXISTS ll_inbound_plan_pallet (
   id BIGINT NOT NULL COMMENT '计划托盘ID（雪花ID）',
   customer_id VARCHAR(128) NOT NULL COMMENT '客户账号标识',
   plan_id BIGINT NOT NULL COMMENT '入库计划ID',
-  pallet_no VARCHAR(64) NOT NULL COMMENT '计划托盘编号',
+  pallet_no VARCHAR(64) NOT NULL COMMENT '当前托盘编号：分配前为计划占位码，分配后为海外仓实物托盘码',
+  source_pallet_no VARCHAR(128) NULL COMMENT '一件代发不可变来源托盘号快照',
+  pallet_type VARCHAR(32) NULL COMMENT '人工计划托盘类型',
   destination_warehouse_id VARCHAR(128) NULL COMMENT '目的仓ID快照',
   destination_warehouse_code VARCHAR(128) NULL COMMENT '目的仓编码快照',
   destination_warehouse_name VARCHAR(255) NULL COMMENT '目的仓名称快照',
@@ -569,6 +650,20 @@ CREATE TABLE IF NOT EXISTS ll_inbound_plan_pallet_allocation (
 ALTER TABLE ll_inbound_plan COMMENT='尾程入库计划表：每张来源入仓单生成一张入库计划，同柜计划共享集装箱号';
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='source_order_id'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN source_order_id BIGINT NOT NULL DEFAULT 0 COMMENT ''来源尾程订单ID，一张入仓单对应一张入库计划'' AFTER customer_id'));
 PREPARE inbound_plan_source_order_stmt FROM @ddl; EXECUTE inbound_plan_source_order_stmt; DEALLOCATE PREPARE inbound_plan_source_order_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='planned_arrival_date'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN planned_arrival_date DATE NULL COMMENT ''人工计划预计到仓日期'' AFTER overseas_warehouse_id'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='pallet_type'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN pallet_type VARCHAR(32) NULL COMMENT ''人工计划托盘类型'' AFTER planned_arrival_date'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='assigned_flag'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN assigned_flag TINYINT NOT NULL DEFAULT 0 COMMENT ''人工计划是否已分配：0否1是'' AFTER pallet_type'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='merge_required'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN merge_required TINYINT NOT NULL DEFAULT 0 COMMENT ''人工计划是否要求合托：0否1是'' AFTER assigned_flag'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='urgent_flag'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN urgent_flag TINYINT NOT NULL DEFAULT 0 COMMENT ''人工计划是否加急：0否1是'' AFTER merge_required'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='creation_mode'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN creation_mode VARCHAR(16) NOT NULL DEFAULT ''AUTO'' COMMENT ''计划生成方式：AUTO柜级自动、MANUAL单票人工'' AFTER urgent_flag'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan' AND column_name='plan_remark'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan ADD COLUMN plan_remark VARCHAR(1000) NULL COMMENT ''入仓计划备注'' AFTER creation_mode'));
+PREPARE inbound_plan_manual_stmt FROM @ddl; EXECUTE inbound_plan_manual_stmt; DEALLOCATE PREPARE inbound_plan_manual_stmt;
 ALTER TABLE ll_inbound_plan
   MODIFY COLUMN id BIGINT NOT NULL COMMENT '入库计划ID（雪花ID）',
   MODIFY COLUMN plan_no VARCHAR(32) NOT NULL COMMENT '入库单号',
@@ -599,7 +694,7 @@ ALTER TABLE ll_inbound_plan_pallet COMMENT='尾程入库计划托盘表：按目
 ALTER TABLE ll_inbound_plan_pallet
   MODIFY COLUMN id BIGINT NOT NULL COMMENT '计划托盘ID（雪花ID）',
   MODIFY COLUMN plan_id BIGINT NOT NULL COMMENT '入库计划ID',
-  MODIFY COLUMN pallet_no VARCHAR(64) NOT NULL COMMENT '计划托盘编号',
+  MODIFY COLUMN pallet_no VARCHAR(64) NOT NULL COMMENT '当前托盘编号：分配前为计划占位码，分配后为海外仓实物托盘码',
   MODIFY COLUMN destination_warehouse_id VARCHAR(128) NULL COMMENT '目的仓ID快照',
   MODIFY COLUMN destination_warehouse_code VARCHAR(128) NULL COMMENT '目的仓编码快照',
   MODIFY COLUMN destination_warehouse_name VARCHAR(255) NULL COMMENT '目的仓名称快照',
@@ -621,6 +716,8 @@ SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE tab
 PREPARE inbound_schema_stmt FROM @ddl; EXECUTE inbound_schema_stmt; DEALLOCATE PREPARE inbound_schema_stmt;
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan_pallet' AND column_name='warehouse_pallet_id'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan_pallet ADD COLUMN warehouse_pallet_id BIGINT NULL COMMENT ''海外仓实物托盘ID'''));
 PREPARE inbound_schema_stmt FROM @ddl; EXECUTE inbound_schema_stmt; DEALLOCATE PREPARE inbound_schema_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan_pallet' AND column_name='pallet_type'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan_pallet ADD COLUMN pallet_type VARCHAR(32) NULL COMMENT ''人工计划托盘类型'' AFTER pallet_no'));
+PREPARE inbound_schema_stmt FROM @ddl; EXECUTE inbound_schema_stmt; DEALLOCATE PREPARE inbound_schema_stmt;
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan_pallet' AND column_name='warehouse_location_id'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan_pallet ADD COLUMN warehouse_location_id BIGINT NULL COMMENT ''海外仓库位ID'''));
 PREPARE inbound_schema_stmt FROM @ddl; EXECUTE inbound_schema_stmt; DEALLOCATE PREPARE inbound_schema_stmt;
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_inbound_plan_pallet' AND column_name='warehouse_resource_lock_id'), 'SELECT 1', 'ALTER TABLE ll_inbound_plan_pallet ADD COLUMN warehouse_resource_lock_id BIGINT NULL COMMENT ''海外仓资源锁ID'''));
@@ -851,7 +948,7 @@ WHERE (l.fba_warehouse_code IS NULL AND o.fba_warehouse_code IS NOT NULL)
 CREATE TABLE IF NOT EXISTS ll_receiving_container_session (
   id BIGINT NOT NULL COMMENT '柜号签收会话ID', customer_id VARCHAR(128) NOT NULL COMMENT '所选柜解析出的客户标识',
   source_container_booking_id VARCHAR(128) NOT NULL COMMENT '稳定来源柜预订ID', container_fact_hash VARCHAR(64) NOT NULL COMMENT '领取时整柜订单与计划事实摘要',
-  container_no VARCHAR(64) NOT NULL COMMENT '集装箱号', overseas_warehouse_id BIGINT NOT NULL COMMENT '操作员Token绑定并冻结的海外实际收货共享物理仓ID', overseas_warehouse_name VARCHAR(255) NOT NULL COMMENT '仓库服务校验后的海外实际收货共享物理仓名称快照', operator_key VARCHAR(128) NOT NULL COMMENT '操作账号唯一标识',
+  container_no VARCHAR(64) NOT NULL COMMENT '集装箱号', overseas_warehouse_id BIGINT NOT NULL COMMENT '平台预分配并由操作员Token匹配的海外接柜仓ID', overseas_warehouse_code VARCHAR(128) NOT NULL COMMENT '海外接柜仓业务编码快照', overseas_warehouse_name VARCHAR(255) NOT NULL COMMENT '仓库服务校验后的海外接柜仓名称快照', operator_key VARCHAR(128) NOT NULL COMMENT '操作账号唯一标识',
   operator_name VARCHAR(255) NULL COMMENT '操作账号名称', active_operator_key VARCHAR(255) NULL COMMENT '未完成会话平台操作账号全局唯一锁键',
   active_container_key VARCHAR(255) NULL COMMENT '未完成会话柜号全局唯一锁键', status VARCHAR(32) NOT NULL DEFAULT 'WAIT_SIGN' COMMENT '会话状态：WAIT_SIGN、SIGNED、RECEIVING、COMPLETED',
   sign_photos JSON NULL COMMENT '签收卸柜照片角色与文件ID列表', prepared_at DATETIME(3) NULL COMMENT '选择柜号时间',
@@ -1087,7 +1184,8 @@ CREATE TABLE IF NOT EXISTS ll_inbound_stock_receipt (
   line_id BIGINT NOT NULL COMMENT '入仓计划明细ID', order_id BIGINT NOT NULL COMMENT '订单ID', inbound_code VARCHAR(128) NOT NULL COMMENT '入仓单号快照',
   sku_code VARCHAR(128) NOT NULL COMMENT 'SKU编码快照', product_name_zh VARCHAR(255) NULL COMMENT '中文品名快照',
   product_name_en VARCHAR(255) NULL COMMENT '英文品名快照',
-  warehouse_pallet_id BIGINT NOT NULL COMMENT '仓库实物托盘ID', pallet_no VARCHAR(64) NOT NULL COMMENT '托盘号',
+  warehouse_pallet_id BIGINT NOT NULL COMMENT '仓库实物托盘ID', pallet_no VARCHAR(64) NOT NULL COMMENT '海外仓实物托盘码',
+  source_pallet_no VARCHAR(128) NULL COMMENT '一件代发不可变来源托盘号快照',
   warehouse_location_id BIGINT NULL COMMENT '仓库库位ID', warehouse_location_code VARCHAR(128) NULL COMMENT '仓库库位编码',
   batch_no VARCHAR(128) NOT NULL COMMENT '库存批次号', received_packages BIGINT NOT NULL COMMENT '实收箱数',
   inventory_balance_id BIGINT NOT NULL COMMENT '库存余额记录ID', inventory_position_id BIGINT NOT NULL COMMENT '库存仓位记录ID',
@@ -1484,6 +1582,12 @@ CREATE TABLE IF NOT EXISTS ll_relabel_item (
   KEY idx_ll_relabel_item_source_position (customer_id,source_inventory_position_id)
 ) ENGINE=InnoDB COMMENT='换标货物冻结明细';
 
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_relabel_item' AND column_name='remark'), 'SELECT 1', 'ALTER TABLE ll_relabel_item ADD COLUMN remark VARCHAR(1000) NULL COMMENT ''货物明细备注'' AFTER label_requirement')); PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_relabel_item' AND column_name='carton_mark'), 'SELECT 1', 'ALTER TABLE ll_relabel_item ADD COLUMN carton_mark VARCHAR(255) NULL COMMENT ''客户自有箱唛'' AFTER relabel_file_url')); PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_relabel_item' AND column_name='fba_carton_mark'), 'SELECT 1', 'ALTER TABLE ll_relabel_item ADD COLUMN fba_carton_mark VARCHAR(255) NULL COMMENT ''关联FBA箱唛'' AFTER carton_mark')); PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_relabel_item' AND column_name='destination_warehouse_id'), 'SELECT 1', 'ALTER TABLE ll_relabel_item ADD COLUMN destination_warehouse_id VARCHAR(128) NULL COMMENT ''该箱目的海外仓ID'' AFTER fba_carton_mark')); PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='ll_relabel_item' AND index_name='idx_ll_relabel_item_destination'), 'SELECT 1', 'ALTER TABLE ll_relabel_item ADD KEY idx_ll_relabel_item_destination (customer_id,destination_warehouse_id,application_id)')); PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt;
+
 CREATE TABLE IF NOT EXISTS ll_relabel_status_history (
   id BIGINT NOT NULL COMMENT '主键ID',
   customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
@@ -1827,9 +1931,12 @@ CREATE TABLE IF NOT EXISTS ll_exception_order (
   delivery_order_id BIGINT NULL COMMENT '关联派送单ID', delivery_no VARCHAR(64) NULL COMMENT '关联派送单号', outbound_no VARCHAR(64) NULL COMMENT '关联出库单号',
   customer_name VARCHAR(255) NULL COMMENT '客户名称快照', overseas_warehouse_id VARCHAR(128) NULL COMMENT '海外仓ID快照', overseas_warehouse_name VARCHAR(255) NULL COMMENT '海外仓名称快照',
   sku_code VARCHAR(128) NULL COMMENT '异常货物SKU', package_count INT NULL COMMENT '异常箱数', return_direction VARCHAR(32) NULL COMMENT '退回方向', return_logistics_no VARCHAR(128) NULL COMMENT '退回物流单号',
-  handling_action VARCHAR(500) NULL COMMENT '异常处理措施', handler_id VARCHAR(128) NULL COMMENT '处理人ID', handler_name VARCHAR(128) NULL COMMENT '处理人名称',
+  handling_action VARCHAR(500) NULL COMMENT '异常处理措施', handling_result VARCHAR(2000) NULL COMMENT '异常处理结果',
+  evidence_file_ids_json JSON NULL COMMENT '异常处理证据文件ID列表', inventory_adjustment_id BIGINT NULL COMMENT '退回库存恢复操作ID',
+  handler_id VARCHAR(128) NULL COMMENT '处理人ID', handler_name VARCHAR(128) NULL COMMENT '处理人名称',
   source_type VARCHAR(32) NOT NULL DEFAULT 'MANUAL' COMMENT '异常来源类型', created_by VARCHAR(128) NULL COMMENT '创建人ID',
-  exception_at DATETIME(3) NOT NULL COMMENT '异常发生时间', created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  exception_at DATETIME(3) NOT NULL COMMENT '异常发生时间', completed_at DATETIME(3) NULL COMMENT '异常处理完成时间',
+  version BIGINT NOT NULL DEFAULT 0 COMMENT '异常订单乐观锁版本', 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 '更新时间',
   PRIMARY KEY(id), UNIQUE KEY uk_ll_exception_no(customer_id,exception_no),
   UNIQUE KEY uk_ll_exception_delivery_return(customer_id,delivery_order_id,exception_type),
@@ -1837,6 +1944,25 @@ CREATE TABLE IF NOT EXISTS ll_exception_order (
   KEY idx_ll_exception_inbound(customer_id,inbound_code)
 ) ENGINE=InnoDB COMMENT='海外仓异常订单';
 
+CREATE TABLE IF NOT EXISTS ll_exception_return_item (
+  id BIGINT NOT NULL COMMENT '异常退回明细ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',
+  exception_order_id BIGINT NOT NULL COMMENT '异常订单ID', outbound_pallet_item_id BIGINT NOT NULL COMMENT '原出库托盘明细ID',
+  inventory_position_id BIGINT NOT NULL COMMENT '原出库库存位置ID', pallet_no VARCHAR(128) NULL COMMENT '原出库托盘码快照',
+  sku_code VARCHAR(128) NULL COMMENT '原出库SKU快照', max_return_packages BIGINT NOT NULL COMMENT '原出库可退箱数上限',
+  approved_return_packages BIGINT NOT NULL COMMENT '批准退回箱数', created_at DATETIME(3) NOT NULL COMMENT '创建时间',
+  PRIMARY KEY(id), UNIQUE KEY uk_ll_exception_return_source(customer_id,exception_order_id,outbound_pallet_item_id,inventory_position_id),
+  KEY idx_ll_exception_return_order(customer_id,exception_order_id)
+) ENGINE=InnoDB COMMENT='异常退回原出库库存冻结明细';
+
+CREATE TABLE IF NOT EXISTS ll_exception_order_command (
+  id BIGINT NOT NULL COMMENT '异常处理命令ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',
+  exception_order_id BIGINT NOT NULL COMMENT '异常订单ID', action VARCHAR(32) NOT NULL COMMENT '异常处理动作',
+  idempotency_key VARCHAR(255) NOT NULL COMMENT '幂等键', request_hash VARCHAR(64) NOT NULL COMMENT '请求内容SHA256哈希',
+  result_json JSON NOT NULL COMMENT '命令结果快照', created_at DATETIME(3) NOT NULL COMMENT '创建时间',
+  PRIMARY KEY(id), UNIQUE KEY uk_ll_exception_command_key(customer_id,action,idempotency_key),
+  KEY idx_ll_exception_command_order(customer_id,exception_order_id,created_at)
+) ENGINE=InnoDB COMMENT='异常处理命令幂等审计';
+
 CREATE TABLE IF NOT EXISTS ll_customer_visit (
   id BIGINT NOT NULL COMMENT '客户回访记录ID',
   customer_id VARCHAR(128) NOT NULL COMMENT '客户数据隔离键',

lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml

@@ -3,6 +3,18 @@ info:
   title: Lastleg Overseas Business API
   version: 1.0.0
 paths:
+  /api/platform/v1/last-leg/inventory/balances/{balanceId}:
+    get:
+      summary: 查询单条库存余额详情
+      description: 仅平台且要求 lastleg:inventory:list；按 balanceId 直接查询非零库存余额，不依赖列表分页。可选 customerId 用于精确客户隔离，越权或不存在统一返回404。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { in: path, name: balanceId, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$', description: 长整型ID按字符串传输 } }
+        - { in: query, name: customerId, required: false, schema: { type: string } }
+      responses:
+        '200': { description: 单条库存余额, content: { application/json: { schema: { $ref: '#/components/schemas/InventoryBalanceApiResponse' } } } }
+        '403': { description: 非平台身份或缺少库存查看权限 }
+        '404': { description: 库存余额不存在、已归零或不属于指定客户 }
   /api/platform/v1/last-leg/inventory/inbound-code-relationships/{inboundCode}:
     get:
       summary: 按入仓码查询海外关系摘要
@@ -149,7 +161,7 @@ paths:
   /api/platform/v1/last-leg/orders:
     get:
       summary: 分页查询尾程订单
-      description: 权限 platform:overseas-warehouse:order:list；平台管理员省略 customerId 时查询全部客户。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；平台管理员省略 customerId 时查询全部客户。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -160,13 +172,13 @@ paths:
         - { name: inboundCode, in: query, schema: { type: string } }
         - { name: sourceOrderNo, in: query, schema: { type: string } }
         - { name: containerNo, in: query, schema: { type: string } }
-        - { name: warehouse, in: query, schema: { type: string } }
+        - { name: warehouse, in: query, description: 按尾程订单冻结的海外接柜仓名称或编码进行大小写无关的包含匹配, schema: { type: string } }
         - { name: transferWarehouseCode, in: query, schema: { type: string } }
         - { name: abnormal, in: query, schema: { type: boolean } }
         - { name: detained, in: query, schema: { type: boolean } }
         - { name: createdFrom, in: query, schema: { type: string, format: date-time } }
         - { name: createdTo, in: query, schema: { type: string, format: date-time } }
-      responses: { '200': { description: 统一 ApiResponse 包装的尾程订单分页；列表行 destinationType 为 FBA 或 OVERSEAS } }
+      responses: { '200': { description: 统一 ApiResponse 包装的尾程订单分页；列表行 destinationType 为 FBA 或 OVERSEAS；inboundCode 仅返回真实来源入仓码，无入仓关系的换标申请和本土散板为空 } }
   /api/platform/v1/last-leg/orders/{id}:
     get:
       summary: 查询尾程订单详情
@@ -192,25 +204,46 @@ paths:
       responses:
         '200': { description: 新增后的费用明细, content: { application/json: { schema: { $ref: '#/components/schemas/LastMileFeeApiResponse' } } } }
         '404': { description: 尾程订单不存在或不属于操作客户 }
-  /api/platform/v1/last-leg/orders/{id}/detained:
+  /api/platform/v1/last-leg/orders/{id}/hold:
     put:
       summary: 设置或解除尾程订单暂扣
-      description: 权限 platform:overseas-warehouse:last-mile-order:edit；库存同步转入或释放暂扣，并通过跨区事件回写国内入仓单。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；使用订单版本和 Idempotency-Key 原子写入计费标记、原因及不可变历史。已进入出库流程的订单不得新增暂扣；暂扣只作用于当前票，不影响同柜其他订单。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
         - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
       requestBody:
         required: true
         content:
           application/json:
-            schema:
-              type: object
-              required: [detained, remark]
-              properties:
-                detained: { type: boolean }
-                remark: { type: string, minLength: 1, maxLength: 500 }
-      responses: { '200': { description: 暂扣状态已更新 } }
+            schema: { $ref: '#/components/schemas/LastlegOrderHoldRequest' }
+      responses:
+        '200': { description: 暂扣状态已更新, content: { application/json: { schema: { type: object, properties: { code: { type: string }, data: { $ref: '#/components/schemas/LastlegOrderHoldResponse' } } } } } }
+        '409': { description: 版本冲突、幂等键冲突、重复状态或订单已进入出库流程 }
+  /api/platform/v1/last-leg/orders/{id}/manual-nodes:
+    get:
+      summary: 查询尾程订单人工展示节点
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；人工覆盖开启后返回完整且固定顺序的8行快照，行值允许为空。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses: { '200': { description: 完整人工展示节点快照 } }
+    put:
+      summary: 永久启用并保存尾程订单人工展示节点
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；提交完整8行快照且至少一个时间非空，使用订单版本和 Idempotency-Key；保存后 nodeSource 永久为 MANUAL，不回写柜节点，也不提供清除或恢复继承接口。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/LastlegOrderManualNodesRequest' } } }
+      responses:
+        '200': { description: 更新后的完整8行人工展示节点快照 }
+        '409': { description: 订单版本或幂等键冲突 }
   /api/platform/v1/last-leg/orders/{id}/pallet-merge-required:
     put:
       summary: 设置尾程订单合托标记
@@ -253,7 +286,7 @@ paths:
   /api/platform/v1/last-leg/orders/container-summaries:
     get:
       summary: 分页查询柜级入库计划进度
-      description: 权限 platform:overseas-warehouse:order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响，仅返回仍有入仓码待生成有效独立计划的柜，全部入仓码均已生成有效独立计划的柜在分页前排除。containerNo 只返回装柜完成事件携带并规范化冻结的真实集装箱号，不从 cabinetNo、订单号或内部 ID 推导。plannedArrivalAt 仅来自装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at；按该时间升序、null 最后、稳定柜 ID 升序。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响，返回全部稳定来源柜；全部入仓码均已生成有效独立计划的柜仍保留，供柜级接柜仓查询与修改，生成计划动作由 allPlansReady/pendingPlanCount 控制。containerNo 只返回装柜完成事件携带并规范化冻结的真实集装箱号，不从 cabinetNo、订单号或内部 ID 推导。plannedArrivalAt 仅来自装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at；按该时间升序、null 最后、稳定柜 ID 升序。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -283,7 +316,7 @@ paths:
   /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}:
     get:
       summary: 查询柜级入库计划进度详情
-      description: 权限 platform:overseas-warehouse:order:list；按稳定柜 ID 返回柜内全部尾程订单、入仓码及各自计划状态，不受订单分页截断。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；按稳定柜 ID 返回柜内全部尾程订单、入仓码及各自计划状态，不受订单分页截断。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
@@ -298,10 +331,27 @@ paths:
                   code: { type: string, enum: ['200'] }
                   data: { $ref: '#/components/schemas/ContainerPlanProgressDetail' }
         '404': { description: 稳定柜 ID 不存在 }
+  /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}/receiving-warehouse:
+    put:
+      summary: 修改整柜海外接柜仓
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；目标必须为国内 Warehouse Service 有效 OVERSEAS 仓。使用柜级版本和 Idempotency-Key，事务内原子同步柜内全部尾程订单及已有入库计划；海外PDA一旦建立接柜会话即永久锁定。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ChangeReceivingWarehouseRequest' }
+      responses:
+        '200': { description: 更新后的柜级摘要, content: { application/json: { schema: { type: object, properties: { code: { type: string, enum: ['200'] }, data: { $ref: '#/components/schemas/ContainerPlanProgressSummary' } } } } }
+        '400': { description: 请求无效或目标不是有效 OVERSEAS 仓 }
+        '409': { description: 版本冲突、幂等键冲突或PDA接柜会话已建立 }
   /api/platform/v1/last-leg/orders/{id}/destination:
     put:
       summary: 将单票尾程订单转入 FBA 目的仓
-      description: 权限 platform:overseas-warehouse:order:edit；目标必须来自国内 Warehouse Service 平台公共 ACTIVE FBA 主档，warehouseId/warehouseCode/warehouseName 必须与权威记录一致。实际海外收货仓、普通国内中转仓、停用仓或伪造字段均返回 A0400“所选FBA仓不存在或已停用”。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；目标必须来自国内 Warehouse Service 平台公共 ACTIVE FBA 主档，warehouseId/warehouseCode/warehouseName 必须与权威记录一致。实际海外收货仓、普通国内中转仓、停用仓或伪造字段均返回 A0400“所选FBA仓不存在或已停用”。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
@@ -318,7 +368,7 @@ paths:
   /api/platform/v1/last-leg/orders/destination:
     put:
       summary: 批量将尾程订单转入 FBA 目的仓
-      description: 权限 platform:overseas-warehouse:order:edit；一次校验国内 Warehouse Service 权威 FBA 主档后，在 Lastleg 事务内更新所选订单及冻结明细。目标仓必须为平台公共 ACTIVE FBA 且 ID/编码/名称完全一致。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；一次校验国内 Warehouse Service 权威 FBA 主档后，在 Lastleg 事务内更新所选订单及冻结明细。目标仓必须为平台公共 ACTIVE FBA 且 ID/编码/名称完全一致。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
@@ -331,26 +381,59 @@ paths:
         '200': { description: 统一 ApiResponse 包装的更新订单数 }
         '400': { description: 所选FBA仓不存在、已停用、类型错误或字段不一致 }
         '503': { description: 国内FBA仓权威主数据暂不可用，写入失败关闭 }
-  /api/platform/v1/last-leg/inbound-plans/convert:
-    post:
-      summary: 平台生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；必须同时传入真实 customerId 与 orderId，服务端按该客户和订单 ID 锁定归属，缺失 customerId 返回 A0400。
+  /api/platform/v1/last-leg/inbound-plans:
+    get:
+      summary: 平台分页查询海外入库订单
+      description: 权限 platform:overseas-warehouse:inbound-order:list；列表中的 overseasWarehouseCode/overseasWarehouseName 只取尾程订单预分配接柜仓事实，warehouseCode/warehouseName 仍表示目的仓。
       security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
+        - { name: planNo, in: query, schema: { type: string } }
+        - { name: inboundCode, in: query, schema: { type: string } }
+        - { name: lxCode, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string } }
+        - { name: overseasWarehouseId, in: query, schema: { type: string } }
+        - { name: destinationWarehouseCode, in: query, schema: { type: string } }
+        - { name: warehouse, in: query, schema: { type: string } }
+        - { name: fbaWarehouseCode, in: query, schema: { type: string } }
+        - { name: appointmentStatus, in: query, schema: { type: string, enum: [UNAPPOINTED, PENDING, SUCCESS, FAILED, CANCELLED] } }
+        - { name: dispatchStatus, in: query, schema: { type: string, enum: [UNSCHEDULED, SCHEDULED] } }
+        - { name: createdFrom, in: query, schema: { type: string, format: date-time } }
+        - { name: createdTo, in: query, schema: { type: string, format: date-time } }
+      responses: { '200': { description: 平台入库订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanPageResponse' } } } } }
+  /api/platform/v1/last-leg/inbound-plans/{planNo}:
+    get:
+      summary: 平台查询海外入库订单详情
+      description: 权限 platform:overseas-warehouse:inbound-order:list；详情中的 overseasWarehouseCode/overseasWarehouseName 只取当前计划来源尾程订单的预分配接柜仓事实。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: planNo, in: path, required: true, schema: { type: string } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses:
+        '200': { description: 平台入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }
+        '404': { description: 入库订单不存在或不属于指定客户 }
+  /api/platform/v1/last-leg/inbound-plans/manual:
+    post:
+      summary: 平台按单票手工生成入库计划
+      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、暂扣状态、真实入仓码、客户归属及有效公共接柜仓。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
       requestBody:
         required: true
         content:
           application/json:
-            schema:
-              type: object
-              required: [customerId, orderId]
-              properties:
-                customerId: { type: string, pattern: '^[1-9][0-9]*$' }
-                orderId: { type: string, pattern: '^[1-9][0-9]*$' }
-      responses: { '200': { description: 统一 ApiResponse 包装的入库计划详情 } }
+            schema: { $ref: '#/components/schemas/ManualInboundPlanRequest' }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的入库计划详情 }
+        '400': { description: 客户、入仓码、仓库主数据或请求字段无效 }
+        '409': { description: 订单版本、状态、暂扣状态、重复计划或幂等键冲突 }
   /api/platform/v1/last-leg/inbound-plans/convert-container:
     post:
-      summary: 按整柜批量生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；使用稳定 sourceContainerBookingId 锁定整柜订单，并要求全柜尾程订单及既有计划的真实 containerNo 快照一致。每个尾程订单/入仓码独立生成一个入库计划，整批原子且幂等；任何柜号漂移均冲突且不部分写入。
+      summary: 按整柜批量生成剩余入库计划
+      description: 权限 platform:overseas-warehouse:inbound-order:create；使用稳定 sourceContainerBookingId 锁定整柜订单，并要求全柜尾程订单及既有有效计划的真实 containerNo 与接柜仓快照一致。已有有效计划保持不变，只为剩余尾程订单/入仓码分别生成独立计划；响应按柜内订单稳定顺序返回全部已有及新增计划。整批原子且幂等，剩余为0时直接返回已有结果；任何快照漂移均冲突且不部分写入。
       security: [{ bearerAuth: [] }]
       requestBody:
         required: true
@@ -508,13 +591,25 @@ paths:
       parameters: [{ name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/OneClickOutboundCreate' } } } }
       responses: { '200': { description: 一件代发出库 PDA 任务 }, '409': { description: 库存或幂等冲突 } }
+  /api/platform/v1/last-leg/outbound-orders/one-click-dropship/candidates:
+    get:
+      summary: 查询一件代发出库候选库存
+      description: 权限 platform:overseas-warehouse:outbound:create；按客户及可选海外仓一次查询服务端权威候选，仅返回 ACTIVE 一件代发档案、OCCUPIED 正可用库存、AVAILABLE 箱唛与 SKU 余额共同覆盖且未被排车、转仓或待执行出库占用的维度。创建命令会再次校验，不信任前端候选快照。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: warehouseId, in: query, required: false, schema: { type: string } }
+      responses:
+        '200':
+          description: 最多 500 条一件代发出库候选；单次 SQL 返回，不逐行补查
+          content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/OneClickOutboundCandidate' } } } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}:
     get:
       summary: 查询出库单详情
       description: 权限 platform:overseas-warehouse:outbound:list；只按全局唯一 outboundNo 定位并从记录解析客户范围，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: outboundNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: 出库单及关联派送单详情 }, '404': { description: 出库单不存在 } }
+      responses: { '200': { description: 出库单、出库托盘及关联派送单详情；pallets[].palletNo 为 Warehouse 权威实物托盘码 }, '404': { description: 出库单不存在 } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}/cancel:
     post:
       summary: 取消未执行出库单
@@ -526,13 +621,13 @@ paths:
   /api/platform/v1/last-leg/delivery-orders:
     get:
       summary: 分页查询平台派送单
-      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。
+      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。每行返回服务端计算的 allowedActions，页面不得自行推导状态门禁。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 派送单分页 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}:
     get:
       summary: 查询平台派送单详情
-      description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读。
+      description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读；order.allowedActions 为当前可执行动作。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 派送单详情 }, '404': { description: 派送单不存在 } }
@@ -548,6 +643,49 @@ paths:
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
       responses: { '200': { description: 已创建异常订单 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}:
+    get:
+      summary: 查询异常订单详情与冻结退回明细
+      description: 权限 platform:overseas-warehouse:exception-order:list；返回 version 和服务端 allowedActions。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 异常订单详情 }, '404': { description: 异常订单不存在 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/start-processing:
+    post:
+      summary: 开始处理异常订单
+      description: 权限 platform:overseas-warehouse:exception-order:process；仅 PENDING→PROCESSING，同版本与同幂等请求可重放。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExceptionStartProcessing' } } } }
+      responses: { '200': { description: 异常处理命令结果 }, '409': { description: 版本、状态或幂等冲突 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/evidence:
+    post:
+      summary: 上传异常处理证据
+      description: 权限 platform:overseas-warehouse:exception-order:process；文件按当前客户和异常订单绑定为 OVERSEAS_EXCEPTION_EVIDENCE。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } }
+      responses: { '200': { description: 异常处理证据元数据 }, '400': { description: 文件或归属无效 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/complete:
+    post:
+      summary: 完成异常处理并原子恢复退回库存
+      description: 权限 platform:overseas-warehouse:exception-order:process；仅 PROCESSING→COMPLETED。退回海外仓必须提交证据和实收目标，库存 RETURN_STOCK_IN 成功后才完成异常单和派送退回。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExceptionComplete' } } } }
+      responses: { '200': { description: 异常处理与库存恢复结果 }, '409': { description: 版本、状态、归属、数量或幂等冲突 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/cancel:
+    post:
+      summary: 取消未处理异常订单
+      description: 权限 platform:overseas-warehouse:exception-order:process；仅 PENDING→CANCELLED。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExceptionCancel' } } } }
+      responses: { '200': { description: 异常取消结果 }, '409': { description: 版本、状态或幂等冲突 } }
   /api/platform/v1/last-leg/exception-orders/resolve:
     get:
       summary: 解析异常订单关联关系
@@ -557,33 +695,34 @@ paths:
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/return-inbound-options:
     get:
       summary: 查询派送退回候选入仓单
-      description: 权限 platform:overseas-warehouse:exception-order:list；属于异常订单列表只读辅助接口。
+      description: 权限 platform:overseas-warehouse:exception-order:list；返回按原出库拣货事实解析的 returnSources，页面不得自由填写 SKU 或猜测库存位置。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 退回候选入仓单 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/mark-return:
     post:
       summary: 将派送单标记为退回入仓
-      description: 权限 platform:overseas-warehouse:delivery:return。
+      description: 权限 platform:overseas-warehouse:delivery:return；items 必须来自 return-inbound-options，服务端冻结源出库明细与批准退回上限。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryMarkReturn' } } } }
       responses: { '200': { description: 已创建退回异常单 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/complete:
     post:
       summary: 标记派送完成并生成回访记录
-      description: 权限 platform:overseas-warehouse:delivery:status。
+      description: 权限 platform:overseas-warehouse:delivery:status。仅 WAIT_DELIVERY/DELIVERING 可完成；DELIVERED 同状态重放成功，其他终态或倒退返回 409。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: 派送状态与回访记录 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
+      responses: { '200': { description: 派送状态与回访记录 }, '409': { description: 版本或状态冲突 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/status:
     put:
       summary: 更新派送状态
-      description: 权限 platform:overseas-warehouse:delivery:status。
+      description: 权限 platform:overseas-warehouse:delivery:status。只允许 WAIT_DELIVERY→DELIVERING/DELIVERED/REJECTED/CANCELLED、DELIVERING→DELIVERED/REJECTED；同状态幂等，终态不可倒退。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
-      responses: { '200': { description: 更新后的派送状态 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
+      responses: { '200': { description: 更新后的派送状态 }, '409': { description: 非法状态迁移 } }
   /api/platform/v1/last-leg/customer-visits:
     get:
       summary: 分页查询客户回访
@@ -811,7 +950,7 @@ paths:
   /api/merchant/v1/last-leg/inbound-plans:
     get:
       summary: 客户分页查询自己的海外入库订单
-      description: 权限 merchant:warehouse:inbound:list；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:warehouse:inbound:list；客户范围只取认证 Token，不接收 customerId；overseasWarehouseCode/overseasWarehouseName 只取该客户尾程订单预分配接柜仓事实，warehouseCode/warehouseName 仍表示目的仓。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -829,7 +968,7 @@ paths:
   /api/merchant/v1/last-leg/inbound-plans/{planNo}:
     get:
       summary: 客户查询自己的海外入库订单详情
-      description: 权限 merchant:warehouse:inbound:list；列表权限包含详情只读，不接收 customerId。
+      description: 权限 merchant:warehouse:inbound:list；列表权限包含详情只读，不接收 customerId；overseasWarehouseCode/overseasWarehouseName 只取该计划来源尾程订单的预分配接柜仓事实。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: planNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 当前客户入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }, '404': { description: 当前客户下入库订单不存在 } }
@@ -1186,6 +1325,39 @@ components:
         height: { type: number, exclusiveMinimum: 0, description: '箱高，CM' }
         weight: { type: number, exclusiveMinimum: 0, description: '箱重，KG' }
         idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+    InventoryBalance:
+      type: object
+      required: [id, customerId, totalPackages, availablePackages, holdPackages, allocatedPackages, pickedPackages, inTransitPackages, receivingPackages, procurementPackages]
+      properties:
+        id: { type: string, pattern: '^[1-9][0-9]*$', description: 库存余额长整型ID，按字符串传输 }
+        customerId: { type: string }
+        customerName: { type: string, nullable: true }
+        overseasWarehouseId: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, nullable: true }
+        overseasWarehouseName: { type: string, nullable: true }
+        destinationWarehouseId: { type: string, nullable: true }
+        destinationWarehouseCode: { type: string, nullable: true }
+        destinationWarehouseName: { type: string, nullable: true }
+        inboundOrderId: { type: string, nullable: true, pattern: '^[1-9][0-9]*$', description: 长整型ID按字符串传输 }
+        inboundOrderNo: { type: string, nullable: true }
+        inboundCode: { type: string, nullable: true }
+        skuCode: { type: string, nullable: true }
+        productNameZh: { type: string, nullable: true }
+        productNameEn: { type: string, nullable: true }
+        totalPackages: { type: integer, format: int64, minimum: 0 }
+        availablePackages: { type: integer, format: int64, minimum: 0 }
+        holdPackages: { type: integer, format: int64, minimum: 0 }
+        allocatedPackages: { type: integer, format: int64, minimum: 0 }
+        pickedPackages: { type: integer, format: int64, minimum: 0 }
+        inTransitPackages: { type: integer, format: int64, minimum: 0 }
+        receivingPackages: { type: integer, format: int64, minimum: 0 }
+        procurementPackages: { type: integer, format: int64, minimum: 0 }
+        updatedAt: { type: string, format: date-time, nullable: true }
+    InventoryBalanceApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/InventoryBalance' } }
     InboundCodeRelationship:
       type: object
       required: [inboundCode, found, taillegOrders, inboundPlans, palletCodes, inventory]
@@ -1259,10 +1431,16 @@ components:
               items: { type: string, pattern: '^[1-9][0-9]*$' }
     ContainerPlanProgressSummary:
       type: object
-      required: [sourceContainerBookingId, containerNo, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
+      required: [sourceContainerBookingId, containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, assignmentVersion, canChangeReceivingWarehouse, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
       properties:
         sourceContainerBookingId: { type: string }
         containerNo: { type: string, pattern: '^[A-Z]{3}[UJZ][0-9]{7}$', description: 装柜完成事件非空且通过 ISO 6346 校验位验证的规范化真实集装箱号；不使用 cabinetNo、订单号或内部 ID 回退 }
+        overseasWarehouseId: { type: string, pattern: '^[1-9][0-9]*$', description: 平台预分配的海外接柜仓ID，不是FBA目的仓 }
+        overseasWarehouseCode: { type: string, description: 海外接柜仓业务编码 }
+        overseasWarehouseName: { type: string, description: 海外接柜仓业务名称 }
+        assignmentVersion: { type: integer, minimum: 0, description: 柜级接柜仓乐观锁版本 }
+        canChangeReceivingWarehouse: { type: boolean }
+        receivingWarehouseLockReason: { type: string, nullable: true }
         totalOrderCount: { type: integer, format: int64 }
         inboundCodeCount: { type: integer, format: int64 }
         missingInboundCodeCount: { type: integer, format: int64 }
@@ -1272,6 +1450,13 @@ components:
         plannedArrivalAt: { type: string, format: date-time, nullable: true, description: 仅来源于装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at }
         allPlansReady: { type: boolean, description: 全柜每票均有入仓码且均存在有效独立计划时为 true }
         blockingReason: { type: string, nullable: true }
+    ChangeReceivingWarehouseRequest:
+      type: object
+      required: [overseasWarehouseId, expectedVersion]
+      properties:
+        overseasWarehouseId: { type: integer, format: int64, minimum: 1 }
+        expectedVersion: { type: integer, minimum: 0 }
+        remark: { type: string, maxLength: 500, nullable: true }
     ContainerPlanProgressDetail:
       type: object
       required: [summary, orders]
@@ -1495,10 +1680,12 @@ components:
         warehouseName: { type: string, description: 国内Warehouse Service主档维护的当前中文名称 }
     ReceivingCandidate:
       type: object
-      required: [sourceContainerBookingId, containerNo, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
+      required: [sourceContainerBookingId, containerNo, overseasWarehouseCode, overseasWarehouseName, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
       properties:
         sourceContainerBookingId: { type: string, description: 头程与尾程共享的稳定柜身份 }
         containerNo: { type: string }
+        overseasWarehouseCode: { type: string }
+        overseasWarehouseName: { type: string }
         status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
         totalOrderCount: { type: integer, minimum: 1 }
         missingInboundCodeCount: { type: integer, minimum: 0 }
@@ -1517,10 +1704,11 @@ components:
         currentAccount: { type: boolean }
     ReceivingSession:
       type: object
-      required: [containerNo, overseasWarehouseId, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, inbounds]
+      required: [containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, inbounds]
       properties:
         containerNo: { type: string }
-        overseasWarehouseId: { type: string, pattern: '^\d+$', description: PDA Token绑定并在认领柜号时冻结的共享实际海外收货仓ID }
+        overseasWarehouseId: { type: string, pattern: '^\d+$', description: 平台预分配并与PDA Token匹配的海外接柜仓ID }
+        overseasWarehouseCode: { type: string, description: 海外接柜仓业务编码快照 }
         overseasWarehouseName: { type: string, description: Warehouse Overseas服务校验后的共享实际海外收货仓名称快照 }
         status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
         operatorName: { type: string, nullable: true }
@@ -1637,7 +1825,7 @@ components:
         orderNo: { type: string }
         orderRefs: { type: string }
         inboundCode: { type: string }
-        palletNo: { type: string }
+        palletNo: { type: string, description: 未入库时为计划托盘码；绑定实物托盘后为 Warehouse 权威实物托盘码 }
         destinationWarehouseId: { type: string }
         destinationWarehouseCode: { type: string }
         destinationWarehouseName: { type: string }
@@ -1729,6 +1917,76 @@ components:
         sellerName: { type: string, nullable: true, maxLength: 128 }
         remark: { type: string, nullable: true, maxLength: 1000 }
         fees: { type: array, minItems: 1, maxItems: 20, items: { $ref: '#/components/schemas/DeliveryFeeInput' } }
+    DeliveryStatusChange:
+      type: object
+      required: [status, expectedVersion]
+      properties:
+        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, DELIVERED, REJECTED, CANCELLED] }
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        remark: { type: string, nullable: true, maxLength: 500 }
+    DeliveryAllowedAction:
+      type: string
+      enum: [START_DELIVERY, COMPLETE_DELIVERY, REJECT_DELIVERY, CANCEL_DELIVERY, MARK_RETURN]
+      description: START/COMPLETE/REJECT/CANCEL 使用通用 status 接口；MARK_RETURN 使用 mark-return 接口。
+    DeliveryMarkReturn:
+      type: object
+      required: [inboundOrderId, reason, returnDirection, items, idempotencyKey]
+      properties:
+        inboundOrderId: { type: string, pattern: '^[1-9][0-9]*$' }
+        reason: { type: string, minLength: 1, maxLength: 1000 }
+        returnDirection: { type: string, enum: [OVERSEAS_WAREHOUSE, CUSTOMER, OTHER] }
+        returnLogisticsNo: { type: string, nullable: true, maxLength: 128 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        items:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            type: object
+            required: [outboundPalletItemId, inventoryPositionId, packageCount]
+            properties:
+              outboundPalletItemId: { type: string, pattern: '^[1-9][0-9]*$' }
+              inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
+              packageCount: { type: integer, format: int64, minimum: 1 }
+    ExceptionStartProcessing:
+      type: object
+      required: [expectedVersion, idempotencyKey]
+      properties:
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        handlingAction: { type: string, nullable: true, maxLength: 1000 }
+    ExceptionCancel:
+      type: object
+      required: [expectedVersion, idempotencyKey, reason]
+      properties:
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        reason: { type: string, minLength: 1, maxLength: 1000 }
+    ExceptionComplete:
+      type: object
+      required: [expectedVersion, idempotencyKey, handlingResult, evidenceFileIds]
+      properties:
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        handlingResult: { type: string, minLength: 1, maxLength: 2000 }
+        evidenceFileIds: { type: array, minItems: 1, maxItems: 20, items: { type: string } }
+        receipts:
+          type: array
+          maxItems: 200
+          items:
+            type: object
+            required: [outboundPalletItemId, inventoryPositionId, receivedPackages, targetPalletId, targetPalletNo, targetLocationId, targetLocationCode]
+            properties:
+              outboundPalletItemId: { type: string, pattern: '^[1-9][0-9]*$' }
+              inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
+              receivedPackages: { type: integer, format: int64, minimum: 1 }
+              targetPalletId: { type: string, pattern: '^[1-9][0-9]*$' }
+              targetPalletNo: { type: string, minLength: 1, maxLength: 128 }
+              targetLocationId: { type: string, pattern: '^[1-9][0-9]*$' }
+              targetLocationCode: { type: string, minLength: 1, maxLength: 128 }
+    ExceptionAllowedAction:
+      type: string
+      enum: [START_PROCESSING, COMPLETE_EXCEPTION, CANCEL_EXCEPTION]
     DeliveryFeeInput:
       type: object
       required: [feeType, currency, amount]
@@ -1755,6 +2013,18 @@ components:
               inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
               packages: { type: integer, format: int64, minimum: 1 }
               sku: { type: string, maxLength: 128 }
+    OneClickOutboundCandidate:
+      type: object
+      required: [inventoryPositionId, overseasWarehouseId, palletNo, skuCode, availablePackages]
+      properties:
+        inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$', description: 创建命令提交键，不作为用户展示编号 }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseName: { type: string, nullable: true }
+        palletNo: { type: string }
+        inboundCode: { type: string, nullable: true }
+        skuCode: { type: string }
+        productName: { type: string, nullable: true }
+        availablePackages: { type: integer, format: int64, minimum: 1, description: 库存位置、SKU余额和AVAILABLE箱唛三者的可用最小值 }
     OutboundCancel:
       type: object
       required: [reason]
@@ -1909,6 +2179,58 @@ components:
         - { $ref: '#/components/schemas/MerchantApiResponse' }
         - type: object
           properties: { data: { $ref: '#/components/schemas/InboundPlanDetail' } }
+    LastlegOrderHoldRequest:
+      type: object
+      required: [held, chargeable, reason, expectedVersion]
+      properties:
+        held: { type: boolean }
+        chargeable: { type: boolean, description: 仅 held=true 时生效；解除暂扣后固定为 false }
+        reason: { type: string, minLength: 1, maxLength: 500 }
+        expectedVersion: { type: integer, minimum: 0 }
+    LastlegOrderHoldResponse:
+      type: object
+      required: [orderId, held, chargeable, version]
+      properties:
+        orderId: { type: integer, format: int64 }
+        held: { type: boolean }
+        chargeable: { type: boolean }
+        reason: { type: string, nullable: true }
+        version: { type: integer, minimum: 0 }
+    LastlegOrderManualNodeCode:
+      type: string
+      enum: [DOMESTIC_CUSTOMS_COMPLETED, ESTIMATED_DEPARTURE, ACTUAL_DEPARTURE, ESTIMATED_ARRIVAL, OVERSEAS_CUSTOMS_COMPLETED, ACTUAL_ARRIVAL_WAITING_UNLOAD, PICKUP_APPOINTED, UNLOADED]
+    LastlegOrderManualNode:
+      type: object
+      required: [nodeCode]
+      properties:
+        nodeCode: { $ref: '#/components/schemas/LastlegOrderManualNodeCode' }
+        nodeAt: { type: string, format: date-time, nullable: true }
+    LastlegOrderManualNodesRequest:
+      type: object
+      required: [expectedVersion, nodes]
+      properties:
+        expectedVersion: { type: integer, minimum: 0 }
+        nodes:
+          type: array
+          minItems: 8
+          maxItems: 8
+          description: 必须包含8个枚举节点且各出现一次，至少一个 nodeAt 非空。
+          items: { $ref: '#/components/schemas/LastlegOrderManualNode' }
+    ManualInboundPlanRequest:
+      type: object
+      description: 单票人工计划只能使用所属柜已冻结的接柜仓；接柜仓变更必须通过柜级接口完成。
+      required: [customerId, orderId, expectedOrderVersion, plannedArrivalDate, palletCount, palletType, assigned, mergeRequired, urgent]
+      properties:
+        customerId: { type: string, pattern: '^[1-9][0-9]*$' }
+        orderId: { type: integer, format: int64, minimum: 1 }
+        expectedOrderVersion: { type: integer, minimum: 0 }
+        plannedArrivalDate: { type: string, format: date }
+        palletCount: { type: integer, minimum: 1, maximum: 999 }
+        palletType: { type: string, minLength: 1, maxLength: 64 }
+        assigned: { type: boolean }
+        mergeRequired: { type: boolean }
+        urgent: { type: boolean }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     PageMetadata:
       type: object
       required: [page, size, total, pages]
@@ -2090,7 +2412,7 @@ components:
           properties: { records: { type: array, items: { $ref: '#/components/schemas/InboundPlanSummary' } } }
     InboundPlanSummary:
       type: object
-      required: [lineId, planId, planNo, customerId, orderId, inboundCode, packageCount, pickedPackageCount, palletCount, status, createdAt, version]
+      required: [lineId, planId, planNo, customerId, orderId, inboundCode, overseasWarehouseCode, overseasWarehouseName, packageCount, pickedPackageCount, palletCount, status, createdAt, version]
       properties:
         lineId: { type: string, pattern: '^[0-9]+$' }
         planId: { type: string, pattern: '^[0-9]+$' }
@@ -2099,6 +2421,8 @@ components:
         orderId: { type: string, pattern: '^[0-9]+$' }
         inboundCode: { type: string }
         orderType: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, description: 接柜仓编码，取自尾程订单预分配接收仓事实 }
+        overseasWarehouseName: { type: string, description: 接柜仓名称，取自尾程订单预分配接收仓事实 }
         warehouseId: { type: string, nullable: true }
         warehouseCode: { type: string, nullable: true }
         warehouseName: { type: string, nullable: true }
@@ -2118,19 +2442,28 @@ components:
         version: { type: integer }
     InboundPlanDetail:
       type: object
-      required: [id, planNo, customerId, status, lineCount, palletCount, totalVolumeCbm, expectedPackageCount, pickedPackageCount, lines, pallets, allocations, version]
+      required: [id, planNo, customerId, overseasWarehouseCode, overseasWarehouseName, status, lineCount, palletCount, totalVolumeCbm, expectedPackageCount, pickedPackageCount, lines, pallets, allocations, version]
       properties:
         id: { type: string, pattern: '^[0-9]+$' }
         planNo: { type: string }
         customerId: { type: string }
         sourceOrderId: { type: string, pattern: '^[0-9]+$', nullable: true }
         containerNo: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, description: 接柜仓编码，取自尾程订单预分配接收仓事实 }
+        overseasWarehouseName: { type: string, description: 接柜仓名称，取自尾程订单预分配接收仓事实 }
         status: { type: string }
         lineCount: { type: integer }
         palletCount: { type: integer }
         totalVolumeCbm: { type: number }
         expectedPackageCount: { type: integer }
         pickedPackageCount: { type: integer }
+        plannedArrivalDate: { type: string, format: date, nullable: true }
+        palletType: { type: string, nullable: true }
+        assigned: { type: boolean }
+        mergeRequired: { type: boolean }
+        urgent: { type: boolean }
+        creationMode: { type: string, enum: [AUTO, MANUAL] }
+        remark: { type: string, nullable: true }
         lines: { type: array, items: { $ref: '#/components/schemas/InboundPlanLine' } }
         pallets: { type: array, items: { $ref: '#/components/schemas/InboundPlanPallet' } }
         allocations: { type: array, items: { $ref: '#/components/schemas/InboundPlanAllocation' } }
@@ -2153,6 +2486,7 @@ components:
       properties:
         id: { type: string, pattern: '^[0-9]+$' }
         palletNo: { type: string }
+        palletType: { type: string, nullable: true }
         destinationWarehouseId: { type: string, nullable: true }
         destinationWarehouseCode: { type: string, nullable: true }
         destinationWarehouseName: { type: string, nullable: true }

lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml

@@ -46,6 +46,14 @@ paths:
       description: 一件代发复用统一出库任务模型；不接收customerId或warehouseId，派送不进入PDA。
       parameters: [{ name: status, in: query, required: false, schema: { type: string } }]
       responses: { '200': { description: 出库任务列表 } }
+  /api/pda/v1/last-leg/outbound-tasks/resolve/{businessNo}:
+    get:
+      summary: 解析出库作业扫码业务号
+      description: 接受一件代发任务号、出库单号或排车单号；按Token绑定仓返回 OUTBOUND 的 taskNo 或 DISPATCH 的 dispatchNo，PDA据此进入正确作业页。
+      parameters: [{ name: businessNo, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200': { description: 正确作业类型及稳定业务编号 }
+        '404': { description: 当前绑定仓无此出库或排车任务 }
   /api/pda/v1/last-leg/outbound-tasks/{taskNo}:
     get:
       summary: 查询一件代发出库任务详情
@@ -581,7 +589,7 @@ components:
             required: [outboundPalletItemId, palletNo, skuCode, inboundCode, packageCount, pickedPackageCount, status, positions]
             properties:
               outboundPalletItemId: { type: string, description: pick请求提交键，不作为用户展示编号 }
-              palletNo: { type: string }
+              palletNo: { type: string, description: Warehouse 权威实物托盘码 }
               skuCode: { type: string }
               inboundCode: { type: string }
               packageCount: { type: integer }
@@ -594,7 +602,7 @@ components:
                   required: [inventoryPositionId, palletNo, cartonMark, skuCode, inboundCode, availablePackages, pickedPackages]
                   properties:
                     inventoryPositionId: { type: string, description: pick请求提交键，不作为用户展示编号 }
-                    palletNo: { type: string }
+                    palletNo: { type: string, description: Warehouse 权威实物托盘码 }
                     cartonMark: { type: string, nullable: true }
                     skuCode: { type: string }
                     inboundCode: { type: string }