# Story 1.2: 用户注册功能

## Status
Draft

## Story
**作为一个** 新用户，
**我想要** 通过用户名、邮箱和密码注册账户，
**以便** 开始使用云盘服务。

## Acceptance Criteria
1. 用户注册表单实现，包含用户名、邮箱、密码字段
2. 前端表单验证功能，包括邮箱格式、密码强度检查
3. 后端注册API实现，用户名和邮箱唯一性验证
4. 密码使用BCrypt加密存储到数据库
5. 注册成功后自动跳转到登录页面
6. 错误信息友好显示，包括用户名已存在、邮箱格式错误等

## Tasks / Subtasks
- [ ] 设计用户注册数据模型 (AC: 3, 4)
  - [ ] 创建User Pydantic模型 (包含username, email, password, confirm_password)
  - [ ] 实现数据验证规则 (username长度、邮箱格式、密码强度)
  - [ ] 配置数据库User模型映射 [Source: architecture.md#数据库架构设计]
  - [ ] 添加数据库唯一约束验证
- [ ] 创建后端注册API (AC: 2, 3, 4, 6)
  - [ ] 实现POST /api/v1/auth/register端点 [Source: architecture.md#API架构设计]
  - [ ] 实现用户名唯一性验证逻辑
  - [ ] 实现邮箱唯一性验证逻辑
  - [ ] 实现bcrypt密码哈希存储 [Source: architecture.md#安全架构设计]
  - [ ] 实现标准API响应格式 [Source: architecture.md#API架构设计]
  - [ ] 实现详细的错误响应处理 (400状态码)
- [ ] 创建前端注册表单组件 (AC: 1, 2, 6)
  - [ ] 创建RegisterForm组件使用shadcn/ui [Source: architecture.md#技术栈架构]
  - [ ] 集成React Hook Form进行表单管理
  - [ ] 实现客户端表单验证 (邮箱格式、密码强度)
  - [ ] 创建输入字段: username、email、password、confirm_password
  - [ ] 添加表单提交按钮和加载状态
  - [ ] 实现表单错误状态显示
- [ ] 实现前后端数据交互 (AC: 5, 6)
  - [ ] 使用React Query创建注册API调用钩子
  - [ ] 实现注册成功处理逻辑
  - [ ] 实现自动跳转到登录页面功能
  - [ ] 实现错误信息显示 (用户名已存在、邮箱格式错误等)
  - [ ] 添加注册成功反馈信息
- [ ] 创建注册页面路由 (AC: 5)
  - [ ] 配置React Router注册页面路由
  - [ ] 创建RegisterPage页面组件
  - [ ] 添加页面标题和说明文字
  - [ ] 添加登录页面链接
- [ ] 实现输入验证和安全检查 (AC: 2, 4)
  - [ ] 实现前端邮箱格式正则验证
  - [ ] 实现密码强度验证 (长度、字符类型)
  - [ ] 实现密码确认匹配验证
  - [ ] 添加用户名格式和长度限制
  - [ ] 实现防重复提交机制
- [ ] 编写注册功能测试 (AC: 1-6)
  - [ ] 后端API单元测试 (成功和失败场景)
  - [ ] 前端组件单元测试 (表单验证、提交逻辑)
  - [ ] 端到端集成测试 (完整注册流程)
  - [ ] 验证密码加密存储测试
  - [] 验证唯一性约束测试

## Dev Notes

### API设计要求
- **端点**: POST /api/v1/auth/register [Source: architecture.md#API架构设计]
- **请求体**:
  ```json
  {
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123",
    "confirm_password": "password123"
  }
  ```
- **成功响应**: 201状态码，包含用户信息 [Source: architecture.md#API架构设计]
- **错误响应**: 400状态码，详细验证错误 [Source: architecture.md#API架构设计]

### 数据库要求
- **用户表**: 使用architecture.md中定义的用户表结构 [Source: architecture.md#数据库架构设计]
- **必填字段**: username (VARCHAR(50) UNIQUE), email (VARCHAR(100) UNIQUE), password_hash (VARCHAR(255))
- **索引**: username和email的唯一索引 [Source: architecture.md#数据库架构设计]
- **密码存储**: 使用bcrypt哈希存储在password_hash字段 [Source: architecture.md#安全架构设计]

### 安全要求
- **密码加密**: 必须使用bcrypt进行密码哈希，盐值自动生成 [Source: architecture.md#安全架构设计]
- **输入验证**: 使用Pydantic进行严格的数据验证和清理 [Source: architecture.md#安全架构设计]
- **SQL注入防护**: 使用SQLAlchemy参数化查询 [Source: architecture.md#安全架构设计]
- **唯一性检查**: 数据库层面的username和email唯一约束

### 前端技术要求
- **组件库**: 使用shadcn/ui的Input、Button、Card、Label组件 [Source: architecture.md#技术栈架构]
- **表单管理**: 使用React Hook Form进行表单状态管理
- **验证库**: 使用Zod进行客户端验证
- **状态管理**: 使用React Query处理API调用和缓存
- **路由**: 使用React Router进行页面导航

### 用户体验要求
- **表单验证**: 实时反馈验证错误
- **加载状态**: 提交时显示加载指示器
- **错误提示**: 友好的错误信息显示
- **成功反馈**: 注册成功后的清晰提示
- **自动跳转**: 成功后自动跳转到登录页面

### Testing
#### 测试标准
- **测试文件位置**:
  - 后端: tests/test_auth.py
  - 前端: src/components/auth/__tests__/RegisterForm.test.tsx
- **测试框架**:
  - 后端: pytest + httpx测试客户端
  - 前端: Vitest + @testing-library/react
- **测试覆盖**:
  - API端点测试 (成功注册、各种失败场景)
  - 表单验证测试 (客户端验证)
  - 密码加密测试 (验证bcrypt哈希)
  - 唯一性约束测试 (用户名、邮箱重复)
  - E2E测试 (完整注册流程)

#### 测试要求
- **API测试**: 必须测试所有验证规则和错误场景
- **组件测试**: 必须测试表单验证和用户交互
- **安全测试**: 必须验证密码正确加密存储
- **集成测试**: 必须测试完整的前后端注册流程

### 技术实现细节
- **前端验证规则**:
  - username: 3-50字符，字母数字下划线
  - email: 有效的邮箱格式
  - password: 最少8位，包含字母和数字
  - confirm_password: 必须与password匹配
- **后端验证规则**:
  - 检查username和email在数据库中的唯一性
  - 密码必须通过bcrypt哈希后存储
  - 使用SQLAlchemy进行安全的数据库操作
- **错误处理**: 统一的错误响应格式，支持字段级别的错误信息

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-10-11 | v1.0 | 初始故事创建 | Sarah (Agile Master) |

## Dev Agent Record
*此部分由开发代理在实现过程中填写*

## QA Results
*此部分由QA代理在测试完成后填写*