baiyue-firstleg/common-event-contract/AGENTS.md

Common Event Contract 模块指引

数据库访问与中文注释约束

• 强制继承 ../AGENTS.md 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。

职责边界

• 维护 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。