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

API接口文档

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

📋 文档文件说明

1. api-documentation.md

详细的API接口文档，包含：

• 80+个API接口 - 用户认证、用户管理、管理员功能、聊天系统、位置广播、通知系统、Zulip集成、数据库管理、操作日志
• 接口概述和通用响应格式
• 每个接口的详细说明、参数、响应示例
• 错误代码说明和状态码映射
• 数据验证规则和业务逻辑
• 使用示例（JavaScript/TypeScript 和 cURL）

2. openapi.yaml

OpenAPI 3.0规范文件，可以用于：

• 导入到Swagger Editor查看和编辑
• 生成客户端SDK（支持多种语言）
• 集成到API网关和测试工具
• 自动化测试和文档生成

3. postman-collection.json

Postman集合文件，包含：

• 所有17个API接口的请求示例
• 预设的请求参数和环境变量
• 完整的响应示例和测试脚本
• 可直接导入Postman进行测试

🚀 快速开始

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

# 启动开发服务器
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
2. 将 docs/api/openapi.yaml 的内容复制粘贴到编辑器中
3. 即可查看可视化的API文档

生成客户端SDK

# 使用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接口概览

🔐 用户认证模块 (12个接口)

接口	方法	路径	描述
用户登录	POST	/auth/login	支持用户名、邮箱或手机号登录
用户注册	POST	/auth/register	创建新用户账户
GitHub OAuth	POST	/auth/github	使用GitHub账户登录或注册
验证码登录	POST	/auth/verification-code-login	使用验证码登录
发送登录验证码	POST	/auth/send-login-verification-code	发送登录验证码
发送邮箱验证码	POST	/auth/send-email-verification	发送邮箱验证码
验证邮箱	POST	/auth/verify-email	验证邮箱验证码
重发邮箱验证码	POST	/auth/resend-email-verification	重新发送邮箱验证码
发送重置验证码	POST	/auth/forgot-password	发送密码重置验证码
重置密码	POST	/auth/reset-password	使用验证码重置密码
修改密码	PUT	/auth/change-password	修改用户密码
刷新令牌	POST	/auth/refresh-token	刷新访问令牌

👥 用户管理模块 (3个接口)

接口	方法	路径	描述
修改用户状态	PUT	/admin/users/:id/status	修改指定用户状态
批量修改状态	POST	/admin/users/batch-status	批量修改用户状态
用户状态统计	GET	/admin/users/status-stats	获取各状态用户统计

🛡️ 管理员模块 (6个接口)

接口	方法	路径	描述
管理员登录	POST	/admin/auth/login	管理员身份认证
获取用户列表	GET	/admin/users	分页获取用户列表
获取用户详情	GET	/admin/users/:id	获取指定用户信息
重置用户密码	POST	/admin/users/:id/reset-password	管理员重置用户密码
获取运行时日志	GET	/admin/logs/runtime	获取运行日志
下载日志归档	GET	/admin/logs/archive	下载全部日志

💬 聊天系统 (3个接口)

接口	方法	路径	描述
获取聊天历史	GET	/chat/history	获取聊天历史记录
获取系统状态	GET	/chat/status	获取聊天系统状态
WebSocket信息	GET	/chat/websocket/info	获取WebSocket连接信息

📍 位置广播 (9个接口)

接口	方法	路径	描述
创建会话	POST	/location-broadcast/sessions	创建新的游戏会话
查询会话列表	GET	/location-broadcast/sessions	查询游戏会话列表
获取会话详情	GET	/location-broadcast/sessions/:sessionId	获取会话详细信息
更新会话配置	PUT	/location-broadcast/sessions/:sessionId/config	更新会话配置
结束会话	DELETE	/location-broadcast/sessions/:sessionId	结束游戏会话
查询位置信息	GET	/location-broadcast/positions	查询用户位置
位置统计	GET	/location-broadcast/positions/stats	获取位置统计
位置历史	GET	/location-broadcast/users/:userId/position-history	获取位置历史
清理用户数据	DELETE	/location-broadcast/users/:userId/data	清理用户数据

