3.1 KiB
3.1 KiB
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 |
| 数据库 | src/main/resources/db/lastleg.sql |
| 测试 | src/test/java/com/baiyue/lastleg/ |
事件建单规则
- 只接受冻结契约支持的事件类型和版本；校验事件 ID、租户、区域、Payload 哈希及必要字段。
- 同一事件/loading plan 生成一个共享尾程单号；
payload.orders每项按sourceInboundId独立落一条ll_order，并保存对应明细和初始状态历史。 - 整个事件消费在一个事务内完成；任意订单失败时不得留下部分订单。
- 相同事件重复投递返回既有结果，不重新生成单号或插入明细。来源入仓单唯一约束是最终防线。
- 内部接口先执行常量时间令牌校验；缺失或错误令牌不得进入消费事务。
查询与租户约束
- 平台查询范围由可信身份/平台权限决定；商户查询只能使用认证身份中的客户 ID。
- 列表、详情、导出和更新必须使用同一租户边界，不能仅在列表过滤而让详情或更新越权。
- 目的仓变更必须写状态/操作历史或审计证据，并使用版本控制防止并发覆盖。
修改与验证
- 表字段、注释和索引同步维护基线 SQL 与统一增量 SQL；生产/存量库只执行增量脚本。
- 事件契约变化同时检查
common-event-contract版本、Event Bridge 消费方和旧 Payload 哈希兼容。 - 定向验证：
mvn -pl lastleg -am test。 - 事件链路变更至少覆盖重复事件、相同来源入仓单、事务回滚、并发单号、内部令牌和租户越权测试。