接入与使用指南
一个新客户从「买了产品」到「线上跑通检测」要经过：开通业务 → 生成策略 → 接入端侧 → 联调验证 → 上线观测。本篇按这个顺序讲，每一步都给出「在哪做、做什么、怎么验证」。
1. 开通阶段：业务、产品、SKU、套餐
| 步骤 | 操作位置 | 产出 | 验证方式 |
|---|---|---|---|
| 1. 建产品与 SKU | 业务中台（mplatform-business）的产品/SKU 管理 | 产品编码、SKU 编码、能力开关 | 产品列表可查、SKU 状态为可用 |
| 2. 开通业务 | 业务中台新增业务，绑定产品与 SKU | businessCode（全局唯一） | 业务状态 OPEN |
| 3. 绑定套餐 | 业务绑定主套餐与备用套餐 | 套餐生效时间、到期时间 | 套餐状态 EFFECT，到期时间正确 |
| 4. 生成密钥 | 产品密钥管理 | secretKey 等签名材料 | 用密钥能算出通过校验的签名 |
关键概念：
- 业务状态只有
OPEN(1)/CLOSE(0)；关闭原因区分「正常关闭」与「套餐失效」。 - SKU 状态决定能力是否可用：
AVAILABLE(900)可用、ON_TRIAL(800)试用中、END_SERVICE(700)服务终止。 - 套餐状态：
EFFECT(1)生效、WAITING_EFFECT(3)待生效、INVALID(2)失效。 - 业务开通后，策略中台会通过事件驱动流水线（
EventTriggeredPipelineExecutor）自动初始化默认策略集与规则，不需要人工从零搭建。这是「新业务为什么一开始就有策略」的原因。
2. 配置阶段：把判定标准写下来
2.1 数据预处理（可选，但大多数场景需要）
用途：请求字段太脏或太单薄时，先做校验、归一化、富化。
| 配置类型 | 例子 |
|---|---|
| 校验 | 手机号格式、身份证校验位 |
| 归一化 | 去除空格、统一大小写、手机号去 +86 |
| 富化 | 手机号归属地、IP 归属地、设备画像、名单回查 |
| 脚本 | Groovy 自定义变换 |
配置完成后，执行结果会写回上下文 prepro.* 字段，供后续条件引用。
2.2 名单（黑白名单）
模型是 名单组（ListGroup）→ 名单项（ListItem），再由 名单匹配器（ListChecker） 描述「从哪个字段取值、查哪个名单组、结果写回哪个字段」。
使用要点：
- 白名单优先于黑名单生效，配置时注意匹配器执行顺序。
- 名单项支持到期自动释放，适合临时性封禁。
- 名单执行侧只读 Redis，配置落库后需要等缓存同步任务写入才生效。
2.3 指标（统计口径）
用途：把「近 1 小时登录次数」「同设备今日关联账号数」这类统计量定义成指标，供条件直接比较。
配置步骤：选择统计对象 → 选择窗口（滑动/固定）→ 选择聚合函数（次数、去重数、求和等）→ 配置过滤条件 → 生成指标编码。
2.4 规则与规则集
一条规则 = 条件组合 + 命中后的动作。条件支持 AND / OR / 命中 N 条 / 自定义表达式。
规则生命周期：
预上线不等于生效
预上线（PRE_ONLINE）阶段的规则只产生「试命中」结果，会出现在命中明细里，但不影响最终处置。新规则必须上线才会真正拦截。这是排查「规则明明命中却放行了」的第一检查点。
2.5 策略与策略集
- 策略集分通用（所有客户共用模板）与私有（客户自建）。
- 策略集有执行模式：常规（判定前）与后置。
- 通用与私有策略集并发执行，各自有超时，任一超时只降级该策略集。
3. 端侧接入阶段
3.1 Web / App：SDK 接入
| 环节 | 接口 | 说明 |
|---|---|---|
| 设备指纹上报 | 设备指纹上传接口（/v1/ad/d 等） | 上报加密设备信息，服务端返回 sid |
| SDK 数据上报 | 智能风控 SDK 上报（/v4/{platform}/up） | 行为、点击、日志等采集数据 |
| 配置拉取 | /v4/c、/v4/j/c 等 | 拉特征开关、采集任务、字段配置 |
| 风险检测 | /v4/{platform}/q 或开放检测接口 | 传入 businessCode 与业务字段，拿判定结果 |
接入顺序建议：先接设备指纹拿 sid → 再接 SDK 数据上报 → 最后接检测接口。因为检测依赖 sid 与画像数据，顺序反了会出现「设备维度条件始终不命中」。
3.2 服务端：开放 API 接入
服务端场景不依赖客户端 SDK，直接调用开放检测接口（v6 为当前版本，v5 稳定版本仍在用，v4 为遗留版本）。
必须携带：businessCode、签名（由 secretKey 计算）、业务字段、设备或账号标识。回包包含风险等级、命中标签与建议处置。
4. 联调阶段：怎么确认接对了
按顺序做四件事，每件都有明确的成功标志：
| 检查 | 方法 | 成功标志 |
|---|---|---|
| 1. 请求是否到达 | 看网关访问日志与检测服务入口日志 | 有对应 businessCode 的请求记录 |
| 2. 上下文是否构建 | 看检测链路 trace | 上下文里有设备、账号、业务字段 |
| 3. 判定是否执行 | 看策略执行日志/trace | 目标策略集被执行，非「跳过/无可用策略」 |
| 4. 处置是否符合预期 | 看检测明细与回包 | 风险等级、命中规则与配置一致 |
常见联调失败原因（按出现频率排序）：
- 签名算法不一致或时间戳过期 → 网关直接拒绝。
businessCode填错或业务未开通/套餐过期 → 检测服务返回业务不可用。- 字段名与元数据定义不一致 → 条件取值为空，规则永远不命中。
- 只在预上线规则上验证 → 看到命中但回包无处置。
5. 上线阶段：观测与调优
上线后必须盯住三类指标：
| 类别 | 指标 | 异常含义 |
|---|---|---|
| 可用性 | 请求量、成功率、耗时 P99 | 耗时上涨通常是 checker 超时或缓存未命中 |
| 判定质量 | 命中率、误拦截投诉、规则命中分布 | 命中率突变先查规则上线与名单同步 |
| 数据完整性 | 明细落库量、数据仓入仓量 | 缺口通常是 Kafka 消费堆积或写入失败 |
调优的常规动作：先用预上线观察新规则命中情况，确认不误伤再上线；对高频误判名单项设置到期时间；对性能敏感场景减少同步指标数量，把非关键指标改为异步。