SDD 精通指南

# 实施计划：用户登录服务

## 技术选型

### 后端框架：FastAPI
**选型理由**：
- 原生支持异步，性能优异
- 自动生成 OpenAPI 文档
- Pydantic 提供强大的数据验证
- 团队已有使用经验

### 数据库：PostgreSQL
**选型理由**：
- 支持复杂查询和事务
- 团队熟悉度高
- 已有基础设施

### 缓存：Redis
**选型理由**：
- 验证码存储（5 分钟过期）
- 登录失败计数（滑动窗口）
- Token 黑名单（登出场景）

## 架构设计

### 组件图
┌─────────┐    ┌──────────┐    ┌──────────┐
│  Client  │───▶│  API GW  │───▶│  Auth    │
│  (Web)   │◀───│  (Nginx) │◀───│  Service │
└─────────┘    └──────────┘    └────┬─────┘
                                    │
                          ┌─────────┼─────────┐
                          ▼         ▼         ▼
                     ┌────────┐ ┌──────┐ ┌────────┐
                     │Postgres│ │Redis │ │ 邮件   │
                     │        │ │      │ │ 服务   │
                     └────────┘ └──────┘ └────────┘

### 数据模型

#### 用户表（users）
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | UUID | PK | 用户唯一标识 |
| email | VARCHAR(255) | UNIQUE, NOT NULL | 邮箱 |
| password_hash | VARCHAR(255) | NOT NULL | bcrypt 加密密码 |
| phone | VARCHAR(20) | UNIQUE, NULLABLE | 手机号 |
| status | ENUM | NOT NULL | 状态：active/locked |
| failed_attempts | INT | DEFAULT 0 | 连续失败次数 |
| locked_until | TIMESTAMP | NULLABLE | 锁定截止时间 |
| created_at | TIMESTAMP | DEFAULT NOW | 创建时间 |

### API 设计

#### POST /api/v1/auth/login
**请求体**：
{
  "email": "user@example.com",
  "password": "***"
}

**成功响应**（200）：
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-08-01T09:04:38Z"
}

**失败响应**（401）：
{
  "error": "invalid_credentials",
  "message": "邮箱或密码错误"
}

## 开发阶段

### Phase 1：基础框架（1 天）
- 项目初始化
- 数据库连接配置
- 基础中间件（日志、错误处理）

### Phase 2：核心功能（2 天）
- 用户认证逻辑
- JWT Token 生成
- 密码加密存储

### Phase 3：安全增强（1 天）
- 登录失败计数
- 账号锁定机制
- 验证码逻辑

### Phase 4：测试与部署（1 天）
- 单元测试（覆盖率 > 80%）
- 集成测试
- Docker 化部署