wangdl/startup-plan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
startup-plan/技术设计/ios-auth-flow.md
WangDL 0eb5f53873 docs: iOS integration audit report + 5 CAPI docs + nginx fix 
- 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>
2026-05-25 16:55:22 +08:00

3.2 KiB
Raw Permalink Blame History

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