whale-town-end/README.md

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

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

[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![NestJS](https://img.shields.io/badge/NestJS-11.1-red.svg)](https://nestjs.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18.3-61dafb.svg)](https://reactjs.org/)
[![Tests](https://img.shields.io/badge/Tests-99%20passing-brightgreen.svg)](#)

## 🎯 核心特性

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

## 🚀 快速开始

### 环境要求
- Node.js >= 18.0.0
- pnpm >= 8.0.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
# 启动管理后台
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](./docs/ARCHITECTURE.md)

## 🛠️ 技术栈

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

## 📊 开发命令

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

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

## 🌍 环境配置

### 开发环境（默认）
```bash
USE_FILE_REDIS=true       # 使用文件存储（无需Redis）
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.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](./docs/deployment/DEPLOYMENT.md)

## 📚 文档

- [架构设计](./docs/ARCHITECTURE.md) - 四层架构详解
- [开发规范](./docs/development/backend_development_guide.md) - 代码规范
- [Git规范](./docs/development/git_commit_guide.md) - 提交规范
- [API文档](http://localhost:3000/api-docs) - Swagger UI
- [测试指南](./docs/development/TESTING.md) - 测试说明

### 🤖 AI代码检查指南

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

**快速开始：**

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

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

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

详细说明：[docs/ai-reading/README.md](./docs/ai-reading/README.md) | 开发者规范：[docs/开发者代码检查规范.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](https://gitea.xinghangee.icu/moyin)
- [jianuo](https://gitea.xinghangee.icu/jianuo)
- [angjustinl](https://gitea.xinghangee.icu/ANGJustinl)

完整贡献者：[docs/CONTRIBUTORS.md](./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](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>