# Kylin Realname Gateway

Kylin 实名认证网关 — NPPA（国家新闻出版署）防沉迷实名验证系统 SDK 封装，对接 `api.wlc.nppa.gov.cn`，提供身份证校验、实名认证、年龄段判定功能。

## 功能特性

- **NPPA 网关对接**：`NppaGatewayService` 对接国家新闻出版署实名认证系统
- **身份证校验**：`IdCardValidator` 18 位校验码验证（GB 11643-1999）
- **身份证加密**：RSA 公钥加密传输（依据《个人信息保护法》第五十一条）
- **年龄段判定**：4 档（未满 8 / 8-16 / 16-18 / 已满 18 周岁）
- **缓存策略**：成功缓存 365±7 天，失败缓存 1 小时
- **签名验证**：HMAC-SHA256 请求签名
- **审计日志**：记录所有认证行为（不含身份证原文）
- **超时控制**：默认 8 秒

## 安装

```bash
composer require kylin/realname-gateway
```

## 配置发布

```bash
php artisan vendor:publish --tag=kylin-realname-gateway-config
```

## 环境变量

```env
NPPA_GATEWAY_URL=https://api.wlc.nppa.gov.cn
NPPA_APP_ID=your_app_id
NPPA_BIZ_ID=your_biz_id
NPPA_SECRET_KEY=your_secret_key
NPPA_PUBLIC_KEY=your_rsa_public_key
NPPA_TIMEOUT_SEC=8
```

## 使用示例

### 实名认证

```php
use Kylin\RealnameGateway\Services\NppaGatewayService;

public function __construct(
    private readonly NppaGatewayService $gateway
) {}

// 提交实名认证
$result = $this->gateway->verify('张三', '110101199001011234', 'game123');

// 返回结构
// [
//     'status' => 'verified',  // verified|failed|error
//     'age_group' => 3,        // 0=<8 1=8-16 2=16-18 3=>=18
//     'message' => '认证成功',
// ]
```

### 查询认证状态

```php
$result = $this->gateway->query('110101199001011234');
// ['status' => 'verified', 'age_group' => 3]
```

### 身份证校验

```php
use Kylin\RealnameGateway\Services\IdCardValidator;

public function __construct(
    private readonly IdCardValidator $validator
) {}

// 校验身份证号格式
$isValid = $this->validator->validate('110101199001011234');

// 提取生日
$birthday = $this->validator->extractBirthday('110101199001011234');

// 计算年龄（周岁）
$age = $this->validator->calculateAge('110101199001011234');

// 判定年龄段
$ageGroup = $this->validator->determineAgeGroup('110101199001011234');
// 0=未满8周岁 1=8-16周岁 2=16-18周岁 3=已满18周岁

// 获取年龄段标签
$label = $this->validator->getAgeGroupLabel($ageGroup);

// 是否未成年
$isMinor = $this->validator->isMinor('110101199001011234');
```

## 年龄段标准

| 年龄段 | 代码 | 说明 | 防沉迷限制 |
|--------|------|------|------------|
| 未满 8 周岁 | 0 | 幼儿 | 禁止登录、禁止充值 |
| 8-16 周岁 | 1 | 少年 | 限时登录、月充≤200元 |
| 16-18 周岁 | 2 | 青少年 | 限时登录、月充≤400元 |
| 已满 18 周岁 | 3 | 成年 | 无限制 |

## 与其他包联动

- **kylin/anti-addiction**：防沉迷系统，基于年龄段实施时段限制和充值限制
- **kylin/audit-log**：审计日志，记录所有认证行为
- **kylin/rbac**：权限控制，限制认证接口访问

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 《关于防止未成年人沉迷网络游戏的通知》(2019.11.1)
- 《关于进一步严格管理 切实防止未成年人沉迷网络游戏的通知》(2021.8.30)
- 《中华人民共和国未成年人保护法》— 第七十四条、第七十五条
- 《未成年人网络保护条例》(2024.1.1) — 第四十六条、第四十七条
- 《中华人民共和国个人信息保护法》— 第二十八条、第二十九条、第五十一条、第五十五条
- 《中华人民共和国网络安全法》— 第二十一条、第四十二条、第四十七条
- 《中华人民共和国数据安全法》— 第二十一条、第二十七条
- GB 11643-1999 身份证号校验标准

## 依赖

- PHP ^8.5
- Laravel ^13.0
- guzzlehttp/guzzle ^7.8

## 许可证

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