# Requirements Document

## Introduction

本文档定义了标注平台的 JWT 权限认证体系需求。该系统将为现有的标注平台添加完整的用户认证和授权功能，包括用户注册、登录、JWT token 管理、以及基于中间件的 API 鉴权机制。

## Glossary

- **Authentication_System**: 用户身份认证系统，负责验证用户身份
- **JWT_Token**: JSON Web Token，用于在客户端和服务器之间安全传输用户身份信息的令牌
- **Access_Token**: 访问令牌，用于访问受保护的 API 端点，有效期较短（15分钟）
- **Refresh_Token**: 刷新令牌，用于获取新的访问令牌，有效期较长（7天）
- **Auth_Middleware**: 认证中间件，在请求到达路由处理器之前验证 JWT token
- **Password_Hash**: 密码哈希，使用 bcrypt 算法加密存储的用户密码
- **User**: 系统用户，具有唯一的用户名和邮箱
- **Role**: 用户角色，定义用户的权限级别（admin, annotator, viewer）
- **Protected_Endpoint**: 受保护的 API 端点，需要有效的 JWT token 才能访问
- **Public_Endpoint**: 公开的 API 端点，无需认证即可访问（如登录、注册）
- **OAuth_Provider**: OAuth 认证提供商，未来用于统一认证（预留字段）
- **OAuth_ID**: OAuth 提供商返回的用户唯一标识（预留字段）
- **Auth_Service**: 认证服务层，封装所有认证相关的业务逻辑

## Requirements

### Requirement 1: 用户注册

**User Story:** 作为新用户，我想要注册一个账号，以便我可以使用标注平台的功能。

#### Acceptance Criteria

1. WHEN 用户提供有效的用户名、邮箱和密码 THEN THE Authentication_System SHALL 创建新用户账号并返回成功消息
2. WHEN 用户提供的用户名已存在 THEN THE Authentication_System SHALL 返回 409 错误并提示用户名已被使用
3. WHEN 用户提供的邮箱已存在 THEN THE Authentication_System SHALL 返回 409 错误并提示邮箱已被使用
4. WHEN 用户提供的密码长度小于 8 个字符 THEN THE Authentication_System SHALL 返回 400 错误并提示密码过短
5. THE Authentication_System SHALL 使用 bcrypt 算法对密码进行哈希加密后存储
6. WHEN 创建新用户 THEN THE Authentication_System SHALL 自动分配默认角色 "annotator"

### Requirement 2: 用户登录

**User Story:** 作为已注册用户，我想要登录系统，以便我可以访问受保护的功能。

#### Acceptance Criteria

1. WHEN 用户提供正确的用户名和密码 THEN THE Authentication_System SHALL 返回 Access_Token 和 Refresh_Token
2. WHEN 用户提供错误的用户名或密码 THEN THE Authentication_System SHALL 返回 401 错误并提示凭据无效
3. THE Access_Token SHALL 包含用户 ID、用户名、邮箱和角色信息
4. THE Access_Token SHALL 设置过期时间为 15 分钟
5. THE Refresh_Token SHALL 设置过期时间为 7 天
6. THE Authentication_System SHALL 在响应中同时返回用户基本信息（ID、用户名、邮箱、角色）

### Requirement 3: Token 刷新

**User Story:** 作为已登录用户，我想要在访问令牌过期后刷新它，以便我可以继续使用系统而无需重新登录。

#### Acceptance Criteria

1. WHEN 用户提供有效的 Refresh_Token THEN THE Authentication_System SHALL 返回新的 Access_Token 和 Refresh_Token
2. WHEN 用户提供无效或过期的 Refresh_Token THEN THE Authentication_System SHALL 返回 401 错误并提示需要重新登录
3. THE Authentication_System SHALL 验证 Refresh_Token 的签名和过期时间
4. THE Authentication_System SHALL 在刷新时生成新的 Refresh_Token 以实现令牌轮换

### Requirement 4: JWT 中间件鉴权

**User Story:** 作为系统管理员，我想要保护 API 端点，以便只有经过认证的用户才能访问受保护的资源。

#### Acceptance Criteria

1. WHEN 请求包含有效的 Authorization header 和 JWT token THEN THE Auth_Middleware SHALL 允许请求继续处理
2. WHEN 请求缺少 Authorization header THEN THE Auth_Middleware SHALL 返回 401 错误并提示缺少认证令牌
3. WHEN 请求包含无效的 JWT token THEN THE Auth_Middleware SHALL 返回 401 错误并提示令牌无效
4. WHEN 请求包含过期的 JWT token THEN THE Auth_Middleware SHALL 返回 401 错误并提示令牌已过期
5. THE Auth_Middleware SHALL 从 JWT token 中提取用户信息并将其附加到请求上下文
6. THE Auth_Middleware SHALL 验证 JWT token 的签名使用配置的密钥

### Requirement 5: 公开端点豁免

**User Story:** 作为系统架构师，我想要某些端点无需认证即可访问，以便用户可以注册和登录。

#### Acceptance Criteria

1. THE Auth_Middleware SHALL 允许 /api/auth/register 端点无需认证访问
2. THE Auth_Middleware SHALL 允许 /api/auth/login 端点无需认证访问
3. THE Auth_Middleware SHALL 允许 /api/auth/refresh 端点无需认证访问
4. THE Auth_Middleware SHALL 允许根路径 / 和 /health 端点无需认证访问
5. THE Auth_Middleware SHALL 允许 /docs 和 /openapi.json 端点无需认证访问

