whale-town-end/docs/api/README.md

# API接口文档

本目录包含了 Whale Town 像素游戏服务器的完整API文档，采用业务功能模块化设计，提供17个接口覆盖所有核心功能。

## 📋 文档文件说明

### 1. api-documentation.md
详细的API接口文档，包含：
- **17个API接口** - 用户认证、用户管理、管理员功能、安全防护
- 接口概述和通用响应格式
- 每个接口的详细说明、参数、响应示例
- 错误代码说明和状态码映射
- 数据验证规则和业务逻辑
- 使用示例（JavaScript/TypeScript 和 cURL）

### 2. openapi.yaml
OpenAPI 3.0规范文件，可以用于：
- 导入到Swagger Editor查看和编辑
- 生成客户端SDK（支持多种语言）
- 集成到API网关和测试工具
- 自动化测试和文档生成

### 3. postman-collection.json
Postman集合文件，包含：
- 所有17个API接口的请求示例
- 预设的请求参数和环境变量
- 完整的响应示例和测试脚本
- 可直接导入Postman进行测试

## 🚀 快速开始

### 1. 启动服务器并查看Swagger文档

```bash
# 启动开发服务器
pnpm run dev

# 访问Swagger UI（推荐）
# 浏览器打开: http://localhost:3000/api-docs
```

### 2. 使用Postman测试API

1. 打开Postman
2. 点击 Import 按钮
3. 选择 `docs/api/postman-collection.json` 文件
4. 导入后即可看到所有API接口
5. 修改环境变量 `baseUrl` 为你的服务器地址（默认：http://localhost:3000）

### 3. 使用OpenAPI规范

#### 在Swagger Editor中查看
1. 访问 [Swagger Editor](https://editor.swagger.io/)
2. 将 `docs/api/openapi.yaml` 的内容复制粘贴到编辑器中
3. 即可查看可视化的API文档

#### 生成客户端SDK
```bash
# 使用swagger-codegen生成JavaScript客户端
swagger-codegen generate -i docs/api/openapi.yaml -l javascript -o ./client-sdk

# 使用openapi-generator生成TypeScript客户端
openapi-generator generate -i docs/api/openapi.yaml -g typescript-axios -o ./client-sdk
```

## 📊 API接口概览

### 🔐 用户认证模块 (9个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 用户登录 | POST | /auth/login | 支持用户名、邮箱或手机号登录 |
| 用户注册 | POST | /auth/register | 创建新用户账户 |
| GitHub OAuth | POST | /auth/github | 使用GitHub账户登录或注册 |
| 发送重置验证码 | POST | /auth/forgot-password | 发送密码重置验证码 |
| 重置密码 | POST | /auth/reset-password | 使用验证码重置密码 |
| 修改密码 | PUT | /auth/change-password | 修改用户密码 |
| 发送邮箱验证码 | POST | /auth/send-email-verification | 发送邮箱验证码 |
| 验证邮箱 | POST | /auth/verify-email | 验证邮箱验证码 |
| 重发邮箱验证码 | POST | /auth/resend-email-verification | 重新发送邮箱验证码 |

### 👥 用户管理模块 (3个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 修改用户状态 | PUT | /admin/users/:id/status | 修改指定用户状态 |
| 批量修改状态 | POST | /admin/users/batch-status | 批量修改用户状态 |
| 用户状态统计 | GET | /admin/users/status-stats | 获取各状态用户统计 |

### 🛡️ 管理员模块 (4个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 管理员登录 | POST | /admin/auth/login | 管理员身份认证 |
| 获取用户列表 | GET | /admin/users | 分页获取用户列表 |
| 获取用户详情 | GET | /admin/users/:id | 获取指定用户信息 |
| 重置用户密码 | POST | /admin/users/:id/reset-password | 管理员重置用户密码 |

### 📊 系统状态 (1个接口)
| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 应用状态 | GET | / | 获取应用运行状态和系统信息 |

## 🧪 快速测试

### 使用cURL测试核心接口

```bash
# 1. 测试应用状态
curl -X GET http://localhost:3000/

# 2. 测试用户注册
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Test123456",
    "nickname": "测试用户",
    "email": "test@example.com"
  }'

# 3. 测试用户登录
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "testuser",
    "password": "Test123456"
  }'

# 4. 测试管理员登录
curl -X POST http://localhost:3000/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "Admin123456"
  }'
```

### 使用JavaScript测试

```javascript
// 用户注册
const registerResponse = await fetch('http://localhost:3000/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'testuser',
    password: 'Test123456',
    nickname: '测试用户',
    email: 'test@example.com'
  })
});

// 用户登录
const loginResponse = await fetch('http://localhost:3000/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifier: 'testuser',
    password: 'Test123456'
  })
});

const loginData = await loginResponse.json();
console.log('登录结果:', loginData);
```

### 使用自动化测试脚本

```bash
# Windows PowerShell
.\test-api.ps1

# Linux/macOS Bash
./test-api.sh

# 自定义测试参数
.\test-api.ps1 -BaseUrl "http://localhost:3000" -TestEmail "custom@example.com"
```

## ⚠️ 注意事项

1. **开发环境**: 当前配置适用于开发环境，生产环境需要使用HTTPS
2. **认证机制**: 项目使用JWT认证，管理员使用独立的Token系统
3. **频率限制**: 已实现API频率限制，登录接口2次/分钟，管理员操作10次/分钟
4. **用户状态**: 支持6种用户状态管理（active、inactive、locked、banned、deleted、pending）
5. **测试模式**: 邮件服务支持测试模式，验证码会在控制台输出
6. **存储模式**: 支持Redis文件存储和内存数据库，便于无依赖测试
7. **安全防护**: 实现了维护模式、内容类型检查、超时控制等安全机制

## 🔄 更新文档

当API接口发生变化时，请同步更新以下文件：
1. 更新Controller和DTO类的Swagger装饰器
2. 更新 `api-documentation.md` 接口文档
3. 更新 `openapi.yaml` 规范文件
4. 更新 `postman-collection.json` 测试集合
5. 重新生成Swagger文档并验证

## 🔗 相关链接

- [NestJS Swagger文档](https://docs.nestjs.com/openapi/introduction)
- [OpenAPI规范](https://swagger.io/specification/)
- [Postman文档](https://learning.postman.com/docs/getting-started/introduction/)
- [Swagger Editor](https://editor.swagger.io/)
- [项目架构文档](../ARCHITECTURE.md)
- [开发规范指南](../development/)