baiyue-firstleg/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；targetRegion=OVERSEAS 投 Lastleg，targetRegion=CN 回投 Firstleg
尾程 HTTP 客户端	service/LastlegEventClient.java、HttpLastlegEventClient.java
国内头程 HTTP 客户端	service/FirstlegEventClient.java、HttpFirstlegEventClient.java；默认内部入口 /internal/firstleg/v1/container-events
人工补投	service/EventReplayService.java；只允许 DEAD 转回 RETRY，记录操作人与原因，并保留原 eventId、payload 与 payloadHash
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、成功、失败、租约、最大次数和人工补投。