### Requirement 6: 用户信息查询

**User Story:** 作为已登录用户，我想要查询我的用户信息，以便我可以查看和验证我的账号详情。

#### Acceptance Criteria

1. WHEN 已认证用户请求获取当前用户信息 THEN THE Authentication_System SHALL 返回用户的 ID、用户名、邮箱、角色和创建时间
2. WHEN 未认证用户请求获取用户信息 THEN THE Auth_Middleware SHALL 返回 401 错误
3. THE Authentication_System SHALL 从 JWT token 中提取用户 ID 来查询用户信息

### Requirement 7: 密码安全

**User Story:** 作为系统管理员，我想要确保用户密码安全存储，以便保护用户账号不被未授权访问。

#### Acceptance Criteria

1. THE Authentication_System SHALL 使用 bcrypt 算法对所有用户密码进行哈希加密
2. THE Authentication_System SHALL 使用 bcrypt 的默认 salt rounds（12 rounds）
3. THE Password_Hash SHALL 永远不会以明文形式存储或传输
4. WHEN 验证密码 THEN THE Authentication_System SHALL 使用 bcrypt.checkpw 进行安全比对

### Requirement 8: 数据库用户表

**User Story:** 作为数据库管理员，我想要一个用户表来存储用户信息，以便系统可以持久化用户数据。

#### Acceptance Criteria

1. THE Authentication_System SHALL 创建 users 表包含 id、username、email、password_hash、role 和 created_at 字段
2. THE users 表 SHALL 在 username 字段上设置唯一约束
3. THE users 表 SHALL 在 email 字段上设置唯一约束
4. THE users 表 SHALL 在 username 和 email 字段上创建索引以提高查询性能
5. THE Authentication_System SHALL 在数据库初始化时自动创建 users 表

### Requirement 9: 环境配置

**User Story:** 作为系统部署人员，我想要通过环境变量配置 JWT 密钥和过期时间，以便在不同环境中使用不同的配置。

#### Acceptance Criteria

1. THE Authentication_System SHALL 从环境变量 JWT_SECRET_KEY 读取 JWT 签名密钥
2. THE Authentication_System SHALL 从环境变量 JWT_ALGORITHM 读取 JWT 算法（默认 HS256）
3. THE Authentication_System SHALL 从环境变量 ACCESS_TOKEN_EXPIRE_MINUTES 读取访问令牌过期时间（默认 15 分钟）
4. THE Authentication_System SHALL 从环境变量 REFRESH_TOKEN_EXPIRE_DAYS 读取刷新令牌过期时间（默认 7 天）
5. WHEN JWT_SECRET_KEY 未设置 THEN THE Authentication_System SHALL 生成随机密钥并在日志中警告

### Requirement 10: 错误处理

**User Story:** 作为 API 用户，我想要收到清晰的错误消息，以便我可以理解认证失败的原因。

#### Acceptance Criteria

1. WHEN 认证失败 THEN THE Authentication_System SHALL 返回包含错误类型和详细消息的 JSON 响应
2. THE Authentication_System SHALL 对不同的错误场景返回适当的 HTTP 状态码（400、401、409、500）
3. THE Authentication_System SHALL 在日志中记录认证失败事件但不记录敏感信息（如密码）
4. WHEN 发生服务器内部错误 THEN THE Authentication_System SHALL 返回 500 错误并记录详细错误信息

### Requirement 11: 现有 API 集成

**User Story:** 作为系统架构师，我想要将认证系统集成到现有的 API 端点，以便保护项目、任务和标注相关的操作。

#### Acceptance Criteria

1. THE Auth_Middleware SHALL 保护所有 /api/projects 端点
2. THE Auth_Middleware SHALL 保护所有 /api/tasks 端点
3. THE Auth_Middleware SHALL 保护所有 /api/annotations 端点
4. WHEN 创建或修改资源 THEN THE Authentication_System SHALL 使用当前认证用户的 ID 作为 user_id 或 assigned_to
5. THE Authentication_System SHALL 确保用户只能访问和修改自己有权限的资源

### Requirement 12: 用户角色权限

**User Story:** 作为系统管理员，我想要基于用户角色控制访问权限，以便不同角色的用户有不同的操作权限。

#### Acceptance Criteria

1. THE Authentication_System SHALL 支持三种角色：admin、annotator、viewer
2. WHEN 用户角色为 admin THEN THE Authentication_System SHALL 允许所有操作
3. WHEN 用户角色为 annotator THEN THE Authentication_System SHALL 允许创建和修改标注，但不能删除项目
4. WHEN 用户角色为 viewer THEN THE Authentication_System SHALL 只允许读取操作，不能创建、修改或删除
5. THE Auth_Middleware SHALL 提供角色检查装饰器用于保护特定端点

### Requirement 13: OAuth 集成预留

**User Story:** 作为系统架构师，我想要为未来的 OAuth 认证服务中心集成预留接口，以便系统可以平滑过渡到统一认证。

#### Acceptance Criteria

1. THE Authentication_System SHALL 设计可扩展的认证接口，支持未来集成 OAuth 提供商
2. THE User 模型 SHALL 预留 oauth_provider 和 oauth_id 字段用于存储 OAuth 提供商信息
3. THE Authentication_System SHALL 将认证逻辑封装在独立的服务层，便于未来替换或扩展
4. THE JWT_Token 结构 SHALL 保持标准化，确保与 OAuth token 兼容
5. THE Authentication_System SHALL 在配置中预留 OAuth 相关的环境变量占位符