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