datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
032c97a1fc4a529e4ad60beb3ce8614253dc9be3
whale-town-end/README.md
moyin d80d2c5cb8 docs：更新README、贡献者文档和部署指南 
- 更新README.md：添加管理员后台系统介绍，更新测试统计为154个用例
- 更新CONTRIBUTORS.md：补充jianuo的管理员后台开发贡献，更新项目里程碑
- 更新DEPLOYMENT.md：完善前后端分离部署方案，添加管理员后台配置说明
- 反映最新管理员后台功能的部署要求和配置变更
2025-12-22 15:13:04 +08:00

438 lines
13 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-10.4-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 是一个功能完整的像素游戏后端服务，提供：
- 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
- 🎛️ **管理员后台系统** - React + Ant Design，用户管理、日志监控、权限控制
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
- 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
- 📚 **完整API文档** - Swagger UI + OpenAPI规范
- 🧪 **全面测试覆盖** - 154个单元测试用例全部通过
---
## 🚀 快速开始
### 📋 环境要求
- **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
### 🧑‍💻 管理员后台系统
项目包含一个功能完整的管理员后台系统，基于 React + Ant Design 构建：
**🎛️ 核心功能：**
- 管理员身份认证（独立Token系统）
- 用户列表管理与搜索
- 用户密码重置功能
- 运行时日志查看与下载
- 响应式界面设计
**📚 详细文档：** [docs/systems/admin-dashboard/README.md](docs/systems/admin-dashboard/README.md)
**🚀 快速启动：**
```bash
# 1. 安装依赖
pnpm install
# 2. 启动后端服务
pnpm run dev
# 3. 启动前端管理界面
pnpm -C client dev
# 4. 访问管理后台
# 地址: http://localhost:5173
# 账号: admin / Admin123456
```
### 🧪 快速测试
```bash
# Windows
.\test-api.ps1
# Linux/macOS
./test-api.sh
```
**测试内容：**
- ✅ 邮箱验证码发送与验证
- ✅ 用户注册与登录
- ✅ 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
# 启动服务后访问
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** - 反向代理和负载均衡
---
## 🏗️ 核心功能
### 🔐 用户认证系统
- **多方式登录** - 用户名/邮箱/手机号
- **邮箱验证** - 完整的验证码流程
- **密码安全** - bcrypt加密 + 强度验证
- **第三方登录** - GitHub OAuth支持
- **权限控制** - 基于角色的访问控制
### 🎛️ 管理员后台系统
- **独立认证** - 专用Token系统，与用户系统隔离
- **用户管理** - 用户列表、搜索、密码重置
- **日志监控** - 实时日志查看、历史日志下载
- **权限控制** - 管理员角色验证（role=9）
- **现代界面** - React + Ant Design响应式设计
### 📧 智能邮件服务
- **测试模式** - 控制台输出，无需SMTP服务器
- **生产模式** - 支持主流邮件服务商
- **模板系统** - 验证码、欢迎邮件等模板
- **自动切换** - 根据配置自动选择模式
### 🗄️ 灵活存储方案
- **Redis文件存储** - 开发测试无需Redis服务器
- **内存数据库** - 无需MySQL即可运行
- **生产就绪** - 支持MySQL + Redis部署
- **自动切换** - 根据配置自动选择存储方式
### 📚 完整API文档
- **Swagger UI** - 交互式API文档
- **OpenAPI规范** - 标准化接口描述
- **Postman集合** - 可导入的测试集合
- **实时更新** - 代码变更自动同步文档
### 🧪 全面测试覆盖
- **单元测试** - 114个测试用例全部通过
- **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-api.ps1 # Windows
./test-api.sh # Linux/macOS
```
### 📈 测试覆盖率
- **单元测试**: 154个测试用例 ✅
- **功能测试**: 用户认证、邮件验证、数据存储、管理员后台 ✅
- **集成测试**: 完整业务流程 ✅
---
## 🌍 部署配置
### 测试环境（默认）
```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>
Reference in New Issue View Git Blame Copy Permalink