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

Event Bridge Service 模块指引

职责边界

• Mapper 只由 EventBridgeApplication.java 对 com.baiyue.eventbridge 根包按 @Mapper 过滤扫描；新增或移动 Mapper 后从后端根运行 node scripts/mapper-scan-contract.mjs，不得增加子域扫描配置。
• 负责跨区事件接收、Inbox 持久化、按目标区域向海外尾程或国内头程投递、失败重试、投递记录和人工补投。
• 只承载可靠传输，不执行尾程建单逻辑，不查询头程或尾程业务表。
• 事件结构和 Payload 哈希以 common-event-contract 为准。

快速索引

功能	入口
接收、状态、人工补投 API	src/main/java/com/baiyue/eventbridge/controller/EventBridgeController.java
Inbox 接收与幂等	service/EventInboxService.java
按目标区域调度与重试	service/OverseasEventDispatcher.java；targetRegion=CN 的 BUSINESS_FEE_SOURCE_CHANGED 与 WALLET_COMMAND_REQUESTED 定向投 Finance，其余国内回投 Firstleg；海外业务事件及 WALLET_COMMAND_COMPLETED 投 Lastleg 通用入口，三类 IAM 安全事件按 eventType 投 Lastleg /internal/lastleg/security/v1/events，传输层不解析 payload
尾程 HTTP 客户端	service/LastlegEventClient.java、HttpLastlegEventClient.java
国内头程 HTTP 客户端	service/FirstlegEventClient.java、HttpFirstlegEventClient.java；默认内部入口 /internal/firstleg/v1/container-events
国内 Finance 事件客户端	service/FinanceEventClient.java、HttpFinanceEventClient.java；费用入口 /internal/finance/v1/business-fee-source-events，资金指令入口 /internal/finance/v1/wallet-command-events，分别配置 finance-consumer-url、finance-wallet-consumer-url，不得误投 Firstleg
人工补投	service/EventReplayService.java；只允许 DEAD 转回 RETRY，记录操作人与原因，并保留原 eventId、payload 与 payloadHash
Inbox 与投递记录	domain/BridgeInbox.java、BridgeDeliveryAttempt.java 及对应 Mapper
传输指标与 Inbox 采样	metrics/EventBridgeMetrics.java、EventBridgeInboxMetricsSampler.java；SLO 与告警合同 docs/development-observability-slo.md
事件 Trace 与原始 HTTP 传播	trace/EventBridgeTraceScope.java、EventBridgeHttpTracePropagation.java；契约与已知缺口 docs/event-trace-propagation.md
内部服务令牌	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 后。
• 指标标签只允许有限 target_region、event_type、result，未知区域/类型折叠为 OTHER，禁止 eventId、customerId、错误消息等高基数标签。Inbox 聚合按现有状态索引定时采样，Prometheus scrape 不得查询数据库；开发阶段 SLO/告警只代表代码合同，不代表监控平台已部署。
• 投递线程只从 Inbox 已冻结 trace_id 建立 MDC；合法 32 位 trace ID 或规范 UUID 可贯通，非法历史值安全重建。每次 JDK HttpClient 投递生成 child span，并覆盖三类标准 Trace 头；不得把 correlationId、eventId、customerId、聚合 ID、JWT 或内部令牌写入 Trace 字段。

修改与验证

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