# 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`。