智能风控检测（yidun-intelligent-risk）
产品的「正面」：所有实时检测请求在这里被接住，构建上下文、跑判定链、组装处置结果、异步落库。
1. 业务定位
一次用户行为（登录、注册、下单、领券、充值、游戏对局）是否来自黑产，最终在这里给出答案：风险等级 + 命中规则/风险标签 + 处置动作。
- 上游：外部调用经 API 网关路由进来；各端 SDK 直接调用
/v4/*/q检测接口；内部系统走/v1/inner/*。 - 下游：处置动作直接影响用户能否继续操作；检测明细经 Kafka 落入 ES/ClickHouse，供运营后台处置与报表统计。
2. 架构与模块划分
| 子模块 | 类型 | 职责 |
|---|---|---|
common | jar | 枚举（ResultStatus、RiskLevelEnum、ExecuteStatus）、常量、工具 |
domain | jar | 领域模型：上下文 AbstractCheckContext、BO/DO |
service/base | jar | DAO、Manager、缓存、外部接口封装 |
service/business | jar | 核心业务：上下文创建、处理链、判定与响应组装 |
facade/http-open-api | app | 对外开放检测 API（v4/v5/v6） |
facade/http-inner-api | app | 内部查询 API |
facade/http-check-api | app | SDK 检测 API |
management/admin、management/console | app | 内部管理后台、客户控制台 |
cache | Dubbo | 缓存服务（产品/配置/策略元数据） |
execute | Dubbo | 判定执行服务 |
query | Dubbo | 明细查询服务 |
scheduler | app | Elastic-Job 定时统计 |
mq | app | Kafka 消费落库 |
offline | app | 离线批处理（团伙、AI 反打金、渠道反作弊） |
分层：协议层 facade → 上下文层 CheckContextCreator → 逻辑层 CheckProcessService（handler 链）→ 数据层 mq/offline/cache。
3. 核心链路
执行引擎 CheckBaseProcessImpl 的规则：
- 每个处理器实现
CheckHandlerService，按before → handle → after三段执行。 - 上下文的
resultStatus一旦不是SUCCESS，立即短路后续处理器，直接进入响应组装。 - 处理器链的顺序写在
@Bean配置里（OpenCheckProcessImpl/SdkCheckProcessImpl），顺序即业务语义。
上下文 AbstractCheckContext 携带四类数据：
| 数据 | 含义 |
|---|---|
Input | 请求原始数据（业务字段、设备信息、签名材料） |
CheckBo | 过检前（pre）与过检后（post）的判定结果 |
Output | 最终响应对象 |
AttachedData | 过程状态，如 resultStatus、耗时打点 |
4. API 版本策略
| 版本 | 入口 | 状态 |
|---|---|---|
| v6 | RiskOpenCheckControllerV6 | 当前主用 |
| v5 | RiskOpenCheckController | 稳定，仍有存量客户 |
| v4 | IRiskOpenCheckController | 遗留，仅维护 |
改动任何一个版本的字段语义都必须向后兼容，且 SDK 与服务端要同步发版。
5. 存储与中间件
| 组件 | 用途 |
|---|---|
| MySQL | 产品配置、风险明细元信息、管理后台数据 |
| Elasticsearch 7.17 | 检测明细检索、风险画像查询 |
| Redis | 令牌、限流、热点配置缓存 |
| Kafka | 检测明细异步落库、命中统计 |
| ClickHouse | 离线分析与看板统计 |
| Apollo | 动态配置刷新（ApolloRefreshBaseConfig） |
| Sentinel | 接口级限流降级 |
6. 设计模式与扩展点
| 模式 | 落点 | 怎么扩展 |
|---|---|---|
| 责任链 | CheckHandlerService 链 | 新增检测能力 = 新增处理器 + 加入对应 ProcessorChain 的 Bean 列表 |
| 模板方法 | AbstractCheckContextCreator | 新接入形态继承并实现上下文构建步骤 |
| 策略 | 各平台 ES 查询服务（Mobile/PC/Web/API/Applet） | 新增平台实现对应策略类 |
| 上下文对象 | AbstractCheckContext | 全链路传参，禁止在处理器间用静态变量传状态 |
7. 上下游依赖
| 方向 | 模块 | 契约 |
|---|---|---|
| 下游 | mplatform-strategy | Dubbo 策略执行（contract v4/v5），是本服务最核心依赖 |
| 下游 | mplatform-business | 业务与套餐可用性、strategyConfigCode |
| 下游 | mplatform-meta | 风险标签定义缓存 MetaRiskTagDefCache |
| 下游 | mplatform-clickhouse | 检测明细与看板统计 |
| 下游 | union-admin | 操作日志、权限缓存 |
| 下游 | irisk-sdk-server | SDK 采集数据回放查询 |
| 上游 | api-gateway | 路由与鉴权 |
8. 工程约束与变更红线
- 处理器链顺序不可随意调整：顺序变化会改变短路点与字段可用性，表现为「某些条件突然取不到值」。
- 主链路禁止同步重存储：明细落库必须走 Kafka，否则高峰期拖垮检测服务。
- 禁止在判定线程内同步写名单：命中加名单走 Kafka 异步动作。
- 新增枚举值必须评估下游反序列化：
ResultStatus等错误码被 SDK 与客户系统依赖。 - 版本兼容：v4/v5/v6 并存，字段增删只能加不能改语义。
9. 关键代码索引
| 主题 | 路径 | 说明 |
|---|---|---|
| 最新开放检测入口 | yidun-intelligent-risk/facade/http-open-api/src/main/java/.../controller/RiskOpenCheckControllerV6.java | v6 控制器 |
| 上下文基类 | yidun-intelligent-risk/domain/src/main/java/.../bo/context/AbstractCheckContext.java | 全链路上下文 |
| 上下文创建 | yidun-intelligent-risk/service/business/src/main/java/.../checkcontext/contextcreator/OpenCheckContextCreator.java | 开放检测上下文构建 |
| 处理链引擎 | yidun-intelligent-risk/service/business/src/main/java/.../check/CheckBaseProcessImpl.java | 责任链执行与短路 |
| 风险等级 | yidun-intelligent-risk/common/src/main/java/.../enums/RiskLevelEnum.java | 等级定义 |
| 错误码 | yidun-intelligent-risk/common/src/main/java/.../enums/ResultStatus.java | 响应状态码 |
| 明细落库 | yidun-intelligent-risk/mq/src/main/java/.../CheckDetailSinkEsConsumer.java | Kafka 消费入库 |
10. 排查要点
| 现象 | 定位 | 结论 |
|---|---|---|
| 响应返回但无判定结果 | 看上下文 resultStatus 与短路点 | 某个 before 处理器就中断了（签名、业务校验、白名单） |
| 风险等级始终为无风险 | 确认策略执行是否被调用 | 策略集未绑定/未上线，或判定被前置校验跳过 |
| 新加的检测能力不生效 | 检查处理器是否加入链 | 只实现未注册，链里没有它 |
| 明细查不到 | 看 Kafka 投递与消费 | 投递失败或消费堆积，与判定逻辑无关 |