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
头程装柜完成 V1	FirstLegLoadingPlanCompletedV1.java；国内生产者见 ../firstleg/service/LoadingCompletedOutboxService.java
契约说明	package-info.java
契约测试	src/test/java/com/baiyue/common/event/EventEnvelopeTest.java、FirstLegLoadingPlanCompletedV1Test.java

修改与验证

• 所有字段与事件类型都视为跨仓公共契约；当前开发阶段不保留旧事件字段、旧版本或兼容解析，目标契约变化时直接修改当前模型，并同步更新 event-bridge-service/、国内生产者、尾程消费者和全部契约测试。
• 哈希算法或规范化规则变化必须同步更新全部生产者和消费者，并保留跨语言确定性测试。
• MQ 事件不携带用户 Access Token；生产者和消费者使用 MQ TLS/ACL 或内部服务身份，事件信封负责事件 ID、业务键、来源/目标区域、版本和 Payload 哈希。
• 从父目录运行 mvn -pl common-event-contract -am test。