尾程平台已完成功能报告（2026-08-15）

1. 交付结论

头程装柜完成到尾程订单的真实链路已打通。头程按客户发布 FirstLegLoadingPlanCompleted V1 事件，经 Event Bridge 可靠投递后，尾程按事件中每一笔最终实装入仓单分别落一条订单记录。同一柜的订单记录共享尾程单号， sourceInboundId 作为来源建单唯一标识。

本报告仅描述当前代码和已经取得证据的能力，不把规划中的功能列为已完成。

2. 已完成功能

2.1 跨区域事件桥

接收并持久化版本化事件信封，保存幂等键、负载摘要和冻结 JSON。
使用数据库租约领取待投递事件，支持多实例竞争和超时租约恢复。
RECEIVED 与 RETRY 都可重新调度，失败采用指数退避，达到上限进入 DEAD。
每次投递写入 bridge_delivery_attempt，记录投递序号、结果、响应码和错误。
支持经过内部令牌保护的死信人工补投；成功后才把 Inbox 标记为 PROCESSED。
Event Bridge 与尾程内部接口使用统一的 X-Internal-Service-Token。

2.2 装柜完成事件消费与尾程建单

只接受 CN -> OVERSEAS、LOADING_PLAN、版本为 1 的装柜完成事件。
强制校验实际 containerNo 和非空 orders，尾程不回查头程数据。
事件 Inbox 以 eventId 防重复，并校验重复事件的 payloadHash。
按 orders 逐笔创建尾程订单；同柜入仓单共享一个不可碰撞的尾程单号。
以 (tenant_id, source_region, source_inbound_id) 保证来源入仓单建单幂等。
保存根入仓单、来源订单、装柜计划版本、交接版本和来源摘要等追溯字段。
保存商品、箱数、数量、托数、重量、体积、目的仓、SKU、FBA 跟踪号、 shipmentNo 和唛头等实装冻结明细。
新订单初始化为 PENDING_ASSIGNMENT，同步写入状态历史。
同一来源入仓单摘要不一致时拒绝静默覆盖。

2.3 尾程订单查询与转仓

按租户分页查询，支持尾程单号、入仓码、头程订单号、柜号、状态、转仓、异常、暂扣和创建时间筛选。
查询订单详情、实装明细和状态历史。
导出 UTF-8 CSV，并处理公式注入风险。
支持单笔和批量转仓，更新订单及明细目的仓快照并写状态历史。
已生成入库计划的订单禁止再次修改目的仓。
普通客户只能查询认证身份对应租户；平台身份必须显式指定客户租户，不允许通过请求参数任意跨客户查询。

2.4 尾程入库计划与 PDA 作业

按租户和实际集装箱生成唯一入库计划。
保存入仓码明细、目的仓快照、计划托盘和托盘分配关系。
按目的仓隔离合托，支持固定容量托盘分配。
提供 PDA 任务、操作幂等记录、托盘合并记录及仓库资源锁关联字段。

2.5 仓库资源和海外认证边界

仓库维护库位、托盘及资源锁，资源锁使用租户幂等键并记录业务归属。
仓库数据源启动保护避免 schema 接错后误执行建表脚本。
海外 Gateway 使用 JWKS 验证非对称 JWT，校验 lastleg-api Audience 及必需 claims。
尾程内部事件入口使用常量时间令牌比较；未配置或令牌错误时拒绝消费。

2.6 工程规范与数据库交付

生产 Spring Bean 的依赖注入已统一为 jakarta.annotation.Resource；仅保留配置值 @Value 和普通值对象/校验器构造器参数，不把不可变业务值误当作 Bean 注入。
新增统一增量入口 scripts/db/incremental.sql，按 001-006 归档 Event Bridge、尾程订单与入库计划/PDA、仓库资源及仓库主数据的字段、中文注释和索引变更。
增量脚本使用 information_schema 守卫，45 个动态 DDL 均成对释放，且不包含业务数据写入、删除或清理语句。

3. 真实链路验收证据

项目	结果
loadingPlanId	`2091000814000009002`
containerNo	`LLSYNC-CNTR-20260814`
tenantId/accountId	`10001`
eventId	`88cd0f63-dc9e-4c16-bdb7-c32b20a83c3b`
payloadHash	`sha256:23011feff2ff91203fb94ebab7cab8306f58e3e128f61d17913d2f74af5c87f4`
Event Bridge 状态	`PROCESSED`
尾程单号	`LMO43831679558828067566368238939`

同一事件实际生成两条入仓单维度订单记录：

sourceInboundId	入仓码	箱数	托数	明细数
`2091000814000000301`	`LLSYNC-20260814-IN-01`	2	1	1
`2091000814000001301`	`LLSYNC-20260814-IN-02`	2	1	1

重复投递相同 eventId 后接口仍返回成功，数据库订单记录总数保持为 2，未重复建单。

4. 数据库交付约定

全量初始化脚本继续由各服务维护：

lastleg/src/main/resources/db/lastleg.sql
event-bridge-service/src/main/resources/db/event-bridge.sql
warehouse/src/main/resources/db/warehouse.sql

从本次交付开始，所有字段和索引变更同时追加到 scripts/db/incremental.sql。该文件按日期和序号只追加，已发布段落不得修改；新增字段和索引必须查询 information_schema 后再执行，禁止放入测试数据、业务数据修复、DELETE 或 TRUNCATE。

当前归档段为 001 Event Bridge、002 仓库资源、003 入库计划/PDA、 004 Event Bridge 存量字段升级、005 尾程订单投影和 006 仓库主数据注释/索引。脚本静态契约校验结果：UTF-8、614 行、45 个 PREPARE 与 45 个释放操作，未包含业务 DML，也未检测到乱码字符。

5. 验证结果

mvn -pl lastleg -am test：34 tests passed。
mvn -pl event-bridge-service -am test：15 tests passed。
mvn -pl warehouse -am test：26 tests passed。
mvn -pl gateway -am test：7 tests passed。
注入改造额外验证：integration-service 1 test passed，audit-service 编译通过。
生产代码扫描无 @Autowired、@Inject 或 Lombok 构造器注入残留；文档和 SQL UTF-8 乱码扫描通过。

6. 当前未声明完成的范围

到港、清关、拆柜、正式入库、出库、派送和签收的完整状态命令链路。
前端尾程订单页面。
权限冻结事件的海外本地投影和完整生产密钥轮换演练。
生产级 mTLS、来源网络白名单、监控告警和灾备演练。

6.3 KiB Raw Blame History Unescape Escape