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>
3.2 KiB
3.2 KiB
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 调用都要处理。