🐋 Whale Town - 像素游戏后端服务

一个基于 NestJS 的现代化 2D 像素风游戏后端服务，采用业务功能模块化架构，支持用户认证、管理员后台、安全防护等完整功能。

🎯 项目简介

Whale Town 是一个功能完整的像素游戏后端服务，采用业务功能模块化架构设计：

• 🔐 用户认证模块 - 完整的登录、注册、密码管理、邮箱验证系统
• 👥 用户管理模块 - 用户状态管理、批量操作、状态统计功能
• 🛡️ 管理员模块 - 管理员认证、用户管理、密码重置、日志查看
• 🔒 安全模块 - 频率限制、维护模式、超时控制、内容类型检查
• 📧 智能邮件服务 - 支持测试模式和生产模式自动切换
• 🗄️ 灵活存储方案 - Redis文件存储 + 内存数据库，支持无依赖测试
• 📚 完整API文档 - Swagger UI + OpenAPI规范，17个接口完整覆盖
• 🧪 全面测试覆盖 - 140个单元测试用例全部通过

---

🚀 快速开始

📋 环境要求

• Node.js >= 18.0.0 (推荐 24.7.0)
• pnpm >= 8.0.0 (推荐 10.25.0)

🛠️ 安装与运行

# 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系统）
• 用户列表管理与搜索
• 用户密码重置功能
• 运行时日志查看与下载
• 响应式界面设计

🚀 快速启动：

# 1. 启动后端服务
pnpm run dev

# 2. 启动前端管理界面
cd client
pnpm install
pnpm run dev

# 3. 访问管理后台
# 地址: http://localhost:5173
# 默认账号: admin / Admin123456

🧪 快速测试

# 运行综合测试（推荐）
.\test-comprehensive.ps1

# 跳过限流测试（更快）
.\test-comprehensive.ps1 -SkipThrottleTest

# 测试远程服务器
.\test-comprehensive.ps1 -BaseUrl "https://your-server.com"

测试内容：

• ✅ 应用状态检查
• ✅ 邮箱验证码发送与验证
• ✅ 用户注册与登录
• ✅ 验证码登录功能
• ✅ 密码重置流程
• ✅ 邮箱冲突检测
• ✅ 验证码冷却时间清除
• ✅ 限流保护机制
• ✅ Redis文件存储功能
• ✅ 邮件测试模式

---

🎓 新开发者指南

第一步：了解项目规范 📚

⚠️ 重要：在开始开发前，请务必阅读以下文档

1. AI辅助开发规范指南 🤖

   • 学会使用AI助手提升开发效率300%
   • 自动生成符合规范的代码和注释
   • 实时检查代码质量

2. 后端开发规范 📝

   • 代码注释标准
   • 业务逻辑设计原则
   • 日志记录要求

3. Git提交规范 🔄

   • 提交信息格式
   • 分支管理策略

第二步：熟悉项目架构 🏗️

📁 项目文件结构总览

whale-town-end/                    # 🐋 项目根目录
├── 📂 src/                        # 源代码目录
│   ├── 📂 business/               # 🎯 业务功能模块（按功能组织）
│   │   ├── 📂 auth/               # 🔐 用户认证模块
│   │   ├── 📂 user-mgmt/          # 👥 用户管理模块  
│   │   ├── 📂 admin/              # 🛡️ 管理员模块
│   │   ├── 📂 security/           # 🔒 安全防护模块
│   │   ├── 📂 zulip/              # 💬 Zulip集成模块
│   │   └── 📂 shared/             # 🔗 共享业务组件
│   ├── 📂 core/                   # ⚙️ 核心技术服务
│   │   ├── 📂 db/                 # 🗄️ 数据库层（MySQL/内存双模式）
│   │   ├── 📂 redis/              # 🔴 Redis缓存（真实Redis/文件存储）
│   │   ├── 📂 login_core/         # 🔑 登录核心服务
│   │   ├── 📂 admin_core/         # 👑 管理员核心服务
│   │   ├── 📂 zulip/              # 💬 Zulip核心服务
│   │   └── 📂 utils/              # 🛠️ 工具服务（邮件、验证码、日志）
│   ├── 📄 app.module.ts           # 🏠 应用主模块
│   └── 📄 main.ts                 # 🚀 应用入口点
├── 📂 client/                     # 🎨 前端管理界面
│   ├── 📂 src/                    # 前端源码
│   ├── 📂 dist/                   # 前端构建产物
│   ├── 📄 package.json            # 前端依赖配置
│   └── 📄 vite.config.ts          # Vite构建配置
├── 📂 docs/                       # 📚 项目文档中心
│   ├── 📂 api/                    # 🔌 API接口文档
│   ├── 📂 development/            # 💻 开发指南
│   ├── 📂 deployment/             # 🚀 部署文档
│   ├── 📄 ARCHITECTURE.md         # 🏗️ 架构设计文档
│   └── 📄 README.md               # 📖 文档导航中心
├── 📂 test/                       # 🧪 测试文件目录
├── 📂 config/                     # ⚙️ 配置文件目录
├── 📂 logs/                       # 📝 日志文件存储
├── 📂 redis-data/                 # 💾 Redis文件存储数据
├── 📂 dist/                       # 📦 后端构建产物
├── 📄 .env                        # 🔧 环境变量配置
├── 📄 package.json                # 📋 项目依赖配置
├── 📄 docker-compose.yml          # 🐳 Docker编排配置
├── 📄 Dockerfile                  # 🐳 Docker镜像配置
└── 📄 README.md                   # 📖 项目主文档（当前文件）

