# 1. 克隆项目
git clone <repository-url>
cd whale-town-end

# 2. 安装依赖
pnpm install

# 3. 配置环境（测试模式，无需数据库和邮件服务器）
cp .env.example .env

# 4. 启动开发服务器
pnpm run dev

🎉 服务启动成功！ 访问 http://localhost:3000

🧑‍💻 管理员后台（Ant Design）

项目包含一个最小可用的管理员后台（管理员登录 / 用户管理 / 重置密码），文档见：

docs/systems/admin-dashboard/README.md

启动方式：

pnpm install

# 后端
pnpm run dev

# 前端后台
pnpm -C client dev

🧪 快速测试

# Windows
.\test-api.ps1

# Linux/macOS  
./test-api.sh

测试内容：

✅ 邮箱验证码发送与验证
✅ 用户注册与登录
✅ Redis文件存储功能
✅ 邮件测试模式

🎓 新开发者指南

第一步：了解项目规范 📚

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

AI辅助开发规范指南 🤖
- 学会使用AI助手提升开发效率300%
- 自动生成符合规范的代码和注释
- 实时检查代码质量
后端开发规范 📝
- 代码注释标准
- 业务逻辑设计原则
- 日志记录要求
Git提交规范 🔄
- 提交信息格式
- 分支管理策略

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

项目根目录/
├── 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层 → 业务层 → 核心层 → 数据层
🔄 双模式支持 - 开发测试模式 + 生产部署模式
📦 模块化设计 - 每个功能独立模块，便于维护扩展
🧪 测试友好 - 完整的单元测试和集成测试覆盖

第三步：体验核心功能 🎮

API文档系统 📖

# 启动服务后访问
http://localhost:3000/api-docs

用户认证系统 🔐
- 邮箱验证码注册
- 多方式登录（用户名/邮箱/手机号）
- 密码重置功能
实时通信 🌐
- WebSocket支持
- Socket.IO集成

第四步：开始贡献 🤝

Fork项目 到你的Gitea账户
创建功能分支：git checkout -b feature/your-feature
遵循规范开发（使用AI助手帮助）
提交代码：git commit -m "feat：添加新功能"
创建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支持
权限控制 - 基于角色的访问控制

📧 智能邮件服务

测试模式 - 控制台输出，无需SMTP服务器
生产模式 - 支持主流邮件服务商
模板系统 - 验证码、欢迎邮件等模板
自动切换 - 根据配置自动选择模式

🗄️ 灵活存储方案

Redis文件存储 - 开发测试无需Redis服务器
内存数据库 - 无需MySQL即可运行
生产就绪 - 支持MySQL + Redis部署
自动切换 - 根据配置自动选择存储方式

📚 完整API文档

Swagger UI - 交互式API文档
OpenAPI规范 - 标准化接口描述
Postman集合 - 可导入的测试集合
实时更新 - 代码变更自动同步文档

🧪 全面测试覆盖

单元测试 - 114个测试用例全部通过
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-api.ps1      # Windows
./test-api.sh       # Linux/macOS

📈 测试覆盖率

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

🌍 部署配置

测试环境（默认）

# 无需数据库和邮件服务器
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

📚 文档中心

🎯 新手必读

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

📖 API文档

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

🏗️ 系统设计

用户认证系统 - 认证架构设计
邮件验证系统 - 验证流程设计
日志系统 - 日志架构设计

🧪 测试指南

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

🤝 贡献者

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

🏆 核心团队

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

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

🌟 如何贡献

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

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

贡献流程：

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

📞 联系我们

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

📄 许可证

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

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

Made with ❤️ by the Whale Town Team

⭐ Star | 🍴 Fork | 📖 Docs | 🐛 Issues

README.md Unescape Escape

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

🎯 项目简介

🚀 快速开始

📋 环境要求

🛠️ 安装与运行