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
契约说明	package-info.java
兼容性测试	src/test/java/com/baiyue/common/event/EventEnvelopeTest.java

修改与验证

• 所有字段与事件类型都视为跨仓公共契约；优先新增可选字段和新版本，禁止无迁移直接改名、改语义或删除。
• 同步检查 event-bridge-service/、国内生产者以及固定 BOM 版本的尾程消费者。
• 哈希算法或规范化规则变化必须保留跨语言、跨版本确定性测试。
• 从父目录运行 mvn -pl common-event-contract -am test。