事件中台（yidun-mplatform-event）
所有「配置变更」的统一分发通道：写一条当前态、记一条流水，下游自己来增量拉。
1. 业务定位
解决「源系统的数据变更如何被下游实时、增量、最终一致地感知」，避免下游直连各中台数据库。
写入方（EventSourceService 枚举）：业务中台、元数据中台、结算中台、SaaS 平台、反垃圾结算、统一运营后台。
读取方：智能风控、设备指纹等通过客户端 SDK 订阅。
2. 架构与模块划分
| 模块 | 类型 | 职责 |
|---|---|---|
common、domain | jar | EventData、OperateType、EventSourceService、DO/BO |
service/base、service/business | jar | DAO/Manager、EventDataInfoServiceImpl |
facade/dubbo-api + dubbo-provider | Dubbo | EventDataInfoFacade 写入 |
facade/http-api | app | EventController 增量拉取 + RocksDB 缓存 |
client/core | jar | 客户端 SDK：拉取、总线、本地存储 |
client/plugin | jar | 监听插件与缓存索引 |
client/spring-boot-starter | jar | @EnableEventClient 自动装配 |
两条链：写入链（Dubbo/HTTP → Service → Manager/DAO）与读取链（HTTP init/fetch → 缓存管理器 → RocksDB/内存队列）。
3. 核心链路
三个设计要点：
- 当前态 + 流水双表：
event_data_info保存最新状态，event_data_operate_record保存每次变更，下游按流水增量拉取。 - 乐观锁更新：并发写入不会互相覆盖，冲突可感知。
- 操作记录在事务提交后写并重试：保证「数据变更一定有流水」，即使失败也会重试 3 次。
4. 关键数据模型
| 表/对象 | 说明 |
|---|---|
event_data_info | 当前态：业务标识、数据类型、数据体、版本 |
event_data_operate_record | 变更流水：操作类型、时间、来源服务 |
OperateType | 新增 / 修改 / 删除 |
EventSourceService | 来源服务枚举，决定数据归属 |
5. 存储与中间件
| 组件 | 用途 |
|---|---|
| MySQL | 事件当前态与流水 |
| RocksDB | HTTP 侧事件缓存持久化（RocksdbStorage） |
| 内存队列 | 缓存批量刷新 |
| MmapStorage | 客户端本地存储（当前仅 MMAP 类型） |
6. 设计模式与扩展点
| 扩展点 | 位置 | 说明 |
|---|---|---|
| 客户端插件 | EventListenerPlugin（SPI PluginLoader） | doListen / doFilter 钩子 |
| 本地存储 | StorageType 枚举 | 当前 MMAP，可扩展异步存储 |
| 生命周期 | EventClientState | UNINITIALIZED → INITIALIZING → INITIALIZED → STARTING → RUNNING → STOPPED → DESTROYING → DESTROYED，状态迁移有强校验 |
7. 上下游依赖
| 方向 | 模块 | 说明 |
|---|---|---|
| 上游 | mplatform-business、mplatform-meta、union-admin、intelligent-risk、device-fingerpint | 写入事件 |
| 下游 | intelligent-risk、device-fingerpint 等 | 客户端 SDK 订阅拉取 |
8. 工程约束与变更红线
save语义不能改：增删改的判定直接影响下游缓存正确性。- 操作记录写失败必须可感知：流水缺失意味着下游永远收不到这次变更。
fetch的时间保护与队列逻辑不能随意改：会导致下游拉到重复或超量数据。- 客户端状态迁移必须强校验：非法迁移会引发并发拉取与缓存错乱。
- 禁止下游直连源系统数据库：这是整套架构的前提。
9. 关键代码索引
| 主题 | 路径 | 说明 |
|---|---|---|
| 写入服务 | yidun-mplatform-event/service/business/src/main/java/.../impl/EventDataInfoServiceImpl.java | save 语义与乐观锁 |
| Dubbo 入口 | yidun-mplatform-event/facade/dubbo-provider/src/main/java/.../EventDataInfoProvider.java | 对外契约 |
| HTTP 拉取 | yidun-mplatform-event/facade/http-api/src/main/java/.../controller/EventController.java | init/fetch |
| 缓存管理 | yidun-mplatform-event/facade/http-api/src/main/java/.../cache/EventCacheManager.java | 刷新与增量 |
| 客户端核心 | yidun-mplatform-event/client/core/src/main/java/.../EventHttpClient.java | 拉取与分发 |
| 自动装配 | yidun-mplatform-event/client/spring-boot-starter/src/main/java/.../EnableEventClient.java | 下游接入 |
10. 排查要点
| 现象 | 定位 | 结论 |
|---|---|---|
| 下游配置一直不更新 | 查 event_data_info 是否有新记录 | 源系统没发事件 |
| 有当前态但下游收不到 | 查 operate_record 是否有流水 | 流水写失败，等重试或补推 |
| 下游收到乱序/重复 | 查客户端游标与 fetch 时间保护 | 游标被重置或并发拉取 |
| 客户端启动缓慢 | 看 init 全量数据量与 RocksDB 加载 | 首次初始化数据量大属正常 |
| 多处缓存不一致 | 对比各下游最后同步时间 | 部分实例事件订阅未生效 |