gamegroup/README.md

# 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. 安装依赖

```bash
npm install
```

### 3. 配置环境变量

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

```bash
cp .env.example .env
```

关键配置项：
```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 启动数据库（推荐）

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

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f
```

### 5. 启动开发服务器

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

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

### 6. 访问应用

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

## 可用脚本

```bash
# 开发
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](开发步骤文档.md)

## API 文档

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

### 响应格式

#### 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1703001234567
}
```

#### 错误响应
```json
{
  "code": 10001,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1703001234567
}
```

### 错误码

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

完整错误码见 [src/common/interfaces/response.interface.ts](src/common/interfaces/response.interface.ts)

## Docker 部署

### 开发环境

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

# 查看日志
docker compose logs -f app

# 停止服务
docker compose down
```

### 生产环境

```bash
# 构建镜像
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)
- [修改记录.md](修改记录.md)