37 lines
5.3 KiB
Markdown
37 lines
5.3 KiB
Markdown
# Common Event Contract 模块指引
|
||
|
||
## 职责边界
|
||
|
||
- 维护国内头程与国外尾程之间稳定、可版本化的事件契约。
|
||
- 只放事件信封、类型、区域、标识、规范化、哈希和校验；不放任一侧领域 Entity、数据库模型或发送实现。
|
||
|
||
## 快速索引
|
||
|
||
| 功能 | 入口 |
|
||
|---|---|
|
||
| 事件信封 | `src/main/java/com/baiyue/common/event/EventEnvelope.java` |
|
||
| 契约校验 | `EventEnvelopeValidator.java` |
|
||
| 事件 ID 与业务键 | `EventIdentifiers.java` |
|
||
| Payload 规范化与哈希 | `EventPayloadCanonicalizer.java`、`EventPayloadHash.java` |
|
||
| 事件类型与区域 | `EventTypes.java`、`RegionCode.java` |
|
||
| 头程装柜完成 V3（当前生产） | `FirstLegLoadingPlanCompletedV3.java` 在 V2 订单快照上增加物理柜空仓、半仓、满仓、锁仓、带锁码五类不可变照片引用；订单级仍冻结 `destinationType=FBA|OVERSEAS`，FBA 可按箱数接收，OVERSEAS 逐明细冻结与实装箱数一致的 SKU/箱号；国内生产者见 `../firstleg/src/main/java/com/baiyue/firstleg/service/LoadingCompletedOutboxService.java`，海外消费者见 `../lastleg-service/src/main/java/com/baiyue/lastleg/service/LoadingCompletedConsumer.java`；V1/V2 仅用于历史事件读取 |
|
||
| 头程装柜完成 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 回传结果，双方以事件与业务幂等键防重，不跨区域同步调用钱包 |
|
||
| IAM 安全事件 V1 | `IamSecurityEventsV1.java`；账号、授权快照等安全事件的冻结模型 |
|
||
| 契约说明 | `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 直接生产者、消费者和全部契约测试。若存在不可变外部事件契约，先单独定义版本升级规则。
|
||
- 哈希算法或规范化规则变化必须同步更新全部生产者和消费者，并保留跨语言确定性测试。
|
||
- MQ 事件不携带用户 Access Token；生产者和消费者使用 MQ TLS/ACL 或内部服务身份，事件信封负责事件 ID、业务键、来源/目标区域、版本和 Payload 哈希。
|
||
- `OVERSEAS_CONTAINER_UNLOADED` 固定从 `OVERSEAS` 发往 `CN`，用于回传海外 PDA 卸柜完成及卸柜照片上传时间；预计报空时间由国内头程按照片上传时间加两天计算，实际报空时间允许后续补充。
|
||
- 从父目录运行 `mvn -pl common-event-contract -am test`。
|