41 lines
3.9 KiB
Markdown
41 lines
3.9 KiB
Markdown
# 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`、成功、失败、租约、最大次数和人工补投。
|