LabelingSystem/.kiro/specs/sso-token-unification/tasks.md

Implementation Plan: SSO Token 统一认证

Overview

将标注平台从本地 JWT 签发迁移为 SSO 统一 token 认证。按照后端核心组件 → 中间件改造 → 路由改造 → 前端适配 → 清理的顺序实施，确保每一步都可验证。

Tasks

• [x] 1. 实现 TokenCacheService

  • 1.1 创建 backend/services/token_cache_service.py，实现内存级 token 缓存
  • 实现 CacheEntry 数据类（user_info + created_at）
  • 实现 get(token) 方法：查询缓存，检查 TTL，过期则删除并返回 None
  • 实现 set(token, user_info) 方法：写入缓存
  • 实现 invalidate(token) 和 clear() 方法
  • 支持通过构造函数配置 TTL（默认 300 秒）
  • Requirements: 3.1, 3.2, 3.7
  • [ ]* 1.2 编写 TokenCacheService 属性测试
  • Property 1: Cache hit returns cached user info
  • Property 4: Cache entries expire after TTL
  • Validates: Requirements 3.1, 3.2, 3.7

• [x] 2. 改造 OAuthService，新增 SSO token 验证和刷新方法

  • 2.1 在 backend/services/oauth_service.py 中新增 verify_sso_token 方法
  • 调用 SSO /oauth/userinfo 端点验证 token
  • 处理 {"code": 0, "data": {...}} 包装格式和标准格式
  • SSO 不可用时抛出 HTTPException(503)
  • token 无效时抛出 HTTPException(401)
  • Requirements: 3.3, 3.4, 3.5, 3.6
  • 2.2 在 backend/services/oauth_service.py 中新增 refresh_sso_token 方法
  • 向 SSO /oauth/token 端点发送 grant_type=refresh_token 请求
  • 处理包装格式和标准格式的响应
  • Requirements: 4.2, 4.3
  • [ ]* 2.3 编写 OAuthService 新方法的单元测试
  • 测试 verify_sso_token 成功/失败/SSO 不可用场景
  • 测试 refresh_sso_token 成功/失败场景
  • Requirements: 3.3, 3.4, 3.5, 3.6, 4.2, 4.3

• [x] 3. 改造 AuthMiddleware

  • 3.1 重写 backend/middleware/auth_middleware.py 的 dispatch 方法
  • 改为先查 TokenCacheService 缓存
  • 缓存未命中时调用 OAuthService.verify_sso_token 验证
  • 验证成功后写入缓存并同步用户到本地数据库
  • 移除对 JWTService 的依赖
  • 更新 PUBLIC_PATHS（移除 auth 端点，添加 oauth/refresh）
  • 处理 SSO 不可用（503）和 token 无效（401）
  • Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6
  • [ ]* 3.2 编写 AuthMiddleware 属性测试
  • Property 2: Successful SSO verification populates cache
  • Property 3: Invalid tokens are rejected
  • Validates: Requirements 3.4, 3.5

• [x] 4. Checkpoint - 后端核心组件验证

  • Ensure all tests pass, ask the user if questions arise.

• [x] 5. 改造 OAuth Router 和移除 Auth Router

  • 5.1 改造 backend/routers/oauth.py 的 callback 端点
  • 移除 JWTService.create_access_token 和 JWTService.create_refresh_token 调用
  • 直接返回 SSO 的 access_token 和 refresh_token
  • 保留用户信息同步逻辑
  • Requirements: 2.1, 5.1, 5.2, 5.3, 5.4
  • 5.2 在 backend/routers/oauth.py 中新增 /api/oauth/refresh 端点
  • 接收 refresh_token，调用 OAuthService.refresh_sso_token
  • 返回新的 access_token 和 refresh_token
  • Requirements: 4.2, 4.3
  • 5.3 在 backend/routers/oauth.py 中新增 /api/oauth/me 端点
  • 从 request.state.user 获取用户信息（由中间件填充）
  • 查询本地数据库返回完整用户信息
  • Requirements: 2.2
  • 5.4 移除 backend/routers/auth.py 中的 login、register、refresh 端点
  • 保留文件但只保留 /api/auth/me 端点（重定向到 /api/oauth/me）或直接移除整个 router
  • 从 backend/main.py 中移除 auth router 的注册
  • Requirements: 1.1, 1.2, 1.3
  • [ ]* 5.5 编写 User Sync 属性测试
  • Property 5: User sync invariant
  • Validates: Requirements 5.2, 5.3, 5.4

• [x] 6. 配置和清理

  • 6.1 更新 backend/config.py
  • 移除 JWT 相关配置（secret_key, algorithm, expire 等）
  • 新增 token_cache_ttl 配置项
  • 更新 config.dev.yaml 和 config.prod.yaml
  • Requirements: 7.1, 7.2, 7.3
  • 6.2 移除不再需要的后端文件
  • 删除 backend/services/jwt_service.py
  • 精简 backend/services/auth_service.py（移除 register_user, login_user, refresh_tokens）
  • 移除 backend/schemas/auth.py 中不再需要的 schema（UserRegister, UserLogin, TokenRefresh, TokenPayload）
  • Requirements: 1.1, 2.3

• [x] 7. 前端适配

  • 7.1 更新 web/apps/lq_label/src/services/api.ts 中的 token refresh 逻辑
  • 将 refresh 端点从 /api/auth/refresh 改为 /api/oauth/refresh
  • 更新 request interceptor 中跳过 token 的路径列表
  • Requirements: 4.1, 4.4
  • 7.2 改造 web/apps/lq_label/src/components/login-form/login-form.tsx
  • 移除本地登录表单，页面加载时自动发起 SSO 登录
  • 保留加载状态和错误提示
  • Requirements: 6.1, 1.4
  • 7.3 移除注册相关前端代码
  • 移除 register-form 组件
  • 从 app.tsx 路由中移除 /register 路由
  • 从 auth-service.ts 中移除 register 函数
  • Requirements: 1.1, 1.4
  • 7.4 更新 web/apps/lq_label/src/services/auth-service.ts
  • 移除 login、register、refreshToken 函数
  • 更新 getCurrentUser 端点为 /api/oauth/me
  • Requirements: 1.1, 2.2

• [x] 8. Final checkpoint - 全面验证

  • Ensure all tests pass, ask the user if questions arise.

Notes

• Tasks marked with * are optional and can be skipped for faster MVP
• Each task references specific requirements for traceability
• Checkpoints ensure incremental validation
• Property tests validate universal correctness properties
• Unit tests validate specific examples and edge cases
• 前端改动较小，主要是端点 URL 变更和登录页简化
• 数据库无 schema 变更，用户表结构保持不变