# Kylin User

Kylin 用户管理包 — CRUD、密码策略、登录安全、个人信息加密、未成年人保护、数据清理、RBAC 权限控制、审计日志。

## 功能特性

- **用户 CRUD**：完整的用户增删改查 API
- **密码策略**：最小长度、大小写字母、数字、特殊字符、定期更换（依据等保 2.0 8.1.4.2）
- **登录安全**：失败锁定（`max_attempts=5`，`lockout_minutes=30`）、异常检测（依据等保 2.0 8.1.4.4）
- **用户状态**：`UserStatus` 枚举（Active/Inactive/Pending/Disabled）
- **用户资料**：`UserProfile` 扩展字段支持
- **敏感字段加密**：身份证号、手机号加密存储（依据《个人信息保护法》第二十八条、第五十一条）
- **未成年人保护**：年龄分组（幼儿/未成年人/成年人/老年人），14 岁以下强制监护人同意（依据《未成年人保护法》第七十二条）
- **数据清理**：`CleanUserDataCommand` 支持软删除超期用户清理、锁定不活跃用户清理，最小保留 90 天（依据《个人信息保护法》第四十七条）
- **RBAC 权限控制**：`UserPolicy` 继承 `CrudPolicy`，与 `kylin/rbac` 集成
- **审计日志**：用户增删改操作自动写入 `kylin/audit-log`，手机号自动脱敏（依据等保 2.0 8.1.4.6）
- **FormRequest 验证**：`StoreUserRequest`/`UpdateUserRequest` 自动验证

## 安装

```bash
composer require kylin/user
```

## 配置发布

```bash
php artisan vendor:publish --tag=kylin-user-config
php artisan vendor:publish --tag=kylin-user-migrations
php artisan migrate
```

## 配置说明

```php
// config/kylin-user.php

'password' => [
    'min_length'        => 8,     // 密码最小长度
    'require_uppercase' => true,  // 需大写字母
    'require_lowercase' => true,  // 需小写字母
    'require_number'    => true,  // 需数字
    'require_symbol'    => false, // 需特殊字符
    'expire_days'       => 0,     // 密码过期天数（0=永不过期）
],

'login' => [
    'max_attempts'     => 5,   // 最大登录失败次数
    'lockout_minutes'  => 30,  // 锁定时长（分钟）
],

'avatar' => [
    'default'  => '/images/default-avatar.png',
    'disk'     => 'public',
    'max_size' => 2048, // KB
],

'privacy' => [
    'consent_required'     => true,  // 注册需用户同意
    'encrypt_id_card'      => true,  // 身份证号加密
    'encrypt_phone'        => true,  // 手机号加密
    'data_retention_days'  => 365,   // 数据保留天数
],

'age_groups' => [
    'child'   => ['max' => 7,   'label' => '幼儿'],
    'minor'   => ['max' => 17,  'label' => '未成年人'],
    'adult'   => ['max' => 59,  'label' => '成年人'],
    'elderly' => ['max' => null, 'label' => '老年人'],
],
```

## 使用示例

### Facade 方式

```php
use Kylin\User\Facades\KylinUser;

// 创建用户
$user = KylinUser::create([
    'name' => '张三',
    'email' => 'zhangsan@example.com',
    'password' => 'SecureP@ss123',
    'phone' => '13800138000',
    'roles' => ['admin'],
]);

// 更新用户
$user = KylinUser::update($user, ['name' => '李四']);

// 删除用户
KylinUser::delete($user);

// 切换用户状态（启用/禁用）
$user = KylinUser::toggleStatus($user);

// 修改密码
KylinUser::changePassword($user, 'OldP@ss123', 'NewP@ss456');

// 更新用户资料
$profile = KylinUser::updateProfile($user, [
    'real_name' => '张三',
    'id_card' => '110101199001011234',
    'birthday' => '1990-01-01',
]);

// 用户列表（支持筛选）
$users = KylinUser::list(['keyword' => '张', 'status' => 'active'], perPage: 15);
```

### 数据清理命令

```bash
# 预览清理（不实际删除）
php artisan user:clean --dry-run

# 实际清理软删除超期用户
php artisan user:clean

# 清理锁定不活跃用户
php artisan user:clean --locked
```

### API 路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/kylin/users | 用户列表（支持 keyword/status 筛选） |
| POST | /api/kylin/users | 创建用户 |
| GET | /api/kylin/users/{id} | 用户详情 |
| PUT | /api/kylin/users/{id} | 更新用户 |
| DELETE | /api/kylin/users/{id} | 删除用户 |
| PATCH | /api/kylin/users/{id}/status | 切换用户状态 |
| PUT | /api/kylin/users/{id}/password | 修改密码 |
| PUT | /api/kylin/users/{id}/profile | 更新用户资料 |

## 数据库表

| 表名 | 说明 |
|------|------|
| `users` | 用户主表（扩展 password_changed_at 字段） |
| `user_profiles` | 用户资料表（real_name/id_card/birthday/guardian_name/guardian_phone） |
| `users_age_group` | 年龄分组字段（age_group） |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 等保 2.0 (GB/T 22239-2019) — 8.1.4.2/8.1.4.4/8.1.4.5/8.1.4.6
- 《中华人民共和国个人信息保护法》— 第六条/第十三条/第十四条/第十七条/第二十八条/第四十七条/第五十一条
- 《中华人民共和国未成年人保护法》— 第七十二条/第七十五条
- 《中华人民共和国网络安全法》— 第二十四条/第四十一条/第四十二条
- 《中华人民共和国数据安全法》— 第二十一条/第二十七条/第二十九条
- 《中华人民共和国密码法》— 第二十七条
- 《互联网用户账号信息管理规定》(2022.8.1)

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- kylin/rbac
- kylin/audit-log（可选，用于审计日志）

## 许可证

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