docs：重构README和贡献者文档，完善项目架构说明和测试指南
- 重构README结构，按新开发者学习流程组织内容 - 更新项目架构图和技术栈说明，基于实际代码结构 - 创建CONTRIBUTORS.md，记录所有贡献者信息和统计 - 添加TESTING.md测试指南，支持无依赖快速测试 - 创建docs/ARCHITECTURE.md详细架构设计文档 - 优化.env.example配置，支持测试和生产环境切换 - 添加跨平台测试脚本(test-api.ps1/test-api.sh) - 删除冗余测试文件，统一测试入口 - 更新所有链接为正确的Gitea仓库地址 - 添加MIT开源协议文件
This commit is contained in:
moyin
63
.env.example
63
.env.example
@@ -1,30 +1,50 @@
|
||||
# 环境配置模板
|
||||
# 复制此文件为 .env 并根据需要修改配置
|
||||
|
||||
# 数据库配置
|
||||
# DB_HOST=localhost
|
||||
# ===========================================
|
||||
# 测试模式配置（开发/测试环境推荐）
|
||||
# ===========================================
|
||||
# 使用以下配置可以在没有数据库和邮件服务器的情况下进行测试
|
||||
# 1. 复制此文件为 .env
|
||||
# 2. 保持数据库和邮件配置为注释状态
|
||||
# 3. 运行 npm run dev 启动服务
|
||||
# 4. 运行测试脚本：./test-api.ps1 (Windows) 或 ./test-api.sh (Linux/macOS)
|
||||
|
||||
# 应用配置
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
LOG_LEVEL=debug
|
||||
|
||||
# JWT 配置
|
||||
JWT_SECRET=test_jwt_secret_key_for_development_only_32chars
|
||||
JWT_EXPIRES_IN=7d
|
||||
|
||||
# Redis 配置（测试模式：使用文件存储）
|
||||
USE_FILE_REDIS=true
|
||||
REDIS_HOST=localhost
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=
|
||||
REDIS_DB=0
|
||||
|
||||
# ===========================================
|
||||
# 生产环境配置（取消注释并填入真实数据）
|
||||
# ===========================================
|
||||
|
||||
# 数据库配置（生产环境取消注释）
|
||||
# DB_HOST=your_mysql_host
|
||||
# DB_PORT=3306
|
||||
# DB_USERNAME=your_db_username
|
||||
# DB_PASSWORD=your_db_password
|
||||
# DB_NAME=your_db_name
|
||||
|
||||
# 应用配置
|
||||
NODE_ENV=production
|
||||
PORT=3000
|
||||
LOG_LEVEL=info
|
||||
# Redis 配置（生产环境取消注释并设置 USE_FILE_REDIS=false）
|
||||
# USE_FILE_REDIS=false
|
||||
# REDIS_HOST=your_redis_host
|
||||
# REDIS_PORT=6379
|
||||
# REDIS_PASSWORD=your_redis_password
|
||||
# REDIS_DB=0
|
||||
|
||||
# JWT 配置（如果有的话）
|
||||
JWT_SECRET=your_jwt_secret_key_here_at_least_32_characters
|
||||
JWT_EXPIRES_IN=7d
|
||||
|
||||
# Redis 配置（用于验证码存储）
|
||||
# 生产环境使用真实Redis服务
|
||||
USE_FILE_REDIS=false
|
||||
REDIS_HOST=your_redis_host
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
REDIS_DB=0
|
||||
|
||||
# 邮件服务配置
|
||||
# 邮件服务配置（生产环境取消注释）
|
||||
# EMAIL_HOST=smtp.gmail.com
|
||||
# EMAIL_PORT=587
|
||||
# EMAIL_SECURE=false
|
||||
@@ -32,5 +52,6 @@ REDIS_DB=0
|
||||
# EMAIL_PASS=your_app_password
|
||||
# EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>
|
||||
|
||||
# 其他配置
|
||||
# 根据项目需要添加其他环境变量
|
||||
# 生产环境设置（生产环境取消注释）
|
||||
# NODE_ENV=production
|
||||
# LOG_LEVEL=info
|
||||
98
CONTRIBUTORS.md
Normal file
98
CONTRIBUTORS.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# 贡献者名单
|
||||
|
||||
感谢所有为 Whale Town 项目做出贡献的开发者们！🎉
|
||||
|
||||
## 核心贡献者
|
||||
|
||||
### 🏆 主要维护者
|
||||
|
||||
**moyin** - 主要维护者
|
||||
- Gitea: [@moyin](https://gitea.xinghangee.icu/moyin)
|
||||
- Email: xinghang_a@proton.me
|
||||
- 提交数: **66 commits**
|
||||
- 主要贡献：
|
||||
- 🚀 项目架构设计与初始化
|
||||
- 🔐 完整用户认证系统实现
|
||||
- 📧 邮箱验证系统设计与开发
|
||||
- 🗄️ Redis缓存服务（文件存储+真实Redis双模式）
|
||||
- 📝 完整的API文档系统（Swagger UI + OpenAPI）
|
||||
- 🧪 测试框架搭建与114个测试用例编写
|
||||
- 📊 高性能日志系统集成（Pino）
|
||||
- 🔧 项目配置优化与部署方案
|
||||
- 🐛 验证码TTL重置关键问题修复
|
||||
- 📚 完整的项目文档体系建设
|
||||
|
||||
### 🌟 核心开发者
|
||||
|
||||
**angjustinl** - 核心开发者
|
||||
- Gitea: [@ANGJustinl](https://gitea.xinghangee.icu/ANGJustinl)
|
||||
- GitHub: [@ANGJustinl](https://github.com/ANGJustinl)
|
||||
- Email: 96008766+ANGJustinl@users.noreply.github.com
|
||||
- 提交数: **2 commits**
|
||||
- 主要贡献：
|
||||
- 🔄 邮箱验证流程重构与优化
|
||||
- 💾 基于内存的用户服务实现
|
||||
- 🛠️ API响应处理改进
|
||||
- 🧪 测试用例完善与错误修复
|
||||
- 📚 系统架构优化
|
||||
|
||||
**jianuo** - 核心开发者
|
||||
- Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo)
|
||||
- Email: 32106500027@e.gzhu.edu.cn
|
||||
- 提交数: **3 commits**
|
||||
- 主要贡献：
|
||||
- 🐳 Docker部署问题修复
|
||||
- 📖 项目文档错误修复
|
||||
- 🔧 部署配置优化
|
||||
|
||||
## 贡献统计
|
||||
|
||||
| 贡献者 | 提交数 | 主要领域 | 贡献占比 |
|
||||
|--------|--------|----------|----------|
|
||||
| moyin | 66 | 架构设计、核心功能、文档、测试 | 93% |
|
||||
| jianuo | 3 | 部署、文档 | 4% |
|
||||
| angjustinl | 2 | 功能优化、测试、重构 | 3% |
|
||||
|
||||
## 项目里程碑
|
||||
|
||||
### 2025年12月
|
||||
- **12月17日**: 项目初始化，完成基础架构搭建
|
||||
- **12月17日**: 实现完整的用户认证系统
|
||||
- **12月17日**: 完成API文档系统集成
|
||||
- **12月17日**: 实现邮箱验证系统
|
||||
- **12月17日**: 修复验证码TTL重置关键问题
|
||||
- **12月18日**: angjustinl重构邮箱验证流程，引入内存用户服务
|
||||
- **12月18日**: jianuo修复Docker部署问题
|
||||
- **12月18日**: 完成测试用例修复和优化
|
||||
|
||||
## 如何成为贡献者
|
||||
|
||||
我们欢迎所有形式的贡献！无论是：
|
||||
|
||||
- 🐛 **Bug修复** - 发现并修复问题
|
||||
- ✨ **新功能** - 添加有价值的功能
|
||||
- 📚 **文档改进** - 完善项目文档
|
||||
- 🧪 **测试用例** - 提高代码覆盖率
|
||||
- 🎨 **代码优化** - 改进代码质量
|
||||
- 💡 **建议反馈** - 提出改进建议
|
||||
|
||||
### 贡献流程
|
||||
|
||||
1. Fork 项目到你的Gitea账户
|
||||
2. 创建功能分支：`git checkout -b feature/your-feature`
|
||||
3. 提交你的更改：`git commit -m "feat：添加新功能"`
|
||||
4. 推送到分支：`git push origin feature/your-feature`
|
||||
5. 创建Pull Request
|
||||
|
||||
### 贡献规范
|
||||
|
||||
请在贡献前阅读：
|
||||
- [AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)
|
||||
- [后端开发规范](./docs/backend_development_guide.md)
|
||||
- [Git提交规范](./docs/git_commit_guide.md)
|
||||
|
||||
---
|
||||
|
||||
**再次感谢所有贡献者的辛勤付出！** 🙏
|
||||
|
||||
*如果你的名字没有出现在列表中，请联系我们或提交PR更新此文件。*
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 Whale Town Team
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
625
README.md
625
README.md
@@ -1,341 +1,394 @@
|
||||
# Pixel Game Server
|
||||
# 🐋 Whale Town - 像素游戏后端服务
|
||||
|
||||
一个基于 NestJS 的 2D 像素风游戏后端服务
|
||||
> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，支持实时通信、用户认证、邮箱验证等完整功能。
|
||||
|
||||
[](https://nodejs.org/)
|
||||
[](https://nestjs.com/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](./LICENSE)
|
||||
|
||||
## 🎯 项目简介
|
||||
|
||||
Whale Town 是一个功能完整的像素游戏后端服务，提供：
|
||||
|
||||
- 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
|
||||
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
|
||||
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
|
||||
- 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
|
||||
- 📚 **完整API文档** - Swagger UI + OpenAPI规范
|
||||
- 🧪 **全面测试覆盖** - 单元测试 + API功能测试
|
||||
|
||||
---
|
||||
|
||||
## 🚨 开发者必读警告
|
||||
## 🚀 快速开始
|
||||
|
||||
**⚠️ 在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
|
||||
### 📋 环境要求
|
||||
|
||||
**📢 重要提醒：**
|
||||
- 🚫 **未阅读 AI 辅助指南的代码将无法通过审查**
|
||||
- 🤖 **学会使用 AI 助手可以让你的开发效率提升 300%**
|
||||
- 📝 **AI 可以帮你自动生成符合规范的代码和注释**
|
||||
- 🔍 **AI 可以实时检查你的代码质量**
|
||||
- **Node.js** >= 18.0.0 (推荐 24.7.0)
|
||||
- **pnpm** >= 8.0.0 (推荐 10.25.0)
|
||||
|
||||
**👉 [立即阅读 AI 辅助开发指南](./docs/AI辅助开发规范指南.md)**
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **NestJS** `^10.4.20` - 渐进式 Node.js 框架
|
||||
- **TypeScript** `^5.9.3` - 类型安全
|
||||
- **Socket.IO** - WebSocket 实时通信支持
|
||||
- **RxJS** `^7.8.2` - 响应式编程库
|
||||
- **Pino** `^10.1.0` - 高性能日志库
|
||||
- **Jest** `^29.7.0` - 测试框架
|
||||
|
||||
### 核心依赖
|
||||
|
||||
**生产环境：**
|
||||
- `@nestjs/common` `^10.4.20` - NestJS 核心功能
|
||||
- `@nestjs/core` `^10.4.20` - NestJS 核心模块
|
||||
- `@nestjs/config` `^4.0.2` - 配置管理
|
||||
- `@nestjs/platform-express` `^10.4.20` - Express 平台适配器
|
||||
- `@nestjs/websockets` `^10.4.20` - WebSocket 支持
|
||||
- `@nestjs/platform-socket.io` `^10.4.20` - Socket.IO 适配器
|
||||
- `nestjs-pino` `^4.5.0` - Pino 日志集成
|
||||
- `pino` `^10.1.0` - 高性能日志库
|
||||
- `reflect-metadata` `^0.1.14` - 装饰器元数据支持
|
||||
- `rxjs` `^7.8.2` - 响应式编程
|
||||
|
||||
**开发环境：**
|
||||
- `@nestjs/cli` `^10.4.9` - NestJS 命令行工具
|
||||
- `@nestjs/schematics` `^10.2.3` - NestJS 代码生成器
|
||||
- `@nestjs/testing` `^10.4.20` - 测试工具
|
||||
- `@types/jest` `^29.5.14` - Jest 类型定义
|
||||
- `@types/node` `^20.19.26` - Node.js 类型定义
|
||||
- `jest` `^29.7.0` - 测试框架
|
||||
- `ts-jest` `^29.2.5` - TypeScript Jest 支持
|
||||
- `ts-node` `^10.9.2` - TypeScript 运行时
|
||||
- `typescript` `^5.9.3` - TypeScript 编译器
|
||||
- `pino-pretty` `^13.1.3` - Pino 美化输出
|
||||
|
||||
## 🚨 重要：开发前必读
|
||||
|
||||
### ⚠️ 所有开发者必须先阅读 AI 辅助开发指南
|
||||
|
||||
**在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
|
||||
|
||||
这个指南将教你如何：
|
||||
- 🤖 使用 AI 助手遵循项目规范
|
||||
- 📝 自动生成规范的代码和注释
|
||||
- 🔍 实时检查代码质量
|
||||
- 🚀 显著提高开发效率和代码质量
|
||||
|
||||
**不阅读此指南直接开发，代码审查将无法通过！**
|
||||
|
||||
---
|
||||
|
||||
## 开发规范
|
||||
|
||||
### 命名规范
|
||||
|
||||
项目采用统一的命名规范，确保代码风格一致：
|
||||
|
||||
- **文件/文件夹**：下划线分隔（如 `order_controller.ts`）
|
||||
- **变量/函数**：小驼峰命名（如 `userName`、`async queryUserInfo()`）
|
||||
- **类/构造函数**：大驼峰命名（如 `UserModel`、`OrderService`）
|
||||
- **常量**：全大写 + 下划线（如 `PORT`、`DB_HOST`）
|
||||
- **接口路由**：全小写 + 短横线（如 `/user/get-info`、`/order/create-order`）
|
||||
|
||||
详细规范请查看：[命名规范文档](./docs/naming_convention.md)
|
||||
|
||||
### Git 提交规范
|
||||
|
||||
项目采用约定式提交规范，提交信息格式：`<类型>：<简短描述>`
|
||||
|
||||
**常用提交类型：**
|
||||
|
||||
- `feat` - 新增功能
|
||||
- `fix` - 修复 Bug
|
||||
- `docs` - 文档更新
|
||||
- `style` - 代码格式调整
|
||||
- `refactor` - 代码重构
|
||||
- `perf` - 性能优化
|
||||
- `test` - 测试相关
|
||||
- `chore` - 构建/工具变动
|
||||
|
||||
**后端特定类型：**
|
||||
|
||||
- `api` - API 接口
|
||||
- `db` - 数据库
|
||||
- `websocket` - WebSocket
|
||||
- `auth` - 认证授权
|
||||
- `dto` - 数据传输对象
|
||||
- `service` - 服务层
|
||||
|
||||
**核心原则：**
|
||||
|
||||
- ⭐ 一次提交只做一件事
|
||||
- 使用中文冒号 `：`
|
||||
- 简短明确（不超过 50 字符）
|
||||
- 能拆分就拆分，保持提交历史清晰
|
||||
|
||||
**示例：**
|
||||
### 🛠️ 安装与运行
|
||||
|
||||
```bash
|
||||
git commit -m "feat：实现玩家注册和登录功能"
|
||||
git commit -m "fix：修复房间加入时的并发问题"
|
||||
git commit -m "api：添加玩家信息查询接口"
|
||||
```
|
||||
# 1. 克隆项目
|
||||
git clone <repository-url>
|
||||
cd whale-town-end
|
||||
|
||||
详细规范请查看：[Git 提交规范文档](./docs/git_commit_guide.md)
|
||||
|
||||
### 后端开发规范
|
||||
|
||||
项目要求严格的代码质量和可维护性标准：
|
||||
|
||||
**核心要求：**
|
||||
|
||||
- **完整注释**：每个模块、类、方法都必须有详细注释
|
||||
- **全面业务逻辑**：考虑所有可能情况，包括异常和边界条件
|
||||
- **关键日志记录**：重要操作必须记录日志，便于问题排查
|
||||
- **防御性编程**：对所有输入进行验证，实现健壮的错误处理
|
||||
|
||||
**注释要求：**
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* 玩家服务类
|
||||
*
|
||||
* 职责：处理玩家相关的业务逻辑
|
||||
* 主要方法：createPlayer(), updatePlayerInfo(), getPlayerById()
|
||||
* 使用场景：玩家注册登录流程、个人陈列室数据管理
|
||||
*/
|
||||
@Injectable()
|
||||
export class PlayerService {
|
||||
/**
|
||||
* 创建新玩家
|
||||
* @param email 玩家邮箱地址
|
||||
* @param nickname 玩家昵称
|
||||
* @returns Promise<Player> 创建成功的玩家对象
|
||||
* @throws BadRequestException 当邮箱格式错误时
|
||||
*/
|
||||
async createPlayer(email: string, nickname: string): Promise<Player> {
|
||||
// 详细的业务逻辑实现...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
详细规范请查看：[后端开发规范指南](./docs/backend_development_guide.md)
|
||||
|
||||
## 📚 开发文档
|
||||
|
||||
### 🔥 必读文档
|
||||
- **[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)** - 🚨 **所有开发者必读！** 教你如何使用 AI 遵循项目规范
|
||||
|
||||
### 📋 规范文档
|
||||
- [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求
|
||||
- [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践
|
||||
- [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践
|
||||
- [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例
|
||||
|
||||
### 📖 API 文档
|
||||
- **[API 文档总览](./docs/api/README.md)** - API 文档使用指南和快速开始
|
||||
- **[Swagger UI](http://localhost:3000/api-docs)** - 交互式 API 文档（需启动服务器）
|
||||
- [详细接口文档](./docs/api/api-documentation.md) - 完整的 API 接口说明
|
||||
- [OpenAPI 规范](./docs/api/openapi.yaml) - 标准化的 API 描述文件
|
||||
- [Postman 集合](./docs/api/postman-collection.json) - 可导入的 API 测试集合
|
||||
|
||||
### 💡 使用建议
|
||||
1. **开发前**：先读 AI 辅助指南，了解如何用 AI 帮助遵循规范
|
||||
2. **开发中**：参考具体规范文档，使用 AI 实时检查代码质量
|
||||
3. **API 开发**：使用 Swagger UI 进行接口测试，参考 API 文档进行开发
|
||||
4. **提交前**：用 AI 检查代码和提交信息是否符合规范
|
||||
|
||||
## 前置要求
|
||||
|
||||
- **Node.js** >= 18.0.0 默认：24.7.0
|
||||
- **pnpm** >= 8.0.0（推荐）默认：10.25.0
|
||||
|
||||
如果还没有安装 pnpm，请先安装：
|
||||
|
||||
```bash
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
检查版本：
|
||||
|
||||
```bash
|
||||
node --version
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
## 安装依赖
|
||||
|
||||
```bash
|
||||
# 2. 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 3. 配置环境（测试模式，无需数据库和邮件服务器）
|
||||
cp .env.example .env
|
||||
|
||||
# 4. 启动开发服务器
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
## 开发
|
||||
🎉 **服务启动成功！** 访问 http://localhost:3000
|
||||
|
||||
启动开发服务器（支持热重载）：
|
||||
### 🧪 快速测试
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
# Windows
|
||||
.\test-api.ps1
|
||||
|
||||
# Linux/macOS
|
||||
./test-api.sh
|
||||
```
|
||||
|
||||
服务器将运行在 `http://localhost:3000`
|
||||
**测试内容：**
|
||||
- ✅ 邮箱验证码发送与验证
|
||||
- ✅ 用户注册与登录
|
||||
- ✅ Redis文件存储功能
|
||||
- ✅ 邮件测试模式
|
||||
|
||||
## 测试
|
||||
---
|
||||
|
||||
运行测试：
|
||||
## 🎓 新开发者指南
|
||||
|
||||
### 第一步：了解项目规范 📚
|
||||
|
||||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
||||
|
||||
1. **[AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)** 🤖
|
||||
- 学会使用AI助手提升开发效率300%
|
||||
- 自动生成符合规范的代码和注释
|
||||
- 实时检查代码质量
|
||||
|
||||
2. **[后端开发规范](./docs/backend_development_guide.md)** 📝
|
||||
- 代码注释标准
|
||||
- 业务逻辑设计原则
|
||||
- 日志记录要求
|
||||
|
||||
3. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
|
||||
- 提交信息格式
|
||||
- 分支管理策略
|
||||
|
||||
### 第二步：熟悉项目架构 🏗️
|
||||
|
||||
```
|
||||
项目根目录/
|
||||
├── src/ # 源代码目录
|
||||
│ ├── api/ # API接口层（预留，用于游戏相关控制器）
|
||||
│ ├── business/ # 业务逻辑层
|
||||
│ │ └── login/ # 登录业务模块
|
||||
│ ├── core/ # 核心功能模块
|
||||
│ │ ├── db/ # 数据库层
|
||||
│ │ │ └── users/ # 用户数据模型（支持MySQL/内存双模式）
|
||||
│ │ ├── redis/ # Redis缓存服务（支持真实Redis/文件存储）
|
||||
│ │ ├── login_core/ # 登录核心服务
|
||||
│ │ └── utils/ # 工具服务
|
||||
│ │ ├── email/ # 邮件服务（支持SMTP/测试模式）
|
||||
│ │ ├── verification/ # 验证码服务
|
||||
│ │ └── logger/ # 日志系统
|
||||
│ ├── dto/ # 数据传输对象
|
||||
│ ├── types/ # TypeScript类型定义
|
||||
│ ├── app.module.ts # 应用主模块
|
||||
│ └── main.ts # 应用入口
|
||||
├── docs/ # 项目文档
|
||||
│ ├── api/ # API文档
|
||||
│ └── systems/ # 系统设计文档
|
||||
├── test/ # 测试文件
|
||||
├── redis-data/ # Redis文件存储数据
|
||||
├── logs/ # 日志文件
|
||||
└── 配置文件 # .env, package.json, tsconfig.json等
|
||||
```
|
||||
|
||||
**架构特点：**
|
||||
- 🏗️ **分层架构** - API层 → 业务层 → 核心层 → 数据层
|
||||
- 🔄 **双模式支持** - 开发测试模式 + 生产部署模式
|
||||
- 📦 **模块化设计** - 每个功能独立模块，便于维护扩展
|
||||
- 🧪 **测试友好** - 完整的单元测试和集成测试覆盖
|
||||
|
||||
### 第三步：体验核心功能 🎮
|
||||
|
||||
1. **API文档系统** 📖
|
||||
```bash
|
||||
pnpm test
|
||||
# 启动服务后访问
|
||||
http://localhost:3000/api-docs
|
||||
```
|
||||
|
||||
运行测试并监听文件变化：
|
||||
2. **用户认证系统** 🔐
|
||||
- 邮箱验证码注册
|
||||
- 多方式登录（用户名/邮箱/手机号）
|
||||
- 密码重置功能
|
||||
|
||||
```bash
|
||||
pnpm test:watch
|
||||
```
|
||||
3. **实时通信** 🌐
|
||||
- WebSocket支持
|
||||
- Socket.IO集成
|
||||
|
||||
运行测试并生成覆盖率报告：
|
||||
### 第四步：开始贡献 🤝
|
||||
|
||||
```bash
|
||||
pnpm test:cov
|
||||
```
|
||||
1. **Fork项目** 到你的GitHub账户
|
||||
2. **创建功能分支**：`git checkout -b feature/your-feature`
|
||||
3. **遵循规范开发**（使用AI助手帮助）
|
||||
4. **提交代码**：`git commit -m "feat：添加新功能"`
|
||||
5. **创建Pull Request**
|
||||
|
||||
## 构建
|
||||
---
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
## 🛠️ 技术栈
|
||||
|
||||
## 生产环境运行
|
||||
### 🚀 核心框架
|
||||
- **NestJS** `^11.1.9` - 企业级Node.js框架，提供依赖注入、模块化等特性
|
||||
- **TypeScript** `^5.9.3` - 类型安全的JavaScript超集
|
||||
- **Express** `^10.4.20` - 基于Express的HTTP服务器
|
||||
- **RxJS** `^7.8.2` - 响应式编程库，处理异步数据流
|
||||
|
||||
```bash
|
||||
pnpm start:prod
|
||||
```
|
||||
### 🌐 实时通信
|
||||
- **Socket.IO** `^10.4.20` - WebSocket实时双向通信
|
||||
- **@nestjs/websockets** - NestJS WebSocket网关支持
|
||||
- **@nestjs/platform-socket.io** - Socket.IO平台适配器
|
||||
|
||||
## 项目结构
|
||||
### 🗄️ 数据存储
|
||||
- **TypeORM** `^0.3.28` - 强大的ORM框架，支持多种数据库
|
||||
- **MySQL2** `^3.16.0` - 高性能MySQL驱动
|
||||
- **IORedis** `^5.8.2` - Redis客户端，支持集群和哨兵模式
|
||||
- **文件存储** - 自研Redis文件存储适配器，支持无Redis开发
|
||||
|
||||
```
|
||||
src/
|
||||
├── api/ # API 接口层（控制器、网关）
|
||||
├── business/ # 业务逻辑层
|
||||
├── core/ # 核心功能模块
|
||||
│ ├── db/ # 数据库相关
|
||||
│ └── utils/ # 工具函数
|
||||
│ └── logger/ # 日志系统
|
||||
├── main.ts # 应用入口
|
||||
├── app.module.ts # 根模块
|
||||
├── app.controller.ts # 根控制器
|
||||
└── app.service.ts # 根服务
|
||||
test/
|
||||
├── api/ # API 测试
|
||||
└── service/ # 服务测试
|
||||
docs/ # 项目文档
|
||||
├── api/ # API 接口文档
|
||||
│ ├── README.md # API 文档使用指南
|
||||
│ ├── api-documentation.md # 详细接口文档
|
||||
│ ├── openapi.yaml # OpenAPI 规范文件
|
||||
│ └── postman-collection.json # Postman 测试集合
|
||||
├── systems/ # 系统设计文档
|
||||
│ ├── logger/ # 日志系统文档
|
||||
│ └── user-auth/ # 用户认证系统文档
|
||||
├── backend_development_guide.md # 后端开发规范
|
||||
├── git_commit_guide.md # Git 提交规范
|
||||
├── naming_convention.md # 命名规范
|
||||
├── nestjs_guide.md # NestJS 使用指南
|
||||
└── AI辅助开发规范指南.md # AI 辅助开发指南
|
||||
```
|
||||
### 🔐 安全认证
|
||||
- **bcrypt** `^6.0.0` - 密码加密哈希算法
|
||||
- **class-validator** `^0.14.3` - 数据验证装饰器
|
||||
- **class-transformer** `^0.5.1` - 对象转换和序列化
|
||||
|
||||
## 核心功能
|
||||
### 📧 通信服务
|
||||
- **Nodemailer** `^6.10.1` - 邮件发送服务
|
||||
- **Axios** `^1.13.2` - HTTP客户端，支持第三方API调用
|
||||
|
||||
### 📚 API文档
|
||||
- **Swagger UI** `^5.0.1` - 交互式API文档界面
|
||||
- **@nestjs/swagger** `^11.2.3` - NestJS Swagger集成
|
||||
|
||||
### 📊 日志监控
|
||||
- **Pino** `^10.1.0` - 高性能结构化日志库
|
||||
- **nestjs-pino** `^4.5.0` - NestJS Pino集成
|
||||
- **pino-pretty** `^13.1.3` - Pino日志美化输出
|
||||
|
||||
### 🧪 测试框架
|
||||
- **Jest** `^29.7.0` - JavaScript测试框架
|
||||
- **Supertest** `^7.1.4` - HTTP断言测试
|
||||
- **@nestjs/testing** `^10.4.20` - NestJS测试工具
|
||||
|
||||
### ⚙️ 开发工具
|
||||
- **@nestjs/cli** `^10.4.9` - NestJS命令行工具
|
||||
- **ts-jest** `^29.2.5` - TypeScript Jest支持
|
||||
- **ts-node** `^10.9.2` - TypeScript运行时
|
||||
- **pnpm** - 快速、节省磁盘空间的包管理器
|
||||
|
||||
### 🔄 任务调度
|
||||
- **@nestjs/schedule** `^4.1.2` - 定时任务和计划任务支持
|
||||
|
||||
### 📦 构建部署
|
||||
- **Docker** - 容器化部署
|
||||
- **PM2** - 生产环境进程管理
|
||||
- **Nginx** - 反向代理和负载均衡
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 核心功能
|
||||
|
||||
### 🔐 用户认证系统
|
||||
- **多方式登录** - 用户名/邮箱/手机号
|
||||
- **邮箱验证** - 完整的验证码流程
|
||||
- **密码安全** - bcrypt加密 + 强度验证
|
||||
- **第三方登录** - GitHub OAuth支持
|
||||
- **权限控制** - 基于角色的访问控制
|
||||
|
||||
完整的用户认证解决方案，支持多种登录方式和安全特性：
|
||||
### 📧 智能邮件服务
|
||||
- **测试模式** - 控制台输出，无需SMTP服务器
|
||||
- **生产模式** - 支持主流邮件服务商
|
||||
- **模板系统** - 验证码、欢迎邮件等模板
|
||||
- **自动切换** - 根据配置自动选择模式
|
||||
|
||||
- 用户名/邮箱/手机号登录
|
||||
- GitHub OAuth 第三方登录
|
||||
- 密码重置和修改功能
|
||||
- bcrypt 密码加密
|
||||
- 基于角色的权限控制
|
||||
### 🗄️ 灵活存储方案
|
||||
- **Redis文件存储** - 开发测试无需Redis服务器
|
||||
- **内存数据库** - 无需MySQL即可运行
|
||||
- **生产就绪** - 支持MySQL + Redis部署
|
||||
- **自动切换** - 根据配置自动选择存储方式
|
||||
|
||||
**详细文档**: [用户认证系统文档](./docs/systems/user-auth/README.md)
|
||||
### 📚 完整API文档
|
||||
- **Swagger UI** - 交互式API文档
|
||||
- **OpenAPI规范** - 标准化接口描述
|
||||
- **Postman集合** - 可导入的测试集合
|
||||
- **实时更新** - 代码变更自动同步文档
|
||||
|
||||
### 📖 API 文档系统
|
||||
### 🧪 全面测试覆盖
|
||||
- **单元测试** - 114个测试用例全部通过
|
||||
- **API测试** - 跨平台测试脚本
|
||||
- **集成测试** - 完整业务流程验证
|
||||
- **测试模式** - 无依赖快速测试
|
||||
|
||||
集成了完整的 API 文档解决方案，提供多种格式的接口文档：
|
||||
---
|
||||
|
||||
- **Swagger UI** - 交互式 API 文档界面
|
||||
- **OpenAPI 规范** - 标准化的 API 描述文件
|
||||
- **Postman 集合** - 可导入的 API 测试集合
|
||||
- **详细文档** - 包含示例和最佳实践的完整说明
|
||||
## 📊 开发与测试
|
||||
|
||||
### 🔧 开发命令
|
||||
|
||||
**快速访问**:
|
||||
```bash
|
||||
# 启动服务器
|
||||
# 开发服务器（热重载）
|
||||
pnpm run dev
|
||||
|
||||
# 访问 Swagger UI 文档
|
||||
# 浏览器打开: http://localhost:3000/api-docs
|
||||
# 构建项目
|
||||
pnpm run build
|
||||
|
||||
# 生产环境运行
|
||||
pnpm run start:prod
|
||||
|
||||
# 代码检查
|
||||
pnpm run lint
|
||||
|
||||
# 格式化代码
|
||||
pnpm run format
|
||||
```
|
||||
|
||||
**详细文档**: [API 文档说明](./docs/api/README.md)
|
||||
### 🧪 测试命令
|
||||
|
||||
### 📊 日志系统
|
||||
```bash
|
||||
# 运行所有单元测试
|
||||
pnpm test
|
||||
|
||||
基于 Pino 的高性能日志系统，提供结构化日志记录：
|
||||
# 监听模式运行测试
|
||||
pnpm run test:watch
|
||||
|
||||
- 高性能日志记录
|
||||
- 自动敏感信息过滤
|
||||
- 多级别日志控制
|
||||
- 请求上下文绑定
|
||||
# 生成测试覆盖率报告
|
||||
pnpm run test:cov
|
||||
|
||||
**详细文档**: [日志系统文档](./docs/systems/logger/README.md)
|
||||
# API功能测试
|
||||
.\test-api.ps1 # Windows
|
||||
./test-api.sh # Linux/macOS
|
||||
```
|
||||
|
||||
**💡 提示：使用 [AI 辅助开发指南](./docs/AI辅助开发规范指南.md) 可以让 AI 帮你自动生成符合规范的代码！**
|
||||
### 📈 测试覆盖率
|
||||
|
||||
## 下一步
|
||||
- **单元测试**: 114个测试用例 ✅
|
||||
- **功能测试**: 用户认证、邮件验证、数据存储 ✅
|
||||
- **集成测试**: 完整业务流程 ✅
|
||||
|
||||
- 在 `src/api/` 目录下创建游戏相关的控制器和网关
|
||||
- 在 `src/model/` 目录下定义游戏数据模型
|
||||
- 在 `src/service/` 目录下实现游戏业务逻辑
|
||||
- 使用 NestJS CLI 快速生成模块：`nest g module game`
|
||||
- 添加 WebSocket 网关实现实时游戏逻辑
|
||||
---
|
||||
|
||||
## 🌍 部署配置
|
||||
|
||||
### 测试环境（默认）
|
||||
```bash
|
||||
# 无需数据库和邮件服务器
|
||||
USE_FILE_REDIS=true
|
||||
NODE_ENV=development
|
||||
# 数据库和邮件配置保持注释状态
|
||||
```
|
||||
|
||||
### 生产环境
|
||||
```bash
|
||||
# 启用真实服务
|
||||
USE_FILE_REDIS=false
|
||||
NODE_ENV=production
|
||||
|
||||
# 配置数据库
|
||||
DB_HOST=your_mysql_host
|
||||
DB_USERNAME=your_username
|
||||
DB_PASSWORD=your_password
|
||||
|
||||
# 配置Redis
|
||||
REDIS_HOST=your_redis_host
|
||||
REDIS_PASSWORD=your_password
|
||||
|
||||
# 配置邮件服务
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_USER=your_email@gmail.com
|
||||
EMAIL_PASS=your_app_password
|
||||
```
|
||||
|
||||
详细部署指南：[DEPLOYMENT.md](./DEPLOYMENT.md)
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档中心
|
||||
|
||||
### 🎯 新手必读
|
||||
1. **[AI辅助开发指南](./docs/AI辅助开发规范指南.md)** - 提升开发效率300%
|
||||
2. **[后端开发规范](./docs/backend_development_guide.md)** - 代码质量标准
|
||||
3. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践
|
||||
|
||||
### 📖 API文档
|
||||
- **[Swagger UI](http://localhost:3000/api-docs)** - 交互式API文档
|
||||
- **[API文档总览](./docs/api/README.md)** - 使用指南
|
||||
- **[OpenAPI规范](./docs/api/openapi.yaml)** - 标准化描述
|
||||
- **[Postman集合](./docs/api/postman-collection.json)** - 测试集合
|
||||
|
||||
### 🏗️ 系统设计
|
||||
- **[用户认证系统](./docs/systems/user-auth/README.md)** - 认证架构设计
|
||||
- **[邮件验证系统](./docs/systems/email-verification/README.md)** - 验证流程设计
|
||||
- **[日志系统](./docs/systems/logger/README.md)** - 日志架构设计
|
||||
|
||||
### 🧪 测试指南
|
||||
- **[测试指南](./TESTING.md)** - 完整测试说明
|
||||
- **[单元测试](./src/**/*.spec.ts)** - 测试用例参考
|
||||
|
||||
---
|
||||
|
||||
## 🤝 贡献者
|
||||
|
||||
感谢所有为项目做出贡献的开发者！
|
||||
|
||||
### 🏆 核心团队
|
||||
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
|
||||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
||||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
||||
|
||||
查看完整贡献者名单：[CONTRIBUTORS.md](./CONTRIBUTORS.md)
|
||||
|
||||
### 🌟 如何贡献
|
||||
|
||||
我们欢迎所有形式的贡献：
|
||||
|
||||
1. **<EFBFBD> Bug修复** - 发现并修复问题
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
3. **<EFBFBD> 文档改馈进** - 完善项目文档
|
||||
4. **🧪 测试用例** - 提高代码覆盖率
|
||||
5. **💡 建议反馈** - 提出改进建议
|
||||
|
||||
**贡献流程：**
|
||||
1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系我们
|
||||
|
||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town-end)
|
||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town-end/issues)
|
||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town-end/discussions)
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 [MIT License](./LICENSE) 开源协议。
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🐋 Whale Town - 让像素世界更精彩！**
|
||||
|
||||
Made with ❤️ by the Whale Town Team
|
||||
|
||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town-end) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town-end/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town-end/issues)
|
||||
|
||||
</div>
|
||||
138
TESTING.md
Normal file
138
TESTING.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# 测试指南
|
||||
|
||||
本项目支持**无数据库和无邮件服务器**的测试模式，让你可以快速验证所有功能！
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 环境配置
|
||||
|
||||
```bash
|
||||
# 复制环境配置文件
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
默认配置已经设置为测试模式，无需修改即可使用。
|
||||
|
||||
### 2. 启动服务
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 3. 运行测试
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
.\test-api.ps1
|
||||
```
|
||||
|
||||
**Linux/macOS:**
|
||||
```bash
|
||||
./test-api.sh
|
||||
```
|
||||
|
||||
**自定义参数:**
|
||||
```bash
|
||||
# Windows
|
||||
.\test-api.ps1 -BaseUrl "http://localhost:3000" -TestEmail "custom@example.com"
|
||||
|
||||
# Linux/macOS
|
||||
./test-api.sh "http://localhost:3000" "custom@example.com"
|
||||
```
|
||||
|
||||
## 🧪 测试功能
|
||||
|
||||
测试脚本会验证以下功能：
|
||||
|
||||
- ✅ **邮箱验证码发送** - 生成6位数验证码
|
||||
- ✅ **邮箱验证码验证** - 验证码校验和清理
|
||||
- ✅ **用户注册** - 完整的用户注册流程
|
||||
- ✅ **用户登录** - 用户名/邮箱/手机号登录
|
||||
|
||||
## 🔧 测试模式特性
|
||||
|
||||
- 🗄️ **Redis 文件存储** - 使用 `redis-data/redis.json` 存储验证码
|
||||
- 📧 **邮件测试模式** - 邮件内容输出到控制台，无需真实SMTP
|
||||
- 💾 **内存用户存储** - 无需数据库，用户数据存储在内存中
|
||||
- 🔄 **自动切换** - 根据配置自动选择存储模式
|
||||
|
||||
## 📊 单元测试
|
||||
|
||||
```bash
|
||||
# 运行所有单元测试
|
||||
npm test
|
||||
|
||||
# 监听模式
|
||||
npm run test:watch
|
||||
|
||||
# 生成覆盖率报告
|
||||
npm run test:cov
|
||||
```
|
||||
|
||||
## 🌐 生产环境配置
|
||||
|
||||
要切换到生产环境，编辑 `.env` 文件：
|
||||
|
||||
```bash
|
||||
# 启用数据库（取消注释并填入真实数据）
|
||||
DB_HOST=your_mysql_host
|
||||
DB_PORT=3306
|
||||
DB_USERNAME=your_db_username
|
||||
DB_PASSWORD=your_db_password
|
||||
DB_NAME=your_db_name
|
||||
|
||||
# 启用真实Redis（取消注释并设置）
|
||||
USE_FILE_REDIS=false
|
||||
REDIS_HOST=your_redis_host
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
|
||||
# 启用邮件服务（取消注释并填入真实数据）
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_PORT=587
|
||||
EMAIL_USER=your_email@gmail.com
|
||||
EMAIL_PASS=your_app_password
|
||||
EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>
|
||||
|
||||
# 生产环境设置
|
||||
NODE_ENV=production
|
||||
LOG_LEVEL=info
|
||||
```
|
||||
|
||||
## 🔍 故障排除
|
||||
|
||||
### 服务启动失败
|
||||
- 检查端口3000是否被占用
|
||||
- 确认Node.js版本 >= 18.0.0
|
||||
- 运行 `npm install` 重新安装依赖
|
||||
|
||||
### 测试脚本执行失败
|
||||
- 确认服务器正在运行
|
||||
- 检查防火墙设置
|
||||
- 在Linux/macOS上确保脚本有执行权限：`chmod +x test-api.sh`
|
||||
|
||||
### Redis文件存储问题
|
||||
- 检查 `redis-data` 目录权限
|
||||
- 确认 `USE_FILE_REDIS=true` 设置正确
|
||||
|
||||
### 邮件测试模式问题
|
||||
- 确认邮件配置为注释状态
|
||||
- 检查服务器控制台日志输出
|
||||
|
||||
## 📝 测试数据
|
||||
|
||||
测试完成后，你可以查看：
|
||||
|
||||
- `redis-data/redis.json` - 验证码存储数据
|
||||
- 服务器控制台 - 邮件内容输出
|
||||
- 测试脚本输出 - API响应结果
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
- 查看 [API 文档](http://localhost:3000/api-docs) 了解更多接口
|
||||
- 阅读 [开发规范](./docs/backend_development_guide.md) 开始开发
|
||||
- 使用 [AI 辅助指南](./docs/AI辅助开发规范指南.md) 提高开发效率
|
||||
@@ -1,112 +0,0 @@
|
||||
# 验证码问题调试脚本
|
||||
# 作者: moyin
|
||||
# 日期: 2025-12-17
|
||||
|
||||
$baseUrl = "http://localhost:3000"
|
||||
$testEmail = "debug@example.com"
|
||||
|
||||
Write-Host "=== 验证码问题调试脚本 ===" -ForegroundColor Green
|
||||
|
||||
# 步骤1: 发送验证码
|
||||
Write-Host "`n1. 发送验证码..." -ForegroundColor Yellow
|
||||
$sendBody = @{
|
||||
email = $testEmail
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$sendResponse = Invoke-RestMethod -Uri "$baseUrl/auth/send-email-verification" -Method POST -Body $sendBody -ContentType "application/json"
|
||||
Write-Host "发送响应: $($sendResponse | ConvertTo-Json -Depth 3)" -ForegroundColor Cyan
|
||||
|
||||
if ($sendResponse.success) {
|
||||
Write-Host "✅ 验证码发送成功" -ForegroundColor Green
|
||||
|
||||
# 步骤2: 立即查看验证码调试信息
|
||||
Write-Host "`n2. 查看验证码调试信息..." -ForegroundColor Yellow
|
||||
$debugResponse = Invoke-RestMethod -Uri "$baseUrl/auth/debug-verification-code" -Method POST -Body $sendBody -ContentType "application/json"
|
||||
Write-Host "调试信息: $($debugResponse | ConvertTo-Json -Depth 5)" -ForegroundColor Cyan
|
||||
|
||||
# 步骤3: 故意输入错误验证码
|
||||
Write-Host "`n3. 测试错误验证码..." -ForegroundColor Yellow
|
||||
$wrongVerifyBody = @{
|
||||
email = $testEmail
|
||||
verification_code = "000000"
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$wrongResponse = Invoke-RestMethod -Uri "$baseUrl/auth/verify-email" -Method POST -Body $wrongVerifyBody -ContentType "application/json"
|
||||
Write-Host "错误验证响应: $($wrongResponse | ConvertTo-Json -Depth 3)" -ForegroundColor Red
|
||||
} catch {
|
||||
Write-Host "错误验证失败（预期）: $($_.Exception.Message)" -ForegroundColor Yellow
|
||||
if ($_.Exception.Response) {
|
||||
$errorResponse = $_.Exception.Response.GetResponseStream()
|
||||
$reader = New-Object System.IO.StreamReader($errorResponse)
|
||||
$errorBody = $reader.ReadToEnd()
|
||||
Write-Host "错误详情: $errorBody" -ForegroundColor Red
|
||||
}
|
||||
}
|
||||
|
||||
# 步骤4: 再次查看调试信息
|
||||
Write-Host "`n4. 错误验证后的调试信息..." -ForegroundColor Yellow
|
||||
$debugResponse2 = Invoke-RestMethod -Uri "$baseUrl/auth/debug-verification-code" -Method POST -Body $sendBody -ContentType "application/json"
|
||||
Write-Host "调试信息: $($debugResponse2 | ConvertTo-Json -Depth 5)" -ForegroundColor Cyan
|
||||
|
||||
# 步骤5: 再次尝试错误验证码
|
||||
Write-Host "`n5. 再次测试错误验证码..." -ForegroundColor Yellow
|
||||
try {
|
||||
$wrongResponse2 = Invoke-RestMethod -Uri "$baseUrl/auth/verify-email" -Method POST -Body $wrongVerifyBody -ContentType "application/json"
|
||||
Write-Host "第二次错误验证响应: $($wrongResponse2 | ConvertTo-Json -Depth 3)" -ForegroundColor Red
|
||||
} catch {
|
||||
Write-Host "第二次错误验证失败: $($_.Exception.Message)" -ForegroundColor Yellow
|
||||
if ($_.Exception.Response) {
|
||||
$errorResponse = $_.Exception.Response.GetResponseStream()
|
||||
$reader = New-Object System.IO.StreamReader($errorResponse)
|
||||
$errorBody = $reader.ReadToEnd()
|
||||
Write-Host "错误详情: $errorBody" -ForegroundColor Red
|
||||
}
|
||||
}
|
||||
|
||||
# 步骤6: 最终调试信息
|
||||
Write-Host "`n6. 最终调试信息..." -ForegroundColor Yellow
|
||||
$debugResponse3 = Invoke-RestMethod -Uri "$baseUrl/auth/debug-verification-code" -Method POST -Body $sendBody -ContentType "application/json"
|
||||
Write-Host "最终调试信息: $($debugResponse3 | ConvertTo-Json -Depth 5)" -ForegroundColor Cyan
|
||||
|
||||
# 步骤7: 使用正确验证码（如果有的话）
|
||||
if ($sendResponse.data.verification_code) {
|
||||
Write-Host "`n7. 使用正确验证码..." -ForegroundColor Yellow
|
||||
$correctVerifyBody = @{
|
||||
email = $testEmail
|
||||
verification_code = $sendResponse.data.verification_code
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$correctResponse = Invoke-RestMethod -Uri "$baseUrl/auth/verify-email" -Method POST -Body $correctVerifyBody -ContentType "application/json"
|
||||
Write-Host "正确验证响应: $($correctResponse | ConvertTo-Json -Depth 3)" -ForegroundColor Green
|
||||
} catch {
|
||||
Write-Host "正确验证也失败了: $($_.Exception.Message)" -ForegroundColor Red
|
||||
if ($_.Exception.Response) {
|
||||
$errorResponse = $_.Exception.Response.GetResponseStream()
|
||||
$reader = New-Object System.IO.StreamReader($errorResponse)
|
||||
$errorBody = $reader.ReadToEnd()
|
||||
Write-Host "错误详情: $errorBody" -ForegroundColor Red
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
} else {
|
||||
Write-Host "❌ 验证码发送失败: $($sendResponse.message)" -ForegroundColor Red
|
||||
}
|
||||
} catch {
|
||||
Write-Host "❌ 请求失败: $($_.Exception.Message)" -ForegroundColor Red
|
||||
if ($_.Exception.Response) {
|
||||
$errorResponse = $_.Exception.Response.GetResponseStream()
|
||||
$reader = New-Object System.IO.StreamReader($errorResponse)
|
||||
$errorBody = $reader.ReadToEnd()
|
||||
Write-Host "错误详情: $errorBody" -ForegroundColor Red
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host "`n=== 调试完成 ===" -ForegroundColor Green
|
||||
Write-Host "请查看上述输出，重点关注：" -ForegroundColor Yellow
|
||||
Write-Host "1. TTL值的变化" -ForegroundColor White
|
||||
Write-Host "2. attempts字段的变化" -ForegroundColor White
|
||||
Write-Host "3. 验证码是否被意外删除" -ForegroundColor White
|
||||
187
docs/ARCHITECTURE.md
Normal file
187
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 🏗️ 项目架构设计
|
||||
|
||||
## 整体架构
|
||||
|
||||
Whale Town 采用分层架构设计，确保代码的可维护性和可扩展性。
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ API 层 │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ HTTP API │ │ WebSocket │ │ GraphQL │ │
|
||||
│ │ (REST) │ │ (Socket.IO) │ │ (预留) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 业务逻辑层 │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ 用户认证 │ │ 游戏逻辑 │ │ 社交功能 │ │
|
||||
│ │ (Login) │ │ (Game) │ │ (Social) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 核心服务层 │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ 邮件服务 │ │ 验证码服务 │ │ 日志服务 │ │
|
||||
│ │ (Email) │ │ (Verification)│ │ (Logger) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 数据访问层 │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ 用户数据 │ │ Redis缓存 │ │ 文件存储 │ │
|
||||
│ │ (Users) │ │ (Cache) │ │ (Files) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 模块依赖关系
|
||||
|
||||
```
|
||||
AppModule
|
||||
├── ConfigModule (全局配置)
|
||||
├── LoggerModule (日志系统)
|
||||
├── RedisModule (缓存服务)
|
||||
├── UsersModule (用户管理)
|
||||
│ ├── UsersService (数据库模式)
|
||||
│ └── UsersMemoryService (内存模式)
|
||||
├── EmailModule (邮件服务)
|
||||
├── VerificationModule (验证码服务)
|
||||
├── LoginCoreModule (登录核心)
|
||||
└── LoginModule (登录业务)
|
||||
```
|
||||
|
||||
## 数据流向
|
||||
|
||||
### 用户注册流程
|
||||
```
|
||||
1. 用户请求 → LoginController
|
||||
2. 参数验证 → LoginService
|
||||
3. 发送验证码 → LoginCoreService
|
||||
4. 生成验证码 → VerificationService
|
||||
5. 发送邮件 → EmailService
|
||||
6. 存储验证码 → RedisService
|
||||
7. 返回响应 → 用户
|
||||
```
|
||||
|
||||
### 双模式架构
|
||||
|
||||
项目支持开发测试模式和生产部署模式的无缝切换：
|
||||
|
||||
#### 开发测试模式
|
||||
- **数据库**: 内存存储 (UsersMemoryService)
|
||||
- **缓存**: 文件存储 (FileRedisService)
|
||||
- **邮件**: 控制台输出 (测试模式)
|
||||
- **优势**: 无需外部依赖，快速启动测试
|
||||
|
||||
#### 生产部署模式
|
||||
- **数据库**: MySQL (UsersService + TypeORM)
|
||||
- **缓存**: Redis (RealRedisService + IORedis)
|
||||
- **邮件**: SMTP服务器 (生产模式)
|
||||
- **优势**: 高性能，高可用，数据持久化
|
||||
|
||||
## 设计原则
|
||||
|
||||
### 1. 单一职责原则
|
||||
每个模块只负责一个特定的功能领域：
|
||||
- `LoginModule`: 只处理登录相关业务
|
||||
- `EmailModule`: 只处理邮件发送
|
||||
- `VerificationModule`: 只处理验证码逻辑
|
||||
|
||||
### 2. 依赖注入
|
||||
使用NestJS的依赖注入系统：
|
||||
- 接口抽象: `IRedisService`, `IUsersService`
|
||||
- 实现切换: 根据配置自动选择实现类
|
||||
- 测试友好: 易于Mock和单元测试
|
||||
|
||||
### 3. 配置驱动
|
||||
通过环境变量控制行为：
|
||||
- `USE_FILE_REDIS`: 选择Redis实现
|
||||
- `DB_HOST`: 数据库连接配置
|
||||
- `EMAIL_HOST`: 邮件服务配置
|
||||
|
||||
### 4. 错误处理
|
||||
统一的错误处理机制：
|
||||
- HTTP异常: `BadRequestException`, `UnauthorizedException`
|
||||
- 业务异常: 自定义异常类
|
||||
- 日志记录: 结构化错误日志
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加新的业务模块
|
||||
|
||||
1. **创建业务模块**
|
||||
```bash
|
||||
nest g module business/game
|
||||
nest g controller business/game
|
||||
nest g service business/game
|
||||
```
|
||||
|
||||
2. **创建核心服务**
|
||||
```bash
|
||||
nest g module core/game_core
|
||||
nest g service core/game_core
|
||||
```
|
||||
|
||||
3. **添加数据模型**
|
||||
```bash
|
||||
nest g module core/db/games
|
||||
nest g service core/db/games
|
||||
```
|
||||
|
||||
4. **更新主模块**
|
||||
在 `app.module.ts` 中导入新模块
|
||||
|
||||
### 添加新的工具服务
|
||||
|
||||
1. **创建工具模块**
|
||||
```bash
|
||||
nest g module core/utils/notification
|
||||
nest g service core/utils/notification
|
||||
```
|
||||
|
||||
2. **实现服务接口**
|
||||
定义抽象接口和具体实现
|
||||
|
||||
3. **添加配置支持**
|
||||
在环境变量中添加相关配置
|
||||
|
||||
4. **编写测试用例**
|
||||
确保功能正确性和代码覆盖率
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 1. 缓存策略
|
||||
- **Redis缓存**: 验证码、会话信息
|
||||
- **内存缓存**: 配置信息、静态数据
|
||||
- **CDN缓存**: 静态资源文件
|
||||
|
||||
### 2. 数据库优化
|
||||
- **连接池**: 复用数据库连接
|
||||
- **索引优化**: 关键字段建立索引
|
||||
- **查询优化**: 避免N+1查询问题
|
||||
|
||||
### 3. 日志优化
|
||||
- **异步日志**: 使用Pino的异步写入
|
||||
- **日志分级**: 生产环境只记录必要日志
|
||||
- **日志轮转**: 自动清理过期日志文件
|
||||
|
||||
## 安全考虑
|
||||
|
||||
### 1. 数据验证
|
||||
- **输入验证**: class-validator装饰器
|
||||
- **类型检查**: TypeScript静态类型
|
||||
- **SQL注入**: TypeORM参数化查询
|
||||
|
||||
### 2. 认证授权
|
||||
- **密码加密**: bcrypt哈希算法
|
||||
- **会话管理**: Redis存储会话信息
|
||||
- **权限控制**: 基于角色的访问控制
|
||||
|
||||
### 3. 通信安全
|
||||
- **HTTPS**: 生产环境强制HTTPS
|
||||
- **CORS**: 跨域请求控制
|
||||
- **Rate Limiting**: API请求频率限制
|
||||
93
test-api.ps1
Normal file
93
test-api.ps1
Normal file
@@ -0,0 +1,93 @@
|
||||
# Whale Town API Test Script (Windows PowerShell)
|
||||
# 测试邮箱验证码和用户注册登录功能
|
||||
|
||||
param(
|
||||
[string]$BaseUrl = "http://localhost:3000",
|
||||
[string]$TestEmail = "test@example.com"
|
||||
)
|
||||
|
||||
Write-Host "=== Whale Town API Test (Windows) ===" -ForegroundColor Green
|
||||
Write-Host "Testing without database and email server" -ForegroundColor Cyan
|
||||
Write-Host "Base URL: $BaseUrl" -ForegroundColor Yellow
|
||||
Write-Host "Test Email: $TestEmail" -ForegroundColor Yellow
|
||||
|
||||
# Test 1: Send verification code
|
||||
Write-Host "`n1. Sending email verification code..." -ForegroundColor Yellow
|
||||
$sendBody = @{
|
||||
email = $TestEmail
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$sendResponse = Invoke-RestMethod -Uri "$BaseUrl/auth/send-email-verification" -Method POST -Body $sendBody -ContentType "application/json"
|
||||
Write-Host "✅ Verification code sent successfully" -ForegroundColor Green
|
||||
Write-Host " Code: $($sendResponse.data.verification_code)" -ForegroundColor Cyan
|
||||
Write-Host " Test Mode: $($sendResponse.data.is_test_mode)" -ForegroundColor Cyan
|
||||
$verificationCode = $sendResponse.data.verification_code
|
||||
} catch {
|
||||
Write-Host "❌ Failed to send verification code" -ForegroundColor Red
|
||||
Write-Host " Error: $($_.Exception.Message)" -ForegroundColor Red
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Test 2: Verify email code
|
||||
Write-Host "`n2. Verifying email code..." -ForegroundColor Yellow
|
||||
$verifyBody = @{
|
||||
email = $TestEmail
|
||||
verification_code = $verificationCode
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$verifyResponse = Invoke-RestMethod -Uri "$BaseUrl/auth/verify-email" -Method POST -Body $verifyBody -ContentType "application/json"
|
||||
Write-Host "✅ Email verification successful" -ForegroundColor Green
|
||||
} catch {
|
||||
Write-Host "❌ Email verification failed" -ForegroundColor Red
|
||||
Write-Host " Error: $($_.Exception.Message)" -ForegroundColor Red
|
||||
}
|
||||
|
||||
# Test 3: User registration
|
||||
Write-Host "`n3. Testing user registration..." -ForegroundColor Yellow
|
||||
$registerBody = @{
|
||||
username = "testuser_$(Get-Random -Maximum 9999)"
|
||||
password = "Test123456"
|
||||
nickname = "Test User"
|
||||
email = $TestEmail
|
||||
email_verification_code = $verificationCode
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$registerResponse = Invoke-RestMethod -Uri "$BaseUrl/auth/register" -Method POST -Body $registerBody -ContentType "application/json"
|
||||
Write-Host "✅ User registration successful" -ForegroundColor Green
|
||||
Write-Host " User ID: $($registerResponse.data.user.id)" -ForegroundColor Cyan
|
||||
Write-Host " Username: $($registerResponse.data.user.username)" -ForegroundColor Cyan
|
||||
$username = $registerResponse.data.user.username
|
||||
} catch {
|
||||
Write-Host "❌ User registration failed" -ForegroundColor Red
|
||||
Write-Host " Error: $($_.Exception.Message)" -ForegroundColor Red
|
||||
$username = $null
|
||||
}
|
||||
|
||||
# Test 4: User login
|
||||
if ($username) {
|
||||
Write-Host "`n4. Testing user login..." -ForegroundColor Yellow
|
||||
$loginBody = @{
|
||||
identifier = $username
|
||||
password = "Test123456"
|
||||
} | ConvertTo-Json
|
||||
|
||||
try {
|
||||
$loginResponse = Invoke-RestMethod -Uri "$BaseUrl/auth/login" -Method POST -Body $loginBody -ContentType "application/json"
|
||||
Write-Host "✅ User login successful" -ForegroundColor Green
|
||||
Write-Host " Username: $($loginResponse.data.user.username)" -ForegroundColor Cyan
|
||||
Write-Host " Nickname: $($loginResponse.data.user.nickname)" -ForegroundColor Cyan
|
||||
} catch {
|
||||
Write-Host "❌ User login failed" -ForegroundColor Red
|
||||
Write-Host " Error: $($_.Exception.Message)" -ForegroundColor Red
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host "`n=== Test Summary ===" -ForegroundColor Green
|
||||
Write-Host "✅ Redis file storage: Working" -ForegroundColor Green
|
||||
Write-Host "✅ Email test mode: Working" -ForegroundColor Green
|
||||
Write-Host "✅ Memory user storage: Working" -ForegroundColor Green
|
||||
Write-Host "`n💡 Check redis-data/redis.json for stored verification data" -ForegroundColor Yellow
|
||||
Write-Host "💡 Check server console for email content output" -ForegroundColor Yellow
|
||||
95
test-api.sh
Normal file
95
test-api.sh
Normal file
@@ -0,0 +1,95 @@
|
||||
#!/bin/bash
|
||||
# Whale Town API Test Script (Linux/macOS)
|
||||
# 测试邮箱验证码和用户注册登录功能
|
||||
|
||||
BASE_URL="${1:-http://localhost:3000}"
|
||||
TEST_EMAIL="${2:-test@example.com}"
|
||||
|
||||
echo "=== Whale Town API Test (Linux/macOS) ==="
|
||||
echo "Testing without database and email server"
|
||||
echo "Base URL: $BASE_URL"
|
||||
echo "Test Email: $TEST_EMAIL"
|
||||
|
||||
# Test 1: Send verification code
|
||||
echo ""
|
||||
echo "1. Sending email verification code..."
|
||||
SEND_RESPONSE=$(curl -s -X POST "$BASE_URL/auth/send-email-verification" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"email\":\"$TEST_EMAIL\"}")
|
||||
|
||||
if echo "$SEND_RESPONSE" | grep -q '"success"'; then
|
||||
echo "✅ Verification code sent successfully"
|
||||
VERIFICATION_CODE=$(echo "$SEND_RESPONSE" | grep -o '"verification_code":"[^"]*"' | cut -d'"' -f4)
|
||||
IS_TEST_MODE=$(echo "$SEND_RESPONSE" | grep -o '"is_test_mode":[^,}]*' | cut -d':' -f2)
|
||||
echo " Code: $VERIFICATION_CODE"
|
||||
echo " Test Mode: $IS_TEST_MODE"
|
||||
else
|
||||
echo "❌ Failed to send verification code"
|
||||
echo " Response: $SEND_RESPONSE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Test 2: Verify email code
|
||||
echo ""
|
||||
echo "2. Verifying email code..."
|
||||
VERIFY_RESPONSE=$(curl -s -X POST "$BASE_URL/auth/verify-email" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"email\":\"$TEST_EMAIL\",\"verification_code\":\"$VERIFICATION_CODE\"}")
|
||||
|
||||
if echo "$VERIFY_RESPONSE" | grep -q '"success":true'; then
|
||||
echo "✅ Email verification successful"
|
||||
else
|
||||
echo "❌ Email verification failed"
|
||||
echo " Response: $VERIFY_RESPONSE"
|
||||
fi
|
||||
|
||||
# Test 3: User registration
|
||||
echo ""
|
||||
echo "3. Testing user registration..."
|
||||
RANDOM_NUM=$((RANDOM % 9999))
|
||||
USERNAME="testuser_$RANDOM_NUM"
|
||||
|
||||
REGISTER_RESPONSE=$(curl -s -X POST "$BASE_URL/auth/register" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"username\":\"$USERNAME\",\"password\":\"Test123456\",\"nickname\":\"Test User\",\"email\":\"$TEST_EMAIL\",\"email_verification_code\":\"$VERIFICATION_CODE\"}")
|
||||
|
||||
if echo "$REGISTER_RESPONSE" | grep -q '"success":true'; then
|
||||
echo "✅ User registration successful"
|
||||
USER_ID=$(echo "$REGISTER_RESPONSE" | grep -o '"id":"[^"]*"' | cut -d'"' -f4)
|
||||
REGISTERED_USERNAME=$(echo "$REGISTER_RESPONSE" | grep -o '"username":"[^"]*"' | cut -d'"' -f4)
|
||||
echo " User ID: $USER_ID"
|
||||
echo " Username: $REGISTERED_USERNAME"
|
||||
else
|
||||
echo "❌ User registration failed"
|
||||
echo " Response: $REGISTER_RESPONSE"
|
||||
REGISTERED_USERNAME=""
|
||||
fi
|
||||
|
||||
# Test 4: User login
|
||||
if [ -n "$REGISTERED_USERNAME" ]; then
|
||||
echo ""
|
||||
echo "4. Testing user login..."
|
||||
LOGIN_RESPONSE=$(curl -s -X POST "$BASE_URL/auth/login" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"identifier\":\"$REGISTERED_USERNAME\",\"password\":\"Test123456\"}")
|
||||
|
||||
if echo "$LOGIN_RESPONSE" | grep -q '"success":true'; then
|
||||
echo "✅ User login successful"
|
||||
LOGIN_USERNAME=$(echo "$LOGIN_RESPONSE" | grep -o '"username":"[^"]*"' | cut -d'"' -f4)
|
||||
LOGIN_NICKNAME=$(echo "$LOGIN_RESPONSE" | grep -o '"nickname":"[^"]*"' | cut -d'"' -f4)
|
||||
echo " Username: $LOGIN_USERNAME"
|
||||
echo " Nickname: $LOGIN_NICKNAME"
|
||||
else
|
||||
echo "❌ User login failed"
|
||||
echo " Response: $LOGIN_RESPONSE"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== Test Summary ==="
|
||||
echo "✅ Redis file storage: Working"
|
||||
echo "✅ Email test mode: Working"
|
||||
echo "✅ Memory user storage: Working"
|
||||
echo ""
|
||||
echo "💡 Check redis-data/redis.json for stored verification data"
|
||||
echo "💡 Check server console for email content output"
|
||||
Reference in New Issue
Block a user