SDK 接入服务（yidun-irisk-sdk-server）
SDK 与风机之间的数据管道：负责「收进来、存起来、发下去、查得到」，不做判定。
1. 业务定位
四件事：
| 能力 | 接口 | 说明 |
|---|---|---|
| 数据上报 | /v4/{platform}/up、/v4/j/up、/v4/c/up | 设备/行为/点击/日志等采集数据 |
| 配置下发 | /v4/c、/v4/j/c、/v4/o/c | 特征开关、采集任务、so/符号文件 |
| 数据回放 | Dubbo UploadQueryService | 风控中心与查询方按需回放采集数据 |
| 管理后台 | console/api | 项目级管理 |
判定由 yidun-intelligent-risk 完成，本服务只保证数据完整与配置可达。
2. 架构与模块划分
| 模块 | 类型 | 职责 |
|---|---|---|
common | jar | 错误码 ResultStatus、token/平台常量、加解密工具、protobuf 生成类 |
domain | jar | 领域模型、缓存模型（产品/采集任务/特征） |
service/base | jar | HBase/Kafka/NOS/Redis 组件、协议与解析 core |
service/business | jar | 各平台采集数据转换、配置与缓存服务、大字段操作 |
facade/http-upload | app | 上报接收（8 个控制器） |
facade/http-configure | app | 配置下发（15+ 策略） |
facade/dubbo-api + facade/dubbo-query | Dubbo | 回放查询契约与实现 |
console/api | app | 管理后台 |
mq | app | Kafka 消费落库 |
3. 上报链路
处理器链的顺序是协议的一部分，改动顺序会改变校验与解密的先后关系。
4. 配置下发链路
5. 存储与中间件
| 组件 | 用途 |
|---|---|
| Kafka | 上报数据投递，消费落库 |
| HBase | 采集明细宽表 |
| Redis | 短时回放数据、配置缓存 |
| NOS | 大字段（超出单条限制的采集内容） |
| MySQL | 项目管理数据 |
6. 错误码与协议约定
| 约定 | 说明 |
|---|---|
| HTTP 状态码恒为 200 | 错误通过响应体 code / msg 表达 |
| 错误码唯一来源 | 本地 com.netease.yidun.common.enums.ResultStatus，禁止引用其他包的同名类 |
| 错误码分段 | 1xxx 参数、2xxx 鉴权、3xxx 路由、4xxx 业务、5xxx 系统 |
| Upload Token | Base64 32 字符，解码 24 字节 = 签名(8) + 混合数据(16)，有效期 1 天 |
| 双协议 | Proto 与 JSON 并存，Proto 解析失败需优雅降级到 JSON |
7. 设计模式与扩展点
| 扩展点 | 位置 | 说明 |
|---|---|---|
| 处理器链 | SdkUploadProcessorChain + UpHandler 实现 | 新增校验/处理环节 |
| 平台转换 | Android/Ios/Pc/Web/Applet/Harmony/Linux CollectConvertServiceImpl | 新增端类型 |
| 配置策略 | AbstractConfigStrategy 子类 | 新增下发场景 |
| 大字段 | CollectLargeFieldOpApi | 大字段切分与 NOS 存取 |
8. 上下游依赖
| 方向 | 模块 | 说明 |
|---|---|---|
| 上游 | 各端 SDK | HTTP 上报与配置拉取 |
| 上游（配置来源） | intelligent-risk cache Dubbo | 产品/配置/采集任务缓存 |
| 上游（事件） | mplatform-event | 配置刷新事件 |
| 下游 | intelligent-risk | 通过 UploadQueryService 回放采集数据 |
9. 工程约束与变更红线
- 主链路禁止同步落库，必须投递 Kafka。
- 错误码不得跨包引用，且新增错误码要同步更新接口文档。
- 外部依赖（Redis/Apollo）失败不阻断启动，降级运行。
- Sentinel fallback 方法签名必须与原方法一致，否则降级不生效。
- 敏感配置不入库不入仓（数据库密码、密钥）。
10. 关键代码索引
| 主题 | 路径 | 说明 |
|---|---|---|
| 上报入口 | yidun-irisk-sdk-server/facade/http-upload/src/main/java/.../controller/risk/AndroidSdkRiskUploadController.java | Android 上报 |
| 处理器链 | yidun-irisk-sdk-server/service/business/src/main/java/.../processor/SdkUploadProcessorChain.java | 校验→处理→存储 |
| 上报存储 | yidun-irisk-sdk-server/service/business/src/main/java/.../storage/UpDataKafkaStorage.java | 写 Kafka |
| 配置下发 | yidun-irisk-sdk-server/facade/http-configure/src/main/java/.../controller/ConfigDeliveryController.java | 配置入口 |
| 配置策略 | yidun-irisk-sdk-server/facade/http-configure/src/main/java/.../strategy/AbstractConfigStrategy.java | 策略路由 |
| 回放查询 | yidun-irisk-sdk-server/facade/dubbo-query/src/main/java/.../provider/UploadQueryServiceImpl.java | Redis → HBase |
| MQ 落库 | yidun-irisk-sdk-server/mq/src/main/java/.../consumer/UnionDataConsumer.java | Kafka 消费 |
11. 排查要点
| 现象 | 定位 | 结论 |
|---|---|---|
| SDK 上报大量失败 | 看响应体 code 分段 | 1xxx 参数/协议、2xxx token、5xxx 服务内部 |
| 上报成功但回放查不到 | 看 Kafka 消费与 HBase 写入 | 异步落库延迟，短时可查 Redis |
| 配置拉取为空 | 看 productCode + platform + version 三者 | 版本不匹配或缓存未刷新 |
| 部分设备数据缺失 | 看大字段切分与 NOS 对象 | 大字段写入失败 |
| Proto 解析异常但业务正常 | 看是否走了 JSON 降级 | 属设计内的降级行为 |