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

Event Bridge Service 模块指引

职责边界

• 负责跨区事件接收、Inbox 持久化、向海外尾程投递、失败重试、投递记录和人工补投。
• 只承载可靠传输，不执行尾程建单逻辑，不查询头程或尾程业务表。
• 事件结构和 Payload 哈希以 common-event-contract 为准。

快速索引

功能	入口
接收、状态、人工补投 API	src/main/java/com/baiyue/eventbridge/controller/EventBridgeController.java
Inbox 接收与幂等	service/EventInboxService.java
海外调度与重试	service/OverseasEventDispatcher.java
尾程 HTTP 客户端	service/LastlegEventClient.java、HttpLastlegEventClient.java
人工补投	service/EventReplayService.java
Inbox 与投递记录	domain/BridgeInbox.java、BridgeDeliveryAttempt.java 及对应 Mapper
内部服务令牌	security/InternalServiceTokenGuard.java
数据库	src/main/resources/db/event-bridge.sql
测试	src/test/java/com/baiyue/eventbridge/

可靠投递规则

• RECEIVED 和到期的 RETRY 都必须可被调度；只有尾程确认成功后才能标记 PROCESSED。
• 每次投递保存 attempt、错误和时间；达到上限进入 DEAD，经授权人工补投后重新进入重试队列。
• 领取任务必须有数据库租约/并发保护，避免多实例重复发送；尾程幂等仍是最终保障。
• 内部接口使用 X-Internal-Service-Token，生产还应置于受信网络或 mTLS 后。

修改与验证

• 定向验证：mvn -pl event-bridge-service -am test。
• 重试相关修改至少覆盖 RECEIVED、RETRY、成功、失败、租约、最大次数和人工补投。