# 5.2 认证流程实战

:::tip 概述
本节通过完整的请求链路，展示从登录到接口调用的认证全流程，包括登录、Token 刷新、接口认证、权限校验、租户隔离五个核心环节。
:::

## 认证全景图

```text
┌─────────────────────────────────────────────────────────────────────┐
│                        认证授权全景                                  │
│                                                                     │
│  ① 登录         POST /api/login                                    │
│     用户名+密码+验证码 → 校验 → 签发 access_token + refresh_token   │
│                                                                     │
│  ② 请求 API     GET/POST /api/xxx                                  │
│     Bearer token → AuthMiddleware → 权限校验 → 注入 userInfo        │
│                                                                     │
│  ③ Token 过期   响应 code=401                                       │
│     refresh_token → POST /api/oauth2/token → 新令牌对               │
│                                                                     │
│  ④ 租户隔离     TenantMiddleware                                    │
│     解析租户 → 注入 tenantId → Logic 层自动过滤                     │
│                                                                     │
│  ⑤ 登出         前端清除 localStorage                               │
│     （JWT 无状态，服务端无需处理）                                   │
└─────────────────────────────────────────────────────────────────────┘
```

## 一、登录流程

### 完整流程图

```text
POST /api/login
{ "username": "admin", "password": "123456", "code": "a3Bx", "key": "xxx" }
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│ LoginController::login()                                │
│                                                         │
│ 1. getParams() 获取请求参数                              │
│ 2. validate($params, LoginValidate::class . '.login')   │
│    │ 失败 → {"code":422, "msg":"参数验证失败"}           │
│    ▼                                                     │
│ 3. LoginLogic::login($username, $password, $code, $key) │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ LoginLogic::login()                                     │
│                                                         │
│ 1. CaptchaService::check($code, $key)                   │
│    │ 失败 → throw "验证码错误"                           │
│    ▼                                                     │
│ 2. JwtService::login($username, $password)              │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ JwtService::login()                                     │
│                                                         │
│ 1. User::withoutGlobalScope(['soft_delete'])            │
│       ->where('username', $username)->find()            │
│    │ 不存在 → throw "用户名或密码错误"                   │
│    ▼                                                     │
│ 2. $user->status != 1                                   │
│    │ 禁用 → throw "账号已被禁用"                         │
│    ▼                                                     │
│ 3. PasswordService::verify($password, $hashed, $salt)   │
│    │ 不匹配 → throw "用户名或密码错误"                   │
│    ▼                                                     │
│ 4. Jwt::createAccessToken($uid, $username)              │
│    Jwt::createRefreshToken($uid, $username)             │
│    ▼                                                     │
│ 5. 返回 { access_token, refresh_token, user }           │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ LoginController 续                                       │
│                                                         │
│ 成功 → LoginLogic::recordLoginLog(成功)                  │
│      → $this->success($result, '登录成功', true)         │
│                                                         │
│ 失败 → LoginLogic::recordLoginLog(失败)                  │
│      → $this->fail($e->getMessage())                    │
└─────────────────────────────────────────────────────────┘
```

### 登录接口详情

**请求：**

```bash
POST /api/login
Content-Type: application/json

{
    "username": "admin",
    "password": "123456",
    "code": "a3Bx",
    "key": "captcha_xxx"
}
```

**成功响应：**

```json
{
    "code": 0,
    "ok": true,
    "msg": "登录成功",
    "data": {
        "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "tokenType": "Bearer",
        "expiresIn": 7200,
        "user": {
            "id": 1,
            "username": "admin",
            "realname": "管理员",
            "avatar": "/uploads/user/avatar/avatar.jpg"
        }
    }
}
```

**失败响应：**

| 场景 | code | msg |
|------|------|-----|
| 验证码错误 | 1 | 验证码错误 |
| 用户不存在 | 1 | 用户名或密码错误 |
| 密码错误 | 1 | 用户名或密码错误 |
| 账号禁用 | 1 | 账号已被禁用 |
| 参数缺失 | 422 | 用户名不能为空 / 密码不能为空 |

## 二、接口认证流程

### 中间件链执行顺序

