ANGJustinl/whale-town-end
1
0
Fork 0
forked from datawhale/whale-town-end
Code Pull Requests Activity
Files
07601b6d7932c1ae6720f43e01b8fff1b5c5dbea
whale-town-end/README.md
moyin 07601b6d79 docs：更新README中的测试说明 
- 更新快速测试部分，使用新的综合测试脚本
- 添加测试脚本的参数说明（跳过限流测试、自定义服务器等）
- 更新测试内容列表，包含新增的功能测试
- 统一测试命令，简化开发者使用流程
2025-12-25 20:51:00 +08:00

451 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🐋 Whale Town - 像素游戏后端服务
> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，采用业务功能模块化架构，支持用户认证、管理员后台、安全防护等完整功能。
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![NestJS](https://img.shields.io/badge/NestJS-11.1-red.svg)](https://nestjs.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
## 🎯 项目简介
Whale Town 是一个功能完整的像素游戏后端服务，采用业务功能模块化架构设计：
- 🔐 **用户认证模块** - 完整的登录、注册、密码管理、邮箱验证系统
- 👥 **用户管理模块** - 用户状态管理、批量操作、状态统计功能
- 🛡️ **管理员模块** - 管理员认证、用户管理、密码重置、日志查看
- 🔒 **安全模块** - 频率限制、维护模式、超时控制、内容类型检查
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
- 📚 **完整API文档** - Swagger UI + OpenAPI规范，17个接口完整覆盖
- 🧪 **全面测试覆盖** - 140个单元测试用例全部通过
---
## 🚀 快速开始
### 📋 环境要求
- **Node.js** >= 18.0.0 (推荐 24.7.0)
- **pnpm** >= 8.0.0 (推荐 10.25.0)
### 🛠️ 安装与运行
```bash
# 1. 克隆项目
git clone <repository-url>
cd whale-town-end
# 2. 安装依赖
pnpm install
# 3. 配置环境（测试模式，无需数据库和邮件服务器）
cp .env.example .env
# 4. 启动开发服务器
pnpm run dev
```
🎉 **服务启动成功！** 访问 http://localhost:3000
### 🧑‍💻 前端管理界面
项目包含一个功能完整的前端管理界面，位于 `client/` 目录：
**🎛️ 核心功能：**
- 管理员身份认证（独立Token系统）
- 用户列表管理与搜索
- 用户密码重置功能
- 运行时日志查看与下载
- 响应式界面设计
**🚀 快速启动：**
```bash
# 1. 启动后端服务
pnpm run dev
# 2. 启动前端管理界面
cd client
pnpm install
pnpm run dev
# 3. 访问管理后台
# 地址: http://localhost:5173
# 默认账号: admin / Admin123456
```
### 🧪 快速测试
```bash
# 运行综合测试（推荐）
.\test-comprehensive.ps1
# 跳过限流测试（更快）
.\test-comprehensive.ps1 -SkipThrottleTest
# 测试远程服务器
.\test-comprehensive.ps1 -BaseUrl "https://your-server.com"
```
**测试内容：**
- ✅ 应用状态检查
- ✅ 邮箱验证码发送与验证
- ✅ 用户注册与登录
- ✅ 验证码登录功能
- ✅ 密码重置流程
- ✅ 邮箱冲突检测
- ✅ 验证码冷却时间清除
- ✅ 限流保护机制
- ✅ Redis文件存储功能
- ✅ 邮件测试模式
---
## 🎓 新开发者指南
### 第一步：了解项目规范 📚
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
1. **[AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)** 🤖
- 学会使用AI助手提升开发效率300%
- 自动生成符合规范的代码和注释
- 实时检查代码质量
2. **[后端开发规范](./docs/backend_development_guide.md)** 📝
- 代码注释标准
- 业务逻辑设计原则
- 日志记录要求
3. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
- 提交信息格式
- 分支管理策略
### 第二步：熟悉项目架构 🏗️
```
项目根目录/
├── src/ # 源代码目录
│ ├── business/ # 业务功能模块（按功能组织）
│ │ ├── auth/ # 🔐 用户认证模块
│ │ ├── user-mgmt/ # 👥 用户管理模块
│ │ ├── admin/ # 🛡️ 管理员模块
│ │ ├── security/ # 🔒 安全模块
│ │ └── shared/ # 🔗 共享组件
│ ├── core/ # 核心技术服务
│ │ ├── db/ # 数据库层（支持MySQL/内存双模式）
│ │ ├── redis/ # Redis缓存服务（支持真实Redis/文件存储）
│ │ ├── login_core/ # 登录核心服务
│ │ ├── admin_core/ # 管理员核心服务
│ │ └── utils/ # 工具服务（邮件、验证码、日志）
│ ├── app.module.ts # 应用主模块
│ └── main.ts # 应用入口
├── client/ # 前端管理界面
├── docs/ # 项目文档
├── test/ # 测试文件
├── redis-data/ # Redis文件存储数据
├── logs/ # 日志文件
└── 配置文件 # .env, package.json, tsconfig.json等
```
**架构特点：**
- 🏗️ **业务功能模块化** - 按业务功能而非技术组件组织代码
- 🔄 **双模式支持** - 开发测试模式 + 生产部署模式
- 📦 **清晰分层** - 业务层 → 核心层 → 数据层
- 🧪 **测试友好** - 完整的单元测试和集成测试覆盖
### 第三步：体验核心功能 🎮
1. **API文档系统** 📖
```bash
# 启动服务后访问
http://localhost:3000/api-docs
```
2. **用户认证系统** 🔐
- 邮箱验证码注册
- 多方式登录（用户名/邮箱/手机号）
- 密码重置功能
3. **实时通信** 🌐
- WebSocket支持
- Socket.IO集成
### 第四步：开始贡献 🤝
1. **Fork项目** 到你的Gitea账户
2. **创建功能分支**：`git checkout -b feature/your-feature`
3. **遵循规范开发**（使用AI助手帮助）
4. **提交代码**：`git commit -m "feat：添加新功能"`
5. **创建Pull Request**
---
## 🛠️ 技术栈
### 🚀 核心框架
- **NestJS** `^11.1.9` - 企业级Node.js框架，提供依赖注入、模块化等特性
- **TypeScript** `^5.9.3` - 类型安全的JavaScript超集
- **Express** `^10.4.20` - 基于Express的HTTP服务器
- **RxJS** `^7.8.2` - 响应式编程库，处理异步数据流
### 🌐 实时通信
- **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开发
### 🔐 安全认证
- **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集成
### 🧑‍💻 管理员后台（前端）
- **Vite** - 前端构建工具（本项目 admin dashboard 使用）
- **React** - 前端 UI 框架
- **React Router** - 前端路由
- **Ant Design** - 企业级 UI 组件库
### 📊 日志监控
- **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** - 反向代理和负载均衡
---
## 🏗️ 核心功能
### 🔐 用户认证模块 (business/auth/)
- **多方式登录** - 用户名/邮箱/手机号
- **邮箱验证** - 完整的验证码流程
- **密码安全** - bcrypt加密 + 强度验证
- **第三方登录** - GitHub OAuth支持
- **密码管理** - 忘记密码、重置密码、修改密码
### 👥 用户管理模块 (business/user-mgmt/)
- **用户状态管理** - 6种状态控制（active、inactive、locked、banned、deleted、pending）
- **批量操作** - 批量修改用户状态
- **状态统计** - 各状态用户数量统计
- **状态变更日志** - 完整的审计日志
### 🛡️ 管理员模块 (business/admin/)
- **独立认证** - 专用Token系统，与用户系统隔离
- **用户管理** - 用户列表、搜索、密码重置
- **日志监控** - 实时日志查看、历史日志下载
- **权限控制** - 管理员角色验证（role=9）
### 🔒 安全模块 (business/security/)
- **频率限制** - 基于IP的请求频率控制
- **维护模式** - 系统维护期间的访问控制
- **内容类型验证** - HTTP请求内容类型检查
- **超时控制** - 可配置的请求超时机制
### 📧 智能邮件服务
- **测试模式** - 控制台输出，无需SMTP服务器
- **生产模式** - 支持主流邮件服务商
- **模板系统** - 验证码、欢迎邮件等模板
- **自动切换** - 根据配置自动选择模式
### 🗄️ 灵活存储方案
- **Redis文件存储** - 开发测试无需Redis服务器
- **内存数据库** - 无需MySQL即可运行
- **生产就绪** - 支持MySQL + Redis部署
- **自动切换** - 根据配置自动选择存储方式
### 📚 完整API文档
- **Swagger UI** - 交互式API文档
- **OpenAPI规范** - 标准化接口描述
- **Postman集合** - 可导入的测试集合
- **实时更新** - 代码变更自动同步文档
### 🧪 全面测试覆盖
- **单元测试** - 140个测试用例全部通过
- **API测试** - 跨平台测试脚本
- **集成测试** - 完整业务流程验证
- **测试模式** - 无依赖快速测试
---
## 📊 开发与测试
### 🔧 开发命令
```bash
# 开发服务器（热重载）
pnpm run dev
# 构建项目
pnpm run build
# 生产环境运行
pnpm run start:prod
# 代码检查
pnpm run lint
# 格式化代码
pnpm run format
```
### 🧪 测试命令
```bash
# 运行所有单元测试
pnpm test
# 监听模式运行测试
pnpm run test:watch
# 生成测试覆盖率报告
pnpm run test:cov
# API功能测试（综合测试脚本）
.\test-comprehensive.ps1
```
### 📈 测试覆盖率
- **单元测试**: 140个测试用例 ✅
- **功能测试**: 用户认证、用户管理、管理员后台、安全防护 ✅
- **集成测试**: 完整业务流程 ✅
---
## 🌍 部署配置
### 测试环境（默认）
```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/ARCHITECTURE.md)** - 系统架构设计
- **[部署指南](./docs/deployment/DEPLOYMENT.md)** - 生产环境部署
### 🧪 测试指南
- **[测试指南](./docs/development/TESTING.md)** - 完整测试说明
- **[单元测试](./src/**/*.spec.ts)** - 测试用例参考
---
## 🤝 贡献者
感谢所有为项目做出贡献的开发者！
### 🏆 核心团队
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/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>
View Git Blame Copy Permalink