# 认证模块说明（`src/auth`）

## 1. 目标

- 提供系统管理员创建、登录、`/me` 身份查询。
- 使用 JWT 做认证，Guard 做鉴权，RolesGuard 做 RBAC。

## 2. 核心接口

- `POST /auth/system-admin`：创建系统管理员（需引导密钥）
- `POST /auth/login`：手机号 + 角色 + 密码登录（支持同手机号多院场景）
- `GET /auth/me`：返回当前登录用户上下文

## 3. 鉴权流程

1. `AccessTokenGuard` 从 `Authorization` 读取 Bearer Token。
2. 校验 JWT 签名、`id`、`iat` 等关键载荷字段。
3. 根据 `id` 回库读取用户当前角色与组织归属，不再直接信任 token 里的角色和范围。
4. 校验 `iat >= user.tokenValidAfter`，若用户被重置密码、seed 重刷或账号被清理，则旧 token 立即失效。
5. 当前数据库用户映射为 `ActorContext` 注入 `request.actor`。
6. `RolesGuard` 根据 `@Roles(...)` 判断角色是否允许访问。

## 4. Token 约定

- Header：`Authorization: Bearer <token>`
- 载荷关键字段：`id`、`iat`
- 角色和组织范围以数据库当前用户记录为准，不以 token 历史载荷为准

## 5. 错误码与中文消息

- 未登录/Token 失效：`401` + 中文 `msg`
- 角色无权限：`403` + 中文 `msg`
- 参数非法：`400` + 中文 `msg`

统一由全局异常过滤器输出：`{ code, msg, data: null }`。

## 6. 失效策略

- 用户密码被修改后，会刷新 `user.tokenValidAfter`，旧 token 全部失效。
- 执行 E2E 重置并重新 seed 后，seed 账号的 `tokenValidAfter` 也会刷新，历史 token 不可继续复用。