Implementation Plan: JWT Authentication System

Overview

本实现计划将 JWT 权限认证体系集成到标注平台中。采用增量开发方式，先实现后端核心功能，再集成到现有 API，最后实现前端。每个任务都包含具体的实现步骤和测试要求。

Tasks

[x] 1. 环境准备和依赖安装
- 安装 PyJWT、bcrypt、python-multipart 等依赖包
- 更新 requirements.txt 文件
- 创建 .env.example 文件模板
- Requirements: 9.1, 9.2, 9.3, 9.4
[ ] 2. 配置模块实现
- 2.1 创建 config.py 配置文件
- 实现 Settings 类使用 pydantic-settings
- 定义 JWT 相关配置（密钥、算法、过期时间）
- 定义 OAuth 预留配置
- 添加默认值和环境变量读取
- Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 13.5
- [ ]* 2.2 编写配置模块单元测试
- 测试环境变量读取
- 测试默认值设置
- 测试配置验证
- Requirements: 9.1, 9.2, 9.3, 9.4
[ ] 3. 数据库模型和初始化
- 3.1 扩展 User 模型
- 在 models.py 中添加 User 类
- 定义所有必需字段（id, username, email, password_hash, role, oauth_provider, oauth_id, created_at）
- 实现 from_row 类方法
- Requirements: 8.1, 13.2
- [x] 3.2 更新数据库初始化
- 在 database.py 的 init_database 函数中添加 users 表创建 SQL
- 添加唯一约束（username, email）
- 创建索引（username, email, oauth）
- Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
- [ ]* 3.3 编写数据库初始化测试
- 测试 users 表创建
- 测试唯一约束
- 测试索引创建
- Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
[ ] 4. Pydantic Schemas 定义
- 4.1 创建 schemas/auth.py 文件
- 定义 UserRegister schema（username, email, password 验证）
- 定义 UserLogin schema
- 定义 TokenResponse schema
- 定义 TokenRefresh schema
- 定义 UserResponse schema
- 定义 TokenPayload schema
- Requirements: 1.1, 1.4, 2.1, 3.1, 6.1
- [ ]* 4.2 编写 schema 验证测试
- 测试密码长度验证（最少 8 字符）
- 测试邮箱格式验证
- 测试用户名长度验证
- Requirements: 1.4
[ ] 5. JWT Service 实现
- 5.1 创建 services/jwt_service.py
- 实现 create_access_token 方法（15分钟过期）
- 实现 create_refresh_token 方法（7天过期）
- 实现 verify_token 方法（验证签名和过期时间）
- 处理 JWT 异常（ExpiredSignatureError, InvalidTokenError）
- Requirements: 2.1, 2.3, 2.4, 2.5, 3.1, 3.3, 4.6
- [ ]* 5.2 编写 JWT Service 单元测试
- 测试 access token 创建和验证
- 测试 refresh token 创建和验证
- 测试 token 过期处理
- 测试无效 token 处理
- Requirements: 2.4, 2.5, 3.2, 4.3, 4.4
- [ ]* 5.3 编写 JWT Service 属性测试
- Property 7: Token 过期时间正确设置
- Validates: Requirements 2.4, 2.5
[ ] 6. Auth Service 实现
- 6.1 创建 services/auth_service.py
- 实现 register_user 方法（用户注册）
- 使用 bcrypt 哈希密码
- 检查用户名和邮箱唯一性
- 自动分配默认角色 "annotator"
- Requirements: 1.1, 1.2, 1.3, 1.5, 1.6, 7.1, 7.2
- [x] 6.2 实现登录功能
- 实现 login_user 方法
- 验证用户名和密码
- 使用 bcrypt.checkpw 验证密码
- 生成 access_token 和 refresh_token
- 返回 tokens 和用户信息
- Requirements: 2.1, 2.2, 2.6, 7.4
- [x] 6.3 实现 token 刷新功能
- 实现 refresh_tokens 方法
- 验证 refresh_token
- 生成新的 access_token 和 refresh_token（token rotation）
- 处理 token 过期和无效情况
- Requirements: 3.1, 3.2, 3.4
- [x] 6.4 实现用户查询功能
- 实现 get_current_user 方法
- 根据 user_id 查询用户信息
- 处理用户不存在情况
- Requirements: 6.1, 6.3
- [ ]* 6.5 编写 Auth Service 单元测试
- 测试用户注册成功场景
- 测试重复用户名/邮箱错误
- 测试登录成功和失败场景
- 测试 token 刷新
- 测试用户查询
- Requirements: 1.1, 1.2, 1.3, 2.1, 2.2, 3.1, 3.2, 6.1
- [ ]* 6.6 编写 Auth Service 属性测试
- Property 1: 用户注册创建有效用户
- Property 2: 密码哈希不可逆
- Property 3: 短密码被拒绝
- Property 4: 新用户默认角色
- Property 5: 登录返回有效 Tokens
- Property 6: Access Token 包含完整用户信息
- Property 8: Token 刷新生成新令牌
- Validates: Requirements 1.1, 1.2, 1.4, 1.5, 1.6, 2.1, 2.3, 3.1, 3.4
[ ] 7. Checkpoint - 核心服务测试
- 确保所有核心服务测试通过
- 验证 JWT token 生成和验证正常
- 验证用户注册和登录流程
- 如有问题请询问用户
[ ] 8. Auth Middleware 实现
- 8.1 创建 middleware/auth_middleware.py
- 实现 AuthMiddleware 类继承 BaseHTTPMiddleware
- 定义公开路径列表（PUBLIC_PATHS）
- 实现 dispatch 方法处理每个请求
- 从 Authorization header 提取 JWT token
- 验证 token 格式（Bearer ）
- 调用 JWTService.verify_token 验证 token
- 将用户信息附加到 request.state.user
- 处理各种错误情况（缺少 token、无效 token、过期 token）
- Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 5.1, 5.2, 5.3, 5.4, 5.5
- [x] 8.2 实现角色检查装饰器
- 实现 require_role 装饰器函数
- 检查 request.state.user 中的角色
- 返回 403 错误如果角色不匹配
- Requirements: 12.2, 12.3, 12.4, 12.5
- [ ]* 8.3 编写 Middleware 单元测试
- 测试公开端点无需认证
- 测试受保护端点需要 token
- 测试缺少 Authorization header
- 测试无效 token 格式
- 测试过期 token
- 测试用户信息附加到 request.state
- Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 5.1, 5.2, 5.3, 5.4, 5.5
- [ ]* 8.4 编写 Middleware 属性测试
- Property 9: 中间件验证有效 Token
- Validates: Requirements 4.1, 4.5
[ ] 9. Auth Router 实现
- 9.1 创建 routers/auth.py
- 创建 APIRouter 实例（prefix="/api/auth", tags=["authentication"]）
- 实现 POST /register 端点
- 实现 POST /login 端点
- 实现 POST /refresh 端点
- 实现 GET /me 端点
- 添加详细的文档字符串
- 使用 Pydantic schemas 进行请求/响应验证
- Requirements: 1.1, 2.1, 3.1, 6.1
- [ ]* 9.2 编写 Auth Router 集成测试
- 测试注册端点（成功和失败场景）
- 测试登录端点（成功和失败场景）
- 测试 token 刷新端点
- 测试获取当前用户端点
- Requirements: 1.1, 1.2, 1.3, 2.1, 2.2, 3.1, 3.2, 6.1, 6.2
- [ ]* 9.3 编写 Auth Router 属性测试
- Property 10: 用户信息端点返回正确数据
- Validates: Requirements 6.1
[ ] 10. 主应用集成
- 10.1 更新 main.py
- 导入 AuthMiddleware
- 在 CORS 中间件之后添加 AuthMiddleware
- 导入并注册 auth router
- 确保中间件顺序正确
- Requirements: 4.1, 11.1, 11.2, 11.3
- [x] 10.2 更新 routers/init.py
- 导出 auth router
- Requirements: 1.1, 2.1, 3.1, 6.1
[ ] 11. 现有 API 集成
- 11.1 更新 Project Router
- 在需要的端点中使用 request.state.user 获取当前用户
- 添加角色检查（如删除操作需要 admin 角色）
- Requirements: 11.1, 11.4, 12.2, 12.3
- [x] 11.2 更新 Task Router
- 在创建任务时使用 request.state.user.id 作为 assigned_to
- 添加角色检查
- Requirements: 11.2, 11.4, 12.2, 12.3
- [x] 11.3 更新 Annotation Router
- 在创建标注时使用 request.state.user.id 作为 user_id
- 确保用户只能访问自己的标注
- Requirements: 11.3, 11.4, 11.5, 12.2, 12.3
- [ ]* 11.4 编写 API 集成测试
- Property 11: 现有 API 端点受保护
- 测试所有受保护端点需要认证
- 测试用户信息正确传递到路由处理器
- Validates: Requirements 11.1, 11.2, 11.3, 11.4
- [ ]* 11.5 编写角色权限属性测试
- Property 12: 角色权限控制
- 测试不同角色的访问权限
- Validates: Requirements 12.2, 12.3, 12.4
[x] 12. Checkpoint - 后端完整测试
- 运行所有测试确保通过
- 测试完整的认证流程（注册 → 登录 → 访问受保护端点 → 刷新 token）
- 验证中间件正确保护所有端点
- 验证角色权限控制
- 如有问题请询问用户
[ ] 13. 环境配置和文档
- 13.1 更新 .env.example
- 添加 JWT_SECRET_KEY 示例
- 添加 JWT_ALGORITHM 示例
- 添加 ACCESS_TOKEN_EXPIRE_MINUTES 示例
- 添加 REFRESH_TOKEN_EXPIRE_DAYS 示例
- 添加 OAuth 预留配置示例
- Requirements: 9.1, 9.2, 9.3, 9.4, 13.5
- [x] 13.2 更新 backend/README.md
- 添加认证系统说明
- 添加环境变量配置说明
- 添加 API 端点文档
- 添加使用示例
- Requirements: 1.1, 2.1, 3.1, 6.1, 9.1
[ ] 14. 前端认证实现（可选）
- 14.1 创建认证 Atoms
- 在 web/apps/lq_label/src/atoms/ 创建 auth-atoms.ts
- 定义 authTokensAtom（使用 atomWithStorage）
- 定义 currentUserAtom
- 定义 isAuthenticatedAtom
- 定义 logoutAtom
- Requirements: 2.1, 6.1
- [x] 14.2 创建认证服务
- 在 web/apps/lq_label/src/services/ 创建 auth-service.ts
- 实现 register 方法
- 实现 login 方法
- 实现 refreshToken 方法
- 实现 getCurrentUser 方法
- Requirements: 1.1, 2.1, 3.1, 6.1
- [x] 14.3 配置 Axios 拦截器
- 在 web/apps/lq_label/src/services/api.ts 更新
- 实现请求拦截器（自动附加 token）
- 实现响应拦截器（处理 token 过期和自动刷新）
- 实现请求队列机制
- Requirements: 2.1, 3.1, 4.1, 4.4
- [x] 14.4 创建登录组件
- 在 web/apps/lq_label/src/components/ 创建 login-form/
- 实现 LoginForm 组件
- 使用 Jotai 管理状态
- 调用 authService.login
- 处理错误显示
- 登录成功后跳转
- Requirements: 2.1
- [x] 14.5 创建注册组件
- 在 web/apps/lq_label/src/components/ 创建 register-form/
- 实现 RegisterForm 组件
- 表单验证（密码长度、邮箱格式）
- 调用 authService.register
- 处理错误显示
- Requirements: 1.1, 1.4
- [x] 14.6 创建路由保护组件
- 在 web/apps/lq_label/src/components/ 创建 protected-route/
- 实现 ProtectedRoute 组件
- 检查 isAuthenticatedAtom
- 未认证时重定向到登录页
- Requirements: 4.1, 11.1, 11.2, 11.3
- [x] 14.7 更新应用路由
- 在 web/apps/lq_label/src/app/app.tsx 中添加认证路由
- 添加 /login 路由
- 添加 /register 路由
- 使用 ProtectedRoute 包装受保护的路由
- Requirements: 1.1, 2.1, 4.1
- [ ] 14.8 更新现有 API 调用
- 将所有 axios 调用替换为 apiClient
- 确保自动附加 token
- 测试 token 刷新机制
- Requirements: 4.1, 11.1, 11.2, 11.3
[ ] 15. 端到端测试
- [ ]* 15.1 编写完整认证流程测试
- 测试注册 → 登录 → 访问受保护端点 → 刷新 token → 登出
- 测试前后端集成
- 测试错误处理
- Requirements: 1.1, 2.1, 3.1, 4.1, 6.1, 11.1, 11.2, 11.3
[ ] 16. Final Checkpoint - 完整系统验证
- 运行所有测试（单元测试 + 属性测试 + 集成测试）
- 手动测试完整的用户流程
- 验证前后端集成
- 检查代码覆盖率（目标 80%+）
- 确认所有需求已实现
- 如有问题请询问用户

Notes

标记 * 的任务为可选测试任务，可以跳过以加快 MVP 开发
每个任务都引用了相关的需求编号，确保可追溯性
Checkpoint 任务用于确保增量验证，及时发现问题
属性测试使用 Hypothesis 库，每个测试最少 100 次迭代
单元测试使用 pytest 框架
前端任务（Task 14）为可选，可以先完成后端再实现前端
所有测试文件必须保存在 backend/test/ 目录中

tasks.md 12 KB Riwayat Mentahan

Implementation Plan: JWT Authentication System

Overview

Tasks

Notes

tasks.md 12 KB

Riwayat Mentahan