5.3 KiB
5.3 KiB
Common Event Contract 模块指引
职责边界
- 维护 Firstleg、Lastleg、Finance 之间稳定、可版本化的业务事件契约。
- 只放事件信封、类型、标识、规范化、哈希和校验；不放部署区域、领域 Entity、数据库模型或发送实现。
快速索引
| 功能 | 入口 |
|---|---|
| 事件信封 | src/main/java/com/baiyue/common/event/EventEnvelope.java |
| 契约校验 | EventEnvelopeValidator.java |
| 事件 ID 与业务键 | EventIdentifiers.java |
| Payload 规范化与哈希 | EventPayloadCanonicalizer.java、EventPayloadHash.java |
| 事件类型与直接目标 | EventTypes.java、EventDeliveryRoute.java；明确白名单，不按区域或默认目标分派 |
| 头程装柜完成 V3（当前生产） | FirstLegLoadingPlanCompletedV3.java 在 V2 订单快照上增加物理柜空仓、半仓、满仓、锁仓、带锁码五类不可变照片引用；订单级仍冻结 `destinationType=FBA |
| 头程装柜完成 V1 解析模型 | FirstLegLoadingPlanCompletedV1.java；用于消费端冻结字段映射，新增生产不得回退为 V1 |
| 海外卸柜完成 V1 | OverseasContainerUnloadedV1.java；按来源柜预订 ID 做柜级聚合/幂等，同一柜只发布一次，信封固定使用 tenantId=0 平台技术范围；unloadingCompletedAt 必须是全柜 complete 时刻，不得用签收拍照时刻代替；海外生产者见 ../lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/service/InboundUnloadCompletedOutboxService.java，国内消费者见 ../firstleg/src/main/java/com/baiyue/firstleg/service/OverseasContainerEventConsumer.java |
| 海外入仓单暂扣变更 V1 | OverseasInboundOrderDetainedChangedV1.java；聚合键固定为来源头程入仓单 ID，暂扣与解除暂扣均由尾程 Outbox 回传，国内按入仓单绑定、客户归属及聚合版本单调消费 |
| 海外派送完成 V1 | OverseasDeliveryCompletedV1.java、EventTypes.OVERSEAS_DELIVERY_COMPLETED；每个按 FBA 仓拆分的派送单完成后，按关联来源入仓单分别发布，携带来源订单、入仓码、FBA 仓和签收时间，国内幂等推进对应 Firstleg 入仓单与 Order 完成 |
| 国内船节点记录 V1 | FirstLegContainerShippingNodeRecordedV1.java；按 containerBookingId 柜级聚合，不携带客户，信封固定使用 tenantId=0 平台技术范围；只接受十节点中带实际时间和完整供应商审计字段的事实，国内生产者 ../firstleg/src/main/java/com/baiyue/firstleg/portschedule/service/CarrierScheduleNodeOutboxService.java，海外消费者 ../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java |
| 海外业务费用来源变更 V1 | BusinessFeeSourceChangedV1.java、EventTypes.BUSINESS_FEE_SOURCE_CHANGED；携带可独立校验入池的完整不可变客户、业务、方向、供应商、付款、来源版本与哈希快照，长整型标识使用字符串；海外生产者见 ../lastleg-service/src/main/java/com/baiyue/lastleg/financefee/，Lastleg Outbox 直接投递 finance/，Finance 不跨区同步回查 |
| 海外业务资金指令与结果 V1 | WalletCommandRequestedV1.java、WalletCommandCompletedV1.java；海外业务通过 Outbox 请求国内 Finance 冻结、结算或释放，Finance 执行后再经 Outbox 回传结果，双方以事件与业务幂等键防重，不跨区域同步调用钱包 |
| 契约说明 | package-info.java |
| 契约测试 | src/test/java/com/baiyue/common/event/EventEnvelopeTest.java、FirstLegLoadingPlanCompletedV1Test.java、FirstLegLoadingPlanCompletedV2Test.java、FirstLegLoadingPlanCompletedV3Test.java、OverseasContainerUnloadedV1Test.java、FirstLegContainerShippingNodeRecordedV1Test.java |
| 真实生产/消费验收 | ../firstleg/src/test/java/com/baiyue/firstleg/service/TaillegRealProducerAcceptanceTest.java、../lastleg-service/src/test/java/com/baiyue/lastleg/service/TaillegRealConsumerAcceptanceTest.java |
修改与验证
- 所有字段与事件类型都视为跨仓公共契约；当前正式模型不保留旧事件字段、旧版本或兼容解析，契约变化时直接修改当前模型，并同步更新 Firstleg/Lastleg/Finance 直接生产者、消费者和全部契约测试。若存在不可变外部事件契约，先单独定义版本升级规则。
- 哈希算法或规范化规则变化必须同步更新全部生产者和消费者，并保留跨语言确定性测试。
- 业务事件不携带用户 Access Token；直接投递使用内部服务身份，信封保留事件ID、业务类型/版本、客户、聚合、追踪及Payload哈希，不再包含sourceRegion/targetRegion。
OVERSEAS_CONTAINER_UNLOADED固定由Lastleg Outbox直投Firstleg，用于回传海外 PDA 卸柜完成及卸柜照片上传时间；预计报空时间规则沿用现业务实现，实际报空时间允许后续补充。- 从父目录运行
mvn -pl common-event-contract -am test。