```text
请求 GET /api/user/page
Authorization: Bearer eyJ...
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│ CorsMiddleware（全局）                                    │
│ OPTIONS 预检 → 返回 204 + CORS 头                        │
│ 普通请求 → 设置跨域头，放行                               │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ AuthMiddleware                                            │
│                                                         │
│ 1. 检查排除列表（login/captcha/oauth2 → 直接放行）       │
│ 2. Jwt::getTokenFromHeader()                            │
│    │ 空 → {"code":401, "msg":"未提供认证令牌"}            │
│    ▼                                                     │
│ 3. Jwt::decode($token)                                  │
│    │ 过期 → {"code":401, "msg":"token已过期"}             │
│    │ 签名无效 → {"code":401, "msg":"token签名无效"}       │
│    ▼                                                     │
│ 4. $decoded->type === 'access'                          │
│    │ 非 access → {"code":401, "msg":"无效的认证令牌"}     │
│    ▼                                                     │
│ 5. $request->userInfo = $decoded                        │
│    │ 注入 uid、username 等到请求对象                      │
│    ▼                                                     │
│ 6. 读取 #[Permission] 注解                              │
│    │ uid=1 → 超级管理员，跳过校验                        │
│    │ 查询用户权限列表 → 匹配权限码                       │
│    │ 无权限 → {"code":403, "msg":"无访问权限"}            │
│    ▼                                                     │
│ 7. 放行                                                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ TenantMiddleware                                          │
│                                                         │
│ 1. 从 JWT payload 获取 uid                              │
│ 2. 查询用户所属租户                                      │
│ 3. $request->tenantId = 租户ID                          │
│ 4. $request->tenantInfo = 租户信息                      │
│    │ 租户禁用/过期 → {"code":403, "msg":"租户异常"}       │
│    ▼                                                     │
│ 5. 放行                                                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ DemoMiddleware                                            │
│                                                         │
│ 1. 检查 DEMO 配置（env('app_demo')）                    │
│ 2. 非演示模式 → 放行                                     │
│ 3. 演示模式 + 写操作（POST/PUT/DELETE）                  │
│    │ 未标注 #[DemoAllow] → {"code":403, "msg":"演示环境"} │
│    ▼                                                     │
│ 4. 放行                                                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ LogMiddleware                                             │
│                                                         │
│ 1. 读取 #[Log] 注解                                     │
│ 2. 记录操作日志（异步/同步）                              │
│ 3. 放行                                                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ UserController::page()                                    │
│                                                         │
│ return parent::_index($this->logic);                    │
│ → Logic::pageList() → Model → Database                  │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
                    JSON 响应返回
```

### 权限校验详解

```text
AuthMiddleware::checkPermission($uid, $permissionCode)
    │
    ▼
1. $uid === 1（超级管理员）
   │ 是 → return true（跳过校验）
   ▼
2. UserRole::where('user_id', $uid)->column('role_id')
   │ 无角色 → return false
   ▼
3. RoleMenu → Menu::whereIn('role_id', $roleIds)
   .where('type', 1)  // type=1 为权限节点
   .column('permission')
   ▼
4. in_array($permissionCode, $permissions)
   │ 包含 → return true（放行）
   │ 不包含 → return false（返回 403）
```

**权限码格式：** `sys:{模块名}:{操作}`

```text
sys:user:add          添加用户
sys:user:update       修改用户
sys:user:delete       删除用户
sys:user:page         用户分页
sys:article:add       添加文章
sys:article:list      文章列表
```

## 三、Token 刷新流程

### 流程图

```text
前端检测到 code=401
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│ 前端响应拦截器                                            │
│                                                         │
│ 1. 从 localStorage 读取 refresh_token                   │
│ 2. POST /api/oauth2/token                               │
│    { grant_type: "refresh_token", refresh_token: "..." } │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ LoginController::token()                                │
│                                                         │
│ 1. 判断 grant_type === 'refresh_token'                  │
│ 2. LoginLogic::refreshToken($refreshToken)              │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ JwtService::refreshToken()                              │
│                                                         │
│ 1. Jwt::decode($refreshToken)                           │
│    │ 无效 → throw "无效的refresh_token"                  │
│    ▼                                                     │
│ 2. $decoded->type === 'refresh'                         │
│    │ 非 refresh → throw "无效的refresh_token"             │
│    ▼                                                     │
│ 3. User::find($decoded->uid)                            │
│    │ 不存在或禁用 → throw "用户不存在或已被禁用"           │
│    ▼                                                     │
│ 4. 签发新 access_token + 新 refresh_token               │
│    ▼                                                     │
│ 5. 返回新令牌对                                          │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ 前端响应拦截器（续）                                      │
│                                                         │
│ 1. 更新 localStorage 中的 access_token                  │
│ 2. 更新 localStorage 中的 refresh_token                 │
│ 3. 用新 access_token 重试原失败请求                      │
└─────────────────────────────────────────────────────────┘
```

