baiyue-firstleg/event-bridge-service/AGENTS.md

Event Bridge Service 模块指引

职责边界

• 负责跨区域事件接收、内部令牌保护、契约校验和 Inbox 幂等持久化。
• 事件模型来自 common-event-contract/；本服务不共享国内/国外业务数据库，也不承载头程或尾程领域逻辑。
• 真实跨区发送、重试调度和死信补投仍需按需求继续完善，不把当前接收骨架描述为完整消息平台。

快速索引

功能	入口
应用入口	src/main/java/com/baiyue/eventbridge/EventBridgeApplication.java
事件接收与状态 API	controller/EventBridgeController.java（/internal/event-bridge）
接收结果与状态 DTO	dto/EventReceiveResult.java、BridgeStatus.java
校验与 Inbox 编排	service/EventInboxService.java
Inbox 抽象与 MyBatis 实现	service/InboxStore.java、MybatisInboxStore.java
Inbox 数据模型	domain/BridgeInbox.java、mapper/BridgeInboxMapper.java
内部服务令牌	security/InternalServiceTokenGuard.java
表结构	src/main/resources/db/event-bridge.sql
测试	src/test/java/com/baiyue/eventbridge/security/、service/
架构边界	../AGENTS.md 的仓库边界、../docs/头程项目目录结构与服务说明.md 的主要调用关系与开发拆分约束

修改与验证

• 先使用 common-event-contract 校验事件 ID、区域、版本、业务键、时间与 Payload 哈希，再执行幂等入库。
• 重复事件应返回稳定结果且不重复产生副作用；数据库唯一约束与应用幂等逻辑要同步。
• 跨区域接口必须鉴权、限流并最小化载荷，禁止携带密钥或非必要客户敏感数据。
• Event Bridge 内部令牌失败和接收基础设施不可用属于统一 HTTP 200 业务契约的明确例外，保留真实 401/503；已经通过 Controller 进入公共异常处理的普通业务失败才使用 HTTP 200 + body code。
• 本服务只扫描 com.baiyue.eventbridge，统一异常和 Correlation 能力依赖 common-web/CommonWebAutoConfiguration 自动装配；调整公共 Web 配置后追加本模块上下文测试。
• 契约变化先遵守 ../common-event-contract/AGENTS.md 的兼容规则，并检查国内外消费者。
• 从父目录运行 mvn -pl event-bridge-service -am test。