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

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
头程装柜完成 V2（当前生产）	FirstLegLoadingPlanCompletedV2.java；订单级冻结 `destinationType=FBA
头程装柜完成 V1 解析模型	FirstLegLoadingPlanCompletedV1.java；用于消费端冻结字段映射，新增生产不得回退为 V1
海外卸柜完成 V1	OverseasContainerUnloadedV1.java；按来源柜预订 ID 做柜级聚合/幂等，同一柜只发布一次；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	FirstLegContainerShippingNodeRecordedV1.java；只接受十节点中带实际时间和完整供应商审计字段的事实，国内生产者 ../firstleg/src/main/java/com/baiyue/firstleg/portschedule/service/CarrierScheduleNodeOutboxService.java，海外消费者 ../lastleg-service/src/main/java/com/baiyue/lastleg/shipping/service/ContainerShippingNodeConsumer.java
IAM 安全事件 V1	IamSecurityEventsV1.java；账号、授权快照等安全事件的冻结模型
契约说明	package-info.java
契约测试	src/test/java/com/baiyue/common/event/EventEnvelopeTest.java、FirstLegLoadingPlanCompletedV1Test.java、FirstLegLoadingPlanCompletedV2Test.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

修改与验证

• 所有字段与事件类型都视为跨仓公共契约；当前开发阶段不保留旧事件字段、旧版本或兼容解析，目标契约变化时直接修改当前模型，并同步更新 event-bridge-service/、国内生产者、尾程消费者和全部契约测试。
• 哈希算法或规范化规则变化必须同步更新全部生产者和消费者，并保留跨语言确定性测试。
• MQ 事件不携带用户 Access Token；生产者和消费者使用 MQ TLS/ACL 或内部服务身份，事件信封负责事件 ID、业务键、来源/目标区域、版本和 Payload 哈希。
• OVERSEAS_CONTAINER_UNLOADED 固定从 OVERSEAS 发往 CN，用于回传海外 PDA 卸柜完成及卸柜照片上传时间；预计报空时间由国内头程按照片上传时间加两天计算，实际报空时间允许后续补充。
• 从父目录运行 mvn -pl common-event-contract -am test。