# JWT 认证系统快速指南

## 概述

本系统已成功集成 JWT（JSON Web Token）认证体系，提供完整的用户注册、登录、令牌刷新和基于角色的访问控制功能。

## 主要特性

✅ **用户注册和登录**
- 用户名和邮箱唯一性验证
- 密码使用 bcrypt 加密存储
- 自动分配默认角色（annotator）

✅ **JWT 令牌管理**
- Access Token（15分钟有效期）
- Refresh Token（7天有效期）
- Token Rotation 机制

✅ **中间件认证**
- 自动验证所有受保护端点
- 公开端点无需认证
- 用户信息自动附加到请求

✅ **基于角色的访问控制**
- annotator：普通标注员
- admin：管理员（可删除资源）

✅ **自动用户关联**
- 创建任务时自动分配给当前用户
- 创建标注时自动使用当前用户 ID
- 用户只能查看和修改自己的标注

## 快速开始

### 1. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# 生成安全的 JWT 密钥
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 编辑 .env 文件，设置 JWT_SECRET_KEY
```

### 2. 启动服务器

```bash
python main.py
```

服务器将在 http://localhost:8000 启动

### 3. 测试认证流程

运行测试脚本：

```powershell
.\test_auth_flow.ps1
```

或手动测试：

```bash
# 注册用户
curl -X POST "http://localhost:8000/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com", "password": "password123"}'

# 登录
curl -X POST "http://localhost:8000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "password123"}'

# 使用 token 访问受保护端点
curl -X GET "http://localhost:8000/api/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## API 端点

### 认证端点（公开）

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/auth/register` | POST | 用户注册 |
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/refresh` | POST | 刷新令牌 |

### 认证端点（需要 token）

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/auth/me` | GET | 获取当前用户信息 |

### 受保护端点

所有 `/api/projects/*`、`/api/tasks/*`、`/api/annotations/*` 端点都需要认证。

### 管理员专用端点

| 端点 | 方法 | 描述 | 角色要求 |
|------|------|------|----------|
| `DELETE /api/projects/{id}` | DELETE | 删除项目 | admin |
| `DELETE /api/tasks/{id}` | DELETE | 删除任务 | admin |

## 权限规则

### 项目（Projects）
- ✅ 所有认证用户可以创建、查看、更新项目
- ❌ 只有管理员可以删除项目

### 任务（Tasks）
- ✅ 所有认证用户可以创建、查看、更新任务
- ✅ 创建任务时，如果未指定 `assigned_to`，自动分配给当前用户
- ❌ 只有管理员可以删除任务

### 标注（Annotations）
- ✅ 所有认证用户可以创建标注
- ✅ 创建标注时，自动使用当前用户 ID（忽略请求中的 user_id）
- ✅ 用户只能查看和修改自己的标注
- ✅ 管理员可以查看和修改所有标注

## 错误处理

### 401 Unauthorized

**原因**：
- 缺少 Authorization header
- Token 格式错误
- Token 已过期
- Token 无效

**解决方案**：
- 确保包含 `Authorization: Bearer <token>` header
- 使用 refresh token 获取新的 access token

### 403 Forbidden

**原因**：
- 用户角色权限不足
- 尝试访问其他用户的资源

**解决方案**：
- 联系管理员提升权限
- 只访问自己的资源

## 安全建议

### 开发环境
- ✅ 可以使用自动生成的 JWT_SECRET_KEY
- ✅ 使用 HTTP（localhost）

### 生产环境
- ⚠️ **必须**设置强随机的 JWT_SECRET_KEY
- ⚠️ **必须**使用 HTTPS
- ⚠️ **必须**配置正确的 CORS 设置
- ⚠️ 建议启用速率限制
- ⚠️ 建议添加日志审计

## 令牌生命周期

```
注册/登录
    ↓
获得 Access Token (15分钟) + Refresh Token (7天)
    ↓
使用 Access Token 访问 API
    ↓
Access Token 过期
    ↓
使用 Refresh Token 获取新的 Access Token
    ↓
继续使用新的 Access Token
    ↓
Refresh Token 过期
    ↓
需要重新登录
```

## 数据库结构

### users 表

| 字段 | 类型 | 描述 |
|------|------|------|
| id | TEXT | 用户唯一标识 |
| username | TEXT | 用户名（唯一） |
| email | TEXT | 邮箱（唯一） |
| password_hash | TEXT | 密码哈希 |
| role | TEXT | 用户角色 |
| oauth_provider | TEXT | OAuth 提供商（预留） |
| oauth_id | TEXT | OAuth ID（预留） |
| created_at | TIMESTAMP | 创建时间 |

## 测试结果

所有测试已通过 ✅

1. ✅ 用户注册
2. ✅ 用户登录
3. ✅ 访问受保护端点（带 token）
4. ✅ 拒绝未认证请求（无 token）
5. ✅ 创建项目（认证）
6. ✅ 创建任务（自动分配给当前用户）
7. ✅ 创建标注（自动使用当前用户 ID）
8. ✅ 令牌刷新
9. ✅ 拒绝非管理员删除操作

## 下一步

### 可选功能（未实现）

- [ ] 前端认证集成（React + Jotai）
- [ ] OAuth 2.0 集成（Google, GitHub）
- [ ] 邮箱验证
- [ ] 密码重置
- [ ] 用户资料管理
- [ ] 审计日志
- [ ] 速率限制
- [ ] 双因素认证（2FA）

### 实现前端认证

参考 `.kiro/specs/jwt-authentication/tasks.md` 中的 Task 14，包含：

1. 创建认证 Atoms（Jotai）
2. 创建认证服务
3. 配置 Axios 拦截器
4. 创建登录/注册组件
5. 实现路由保护

## 故障排除

### 问题：服务器启动时提示"使用默认生成的 JWT_SECRET_KEY"

**解决方案**：这是正常的开发环境提示。生产环境请在 `.env` 文件中设置 `JWT_SECRET_KEY`。

### 问题：Token 一直提示过期

**解决方案**：
1. 检查系统时间是否正确
2. 使用 refresh token 获取新的 access token
3. 如果 refresh token 也过期，需要重新登录

### 问题：无法访问其他用户的标注

**解决方案**：这是设计行为。普通用户只能访问自己的标注，管理员可以访问所有标注。

## 联系方式

如有问题或建议，请联系项目维护者。

---

**文档版本**: 1.0  
**最后更新**: 2024-01-22  
**状态**: ✅ 生产就绪