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

基于 NestJS 的现代化 2D 像素游戏后端，采用四层架构（Gateway-Business-Core-Data），支持用户认证、实时通信、Zulip集成、管理员后台。

🎯 核心特性

• 🔐 用户认证：多方式登录、验证码登录、GitHub OAuth
• 🌐 实时通信：原生WebSocket、位置广播、地图房间管理
• 💬 Zulip集成：游戏内聊天与Zulip社群双向同步
• 👑 管理员后台：React界面、用户管理、日志监控
• 🛡️ 安全防护：频率限制、维护模式、JWT认证
• 🗄️ 灵活存储：MySQL/内存双模式、Redis/文件双模式
• 📚 完整文档：Swagger UI、WebSocket测试工具

🚀 快速开始

环境要求

• Node.js >= 18.0.0
• pnpm >= 8.0.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

前端管理界面

# 启动管理后台
cd client
pnpm install
pnpm run dev

访问：http://localhost:5173
默认账号：admin / Admin123456

在线体验

• API文档：https://whaletownend.xinghangee.icu/api-docs
• WebSocket测试：https://whaletownend.xinghangee.icu/websocket-test

🏗️ 项目架构

四层架构设计

Gateway Layer (网关层)
    ↓ HTTP/WebSocket协议处理、数据验证
Business Layer (业务层)
    ↓ 业务逻辑实现、服务协调
Core Layer (核心层)
    ↓ 技术基础设施、数据访问
Data Layer (数据层)
    ↓ 数据持久化、缓存管理

目录结构

whale-town-end/
├── src/
│   ├── gateway/          # 网关层：auth, location_broadcast
│   ├── business/         # 业务层：auth, user_mgmt, admin, zulip, notice
│   ├── core/             # 核心层：db, redis, login_core, admin_core, utils
│   ├── app.module.ts
│   └── main.ts
├── client/               # React管理界面
├── docs/                 # 项目文档
├── test/                 # 测试文件
└── config/               # 配置文件

详细架构：docs/ARCHITECTURE.md

🛠️ 技术栈

后端： NestJS 11 + TypeScript 5 + MySQL + Redis + WebSocket
前端： React 18 + Vite 7 + Ant Design 5
测试： Jest + Supertest（99个测试用例）
部署： Docker + PM2 + Nginx

📊 开发命令

# 开发
pnpm run dev              # 启动开发服务器
pnpm run build            # 构建项目
pnpm run start:prod       # 生产环境运行

# 测试
pnpm test                 # 运行单元测试
pnpm run test:cov         # 测试覆盖率
.\test-comprehensive.ps1  # API功能测试

🌍 环境配置

开发环境（默认）

USE_FILE_REDIS=true       # 使用文件存储（无需Redis）
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.163.com
EMAIL_USER=your_email@163.com
EMAIL_PASS=your_password

# Zulip
ZULIP_SERVER_URL=https://your-zulip.com/
ZULIP_BOT_API_KEY=your_api_key

详细配置：docs/deployment/DEPLOYMENT.md

📚 文档

• 架构设计 - 四层架构详解
• 开发规范 - 代码规范
• Git规范 - 提交规范
• API文档 - Swagger UI
• 测试指南 - 测试说明

🤖 AI代码检查指南

项目提供了完整的AI辅助代码检查流程，帮助确保代码质量和规范性。

快速开始：

向AI发送以下prompt开始代码检查：

请使用 docs/ai-reading 中readme的规范对 [模块路径] 进行完整的代码检查。

如何使用：

• AI会按照7个步骤逐步执行检查（命名规范、注释标准、代码质量、架构层级、测试覆盖、文档生成、代码提交）
• 每个步骤完成后会提供检查报告，等待确认后继续下一步
• 如有问题会自动修复并重新验证
• 这里建议每个步骤结束后，人工确认是否执行了修复，如果进行了修复，请告诉他：请重新执行一遍该步骤，看看是否有遗漏。

详细说明：docs/ai-reading/README.md | 开发者规范：docs/开发者代码检查规范.md

🤝 参与贡献

贡献流程

1. Fork项目
2. 创建分支：git checkout -b feature/your-feature
3. 开发功能（遵循开发规范）
4. 运行测试：pnpm test
5. 提交代码：git commit -m "feat: 添加新功能"
6. 创建Pull Request

核心团队

• moyin
• jianuo
• angjustinl

完整贡献者：docs/CONTRIBUTORS.md

📝 版本历史

• v2.1.0 (2026-01) - WebSocket架构升级、地图房间管理
• v2.0.0 (2025-12) - 四层架构重构、Zulip集成、管理员后台
• v1.2.0 (2025-11) - 用户管理、安全防护、邮件服务
• v1.0.0 (2025-10) - 项目初始化、用户认证、双模式存储

📞 联系方式

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

📄 许可证

MIT License

---

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

Made with ❤️ by the Whale Town Team

⭐ Star | 🍴 Fork | 📖 Docs | 🐛 Issues