GameGroup 后端项目

基于 NestJS + TypeScript + MySQL + Redis 的游戏小组管理系统后端

项目简介

GameGroup 是一个为游戏固定玩家和游戏工会组织提供的管理平台，支持预约组队、游戏选择、信息公示、账目管理等功能。

技术栈

• 框架: NestJS 10.x
• 语言: TypeScript 5.x
• 数据库: MySQL 8.0
• 缓存: Redis 7.x
• ORM: TypeORM
• 认证: JWT (passport-jwt)
• 文档: Swagger
• 容器化: Docker + Docker Compose

项目结构

backend/
├── src/
│   ├── common/              # 公共模块
│   │   ├── decorators/      # 自定义装饰器
│   │   ├── filters/         # 全局异常过滤器
│   │   ├── guards/          # 守卫 (RBAC)
│   │   ├── interceptors/    # 拦截器
│   │   ├── pipes/           # 管道
│   │   ├── utils/           # 工具函数
│   │   ├── enums/           # 枚举定义
│   │   └── interfaces/      # 接口定义
│   ├── config/              # 配置文件
│   ├── entities/            # 数据库实体
│   ├── modules/             # 业务模块（待开发）
│   ├── app.module.ts        # 根模块
│   └── main.ts              # 应用入口
├── .env                     # 环境变量
├── docker-compose.yml       # Docker 编排
├── Dockerfile               # Docker 镜像
├── 开发步骤文档.md          # 开发计划
└── 修改记录.md              # 修改日志

快速开始

1. 环境准备

确保已安装以下软件：

• Node.js 18+
• MySQL 8.0+ （或使用 Docker）
• Redis 7.x+ （或使用 Docker）

2. 安装依赖

npm install

3. 配置环境变量

复制 .env.example 到 .env，并根据实际情况修改配置：

cp .env.example .env

关键配置项：

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=gamegroup

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT 密钥（生产环境请务必修改）
JWT_SECRET=your-super-secret-jwt-key

4. 使用 Docker 启动数据库（推荐）

# 启动 MySQL 和 Redis
docker compose up -d mysql redis

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

5. 启动开发服务器

# 开发模式（热重载）
npm run start:dev

# 生产模式
npm run build
npm run start:prod

6. 访问应用

• API 地址: http://localhost:3000/api
• Swagger 文档: http://localhost:3000/docs

可用脚本

# 开发
npm run start          # 启动应用
npm run start:dev      # 开发模式（热重载）
npm run start:debug    # 调试模式

# 构建
npm run build          # 编译 TypeScript

# 测试
npm run test           # 单元测试
npm run test:e2e       # E2E 测试
npm run test:cov       # 测试覆盖率

# 代码质量
npm run lint           # ESLint 检查
npm run format         # Prettier 格式化

数据库

自动同步（开发环境）

开发环境下，TypeORM 会自动根据实体文件同步数据库结构（synchronize: true）。

手动管理（生产环境）

生产环境建议使用迁移（Migration）管理数据库。

核心功能模块

已完成

✅ 项目基础架构
✅ 数据库实体设计
✅ 统一响应格式
✅ 全局异常处理
✅ 日志系统
✅ 参数验证

待开发

⬜ 认证模块（Auth）
⬜ 用户模块（Users）
⬜ 小组模块（Groups）
⬜ 游戏库模块（Games）
⬜ 预约模块（Appointments）
⬜ 账目模块（Ledgers）
⬜ 排班模块（Schedules）
⬜ 黑名单模块（Blacklist）
⬜ 荣誉墙模块（Honors）
⬜ 资产管理模块（Assets）
⬜ 积分系统（Points）
⬜ 竞猜系统（Bets）

详见 开发步骤文档.md

API 文档

启动项目后访问 Swagger 文档：http://localhost:3000/docs

响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1703001234567
}

错误响应

{
  "code": 10001,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1703001234567
}

错误码

错误码	说明
0	成功
10001	用户不存在
10002	密码错误
20001	小组不存在
30001	预约不存在
90001	服务器错误

完整错误码见 src/common/interfaces/response.interface.ts

Docker 部署

开发环境

# 启动所有服务
docker compose up -d

# 查看日志
docker compose logs -f app

# 停止服务
docker compose down

生产环境

# 构建镜像
docker build -t gamegroup-backend:latest .

# 运行容器
docker run -d \
  --name gamegroup-backend \
  -p 3000:3000 \
  --env-file .env.production \
  gamegroup-backend:latest

开发规范

Git 提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式（不影响代码运行）
refactor: 重构
test: 测试相关
chore: 构建/工具链相关

代码规范

• 使用 ESLint + Prettier
• 遵循 TypeScript 最佳实践
• 必须通过类型检查
• 复杂逻辑添加注释

常见问题

1. 数据库连接失败

检查：

• MySQL 服务是否启动
• 数据库配置是否正确
• 防火墙是否允许连接

2. Redis 连接失败

检查：

• Redis 服务是否启动
• Redis 配置是否正确

3. 端口被占用

修改 .env 中的 PORT 配置

---

当前项目状态: 🚧 基础架构搭建完成，业务模块开发中

下一步计划: 开发认证模块（Auth）和用户模块（Users）

详见：

• 开发步骤文档.md
• 修改记录.md