# Kylin Risk Engine

> 麒麟游戏 — 游戏风控引擎扩展包

游戏风控引擎，提供设备指纹采集、评分卡规则引擎、决策路由、黑白名单、人脸复核触发功能，符合游戏行业防沉迷与反欺诈要求。

## 功能特性

### 设备指纹
- 设备指纹采集与聚合
- 多设备账号切换检测
- 异常设备识别

### 评分卡规则引擎
- v1 内置 6 条规则，可配置扩展
- 规则命中评分聚合
- 风险分数计算

### 决策路由
- `RiskDecision` 枚举决策：`pass` / `observe` / `face_required` / `lockout`
- 分数阈值可配置
- 决策结果审计记录

### 黑白名单
- `BlackWhiteList` 模型，支持 IP/设备/账号维度
- 黑名单自动拦截
- 白名单免检通过

### 人脸复核
- `FaceVerificationService` 人脸验证触发
- 高风险用户强制人脸复核
- 支持多供应商（腾讯/阿里/百度）

### 风险事件
- `RiskEvent` 风险事件记录
- `RiskEventType` 事件类型分类
- 事件链路追溯

## 安装

```bash
composer require kylin/risk_engine
php artisan vendor:publish --tag=kylin-risk-engine-config
php artisan vendor:publish --tag=kylin-risk-engine-migrations
php artisan migrate
```

## 使用示例

### 风险评估

```php
use Kylin\RiskEngine\Facades\KylinRiskEngine;

// 风险评估
$result = KylinRiskEngine::evaluate(123, [
    'device_account_switch_count' => 4,
    'ip_registrations_24h_count'  => 6,
]);

// 返回结构
// [
//     'score' => 50,
//     'decision' => 'observe',  // pass|observe|face_required|lockout
//     'hits' => [
//         ['rule' => 'multi_device_switch', 'score' => 30],
//         ['rule' => 'multi_ip_registration', 'score' => 20],
//     ],
// ]
```

### 黑白名单管理

```php
use Kylin\RiskEngine\Models\BlackWhiteList;

// 添加黑名单
BlackWhiteList::create([
    'type' => 'black',
    'dimension' => 'ip',
    'value' => '192.168.1.100',
    'reason' => '异常注册',
    'expires_at' => now()->addDays(30),
]);

// 检查是否在黑名单
$isBlocked = BlackWhiteList::isBlacklisted('ip', '192.168.1.100');
```

### 人脸复核触发

```php
use Kylin\RiskEngine\Services\FaceVerificationService;

// 触发人脸验证
$result = $faceService->verify($userId, $referenceImage, $liveImage, true);

// 标记用户已完成人脸复核（24 小时有效）
$faceService->markVerified($userId);

// 检查用户是否已完成人脸复核
if (! $faceService->hasVerified($userId)) {
    // 引导用户进行人脸复核
}
```

### API 路由

所有路由需通过 `auth:sanctum` 鉴权。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/kylin/risk-engine/evaluate | 风险评估 |
| GET | /api/kylin/risk-engine/cached-score | 获取缓存的风险评分 |
| POST | /api/kylin/risk-engine/face/verify | 人脸复核 |
| GET | /api/kylin/risk-engine/face/status | 检查人脸复核状态 |
| GET | /api/kylin/risk-engine/list | 黑白名单查询 |
| POST | /api/kylin/risk-engine/list | 添加黑白名单 |
| DELETE | /api/kylin/risk-engine/list/{id} | 删除黑白名单条目 |

## 数据库表

| 表名 | 说明 |
|------|------|
| `kylin_risk_events` | 风险事件记录表 |
| `kylin_risk_black_white_list` | 黑白名单表 |

## 配置

详见 `config/kylin-risk-engine.php`，支持环境变量覆盖：
- `RISK_CACHE_STORE`（默认 redis）— 缓存存储
- `RISK_FACE_PROVIDER`（默认 tencent）— 人脸验证供应商
- `RISK_SCORE_THRESHOLD_PASS`（默认 20）— 通过阈值
- `RISK_SCORE_THRESHOLD_OBSERVE`（默认 50）— 观察阈值
- `RISK_SCORE_THRESHOLD_FACE`（默认 70）— 人脸复核阈值
- `RISK_SCORE_THRESHOLD_LOCKOUT`（默认 90）— 锁定阈值

## 决策阈值

| 分数范围 | 决策 | 说明 |
|----------|------|------|
| 0-20 | `pass` | 正常放行 |
| 21-50 | `observe` | 观察记录 |
| 51-70 | `face_required` | 强制人脸复核 |
| 71-100 | `lockout` | 账号锁定 |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 《中华人民共和国网络安全法》— 第二十一条、第四十七条
- 《中华人民共和国个人信息保护法》— 第二十八条（人脸信息为敏感个人信息）
- 《关于防止未成年人沉迷网络游戏的通知》— 防沉迷联动
- 《未成年人网络保护条例》— 第四十六条、第四十七条
- 等保 2.0 (GB/T 22239) 8.1.4.6 — 审计日志

## 与其他包联动

- **kylin/anti-addiction**：防沉迷系统，风控触发防沉迷限制
- **kylin/realname-gateway**：实名认证，风控触发实名复核
- **kylin/audit-log**：审计日志，记录所有风控决策
- **kylin/rbac**：权限控制，限制风控配置访问

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- kylin/audit-log（审计日志）

## 许可证

私有软件，未经授权禁止使用。
