docs: 重构文档结构和组织

- 重新组织docs目录结构，按功能模块分类
- 新增deployment和development目录
- 更新API文档结构
- 添加客户端README文档
- 移除过时的文档文件

docs/api/README.md

@@ -1,29 +1,30 @@
 # API接口文档
 
-本目录包含了像素游戏服务器用户认证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网关
-- 自动化测试
+- 生成客户端SDK（支持多种语言）
+- 集成到API网关和测试工具
+- 自动化测试和文档生成
 
 ### 3. postman-collection.json
 Postman集合文件，包含：
-- 所有API接口的请求示例
-- 预设的请求参数
-- 响应示例
+- 所有17个API接口的请求示例
+- 预设的请求参数和环境变量
+- 完整的响应示例和测试脚本
 - 可直接导入Postman进行测试
 
 ## 🚀 快速开始
@@ -34,7 +35,7 @@ Postman集合文件，包含：
 # 启动开发服务器
 pnpm run dev
 
-# 访问Swagger UI
+# 访问Swagger UI（推荐）
 # 浏览器打开: http://localhost:3000/api-docs
 ```
 
@@ -64,78 +65,144 @@ openapi-generator generate -i docs/api/openapi.yaml -g typescript-axios -o ./cli
 
 ## 📊 API接口概览
 
+### 🔐 用户认证模块 (9个接口)
 | 接口 | 方法 | 路径 | 描述 |
 |------|------|------|------|
 | 用户登录 | POST | /auth/login | 支持用户名、邮箱或手机号登录 |
 | 用户注册 | POST | /auth/register | 创建新用户账户 |
 | GitHub OAuth | POST | /auth/github | 使用GitHub账户登录或注册 |
-| 发送验证码 | POST | /auth/forgot-password | 发送密码重置验证码 |
+| 发送重置验证码 | 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测试登录接口
+### 使用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": "password123"
+    "password": "Test123456"
   }'
 
-# 测试用户注册
-curl -X POST http://localhost:3000/auth/register \
+# 4. 测试管理员登录
+curl -X POST http://localhost:3000/admin/auth/login \
   -H "Content-Type: application/json" \
   -d '{
-    "username": "newuser",
-    "password": "password123",
-    "nickname": "新用户",
-    "email": "newuser@example.com"
+    "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 response = await fetch('http://localhost:3000/auth/login', {
+const loginResponse = await fetch('http://localhost:3000/auth/login', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
   },
   body: JSON.stringify({
     identifier: 'testuser',
-    password: 'password123'
+    password: 'Test123456'
   })
 });
 
-const data = await response.json();
-console.log(data);
+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认证机制
-3. **限流**: 建议对认证接口实施限流策略
-4. **验证码**: 示例中返回验证码仅用于演示，生产环境不应返回
-5. **错误处理**: 建议实现统一的错误处理机制
+2. **认证机制**: 项目使用JWT认证，管理员使用独立的Token系统
+3. **频率限制**: 已实现API频率限制，登录接口2次/分钟，管理员操作10次/分钟
+4. **用户状态**: 支持6种用户状态管理（active、inactive、locked、banned、deleted、pending）
+5. **测试模式**: 邮件服务支持测试模式，验证码会在控制台输出
+6. **存储模式**: 支持Redis文件存储和内存数据库，便于无依赖测试
+7. **安全防护**: 实现了维护模式、内容类型检查、超时控制等安全机制
 
 ## 🔄 更新文档
 
 当API接口发生变化时，请同步更新以下文件：
-1. 更新DTO类的Swagger装饰器
-2. 更新 `api-documentation.md`
-3. 更新 `openapi.yaml`
-4. 更新 `postman-collection.json`
-5. 重新生成Swagger文档
+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/)
+- [Swagger Editor](https://editor.swagger.io/)
+- [项目架构文档](../ARCHITECTURE.md)
+- [开发规范指南](../development/)