# 🐋 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 是一个功能完整的像素游戏后端服务，提供：

- 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
- 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
- 📚 **完整API文档** - Swagger UI + OpenAPI规范
- 🧪 **全面测试覆盖** - 单元测试 + API功能测试

---

## 🚀 快速开始

### 📋 环境要求

- **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

### 🧪 快速测试

```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项目** 到你的GitHub账户
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集成

### 📊 日志监控
- **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服务器
- **生产模式** - 支持主流邮件服务商
- **模板系统** - 验证码、欢迎邮件等模板
- **自动切换** - 根据配置自动选择模式

### 🗄️ 灵活存储方案
- **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
```

### 📈 测试覆盖率

- **单元测试**: 114个测试用例 ✅
- **功能测试**: 用户认证、邮件验证、数据存储 ✅
- **集成测试**: 完整业务流程 ✅

---

## 🌍 部署配置

### 测试环境（默认）
```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. **� Bug修复**  - 发现并修复问题
2. **✨ 新功能** - 添加有价值的功能  
3. **� 文档改馈进** - 完善项目文档
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>