WangDL
0eb5f53873
- iOS integration readiness audit (blocker list, module map, deployment check) - CAPI contract for iOS (15 modules, 80+ endpoints) - CAPI error codes and status enums - iOS auth flow, file upload import flow, learning review flow - Web product page nginx fix (reenable longde.cloud) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# 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 调用都要处理。
|