数据预处理（yidun-checker-preprocess）
判定之前先把「脏数据」洗成「可比对的数据」：校验、归一化、富化，结果统一写进
prepro.*。
1. 业务定位
策略与规则拿到的原始字段往往不可直接比较：
| 问题 | 预处理动作 |
|---|---|
格式不统一（手机号带 +86、带空格） | 归一化 |
| 缺少判断依据（不知道 IP 归属地） | 富化（IP/号码/地址/画像/名单） |
| 需要复杂变换 | Groovy 脚本 |
| 字段本身不可信 | 校验（格式、证件校验位） |
每套策略通过 预处理编码（prepareKey） 引用一组预处理配置，执行后结果合并回上下文 prepro.*。
2. 架构与模块划分
| 模块 | 类型 | 职责 |
|---|---|---|
common | jar | 错误码、CommandTypeEnum、Groovy/号码/证件工具 |
domain | jar | DO/BO |
service/base、service/business | jar | DAO/缓存、配置 CRUD 业务 |
console/dubbo-api + dubbo-provider | Dubbo | 配置与脚本生命周期管理 |
execution/dubbo-api + dubbo-provider | Dubbo | 执行引擎 PreproExecutionProvider |
分层：管理面（console → business → base）与执行面（execution → command → 外部数据源）分离，公共层 common。
3. 核心链路
三条执行纪律：
- 执行期不查 DB：配置与脚本都来自本地缓存（
PreprocessCache/PreprocessScriptCache）。 - 并发 + 总超时：多个预处理任务并发执行，单次执行有 300ms 上限，超时降级不阻塞判定。
- 统一转型：所有命令结果按元数据字段类型转换，避免类型错乱传到规则层。
4. 命令体系
CommandTypeEnum 定义了 44 种命令类型，按语义分四类：
| 类别 | 典型命令 | 用途 |
|---|---|---|
| 校验 | 手机号、身份证、邮箱格式校验 | 过滤脏数据 |
| 变换 | 截取、拼接、四则运算、脱敏 | 构造新字段 |
| 富化 | IP 归属地、号码归属地、地址解析、画像查询、名单回查 | 补足判断依据 |
| 脚本 | Groovy 脚本执行 | 自定义逻辑 |
所有命令继承 AbstractPreChecker：统一参数解析（字段 code / 字段 path / 常量）→ 大小限制校验 → 执行 → 类型转换。
5. 存储与中间件
| 组件 | 用途 |
|---|---|
| MySQL | 预处理配置、Groovy 脚本、模板 |
| 本地缓存 | 配置与脚本（启动加载 + 变更刷新） |
| Redis | 部分命令的中间缓存 |
| Groovy 引擎 | 脚本沙箱编译执行（executeWithCache） |
6. 设计模式与扩展点
| 扩展点 | 位置 | 说明 |
|---|---|---|
| 命令类型 | CommandTypeEnum + *Command 类 | 新增能力 = 新增枚举 + 实现类 + 前端配置项 |
| 外部数据源 | command/service/* | 新增数据源需实现统一查询接口 |
| 脚本 | PreprocessScriptManagementService | 脚本版本管理、操作日志 |
| 模板 | 配置模板 | 批量套用常见预处理组合 |
7. 上下游依赖
| 方向 | 模块 | 说明 |
|---|---|---|
| 上游 | mplatform-strategy | 判定前按策略的 preproCodes 调用 |
| 上游 | checker-rule | 规则执行前置富化 |
| 上游 | device-fingerpint | 设备业务自建预处理配置 |
| 下游 | mplatform-meta | 字段定义（fieldCode → jsonPath、类型） |
| 下游 | union-admin | 配置与脚本变更操作日志 |
| 下游 | Groovy 组件 | 脚本沙箱执行 |
8. 工程约束与变更红线
- 超时是硬约束：任何命令都不能长时间阻塞，外部查询必须设超时。
- 类型转换必须走元数据：绕过
MetaFieldTypeEnum会造成规则条件类型不匹配。 - 脚本必须沙箱执行：禁止在脚本中访问文件系统/网络。
- 配置与脚本要留操作日志：预处理是最容易被误改的配置之一。
field/sql版本化：表结构变更必须同步提交 SQL，否则部署建表失败。
9. 关键代码索引
| 主题 | 路径 | 说明 |
|---|---|---|
| 执行入口 | yidun-checker-preprocess/execution/dubbo-provider/src/main/java/.../PreproExecutionProvider.java | Dubbo 执行 |
| 执行核心 | yidun-checker-preprocess/execution/dubbo-provider/src/main/java/.../service/DataPreproChecker.java | 取配置、并发执行、合并 |
| 命令基类 | yidun-checker-preprocess/execution/dubbo-provider/src/main/java/.../command/AbstractPreChecker.java | 参数解析与转型 |
| 命令类型 | yidun-checker-preprocess/common/src/main/java/.../enums/CommandTypeEnum.java | 44 种命令字典 |
| 配置缓存 | yidun-checker-preprocess/execution/dubbo-provider/src/main/java/.../cache/PreprocessCache.java | 执行侧缓存 |
| 管理服务 | yidun-checker-preprocess/service/business/src/main/java/.../DataPretreatmentServiceImpl.java | 配置 CRUD |
10. 排查要点
| 现象 | 定位 | 结论 |
|---|---|---|
| 规则条件取值为空 | 看 trace 里 prepro.* 是否产出 | 预处理未配置、执行超时被降级，或字段 code 错 |
| 字段类型不匹配 | 看元数据里字段类型定义 | 命令输出类型与字段定义不一致 |
| 预处理整体变慢 | 看任务耗时与外部数据源 | 富化类命令超时，检查对外部服务的调用 |
| 脚本改动不生效 | 看脚本缓存版本 | 脚本缓存未刷新 |
| 改了配置但结果不变 | 看配置缓存最后刷新时间 | 执行侧未加载新配置 |