初始化游戏小组管理系统后端项目
- 基于 NestJS + TypeScript + MySQL + Redis 架构 - 完整的模块化设计（认证、用户、小组、游戏、预约等） - JWT 认证和 RBAC 权限控制系统 - Docker 容器化部署支持 - 添加 CLAUDE.md 项目开发指南 - 配置 .gitignore 忽略文件 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
UGREEN USER
288
README.md
Normal file
288
README.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user