# iOS 认证流程

> 版本：0.1.0 | 更新：2026-05-24

## 流程图

```
iOS App                          API Server                    Apple

1. 用户点击"使用 Apple 登录"
   Sign in with Apple 弹窗
   ─────────────────────────────────────────────────────────►  验证用户身份
   ◄─────────────────────────────────────────────────────────  返回 identityToken

2. POST /api/auth/apple
   { identityToken, fullName?, email? }
   ──────────────────────────►  验证 identityToken
                                通过 Apple JWKS 验签
                                验证 issuer + audience
                                查找或创建用户
                                生成 JWT + RefreshToken
   ◄──────────────────────────  { accessToken, refreshToken, user }

3. 存储 Token
   Keychain: accessToken + refreshToken

4. 后续请求携带 accessToken
   GET /api/users/me
   Authorization: Bearer <accessToken>
   ──────────────────────────►  JwtAuthGuard 验证
                                - 解码 JWT
                                - 检查 type=user
                                - 查询用户状态 (active/deleted)
   ◄──────────────────────────  用户数据

5. Token 过期时刷新 (401)
   POST /api/auth/refresh
   { refreshToken }
   ──────────────────────────►  验证 refresh token hash
                                检查用户状态
                                撤销旧 token → 签发新对
   ◄──────────────────────────  { accessToken, refreshToken, user }

6. 登出
   POST /api/auth/logout
   { refreshToken }
   ──────────────────────────►  撤销 refresh token
   ◄──────────────────────────  200 OK
```

## Token 存储建议

| Token | 存储位置 | 说明 |
|-------|----------|------|
| accessToken | Keychain / Secure Enclave | 短期（1h），频繁使用 |
| refreshToken | Keychain | 长期（7d），仅在刷新时使用 |

## 错误处理

| HTTP | message | iOS 处理 |
|------|---------|----------|
| 401 | "请先登录" | 跳转登录页 |
| 401 | "登录已过期，请重新登录" | 尝试刷新 token，失败则跳转登录 |
| 401 | "账号已被禁用" | 显示禁用提示，退出 |
| 401 | "账号不存在或已注销" | 跳转登录页 |
| 401 | "Apple 登录未配置" | 显示维护提示 |

## 自动刷新策略

```
请求 → 401?
  ├── 是 → 尝试 POST /api/auth/refresh
  │         ├── 成功 → 更新 Keychain，重试原请求
  │         └── 失败 → 清除 Token，跳转登录
  └── 否 → 正常处理
```

建议在 HTTP 拦截器/中间件层实现，避免每个 API 调用都要处理。