# Lastleg Service 模块指引

## 职责与边界

- 负责消费头程装柜完成事件，保存业务 Inbox，并按最终实装入仓单建立尾程订单、明细冻结快照和初始状态历史。
- 负责尾程订单列表、详情、导出和目的仓调整，以及海外入仓计划、托盘分配与 PDA 入仓作业。
- 不查询头程数据库，不调用头程接口补齐建单字段；事件快照缺失时应拒绝消费并保留可诊断错误。

## 快速索引

| 功能 | 入口 |
|---|---|
| 事件接收、订单列表/详情/导出、目的仓调整 | `src/main/java/com/baiyue/lastleg/controller/LastlegOrderController.java` |
| 装柜完成事件消费 | `service/LoadingCompletedConsumer.java` |
| 尾程单号生成 | `service/LastlegOrderNoGenerator.java` |
| 订单查询与更新 | `service/LastlegOrderService.java` |
| 业务 Inbox | `entity/LastlegEventInbox.java`、`mapper/LastlegEventInboxMapper.java` |
| 尾程订单、明细、状态历史 | `entity/LastlegOrder.java`、`LastlegOrderDetail.java`、`LastlegOrderStatusHistory.java` 及对应 Mapper |
| 内部令牌保护 | `security/InternalServiceTokenGuard.java` |
| 入仓计划转换/查询 | `inboundplan/controller/InboundPlanController.java`、`inboundplan/service/InboundPlanService.java` |
| 托盘分配算法 | `inboundplan/service/PalletAllocator.java` |
| PDA 入仓、实收、上架、合托、完成 | `inboundplan/pda/controller/`、`inboundplan/pda/service/InboundPdaWorkflowService.java` |
| 仓储资源调用 | `inboundplan/pda/gateway/WarehouseResourceGateway.java`、`HttpWarehouseResourceGateway.java` |
| 仓储转运、历史订单/入仓绑定、可选换标联动 | `transfer/controller/WarehouseTransferController.java`、`transfer/service/WarehouseTransferService.java` |
| 一件代发接收、SKU/箱唛库存 | `dropship/service/DropshipOrderService.java`、`dropship/entity/`、`dropship/mapper/` |
| 货物废弃、待审锁箱、审批扣减 | `discard/controller/CargoDiscardController.java`、`discard/service/CargoDiscardService.java` |
| 海外采购、客户下单、采购审核、手工出库与采购库存 | `procurement/controller/`、`procurement/service/OverseasProcurementService.java` |
| 数据库基线、表索引与中文注释契约 | `src/main/resources/db/lastleg.sql`、`src/test/java/com/baiyue/lastleg/schema/SchemaChineseCommentContractTest.java` |
| 测试 | `src/test/java/com/baiyue/lastleg/` |

## 数据库表索引与注释约束

| 业务域 | 表名 | 中文含义 |
|---|---|---|
| 核心订单与事件 | `ll_loading_*`、`ll_event_*`、`ll_order*`、`ll_inbound_order*` | 事件收件、尾程订单、明细及状态历史 |
| 入仓计划与作业 | `ll_inbound_plan*`、`ll_inbound_pda*`、`ll_inbound_pallet_merge`、`ll_inbound_fba_appointment*` | 入仓计划、托盘分配、PDA 作业、合托及 FBA 预约 |
| 库存 | `ll_inventory_*`、`ll_inbound_stock_receipt` | 库存余额、仓位、流水、命令幂等及实收快照 |
| 派车与出库 | `ll_dispatch_*`、`ll_outbound_*`、`ll_delivery_order` | 派车、PDA 拣货、出库及派送 |
| 转仓与换标 | `ll_warehouse_transfer_*`、`ll_relabel_*` | 转仓单、库存转移、目标收货及换标 |
| 一件代发与废弃 | `ll_dropship_*`、`ll_cargo_discard_*` | 托盘/箱唛库存、流水和废弃审批 |
| 采购与卡车 | `ll_overseas_procurement_*`、`ll_us_truck_*` | 海外采购及美国卡车运输 |

- 新增或修改表时，表 `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 分配，不得覆盖来源托盘快照。
- 其他订单类型只建立入仓单维度的尾程订单与冻结明细，来源 `palletCount` 强制为 0；后续 PDA 托盘属于海外仓作业资源。
- 整个事件消费在一个事务内完成；任意订单失败时不得留下部分订单。
- 相同事件重复投递返回既有结果，不重新生成单号或插入明细。来源入仓单唯一约束是最终防线。
- 内部接口先执行常量时间令牌校验；缺失或错误令牌不得进入消费事务。

## 查询与租户约束

- 平台查询范围由可信身份/平台权限决定；商户查询只能使用认证身份中的客户 ID。
- 列表、详情、导出和更新必须使用同一租户边界，不能仅在列表过滤而让详情或更新越权。
- 目的仓变更必须写状态/操作历史或审计证据，并使用版本控制防止并发覆盖。
- 货物废弃只使用可核对 SKU 和箱唛的一件代发库存。创建申请只能将箱从 `AVAILABLE` 锁定为 `DISCARD_PENDING`，不得扣减 SKU 箱数；实际扣库存节点固定为具备 `lastleg:cargo-discard:approve` 权限的仓库/PDA 审核人确认废弃时，并且必须在审核事务内调用专用 discard adjustment。该 adjustment 必须将箱改为 `DISCARDED`、写逐箱业务流水及唯一幂等键，并校验 `扣减前箱数 - 废弃箱数 = 扣减后箱数` 且逐箱数等于申请总箱数；任一环节失败须整体回滚。拒绝申请只释放锁箱，不得扣库存。
- 海外采购客户下单固定进入 `PENDING_REVIEW`；采购表的 `inbound_quantity - outbound_quantity` 只表示采购业务单据余量，不得写入或冒充 `available_packages`。审核/下单只能停留在采购单据（或明确的 `procurement_packages` 桶）；只有海外仓 PDA 完成实收后，`InboundStockReceiptService` 才能以 `PDA_STOCK_IN:{taskId}:{allocationId}` 幂等键调用库存 `stockIn` 转入可用库存。禁止通过通用平台接口绕过 PDA 入可用库存。
- 派车状态只允许 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`。

## 修改与验证

- 表字段、注释和索引同步维护基线 SQL 与统一增量 SQL；生产/存量库只执行增量脚本。
- 事件契约变化同时检查 `common-event-contract` 版本、Event Bridge 消费方和旧 Payload 哈希兼容。
- 定向验证：`mvn -pl lastleg -am test`。
- 事件链路变更至少覆盖重复事件、相同来源入仓单、事务回滚、并发单号、内部令牌和租户越权测试。