暂存提交

event-bridge-service/AGENTS.md

@@ -2,33 +2,32 @@
 
 ## 职责边界
 
-- 负责跨区域事件接收、内部令牌保护、契约校验和 Inbox 幂等持久化。
-- 事件模型来自 `common-event-contract/`；本服务不共享国内/国外业务数据库，也不承载头程或尾程领域逻辑。
-- 真实跨区发送、重试调度和死信补投仍需按需求继续完善，不把当前接收骨架描述为完整消息平台。
+- 负责跨区事件接收、Inbox 持久化、向海外尾程投递、失败重试、投递记录和人工补投。
+- 只承载可靠传输，不执行尾程建单逻辑，不查询头程或尾程业务表。
+- 事件结构和 Payload 哈希以 `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` |
+| 接收、状态、人工补投 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` |
-| 国内装柜完成生产链 | `../firstleg/service/LoadingCompletedOutboxService.java`、`LoadingCompletedOutboxRelay.java`、`client/EventBridgeClient.java`；Payload 为 `../common-event-contract/src/main/java/com/baiyue/common/event/FirstLegLoadingPlanCompletedV1.java` |
-| 表结构 | `src/main/resources/db/event-bridge.sql` |
-| 测试 | `src/test/java/com/baiyue/eventbridge/security/`、`service/` |
-| 架构边界 | `../AGENTS.md` 的仓库边界、`../docs/头程项目目录结构与服务说明.md` 的主要调用关系与开发拆分约束 |
+| 数据库 | `src/main/resources/db/event-bridge.sql` |
+| 测试 | `src/test/java/com/baiyue/eventbridge/` |
+
+## 可靠投递规则
+
+- `RECEIVED` 和到期的 `RETRY` 都必须可被调度；只有尾程确认成功后才能标记 `PROCESSED`。
+- 每次投递保存 attempt、错误和时间；达到上限进入 `DEAD`，经授权人工补投后重新进入重试队列。
+- 领取任务必须有数据库租约/并发保护，避免多实例重复发送；尾程幂等仍是最终保障。
+- 内部接口使用 `X-Internal-Service-Token`，生产还应置于受信网络或 mTLS 后。
 
 ## 修改与验证
 
-- 先使用 `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` 直接同步当前模型、国内生产者和国外消费者，不保留旧事件兼容分支。
-- Event Bridge 只负责事件接收、校验和 Inbox 幂等，不负责用户登录或 JWT 转发；MQ 投递链路的服务身份与用户 Token 分离。
-- 从父目录运行 `mvn -pl event-bridge-service -am test`。
+- 定向验证：`mvn -pl event-bridge-service -am test`。
+- 重试相关修改至少覆盖 `RECEIVED`、`RETRY`、成功、失败、租约、最大次数和人工补投。