### 刷新接口详情

**请求：**

```bash
POST /api/oauth2/token
Content-Type: application/json

{
    "grant_type": "refresh_token",
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}
```

**成功响应：**

```json
{
    "code": 0,
    "ok": true,
    "msg": "success",
    "data": {
        "accessToken": "eyJ...(新access_token)",
        "refreshToken": "eyJ...(新refresh_token)",
        "tokenType": "Bearer",
        "expiresIn": 7200
    }
}
```

**失败响应：**

| 场景 | code | msg |
|------|------|-----|
| 缺少 refresh_token | 1 | 缺少refresh_token参数 |
| refresh_token 无效/过期 | 1 | 无效的refresh_token |
| 用户不存在/禁用 | 1 | 用户不存在或已被禁用 |

## 四、完整请求示例

以"查询用户分页"为例，展示一次认证请求的完整链路：

```text
① 前端发起请求
   GET /api/user/page?pageNo=1&pageSize=20
   Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
       │
       ▼
② CorsMiddleware → 设置跨域头，放行
       │
       ▼
③ AuthMiddleware
   │ getTokenFromHeader() → "eyJ..."
   │ Jwt::decode() → { uid:1, username:"admin", type:"access", exp:... }
   │ type === 'access' ✓
   │ $request->userInfo = $decoded
   │ checkPermission(1, 'sys:user:page')
   │ uid=1 → 超级管理员，跳过
   ▼
④ TenantMiddleware
   │ 查询用户租户 → tenantId=1
   │ $request->tenantId = 1
   ▼
⑤ DemoMiddleware → 非演示模式，放行
       │
       ▼
⑥ LogMiddleware → GET 查询不记录日志，放行
       │
       ▼
⑦ UserController::page()
   │ return parent::_index($this->logic)
   ▼
⑧ UserLogic::pageList($params)
   │ applyTenantScope() → WHERE tenant_id = 1
   │ applyDataScope() → 按角色 data_scope 过滤
   │ → SELECT * FROM think_user WHERE is_delete=0 AND tenant_id=1 ...
   ▼
⑨ 返回 JSON
   {
     "code": 0,
     "ok": true,
     "msg": "操作成功",
     "data": {
       "records": [...],
       "total": 42,
       "size": 20,
       "current": 1,
       "pages": 3
     }
   }
```

## 五、前端自动刷新 Token 实现

```typescript
// src/utils/http/axios/index.ts

let isRefreshing = false;
let pendingRequests: Function[] = [];

axios.interceptors.response.use(
    response => response,
    async error => {
        const { config, response } = error;

        // 非 401 错误直接抛出
        if (response?.status !== 401) {
            return Promise.reject(error);
        }

        // 已在刷新中，将请求加入队列等待
        if (isRefreshing) {
            return new Promise(resolve => {
                pendingRequests.push((newToken: string) => {
                    config.headers['Authorization'] = `Bearer ${newToken}`;
                    resolve(axios(config));
                });
            });
        }

        isRefreshing = true;
        config._retry = true;

        try {
            const refreshToken = localStorage.getItem('refresh_token');
            const res = await refreshTokenApi(refreshToken);
            const { accessToken, refreshToken: newRefreshToken } = res.data;

            // 更新存储
            localStorage.setItem('access_token', accessToken);
            localStorage.setItem('refresh_token', newRefreshToken);

            // 重试当前请求
            config.headers['Authorization'] = `Bearer ${accessToken}`;

            // 执行队列中的等待请求
            pendingRequests.forEach(cb => cb(accessToken));
            pendingRequests = [];

            return axios(config);
        } catch (e) {
            // 刷新失败，清除登录态，跳转登录页
            localStorage.clear();
            window.location.href = '/login';
            return Promise.reject(e);
        } finally {
            isRefreshing = false;
        }
    }
);
```

## 六、OAuth2 兼容接口

系统同时提供 OAuth2 风格的 Token 接口，兼容标准 OAuth2 客户端：

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/oauth2/token` | POST | 获取令牌（grant_type=password 或 refresh_token） |
| `/api/oauth2/remove/{token}` | DELETE | 吊销令牌 |
| `/api/oauth2/check/token` | GET | 检测令牌有效性 |

### 密码模式获取令牌

```bash
POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin&password=123456
```

### 刷新模式获取令牌

```bash
POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=eyJ...
```