167 lines
31 KiB
Markdown
167 lines
31 KiB
Markdown
# Lastleg Service 模块指引
|
||
|
||
## 职责与边界
|
||
|
||
- Mapper 必须标注 `@Mapper`，仅由 `BaiyueLastlegApplication.java` 对 `com.baiyue.lastleg` 根包按 `annotationClass = Mapper.class` 扫描；禁止局部 `*MapperConfiguration` 和包白名单。验证：`scripts/mapper-scan-contract.mjs`、`MapperRegistrationArchitectureTest.java`。
|
||
- 消费头程装柜完成事件并保存 Inbox，按实装入仓单建立待分配尾程订单、冻结明细和初始历史；不自动建计划。平台调用 `/api/platform/v1/last-leg/inbound-plans/convert-container` 后才按柜内每票生成计划并推进订单。
|
||
- 负责尾程订单查询/导出、入库计划、暂扣/解除、人工节点、目的仓调整、托盘分配与 PDA 入仓；卸柜完成通过本地 Outbox 向头程回传报空事实。
|
||
- 不跨库查询头程或回调补建单字段；快照缺失须拒绝消费并保留诊断。
|
||
|
||
## 快速索引
|
||
|
||
业务包相对 `src/main/java/com/baiyue/lastleg/`；`src/`、`docs/`、`scripts/`、`../` 相对服务目录。裸类名在指定包内检索。
|
||
|
||
拼车接货与车次准备：`fleet/trip/`、`fleet/business/`；合同`fleet-preparation-v1.yaml`，流程见 `../../docs/海外仓业务/内部拼车需求池首版开发契约.md`。
|
||
|
||
事件重试：`controller/EventOperationsController.java`，内部 `/internal/lastleg/event-operations/{entryId}` 查询、`/retry` 写入；仅卸柜、派送、暂扣、资金及费用事件，以 `EVENT_OPERATIONS_TOKEN` 保护。原事件不可改，DEAD→PENDING 与 `event_delivery_retry_audit` 同事务；脚本 `scripts/event-outbox-operations.mjs`。
|
||
|
||
沿代码追踪；状态、权限、资源或接口边界不明时，定向检索 `docs/business-index.md`；局部任务不扩读无关约束。
|
||
|
||
退货链查 `returnreceipt/`；计划、自动托盘、柜级预览及来源托盘查 `inboundplan/`。
|
||
|
||
| 功能 | 首个入口 |
|
||
|---|---|
|
||
| 内部模块化基线与依赖分析 | `docs/lastleg-internal-modularization-baseline.md` |
|
||
| 自营领星统计 | `selfoperated/analytics/`；平台入口 `controller/PlatformAnalyticsController.java`，契约见 `../../docs/自营业务/README.md`；权限源 `../iam/src/main/resources/db/selfoperated-analytics-permissions.sql`。 |
|
||
| 订单查询与控制 / 导出 | `controller/LastlegOrderController.java`；异步导出见 `export/` 与 `lastleg-exports-v1.yaml` |
|
||
| 尾程订单完整计划、柜级到仓时间、暂扣与人工节点 | `controller/LastlegOrderController.java` |
|
||
| 客户尾程订单列表与详情 | `controller/MerchantLastlegOrderController.java` |
|
||
| 装柜完成事件消费 | `service/LoadingCompletedConsumer.java` |
|
||
| 尾程单号生成 | `service/LastlegOrderNoGenerator.java` |
|
||
| 订单查询与更新 | `service/LastlegOrderService.java` |
|
||
| 业务 Inbox | `entity/LastlegEventInbox.java` |
|
||
| 尾程订单、明细、状态历史 | `entity/LastlegOrder.java` |
|
||
| 独立尾程入仓单快照 | `entity/LastlegInboundOrder.java` |
|
||
| 内部令牌保护 | `security/InternalServiceTokenGuard.java` |
|
||
| 统一会话校验 | 复用 `../common-security/` Redis会话与Auth权威状态校验；Lastleg不维护授权投影 |
|
||
| 入仓计划分页、柜级预览、转换与详情 | `inboundplan/controller/InboundPlanController.java` |
|
||
| 自动生成托盘、资源生成失败与重试 | `inboundplan/service/ContainerInboundPlanConversionCoordinator.java` 的 `convertManualAndAutoMaterialize`；详细规则定向查 `docs/business-index.md` 的“人工计划自动生成托盘与资源重试” |
|
||
| 托盘分配算法 | `inboundplan/service/PalletAllocator.java` |
|
||
| 跨客户同仓预约、日历 | `InboundPlanController.java`；在途/外接货跟进与覆盖见`appointmentplanning/` |
|
||
| PDA 入仓、柜号签收、实收、上架与完成 | `inboundplan/pda/controller/ReceivingContainerController.java` → `inboundplan/pda/service/ReceivingContainerService.java`；门禁与状态定向查 `docs/business-index.md` 的“PDA 入仓、实收、上架与完成” |
|
||
| PDA 卸柜照片上传、归属校验与预览 | `ReceivingContainerController.java` |
|
||
| PDA 国内装柜照片对照 | `ReceivingContainerController.java` |
|
||
| 卸柜照片与海外卸柜完成 Outbox | `ReceivingContainerController.java` |
|
||
| 拆柜打托成本与客户应收分摊 | `inboundplan/service/DestuffingPalletCostJob.java` |
|
||
| 尾程暂扣状态回传 | `service/InboundOrderDetainedOutboxService.java` |
|
||
| 派送完成回传 | `delivery/service/DeliveryCompletedOutboxService.java` |
|
||
| 入仓后 SKU 库存余额、库位和流水 | `inventory/` |
|
||
| 海外PDA盘点、同仓整托移库、托盘组拆换绑与换标现场作业 | `pda/stocktake/` |
|
||
| 贴标申请、箱唛/SKU/组合换标与 PDA 完工 | `relabel/` |
|
||
| PDA 仓内通用扫码与操作历史 | `pda/warehouse/controller/PdaWarehouseController.java` |
|
||
| 船节点接收与海外 PDA 可收货门禁 | `shipping/service/ContainerShippingNodeConsumer.java` |
|
||
| 平台排车列表/详情与智能预排 | `dispatch/controller/DispatchQueryController.java` |
|
||
| 排车编辑、PDA 出库、派送与交接 | `dispatch/controller/DispatchController.java` |
|
||
| 仓储资源调用 | `inboundplan/pda/gateway/WarehouseResourceGateway.java` |
|
||
| 仓储转运、历史订单/入仓绑定、可选换标联动 | `transfer/controller/WarehouseTransferController.java` |
|
||
| 一件代发接收、SKU/箱唛库存 | `dropship/controller/DropshipOrderController.java` |
|
||
| 货物废弃、待审锁箱、实际确认扣减 | `discard/controller/CargoDiscardController.java` |
|
||
| 客户拜访、派送状态与签收附件 | `customervisit/controller/CustomerVisitController.java` |
|
||
| 派送三类资料、摘要与历史证据 | `delivery/controller/DeliveryDocumentController.java` |
|
||
| 异常订单与派送退回入仓 | `exceptionorder/controller/ExceptionOrderController.java` |
|
||
| 海外采购、客户下单、采购审核、客户/采购仓候选与操作流水 | `procurement/controller/` |
|
||
| 海外业务资金指令与结果 | `wallet/WalletCommandOutboxService.java` |
|
||
| 海外业务费用来源 | `financefee/controller/PlatformOverseasFeeSourceController.java` |
|
||
| 美国/本土卡车订单 | `trucking/controller/PlatformUsTruckOrderController.java` |
|
||
| 本土散板订单 | `looseboard/controller/PlatformLocalLooseboardController.java` |
|
||
| 海外仓报价、月度汇率、车辆主数据 | `masterdata/quote/` |
|
||
| 司机档案、证照上传/审核、资格预览与历史 | `fleet/driver/PlatformDriverController.java`、`DriverService.java`；OpenAPI `fleet-drivers-v1.yaml`，表 `ll_fleet_driver` / `ll_fleet_driver_history`；资格规则 `fleet/domain/DriverQualificationPolicy.java` |
|
||
| 车辆运维：保养、加油、维修、故障、救援、异常 | `fleet/maintenance/PlatformVehicleCareController.java`、`VehicleCareService.java`；合同`fleet-vehicle-records-v1.yaml`。按车/类型隔离，单位/币种明确，处理不等付款；创建/附件幂等，更正留版本历史，不改主档里程/状态。维修救援经`financefee/fleet/VehicleCareFinanceAdapter`入公司成本，Finance为付款权威，未关联UNLINKED，不生成客户应收 |
|
||
| 车次计划、车/司机分配与占用、客户排车关联 | `fleet/trip/PlatformFleetTripController.java`、`FleetTripService.java`；OpenAPI `fleet-trips-v1.yaml`；`FleetDispatchGateway` 由 `dispatch/fleet/DispatchFleetAdapter.java` 实现，`FleetDispatchBindingGuard` 控制子单独立修改/发车；车辆通过 `VehicleRepository` 和 `VehicleAssignmentGuard` 协作，fleet不直读车辆持久化适配器 |
|
||
| 调度与理货审核 | `FleetTripService.reviewDispatch`、`FleetTripExecutionService.reviewLoading`；每张客户排车单先调度通过，整车确认实载后理货通过。`FleetDispatchBindingGuard.requirePickingApproved` 在新拣货/完成前核对当前单审核；已成功操作的同键重放保留原结果 |
|
||
| 外接询价、确认占位及取消 | `fleet/trip/PlatformFleetBookingController.java`、`FleetBookingService.java`、`FleetBookingReservations.java`；客户从`fleet/customer/`读取IAM有效主档与资格，询价不占位，确认后与自有货计划共同校验逐段容量。约定金额不代表应收/实收，`FleetBookingIncomingGateway`由`transfer/fleet/FleetIncomingAdapter`实现来货登记/实收确认，排车关联通过`FleetDispatchGateway.sourceCargo`核对实收来源 |
|
||
| 拣货前计划容量与逐段余位 | `FleetTripExecutionService.capacityPlan/confirmCapacityPlan`、`/fleet/trips/{tripNo}/capacity-plan`；保存自有货的计划值，不检查拣货完成、不推进审核或扣库存；`planValid`校验当前货物hash，不把计划值当实测值，资源/计划/关联变更后须重新核对 |
|
||
| 实物装载、逐段容量与整车PDA发车 | `fleet/trip/FleetTripExecutionService.java`、`FleetExecutionModels.java`；平台 `/fleet/trips/{tripNo}/loading`，PDA沿用 `/dispatches/{dispatchNo}/depart` 但提交车次版本并返回整车结果；`DispatchPdaWorkflowService.depart` 为车次事务内子操作，不独立对外调用 |
|
||
| 车次货物结案、车辆和司机分别释放 | `fleet/trip/FleetTripCompletionService.java`、`FleetCompletionModels.java`；平台 `/fleet/trips/{tripNo}/completion`、`/complete`、`/resources/release`，独立complete/release权限。结案核对所有派送终态与实发数量；实际任务结束时间/地点及车辆结束状态单独记录，不以结案或收款自动释放资源 |
|
||
| 跨服务 HTTP 客户端装配 | `config/LastlegRestClientFactory.java` |
|
||
| 数据库基线、表索引与中文注释契约 | `src/main/resources/db/lastleg.sql` |
|
||
| 测试 | `src/test/java/com/baiyue/lastleg/` |
|
||
| 真实事件消费验收 | `src/test/java/com/baiyue/lastleg/service/TaillegRealConsumerAcceptanceTest.java` |
|
||
|
||
## 海外仓全流程开发路由
|
||
|
||
- 车次成本：`fleet/trip/FleetTripCostService.java`、`fleet-trip-costs-v1.yaml`；按DEPART实测及外接实收分摊，不产生客户账单/付款。
|
||
- 报价/统计：`fleet/quote/`、`fleet/reporting/`，合同`fleet-quotes-v1.yaml`、`fleet-operations-v1.yaml`；实测凭证按车次归属，仅当前/历史版本引用可下载。
|
||
- 外接选价合同：`fleet-quote-candidates-v1.yaml`、`fleet-trips-v1.yaml`；来源快照与成交价分开，确认承运复验。
|
||
- 在途交接：`fleet/exception/`、`fleet-handovers-v1.yaml`；后台确认交接，旧资源分别结束任务，DEPART不重写。
|
||
|
||
- 车辆履约投影：`fleet/trip/PlatformVehicleFulfillmentController.java` → `VehicleFulfillmentService` / `VehicleFulfillmentMapper`，合同`fleet-vehicle-fulfillment-v1.yaml`。派送同时要求vehicle:list与delivery:list，更换历史要求vehicle:list与trip:list；客户与排车双键关联，不跨库。按不可变DEPART/ASSIGN关联车辆，首次分配不算更换，不按当前车牌猜历史。只读重复读事务分页；不返回内部ID或整份客户快照。
|
||
|
||
- 海外仓全流程连续覆盖尾程订单、入仓计划/PDA 入仓、换标、产品与箱唛快照、库存、转运、废弃、采购、本土卡车、本土散板、排车查询/智能预排、排车编辑/取消/发车、PDA 拣货与出库、一件代发、转派送、客户派送单、异常退回和客户回访。
|
||
- 服务端正式入口包括 `dispatch/controller/DispatchController.java`、`dispatch/pda/controller/DispatchPdaController.java`、`delivery/controller/DeliveryTransferController.java`、`delivery/controller/OutboundPdaController.java`、`delivery/controller/MerchantDeliveryController.java`、`exceptionorder/` 与 `customervisit/`；设备页面是否可用以海外 PDA 正式路由和能力开关为准，未由 PDA 承载的操作由 Admin/Client 完成。
|
||
- 平台一件代发出库候选由 `/outbound-orders/one-click-dropship/candidates` 统一返回已完成入库且仍有可用箱唛、SKU 汇总和库存仓位绑定的托盘明细；查询不强制先传 `customerId`，未传时跨客户展示供页面分页筛选，创建时必须从所选候选解析为唯一客户和唯一海外仓，禁止一张出库单跨客户或跨仓。创建后出库单按 `WAIT_PICK → PICKING → PICKED → OUTBOUNDED` 推进；海外 PDA 扫描托盘码时通过整托命令原子拣取该托盘在当前任务内全部剩余箱件和 SKU，任一库存明细失败须整托回滚，逐箱拣货入口继续保留。
|
||
- 排车转派送允许在 `PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART` 阶段幂等生成一张 `WAIT_OUTBOUND` 出库单，并按目的FBA仓生成多张派送单，但必须早于发车；BOL和签收资料均绑定拆分后的单仓派送单，派送费用仍只发布一次。PDA 排车详情由 `DispatchPdaWorkflowService` 返回 `canDepart`、`departBlockReason`，只有车辆信息完整、拣货任务完成且箱数核平、排车为 `READY_TO_DEPART`、关联出库单仍为 `WAIT_OUTBOUND` 时才允许发车，PDA 不得自行推导该门禁。
|
||
- 共享车次关联取排车单自身客户与起运仓；排车有效关联唯一，多客户不合并库存归属。`FleetDispatchBindingGuard` 在子单行锁内阻止独立编辑/移托/取消及绕过车次协调单独发车；转派送的新建请求不能覆盖车次车辆司机，已成功转换的重放继续返回既有单据。PDA详情同步返回车次统一发车阻断原因；关联与改派通过 `FleetDispatchGateway` 同事务同步尚未执行的派送快照。已拣货禁止直接解除关联或变更路线；发车前可统一换车/司机或保持路线调整时间，保留拣货事实与到达时间，重验司机任务覆盖及替换车辆对已确认装载的容量，成功后调度审核、理货审核及原装载确认失效；仅修改备注保留审核与装载。已出库/发车不允许此类修改。
|
||
- 实物装载按仓库托盘ID去重计量，客户货量与物理占位分别保存；重量/体积为明确确认的实际值，不读取计费材积重回填。路线卸货站的 `destinationKey` 必须匹配原货物目的地，同实托不同目的地先拆托。装载确认保存来源hash、版本、操作人和历史；改计划/改派/关联变化使确认失效。整车发车在同一Lastleg事务中复核所有子单、车辆占用及司机证照，调用原子单出库命令后统一提交 `IN_TRANSIT` 和幂等结果；任一失败全车回滚，`DEPARTING`只在事务内部使用。PDA列表按车次复用发车门禁查询，再按当前客户排车单审核返回canPick/pickBlockReason；客户A通过不能代替客户B通过。重新确认装载或重新调度审核使理货审核待审，审核历史不删除；过期前30天提醒与阻断分别返回。
|
||
- 车次结案只消费派送事实：实签须signedAt/signedPackages，实退须原来源入账流水/RETURN_COMPLETED；实签加本趟实退等于原实发且余量为零。拒收、待退回、取消不算完成，时间取最后实际终态。结案不改客户状态/费用、不释放占用；车/司机分别记录实际结束时间地点，车辆状态与释放同事务。过期证照不阻止旧任务结束、不恢复新任务资格；原键重放不影响后续车次。
|
||
- 已签收后另发起退货保留原运输的签收事实，后续退货不重开原车次、不被车次结案改写；未签收货物仍按实际退回完成核对。`DeliveryDocumentService.save` 首次保存签收资料触发完成时要求关联出库已OUTBOUNDED，未出库可以准备BOL/装车资料但不能提前完成派送。
|
||
- 排车执行与 `delivery/` Controller 和其他尾程业务接口一同注册，不受功能开关控制。平台排车列表与详情仍由 `lastleg.dispatch-query-api.enabled=true` 独立启用；入库单智能排车候选、草稿锁定/解锁/释放和预排创建仍由 `lastleg.smart-dispatch-api.enabled=true` 独立启用。这些排车平台入口均不接收 `customerId`：排车列表跨客户分页，详情按全局排车单号定位后使用记录自身客户范围加载明细；智能排车候选未传计划 ID 时跨客户查询，传入时根据计划 ID 解析范围；托盘移入草稿时立即以操作人和随机草稿标识锁定，移除或关闭时释放，草稿锁超时失效；预排创建根据所选托盘 ID 在服务端解析并校验唯一客户范围，并将当前操作人的草稿锁原子转换为正式排车锁。
|
||
- 仓库 ID、类型、状态、地址和能力唯一权威归国内 `warehouse-service`；海外库位、实物托盘和资源锁归 `warehouse-overseas-service/` 且只引用同一国内 `warehouseId`。Lastleg PDA 通过 Warehouse Overseas 内部资源入口校验该国内共享收货仓，不得要求海外数据库重复建仓；浏览器 API 统一经 `gateway/`。
|
||
|
||
- 外接预订以父车次行锁串行确认容量；DRAFT不占位，CONFIRMED占位，CANCELLED释放，创建/确认/取消保留请求键与内容摘要。报价与记录快照进入既有车次历史。重新核对自有货计划不得占用已确认外接容量，换小车须能容纳两者；同车只换司机不额外要求先重新核对容量。CONFIRMED和RECEIVED尚未绑定实际发运时阻止整车发车；通过真实来货实测、运费确认及来源核对后转为BOUND，解除未开工排车关联回RECEIVED。报价或登记来货不冒充库存/已出库；取消未执行预订仅释放承运容量，来货及已入库货物保留。
|
||
- 外接约定运费由`fleet/trip/FleetBookingFreight`按排车来源、绑定车次、目的地和完整实收量复核；`DeliveryTransferService`在原转派送事务内发布到对应目的地派送单的`OVERSEAS_DELIVERY_FEE`，通过既有费用Outbox进入Finance。预览只读且使用dispatch:list；确认原货物/报价摘要后写入，全部外接货禁止再填派送应收，额外装车/买约仍独立。明确零约定留操作事实不发布虚构零费用。首版确认承运币种限现行费用支持的CNY/USD，原头程费用覆盖按下条处理。
|
||
- 原运费覆盖由`delivery/service/DeliveryFeeCoverageService`与`DispatchFeeCargoMapper`按实际库存组成及本次已拣数量还原，核平每条排车箱数；不可用MIN展示入仓码替代整托全部来源。`FinanceFeeCoverageClient`批量只读Finance，平台转派送按费用ID/版本/hash和当前货物/目的地摘要复核，只有全部相关货物已覆盖的服务才免新增应收，供应商应付独立。客户接口禁止自行声明覆盖。确认快照保存到`ll_outbound_order.fee_coverage_json`，原费用不复制、不抵扣金额、不生成伪零费用；详情按本派送货物过滤只读快照，之后财务更正不自动改写旧发运。普通无引用请求保持原新增收费要求。
|
||
- 派送出库取消按dispatch→outbound加锁，核对排车未拣货/发车并先解除车次关联；取消出库不代替取消排车占用。来源订单按本次转派送历史的原状态恢复，显式清空出库/派送关联并增加版本，不统一写RECEIVED。只对本派送当前已审核有效的DELIVERY_FEE应收申请作废，其他费用保留核对，完整取消原因分段保存在派送操作记录。
|
||
- `financefee/state/OverseasFeeCancellation`从不可变费用Outbox批量读取voidStatus；请求/拒绝/未知结果保留ACTIVE，只有Finance匹配APPLIED/DUPLICATE后，在投递审计同事务中落VOIDED。撤销候选必须等待原发布成功，未满足前置的PENDING撤销在LIMIT前排除，避免堵住后续投递；过期PROCESSING仍按租约恢复。费用调整使用READ_COMMITTED并在来源行锁后检查未决撤销，禁止旧快照漏检。前端与API区分待财务确认、待财务处理和确认作废，不能以物流取消或HTTP请求发出认定账务已撤销。
|
||
|
||
## 数据库表索引与注释约束
|
||
|
||
表名与中文含义按需查 `docs/business-index.md` 的“数据库表索引”；修改约束如下。
|
||
|
||
- 新增或修改表时，表 `COMMENT` 和每个普通字段的 `COMMENT` 必须填写准确的中文业务含义，不得只写英文、字段名或类型名。
|
||
- `SchemaChineseCommentContractTest` 自动扫描全部 `ll_` 表，无需维护表名白名单；新增字段必须同步更新基线 SQL、建表增量和存量备注迁移，增量脚本的 `ADD/MODIFY COLUMN` 不得丢失中文备注。
|
||
- 表备注、字段备注和索引变更必须可重复执行；存量库的备注修订通过统一增量脚本落地，不依赖基线建表语句。
|
||
|
||
## 事件建单规则
|
||
|
||
- 只接受冻结契约支持的事件类型和版本；校验事件 ID、租户、区域、Payload 哈希及必要字段。
|
||
- 同一实际集装箱 `containerNo` 生成一个共享业务尾程单号；`payload.orders` 每项按 `sourceInboundId` 独立落一条雪花 ID `ll_order`，并保存对应明细和初始状态历史。整柜操作不使用 `cabinetNo`。
|
||
- `ONE_CLICK_DROPSHIP` 每个来源入仓单必须携带一个或多个不可变来源托盘快照；每托按 SKU 携带箱数、数量和箱唛。校验订单汇总一致、托盘号/SKU/箱唛唯一后，按托建立档案及 SKU 库存，并建立箱唛和流水。仓库实物托盘由 Warehouse API 分配，不得覆盖来源托盘快照。
|
||
- 其他订单类型建立入仓单维度的尾程订单与冻结明细，并保留头程推荐托数；尾程入仓计划至少按推荐托数生成计划托盘，PDA 再把箱级事实绑定到海外仓实物托盘。
|
||
- 整个事件消费在一个事务内完成；任意订单失败时不得留下部分订单。
|
||
- 相同事件重复投递返回既有结果，不重新生成单号或插入明细。来源入仓单唯一约束是最终防线。
|
||
- 装柜完成事件只把尾程订单建立为 `PENDING_ASSIGNMENT`。`FIRST_LEG` 在途库存使用不可变来源入仓码作为计划生成前的 `inbound_order_no` 展示快照；平台人工转换成功后，同一事务将订单推进为 `INBOUND_PLANNED`，并把对应库存余额的该快照收口为新 `planNo`。
|
||
- 内部接口先执行常量时间令牌校验；缺失或错误令牌不得进入消费事务。
|
||
- 通用 `/internal/lastleg/events` 只白名单接收装柜完成、实际船节点与资金结果事件；未知或IAM安全事件必须拒绝。
|
||
- PDA 入仓任务完成前必须先通过 `/unload-photos` 保存非空且不重复的卸柜照片文件 ID；照片上传时间由服务端记录，预计报空时间固定为照片上传时间加两天。完成入仓时，库存入账、计划/任务状态推进与 `OVERSEAS_CONTAINER_UNLOADED` V1 Outbox 必须处于同一事务；事件绑定来源头程货柜身份，不得从前端请求拼装或回查头程数据库。
|
||
- 海外 PDA 柜号签收只允许平台 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 使用 `lastleg:pda:operate`；国内头程 PDA 角色不得进入。PDA 不接收 `customerId`，候选按来源柜跨客户聚合，同柜允许多个客户；选柜会话、三类照片及整柜完成事实只绑定 `sourceContainerBookingId + containerNo`，文件与柜级跨区事件使用 `tenantId=0` 平台技术范围。签收后按每个入仓计划自身客户生成任务，扫码、SKU 实收、托盘和库存始终使用入仓码所属票的真实客户。未完成会话按平台操作账号和柜号分别全局唯一；平台管理员和客户账号不得进入该作业入口。
|
||
|
||
## 查询与租户约束
|
||
|
||
- 平台查询范围由可信身份/平台权限决定；商户查询只能使用认证身份中的客户 ID。
|
||
- 尾程平台只读查询接口的 `customerId` 为可选筛选条件：平台身份省略时查询全部客户数据，传入时按指定客户过滤；商户身份忽略客户端传入值并始终按 Token 中的自身客户隔离。创建、编辑、审核等需要明确目标客户的写接口仍必须传入 `customerId`。
|
||
- 常规入仓库存余额以客户、海外仓、目的仓和入仓单为唯一业务维度并汇总箱数；SKU 继续保存在箱唛、实收和流水快照中，余额 SKU 仅作单 SKU 展示或以 `MIXED` 标识多 SKU，不参与当前唯一维度。
|
||
- 托盘是 PDA 出库的作业单位，但不是库存归属单位：`ll_inventory_position` 通过余额和托盘保存“托盘包含哪些入仓单、各多少箱”的组成明细。合托后的同一实物托盘允许对应多个入仓单，换标冻结和后续出库核算必须按这些明细分别记账；整托出库可扫描托盘一次完成，部分出库先拆托或按明细核平，不得用 FIFO 猜测来源入仓单。普通尾程入库只确认某入仓单在托盘上的箱数，没有逐箱唛到托盘的快照；贴标下单由客户填写我方箱唛，库存仓位只作为冻结记账锚点和现场大概位置，不能据此声称箱唛位于某个具体托盘。贴标任务以我方箱唛为主键，同箱多 SKU 只存为子明细且不重复冻结。
|
||
- 换标箱唛经现场确认后执行 `pallet-operations/relabel-disassemble`：允许仅移动该换标单对应的 `hold_packages`，不得解冻为普通可用库存；事务内同步更新 `ll_relabel_item.source_inventory_position_id`。若客户确认后已生成换标出库单，还必须在拣货开始前同步拆分或改写 `ll_outbound_pallet_item` 的托盘、箱唛、箱数与来源仓位快照，使 PDA 后续按新旧托盘分别扫描且每个指定箱唛只出库一次。
|
||
- `FIRST_LEG` 在途、计划转换与 PDA 入账统一使用尾程订单冻结的实际接柜海外仓 ID/编码/名称，禁止使用国内来源仓或 FBA 目的仓冒充；接柜仓变更必须在同一事务内修订尚未形成实物仓位的在途余额并写零差额审计流水。余额分页、汇总和 CSV 默认排除所有数量桶均为零的维度，跨仓入账清空的无仓位来源余额必须原子删除。
|
||
- 列表、详情、导出和更新必须使用同一租户边界，不能仅在列表过滤而让详情或更新越权。
|
||
- 目的仓变更必须写状态/操作历史或审计证据，并使用版本控制防止并发覆盖。
|
||
- 一件代发废弃：申请只锁箱 `AVAILABLE→DISCARD_PENDING`；平台批准（`lastleg:cargo-discard:approve`）只授权。绑定仓的海外 PDA（`lastleg:pda:operate`）实际确认时，同事务调用 discard adjustment，扣 SKU 件数及库存余额/位置，实际箱转 `DISCARDED` 并写唯一逐箱流水，数量须守恒；未废弃预留箱释放，失败整体回滚。按实际数量汇总费用，平台结案不再扣减。终态同完整载荷重放不新增流水/历史，异数量拒绝；驳回只释放锁箱。完整流程见 `../../docs/头程到尾程分阶段流程/阶段五-海外接柜库存与库内服务.md` 第9.5节。
|
||
- 海外采购样品履约按 `../../docs/海外仓业务/采购订单样品履约流程变更需求.md` 执行：通用编辑仅限内部备注，实收、装箱、面单、两段交寄和资金走独立节点。采购使用 Admin 履约台账，不接入 PDA、不写 WMS 可用库存。
|
||
- 派车状态只允许 PDA 拣货、完成和出库动作推进，普通派车编辑接口不得修改状态。PDA 写操作要求 `lastleg:pda:operate`；后台库存表单操作要求 `lastleg:inventory:manage`，盘点调整另要求 `lastleg:inventory:adjust`，转仓库存操作要求 `lastleg:warehouse-transfer:manage`。
|
||
- `ll_order.current_status` 只保存尾程主流程状态；换标、转仓、出库和派送等子单精确状态保存到各自单据并汇总到 `sub_order_status`，不得再用子单状态覆盖主流程状态。PDA 入仓及库存落账完成后，主流程状态固定推进为 `INBOUND_COMPLETED`。
|
||
|
||
## 修改与验证
|
||
|
||
- `RelabelBindingGuard` 校验已保存组托历史与当前库存托盘一致，箱唛/混合换标正常完工、客户确认与排车提交均复验；纯 SKU 不要求移托，异常手动完工仍须在客户确认前补齐绑定。创建申请按库存余额串行检查箱唛既有申请，拒绝重复申请；历史扫码全局唯一约束尚未改为多轮复用。
|
||
|
||
- 已确认箱唛改绑复用 `PdaPalletOperationService.relabelDisassemble` 不带 `actualSource` 的精确来源分支，按现有绑定移动 HOLD 库存，不重新分配冻结锚点；成功同样记录 `PALLET_BIND` 以展示最新目标。`requireUnallocatedRelabel` 在入口与事务锁单后限制排车/出库占用，已创建出库单也不可直接改绑。回归 `PdaPalletOperationServiceTest`。
|
||
|
||
- PDA旧SKU单扫：`PdaRelabelService.scanSku` 和 `/relabel-tasks/{relabelNo}/skus/scan`，按箱itemId+skuIndex核对旧SKU，服务端取新SKU/数量，逐条记录现有 `SKU_SCAN` 历史，版本、幂等、认领和仓库校验不变；同箱全部SKU完成再推进SKU阶段，混合单需两阶段才生成一条箱事实。无新增字段；前端按历史当前轮次隐藏已完成子项，重复旧SKU须由操作员选实际箱。
|
||
|
||
- 数量拆托成功在现有 `ll_relabel_pda_history` 写 `PALLET_BIND`，保存本轮、箱唛和目标托盘；同轮已组托箱从候选排除并在事务内防重复，返工使用新的 reviewedAt 轮次。PDA 通过详情 history 展示组托记录；不需要新增库存表字段。
|
||
|
||
- 换标按数量拆合托：`palletops/PdaPalletOperationService.relabelSources` 返回原入仓库存池的托盘组成，不能视为箱唛定位；`relabel-disassemble` 的 `actualSource` 携带仓位版本及现场箱数，`cartonMarks` 为本批目标绑定确认。实际托盘与冻结锚点不同时，在同余额/批次内仅重新分配本单冻结桶后合托，库存余额及原入仓单归属不变，保留逐仓位流水、物理资源补偿及幂等。每次一条实际来源仓位，可分批多托；已生成出库单禁止此重分配。认领人处理中即可新增托盘，不需客户确认；此能力不等于已具备真机打印或整单强制组托门禁。
|
||
|
||
- 换标申请生成的 `RELABEL_APPLICATION` 尾程主单使用 `WAIT_RELABEL`（待换标），不进入普通入库计划池；子状态仍区分处理中/待客户确认。客户确认后统一为 `WAIT_OUTBOUND`（待出库），卡车分支按换标申请的 `WAIT_PRE_DISPATCH` 资格参与排车，不重复入库。存量修正脚本 `../scripts/db/relabel-wait-status-incremental.sql` 仅调整尚未生成入库单的遗留待分配换标主单。
|
||
|
||
- 混合换标 `CARTON_AND_SKU` 使用现有 PDA 历史保存 `MIXED_CARTON/MIXED_SKU` 分项事实（itemId + 退回轮次）；同一项防重复，两项全部完成才写一条箱事实并增加整箱计数。详情返回 `cartonProcessedPackages/skuProcessedPackages`；不得将单项完成当作整箱完成，返工后旧轮次不计入当前分项进度。
|
||
|
||
- 换标复核闭环：`PdaRelabelService.complete` 直接提交待客户确认，`RelabelApplicationService.confirmCompletion` 原子完成 PDA 复核；平台 `RelabelApplicationController` 的 `/review-task`、`/rework` 按状态权限提供带版本的退回。退回备注必填，上一轮事实及照片引用写入 `REWORK_ARCHIVE` 历史，原事实标记 `REWORK_ARCHIVED` 并释放扫描唯一键，当前计数归零；客户已确认不可退回。PDA 不再自行批准复核。
|
||
|
||
- 移动包、拆分端口/适配器或引入新的跨子域依赖时，先核对内部模块化基线并运行 `node --test scripts/analyze-lastleg-dependencies.test.mjs`；确需更新依赖基线时必须说明稳定边界变化，不能把临时循环依赖登记为长期豁免。
|
||
- 表字段、注释和索引同步维护基线 SQL 与统一增量 SQL；生产/存量库只执行增量脚本。
|
||
- 事件契约变化同时检查 `common-event-contract`、直接生产者/消费者、Outbox/Inbox 和 DeliveryAck 的 eventId/payloadHash；按 `../../docs/统一认证与服务通信契约.md` 的逐事件表验证，不引入旧 Payload 兼容。
|
||
- 定向验证：从后端根执行 `mvn -pl lastleg-service -am test`。
|
||
- 事件链路变更至少覆盖重复事件、相同来源入仓单、事务回滚、并发单号、内部令牌和租户越权测试。
|