# 用户与 RBAC

FluxiQ PIX 中的用户管理、基于角色的访问控制和多因素认证。

## 前提条件

- 拥有 FluxiQ PIX 管理门户的管理员访问权限
- 了解您机构的角色层次结构

## 默认用户

| 用户 | 密码 | 角色 |
|------|------|------|
| admin | Admin@2026! | 系统管理员 |
| operator | Operator@2026! | 交易操作员 |
| viewer | Viewer@2026! | 只读查看者 |
| integration | FluxiQ@2026! | FluxiQ 集成 |

## RBAC 架构

```mermaid
graph TD
    USER[用户] -->|属于| GROUP[群组]
    GROUP -->|拥有| FEATURES[功能/权限]
    FEATURES -->|检查| PLUG[RequirePermission 插件]
    PLUG -->|ETS 缓存<br/>5分钟 TTL| ETS[(ETS 表)]
    ETS -->|从DB刷新| DB[(group_features 表)]
```

### 权限检查流程

1. 请求携带 JWT cookie 到达
2. `JWTAuth` 插件提取用户并检查 Token 黑名单
3. `RequirePermission` 插件在 ETS 缓存中检查用户的群组功能
4. 缓存未命中 -> 查询 `monetarie_auth.group_features` 表 -> 缓存 5 分钟
5. 权限拒绝 -> HTTP 403（RFC 7807 格式）

### 关键特性

- **失败关闭**：数据库错误导致访问拒绝（而非授予）
- **SSO 透传**：Core Banking Guardian tokens 跳过 RBAC 检查
- **ETS 缓存**：权限查询快速（无需每次请求查询数据库）
- **35 个受保护操作**：控制器操作标注了所需权限

## 群组与权限

群组定义在 `monetarie_auth.groups` 中，通过 `monetarie_auth.group_features` 关联到功能：

| 群组 | 典型权限 |
|------|----------|
| 系统管理员 | 所有权限 |
| 交易操作员 | 创建/查看交易、管理密钥 |
| 查看者 | 所有模块的只读访问 |
| 集成 | Core Banking 集成的 API 访问 |

## 多因素认证

FluxiQ PIX 支持基于 TOTP 的 MFA 和备份码：

### 设置流程

1. 用户在个人设置中启用 MFA
2. 系统生成 TOTP 密钥和二维码
3. 用户使用认证器应用扫描二维码
4. 用户使用 TOTP 码验证
5. 系统提供备份码

### MFA 登录

```mermaid
sequenceDiagram
    用户->>+后端: POST /auth/login (凭据)
    后端-->>-用户: {mfa_required: true, mfa_token: "..."}
    用户->>+后端: POST /auth/mfa/verify (验证码 + mfa_token)
    后端-->>-用户: Set-Cookie: pix_session
```

### MFA 模式

| 字段 | 类型 | 描述 |
|------|------|------|
| `mfa_enabled` | boolean | MFA 是否启用 |
| `mfa_secret` | string | TOTP 密钥（加密存储） |
| `mfa_backup_codes` | array | 一次性备份码 |
| `mfa_last_used_at` | datetime | 最后 MFA 验证时间 |

## 账户安全

### 登录速率限制

- 每个 IP 地址每 15 分钟 10 次登录尝试
- 适用于 `/auth/login` 和 `/auth/mfa/verify`
- Redis 令牌桶算法
- 返回 HTTP 429 带 `Retry-After` 头

### 账户锁定

- 10 次登录失败后，账户自动锁定（`is_blocked = true`）
- 通用错误响应防止账户枚举
- 管理员必须手动解锁账户

### 密码过期

- 认证时检查 `password_expires` 字段
- 过期密码需要在登录前重置

### Token 黑名单

- 注销时，JWT 被添加到 Redis 黑名单，保留剩余 TTL
- 每个认证请求都检查黑名单
- 防止注销后使用被盗 Token

## 审计日志

所有用户操作记录在 `monetarie_audit.activity_log` 中（月度分区）：

| 字段 | 描述 |
|------|------|
| `user_id` | 操作用户 UUID |
| `action` | 执行的操作 |
| `entity_type` | 资源类型 |
| `entity_id` | 资源 UUID |
| `ip_address` | 客户端 IP |
| `created_at` | 时间戳 |

审计日志可通过管理门户导出为 CSV。

## 预期结果

配置用户和 RBAC 后：

- 用户可以使用分配的角色登录
- RBAC 根据群组权限限制访问
- MFA 为敏感账户提供额外安全保障
- 速率限制和账户锁定防止暴力破解
- 所有操作已审计以满足合规要求