添加快速索引文件

common-event-contract/AGENTS.md

@@ -0,0 +1,25 @@
+# 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`。