🔔 通知系统 (7个接口)

接口	方法	路径	描述
创建通知	POST	/api/notices	创建新通知
获取通知列表	GET	/api/notices	获取通知列表
未读通知数量	GET	/api/notices/unread-count	获取未读数量
获取通知详情	GET	/api/notices/:id	获取通知详情
标记已读	PATCH	/api/notices/:id/read	标记为已读
发送系统通知	POST	/api/notices/system	发送系统通知
发送广播通知	POST	/api/notices/broadcast	发送广播通知

🔗 Zulip集成 (17个接口)

接口	方法	路径	描述
创建关联	POST	/zulip-accounts	创建Zulip账号关联
查询关联列表	GET	/zulip-accounts	查询关联列表
获取关联详情	GET	/zulip-accounts/:id	根据ID获取关联
根据游戏用户ID获取	GET	/zulip-accounts/game-user/:gameUserId	根据游戏用户ID获取
根据Zulip用户ID获取	GET	/zulip-accounts/zulip-user/:zulipUserId	根据Zulip用户ID获取
根据邮箱获取	GET	/zulip-accounts/zulip-email/:zulipEmail	根据邮箱获取
更新关联	PUT	/zulip-accounts/:id	更新关联信息
根据游戏用户ID更新	PUT	/zulip-accounts/game-user/:gameUserId	根据游戏用户ID更新
删除关联	DELETE	/zulip-accounts/:id	删除关联
根据游戏用户ID删除	DELETE	/zulip-accounts/game-user/:gameUserId	根据游戏用户ID删除
需要验证的账号	GET	/zulip-accounts/management/verification-needed	获取需要验证的账号
错误状态账号	GET	/zulip-accounts/management/error-accounts	获取错误状态账号
批量更新状态	PUT	/zulip-accounts/management/batch-status	批量更新状态
账号统计	GET	/zulip-accounts/management/statistics	获取统计信息
验证账号	POST	/zulip-accounts/management/verify	验证账号有效性
检查邮箱存在	GET	/zulip-accounts/validation/email-exists/:email	检查邮箱是否存在
检查用户ID存在	GET	/zulip-accounts/validation/zulip-user-exists/:zulipUserId	检查用户ID是否存在

🗄️ 数据库管理 (6个接口)

接口	方法	路径	描述
获取用户列表	GET	/admin/database/users	获取用户列表
获取用户详情	GET	/admin/database/users/:id	获取用户详情
搜索用户	GET	/admin/database/users/search	搜索用户
创建用户	POST	/admin/database/users	创建新用户
更新用户	PUT	/admin/database/users/:id	更新用户信息
删除用户	DELETE	/admin/database/users/:id	删除用户

📝 操作日志 (2个接口)

接口	方法	路径	描述
获取日志列表	GET	/admin/operation-logs	获取操作日志列表
获取日志详情	GET	/admin/operation-logs/:id	获取日志详情

📊 系统状态 (1个接口)

接口	方法	路径	描述
应用状态	GET	/	获取应用运行状态和系统信息

🧪 快速测试

使用cURL测试核心接口

# 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测试

// 用户注册
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);

使用自动化测试脚本

# 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. 安全防护: 实现了维护模式、内容类型检查、超时控制等安全机制
8. WebSocket: 实时功能（聊天、位置广播）推荐使用WebSocket接口
9. Zulip集成: 支持与Zulip聊天系统的完整集成
10. 操作审计: 管理员操作自动记录审计日志

🔄 更新文档

当API接口发生变化时，请同步更新以下文件：

1. 更新Controller和DTO类的Swagger装饰器
2. 更新 api-documentation.md 接口文档
3. 更新 openapi.yaml 规范文件
4. 更新 postman-collection.json 测试集合
5. 重新生成Swagger文档并验证

🔗 相关链接

• NestJS Swagger文档
• OpenAPI规范
• Postman文档
• Swagger Editor
• 项目架构文档
• 开发规范指南