# Kylin Guardian

Kylin 未成年人监护系统包 -- 监护人注册/绑定/管控/通知。

## 功能特性

- **监护人注册**：实名认证，身份证号加密存储
- **绑定管理**：绑定/解绑未成年人，支持多种关系类型
- **游戏报告**：查看未成年人游戏时长、消费数据
- **时间限制**：设置每日游戏时长、允许游戏时段
- **消费限制**：设置日消费上限、月消费上限、单次消费上限
- **强制管控**：强制下线、允许上线
- **远程配置**：客户端 SDK 拉取管控策略
- **通知推送**：登录通知、消费通知、时长预警、强制下线通知

## 安装

```bash
composer require kylin/guardian
```

## 配置发布

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

## 使用示例

### Facade

```php
use Kylin\Guardian\Facades\KylinGuardian;

// 注册监护人
$guardian = KylinGuardian::register([
    'user_id' => 1,
    'name' => '张三',
    'phone' => '13800138000',
    'id_card' => '110101199001011234',
    'relationship' => 'parent',
]);

// 绑定未成年人
$binding = KylinGuardian::bind($guardian->id, $minorUserId, 'parent');

// 设置时间限制
KylinGuardian::setPlayLimit($binding->id, [
    'daily_minutes' => 60,
    'allowed_periods' => [
        ['start' => '08:00', 'end' => '22:00'],
    ],
]);

// 设置消费限制
KylinGuardian::setSpendingLimit($binding->id, [
    'daily_max' => 30,
    'monthly_max' => 100,
]);

// 强制下线
KylinGuardian::forceOffline($binding->id);

// 允许上线
KylinGuardian::allowOnline($binding->id);

// 获取游戏报告
$report = KylinGuardian::getMinorReport($binding->id);

// 获取远程配置（供客户端 SDK 使用）
$config = KylinGuardian::getRemoteConfig($binding->id);
```

### 通知服务

```php
use Kylin\Guardian\Services\GuardianNotifyService;

$notifyService = app(GuardianNotifyService::class);

// 通知登录
$notifyService->notifyLogin($bindingId);

// 通知消费
$notifyService->notifySpending($bindingId, 50.0);

// 时长预警
$notifyService->notifyTimeWarning($bindingId, 10);

// 强制下线通知
$notifyService->notifyForceOffline($bindingId);
```

### API 路由

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/kylin/guardian/register | 监护人注册 |
| POST | /api/kylin/guardian/bind | 绑定未成年人 |
| POST | /api/kylin/guardian/unbind/{bindingId} | 解绑 |
| GET  | /api/kylin/guardian/bindings | 绑定列表 |
| GET  | /api/kylin/guardian/binding/{bindingId}/report | 未成年人游戏报告 |
| POST | /api/kylin/guardian/binding/{bindingId}/set-play-limit | 设置时间限制 |
| POST | /api/kylin/guardian/binding/{bindingId}/set-spending-limit | 设置消费限制 |
| POST | /api/kylin/guardian/binding/{bindingId}/force-offline | 强制下线 |
| POST | /api/kylin/guardian/binding/{bindingId}/allow-online | 允许上线 |
| GET  | /api/kylin/guardian/binding/{bindingId}/remote-config | 获取远程配置 |

### 关系类型

| 值 | 说明 |
|----|------|
| parent | 父母 |
| grandparent | 祖父母/外祖父母 |
| other_relative | 其他亲属 |
| legal_guardian | 法定监护人 |

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- kylin/user
- kylin/notification

## 许可证

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