# 认证API

<cite>
**本文档引用的文件**
- [auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [auth.service.ts](file://server/src/modules/auth/auth.service.ts)
- [auth.ts](file://server/src/middleware/auth.ts)
- [rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [app.ts](file://server/src/app.ts)
- [errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [index.ts](file://server/src/types/index.ts)
- [index.ts](file://server/src/config/index.ts)
- [index.ts](file://server/src/models/index.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

本文件为音频TTS平台的认证模块API文档，涵盖以下三个核心接口：
- 发送验证码接口：POST /api/auth/send-code
- 手机号登录接口：POST /api/auth/login  
- 获取用户信息接口：GET /api/auth/user-info

文档详细说明了每个接口的请求参数、响应格式、HTTP状态码和错误处理机制，并提供了完整的请求示例和响应示例，包括成功和失败场景。同时说明了JWT令牌的使用方式和认证头部的设置方法，包含安全考虑、频率限制和最佳实践建议。

## 项目结构

认证模块采用分层架构设计，主要包含以下层次：

```mermaid
graph TB
subgraph "应用层"
Router[路由层]
Controller[控制器层]
end
subgraph "业务逻辑层"
Service[服务层]
end
subgraph "基础设施层"
Middleware[中间件层]
Database[(数据库)]
Redis[(Redis缓存)]
end
subgraph "外部服务"
SMS[短信服务]
Storage[存储服务]
end
Router --> Controller
Controller --> Service
Service --> Database
Service --> Redis
Service --> SMS
Controller --> Middleware
Middleware --> Service
```

**图表来源**
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)

**章节来源**
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)

## 核心组件

### 路由与控制器

认证模块通过Koa Router提供RESTful API接口，采用模块化设计，每个接口都有独立的路由处理函数。

### 服务层

服务层封装了核心业务逻辑，包括：
- 验证码生成与验证
- JWT令牌生成与验证
- 用户信息管理
- 数据库操作

### 中间件层

中间件层提供认证、授权、频率限制等横切关注点，确保系统的安全性和稳定性。

**章节来源**
- [auth.controller.ts:10-64](file://server/src/modules/auth/auth.controller.ts#L10-L64)
- [auth.service.ts:10-97](file://server/src/modules/auth/auth.service.ts#L10-L97)
- [auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)

## 架构概览

认证系统的整体架构如下：

```mermaid
sequenceDiagram
participant Client as 客户端
participant Router as 路由器
participant Controller as 控制器
participant Service as 服务层
participant DB as 数据库
participant Redis as Redis缓存
Client->>Router : HTTP请求
Router->>Controller : 调用对应处理函数
Controller->>Service : 执行业务逻辑
Service->>DB : 查询/更新用户信息
Service->>Redis : 缓存验证码
Service-->>Controller : 返回处理结果
Controller-->>Client : HTTP响应
Note over Client,DB : 认证流程中涉及JWT令牌验证
```

**图表来源**
- [app.ts:100](file://server/src/app.ts#L100)
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)

## 详细组件分析

### 发送验证码接口

#### 接口定义
- **URL**: POST /api/auth/send-code
- **功能**: 向指定手机号发送验证码
- **认证**: 无需认证

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| phone | string | 是 | 手机号码 | "13800001111" |

#### 响应格式

**成功响应**:
```json
{
  "code": 0,
  "message": "验证码发送成功",
  "data": {
    "phone": "13800001111",
    "code": "1234"
  }
}
```

**失败响应**:
```json
{
  "code": 400,
  "message": "请输入正确的手机号",
  "data": null
}
```

#### HTTP状态码
- 200: 请求成功
- 400: 参数验证失败
- 500: 服务器内部错误

#### 业务逻辑

```mermaid
flowchart TD
Start([开始]) --> ValidatePhone[验证手机号格式]
ValidatePhone --> PhoneValid{手机号有效?}
PhoneValid --> |否| ReturnError[返回错误]
PhoneValid --> |是| GenerateCode[生成验证码]
GenerateCode --> StoreCode[存储到Redis/内存]
StoreCode --> ReturnSuccess[返回成功响应]
ReturnError --> End([结束])
ReturnSuccess --> End
```

**图表来源**
- [auth.controller.ts:11-30](file://server/src/modules/auth/auth.controller.ts#L11-L30)
- [auth.service.ts:11-19](file://server/src/modules/auth/auth.service.ts#L11-L19)

**章节来源**
- [auth.controller.ts:11-30](file://server/src/modules/auth/auth.controller.ts#L11-L30)
- [auth.service.ts:11-19](file://server/src/modules/auth/auth.service.ts#L11-L19)

### 手机号登录接口

#### 接口定义
- **URL**: POST /api/auth/login
- **功能**: 使用手机号进行登录或注册
- **认证**: 无需认证

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| phone | string | 是 | 手机号码 | "13800001111" |
| code | string | 否 | 验证码 | "123456" |

#### 响应格式

**成功响应**:
```json
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "123",
      "phone": "13800001111",
      "nickname": "用户1111",
      "avatar": "https://api.dicebear.com/...",
      "memberLevel": 0,
      "isNewUser": true
    }
  }
}
```

**失败响应**:
```json
{
  "code": 400,
  "message": "验证码错误或已过期",
  "data": null
}
```

#### HTTP状态码
- 200: 登录成功
- 400: 验证失败或参数错误
- 500: 服务器内部错误

#### 登录流程

```mermaid
sequenceDiagram
participant Client as 客户端
participant Controller as 控制器
participant Service as 服务层
participant DB as 数据库
Client->>Controller : POST /api/auth/login
Controller->>Controller : 验证手机号格式
Controller->>Service : loginWithPhone(phone, code)
Service->>Service : 验证验证码(可选)
Service->>DB : 查找用户或创建新用户
DB-->>Service : 用户信息
Service->>Service : 生成JWT令牌
Service-->>Controller : 返回登录结果
Controller-->>Client : 返回登录响应
```

**图表来源**
- [auth.controller.ts:33-52](file://server/src/modules/auth/auth.controller.ts#L33-L52)
- [auth.service.ts:44-97](file://server/src/modules/auth/auth.service.ts#L44-L97)

**章节来源**
- [auth.controller.ts:33-52](file://server/src/modules/auth/auth.controller.ts#L33-L52)
- [auth.service.ts:44-97](file://server/src/modules/auth/auth.service.ts#L44-L97)

### 获取用户信息接口

#### 接口定义
- **URL**: GET /api/auth/user-info
- **功能**: 获取当前登录用户的详细信息
- **认证**: 需要JWT认证

#### 请求参数
- 无查询参数

#### 响应格式

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "123",
    "phone": "13800001111",
    "nickname": "用户1111",
    "avatar": "https://api.dicebear.com/...",
    "memberLevel": 0,
    "memberExpireAt": "",
    "dailyUsage": 0
  }
}
```

**失败响应**:
```json
{
  "code": 401,
  "message": "Token 已过期",
  "data": null
}
```

#### HTTP状态码
- 200: 获取成功
- 401: 未授权或Token无效
- 404: 用户不存在
- 500: 服务器内部错误

#### 认证流程

```mermaid
flowchart TD
Start([开始]) --> CheckAuthHeader[检查Authorization头]
CheckAuthHeader --> HasAuth{存在认证头?}
HasAuth --> |否| ReturnUnauthorized[返回401]
HasAuth --> |是| ParseToken[解析Bearer Token]
ParseToken --> VerifyToken[验证JWT令牌]
VerifyToken --> TokenValid{令牌有效?}
TokenValid --> |否| ReturnInvalidToken[返回401]
TokenValid --> |是| GetUser[获取用户信息]
GetUser --> ReturnUserInfo[返回用户信息]
ReturnUnauthorized --> End([结束])
ReturnInvalidToken --> End
ReturnUserInfo --> End
```

**图表来源**
- [auth.ts:20-49](file://server/src/middleware/auth.ts#L20-L49)
- [auth.controller.ts:55-64](file://server/src/modules/auth/auth.controller.ts#L55-L64)

**章节来源**
- [auth.controller.ts:55-64](file://server/src/modules/auth/auth.controller.ts#L55-L64)
- [auth.ts:20-49](file://server/src/middleware/auth.ts#L20-L49)

## 依赖关系分析

### 组件依赖图

```mermaid
graph TB
subgraph "外部依赖"
JWT[jsonwebtoken]
Prisma[Prisma Client]
Redis[Redis]
end
subgraph "内部模块"
AuthController[auth.controller.ts]
AuthService[auth.service.ts]
AuthMiddleware[auth.ts]
ErrorHandler[errorHandler.ts]
RateLimiter[rate-limiter.ts]
Config[config.ts]
Types[index.ts]
Models[index.ts]
end
AuthController --> AuthService
AuthController --> AuthMiddleware
AuthController --> ErrorHandler
AuthService --> Prisma
AuthService --> JWT
AuthService --> Redis
AuthMiddleware --> JWT
AuthMiddleware --> ErrorHandler
RateLimiter --> Redis
Config --> AuthMiddleware
Types --> AuthController
Models --> AuthService
```

**图表来源**
- [auth.controller.ts:1-7](file://server/src/modules/auth/auth.controller.ts#L1-L7)
- [auth.service.ts:1-5](file://server/src/modules/auth/auth.service.ts#L1-L5)
- [auth.ts:1-5](file://server/src/middleware/auth.ts#L1-L5)
- [rate-limiter.ts:1-2](file://server/src/middleware/rate-limiter.ts#L1-L2)

### 数据流分析

```mermaid
erDiagram
USER {
int id PK
string phone
string nickname
string avatar
int memberLevel
int dailyUsage
string lastUsageDate
datetime createdAt
datetime updatedAt
}
SMS_CODE {
string phone PK
string code
datetime expireAt
}
JWT_TOKEN {
string userId
string phone
datetime iat
datetime exp
}
USER ||--o{ JWT_TOKEN : "拥有"
USER ||--o{ SMS_CODE : "关联"
```

**图表来源**
- [index.ts:4-16](file://server/src/types/index.ts#L4-L16)
- [auth.service.ts:7-32](file://server/src/modules/auth/auth.service.ts#L7-L32)

**章节来源**
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)

## 性能考虑

### 频率限制策略

系统实现了多层级的频率限制机制：

| 限制类型 | 配置 | 说明 |
|----------|------|------|
| 全局限流 | 100次/分钟 | 对整个API进行总体限制 |
| 登录接口 | 5次/分钟 | 防止暴力破解 |
| 验证码发送 | 1次/分钟 | 防止短信轰炸 |
| TTS生成 | 20次/分钟 | 根据用户等级限制 |
| 文件上传 | 10次/分钟 | 限制上传频率 |

### 缓存策略

- **验证码缓存**: 使用内存Map存储，生产环境建议使用Redis
- **用户会话**: JWT令牌存储在客户端，减少服务器状态
- **配置缓存**: 应用启动时加载并缓存配置信息

### 性能优化建议

1. **Redis迁移**: 生产环境建议将验证码存储从内存迁移到Redis
2. **连接池**: 使用数据库连接池提高并发性能
3. **缓存预热**: 对热点用户信息进行缓存预热
4. **异步处理**: 将耗时操作（如短信发送）改为异步处理

## 故障排除指南

### 常见错误及解决方案

#### 认证相关错误

| 错误类型 | HTTP状态码 | 错误信息 | 解决方案 |
|----------|------------|----------|----------|
| 缺少认证头 | 401 | 缺少 Authorization 头 | 在请求头添加Authorization: Bearer <token> |
| Token格式错误 | 401 | Authorization 格式错误 | 确保使用Bearer前缀和有效的JWT令牌 |
| Token过期 | 401 | Token 已过期 | 重新登录获取新令牌 |
| Token无效 | 401 | Token 无效 | 检查令牌签名和有效期 |

#### 业务逻辑错误

| 错误类型 | HTTP状态码 | 错误信息 | 解决方案 |
|----------|------------|----------|----------|
| 手机号格式错误 | 400 | 请输入正确的手机号 | 验证手机号格式为11位数字 |
| 验证码错误 | 400 | 验证码错误或已过期 | 检查验证码是否正确且未过期 |
| 用户不存在 | 404 | 用户不存在 | 确认用户已注册或重新登录 |

#### 频率限制错误

| 错误类型 | HTTP状态码 | 错误信息 | 解决方案 |
|----------|------------|----------|----------|
| 请求过于频繁 | 429 | 请求过于频繁，请稍后再试 | 等待Retry-After指定的时间后重试 |

### 调试技巧

1. **开发环境认证**: 设置环境变量`AUTH_ENABLED=false`可跳过认证
2. **详细错误日志**: 开发环境下会返回完整的错误堆栈信息
3. **请求追踪**: 使用Sentry进行错误监控和追踪

**章节来源**
- [auth.ts:8-18](file://server/src/middleware/auth.ts#L8-L18)
- [errorHandler.ts:3-24](file://server/src/middleware/errorHandler.ts#L3-L24)
- [rate-limiter.ts:60-71](file://server/src/middleware/rate-limiter.ts#L60-L71)

## 结论

认证模块提供了完整的移动端用户认证解决方案，具有以下特点：

### 安全特性
- JWT令牌认证机制
- 多层频率限制
- 输入参数验证
- XSS和SQL注入防护

### 可扩展性
- 模块化设计便于维护
- 中间件架构支持功能扩展
- 配置驱动的认证策略

### 最佳实践建议
1. **生产环境部署**: 启用认证中间件，使用Redis存储验证码
2. **安全配置**: 使用强密码学密钥，定期轮换JWT密钥
3. **监控告警**: 集成Sentry进行错误监控，设置合理的告警阈值
4. **性能优化**: 实施缓存策略，使用连接池和异步处理

该认证模块为音频TTS平台提供了可靠的基础设施，支持后续功能的扩展和演进。