架构特点：

• 🏗️ 业务功能模块化 - 按业务功能而非技术组件组织代码
• 🔄 双模式支持 - 开发测试模式 + 生产部署模式
• 📦 清晰分层 - 业务层 → 核心层 → 数据层
• 🧪 测试友好 - 完整的单元测试和集成测试覆盖

第三步：体验核心功能 🎮

1. API文档系统 📖

   # 启动服务后访问
   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测试 - 跨平台测试脚本
• 集成测试 - 完整业务流程验证
• 测试模式 - 无依赖快速测试

---

📊 开发与测试

🔧 开发命令

# 开发服务器（热重载）
pnpm run dev

# 构建项目
pnpm run build

# 生产环境运行
pnpm run start:prod

# 代码检查
pnpm run lint

# 格式化代码
pnpm run format

🧪 测试命令

# 运行所有单元测试
pnpm test

# 监听模式运行测试
pnpm run test:watch

# 生成测试覆盖率报告
pnpm run test:cov

# API功能测试（综合测试脚本）
.\test-comprehensive.ps1

📈 测试覆盖率

• 单元测试: 140个测试用例 ✅
• 功能测试: 用户认证、用户管理、管理员后台、安全防护 ✅
• 集成测试: 完整业务流程 ✅

---

🌍 部署配置

测试环境（默认）

# 无需数据库和邮件服务器
USE_FILE_REDIS=true
NODE_ENV=development
# 数据库和邮件配置保持注释状态

生产环境

# 启用真实服务
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

---

📚 文档中心

🎯 新手必读

1. AI辅助开发指南 - 提升开发效率300%
2. 后端开发规范 - 代码质量标准
3. Git提交规范 - 版本控制最佳实践

📖 API文档

• Swagger UI - 交互式API文档
• API文档总览 - 使用指南
• OpenAPI规范 - 标准化描述
• Postman集合 - 测试集合

🏗️ 系统设计

• 架构文档 - 系统架构设计
• 部署指南 - 生产环境部署

🧪 测试指南

• 测试指南 - 完整测试说明
• 单元测试 - 测试用例参考

---

🤝 贡献者

感谢所有为项目做出贡献的开发者！

🏆 核心团队

• moyin - 核心开发者
• jianuo - 核心开发者
• angjustinl - 核心开发者

查看完整贡献者名单：docs/CONTRIBUTORS.md

🌟 如何贡献

我们欢迎所有形式的贡献：

1. <EFBFBD> Bug修复 - 发现并修复问题
2. ✨ 新功能 - 添加有价值的功能
3. <EFBFBD> 文档改馈进 - 完善项目文档
4. 🧪 测试用例 - 提高代码覆盖率
5. 💡 建议反馈 - 提出改进建议

贡献流程：

1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR

---

📞 联系我们

• 项目地址: Gitea Repository
• 问题反馈: Issues
• 功能建议: Discussions

📄 许可证

本项目采用 MIT License 开源协议。

---

🐋 Whale Town - 让像素世界更精彩！

Made with ❤️ by the Whale Town Team

⭐ Star | 🍴 Fork | 📖 Docs | 🐛 Issues