gamegroup/doc/development/开发步骤文档.md

GameGroup 后端开发步骤文档

项目概述

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

技术栈

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

---

开发步骤

第一阶段：项目初始化与基础配置 (Day 1-2)

1.1 初始化 NestJS 项目

npm i -g @nestjs/cli
nest new gamegroup-backend

1.2 安装核心依赖

# ORM 和数据库
npm install @nestjs/typeorm typeorm mysql2
npm install @nestjs/config

# 缓存
npm install @nestjs/cache-manager cache-manager
npm install cache-manager-redis-store redis

# 认证
npm install @nestjs/passport passport passport-jwt
npm install @nestjs/jwt bcrypt
npm install -D @types/bcrypt @types/passport-jwt

# 验证
npm install class-validator class-transformer

# 文档
npm install @nestjs/swagger

# 工具类
npm install dayjs
npm install @nestjs/schedule

1.3 项目结构规划

backend/
├── src/
│   ├── common/              # 公共模块
│   │   ├── decorators/      # 自定义装饰器
│   │   ├── filters/         # 全局异常过滤器
│   │   ├── guards/          # 守卫 (RBAC)
│   │   ├── interceptors/    # 拦截器
│   │   ├── pipes/           # 管道
│   │   └── utils/           # 工具函数
│   ├── config/              # 配置文件
│   ├── modules/             # 业务模块
│   │   ├── auth/            # 认证模块
│   │   ├── users/           # 用户模块
│   │   ├── groups/          # 小组模块
│   │   ├── games/           # 游戏库模块
│   │   ├── appointments/    # 预约模块
│   │   ├── ledgers/         # 账目模块
│   │   ├── schedules/       # 排班模块
│   │   ├── blacklist/       # 黑名单模块
│   │   ├── honors/          # 荣誉墙模块
│   │   ├── assets/          # 资产模块
│   │   ├── points/          # 积分模块
│   │   └── bets/            # 竞猜模块
│   ├── entities/            # 数据库实体
│   ├── app.module.ts
│   └── main.ts
├── .env                     # 环境变量
├── .env.example             # 环境变量示例
├── docker-compose.yml       # Docker 编排
├── Dockerfile               # Docker 镜像
└── package.json

1.4 配置文件设置

• 创建 .env 文件
• 配置数据库连接
• 配置 Redis 连接
• 配置 JWT 密钥

---

第二阶段：核心基础设施 (Day 3-4)

2.1 数据库实体设计

按照设计文档创建所有实体：

• User (用户)
• Group (小组)
• GroupMember (小组成员)
• Game (游戏)
• Appointment (预约)
• AppointmentParticipant (预约参与)
• Ledger (账目)
• Schedule (排班)
• Blacklist (黑名单)
• Honor (荣誉)
• Asset (资产)
• AssetLog (资产日志)
• Point (积分)
• Bet (竞猜)

2.2 公共模块开发

• 全局异常过滤器: 统一错误响应格式
• 响应拦截器: 统一成功响应格式
• 验证管道: 全局 DTO 验证
• 角色守卫: RBAC 权限控制
• 日志中间件: 请求日志记录

2.3 认证系统

• 注册功能 (邮箱/手机号)
• 登录功能 (JWT Token)
• Token 刷新机制
• 密码加密 (bcrypt)

---

第三阶段：核心业务模块开发 (Day 5-10)

3.1 用户模块 (Day 5)

• 用户信息管理
• 会员状态管理
• 用户登录历史记录

3.2 小组模块 (Day 6)

• 创建小组 (权限校验: 非会员最多1个)
• 加入小组 (权限校验: 非会员最多3个)
• 小组信息编辑
• 成员管理 (踢人、设置管理员)
• 子组功能 (会员专属)
• 公示信息管理

3.3 游戏库模块 (Day 7)

• 游戏 CRUD
• 游戏分类
• 游戏搜索

3.4 预约模块 (Day 7-8)

• 发起预约 (权限校验)
• 加入/退出预约
• 预约状态管理
• 人数限制控制 (乐观锁)
• 预约历史查询

3.5 投票功能 (Day 8)

• 发起投票
• 投票结果统计
• 投票转预约

3.6 账目模块 (Day 9)

• 记账功能
• 账目分类
• 月度汇总
• 层级汇总 (大组->子组)

3.7 排班助手 (Day 10)

• 录入个人空闲时间
• 计算时间交集算法
• 推荐最佳时间

---

第四阶段：高级功能模块 (Day 11-14)

4.1 黑名单系统 (Day 11)

• 提交黑名单
• 审核机制
• 匹配预警

4.2 荣誉墙 (Day 11)

• 创建荣誉记录
• 上传媒体文件
• 时间轴展示

4.3 资产管理 (Day 12)

• 公用账号管理 (加密存储)
• 库存管理
• 借还记录

4.4 积分系统 (Day 13)

• 积分获取规则
• 积分消耗
• 积分流水

4.5 竞猜系统 (Day 14)

• 创建竞猜
• 下注功能
• 结算逻辑

---

第五阶段：集成与优化 (Day 15-17)

5.1 消息推送系统

• 事件总线设计
• 推送队列 (可选 Bull)
• 第三方机器人集成 (Discord/KOOK/QQ)

5.2 文件上传服务

• 本地存储
• 云存储集成 (阿里云 OSS / 腾讯云 COS)

5.3 缓存优化

• 用户信息缓存
• 热门游戏缓存
• 小组信息缓存

5.4 数据库优化

• 索引优化
• 查询优化
• 数据归档策略

5.5 Swagger API 文档

• 所有接口文档化
• DTO 注解
• 认证配置

---

第六阶段：测试与部署 (Day 18-20)

6.1 单元测试

• Service 层测试
• Controller 层测试

6.2 Docker 部署

# docker-compose.yml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - mysql
      - redis
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: gamegroup
      MYSQL_ROOT_PASSWORD: password
  redis:
    image: redis:7-alpine

6.3 CI/CD 配置

• GitHub Actions
• 自动化测试
• 自动部署

6.4 性能测试

• 压力测试 (K6)
• 接口性能监控

---

开发规范

代码规范

• 使用 ESLint + Prettier
• 命名规范：驼峰命名、有意义的变量名
• 注释规范：复杂逻辑必须注释

Git 规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具

API 响应格式

// 成功
{
  "code": 200,
  "message": "success",
  "data": { ... }
}

// 失败
{
  "code": 40001,
  "message": "用户不存在",
  "data": null
}

---

错误码定义

用户相关 (10xxx)

• 10001: 用户不存在
• 10002: 密码错误
• 10003: 用户已存在
• 10004: Token 无效
• 10005: Token 过期

小组相关 (20xxx)

• 20001: 小组不存在
• 20002: 小组已满员
• 20003: 无权限操作
• 20004: 非会员小组数量超限
• 20005: 加入小组数量超限

预约相关 (30xxx)

• 30001: 预约不存在
• 30002: 预约已满
• 30003: 预约已关闭
• 30004: 已加入预约

系统相关 (90xxx)

• 90001: 服务器错误
• 90002: 参数错误
• 90003: 数据库错误

---

当前进度

• 第一阶段: 项目初始化
• 第二阶段: 基础设施
• 第三阶段: 核心业务
  • 用户模块
  • 小组模块
  • 游戏库模块
  • 预约模块
  • 账目模块
  • 排班助手
• 第四阶段: 高级功能（✅ 已完成）
  • 黑名单系统
  • 荣誉墙系统
  • 资产管理系统
  • 积分系统
  • 竞猜系统
• 第五阶段: 集成优化
• 第六阶段: 测试部署（单元测试已开始）

---

下一步行动

1. ✅ 完成黑名单系统开发
2. ✅ 完成荣誉墙系统开发
3. ✅ 完成资产管理模块
4. ✅ 完成积分系统模块
5. ✅ 完成竞猜系统模块
6. ✅ 为所有第四阶段模块编写单元测试（61个测试全部通过）
7. ⏭️ 集成测试与优化
8. ⏭️ 修复已知的27个测试失败

---

最新更新 (2025-12-19)

✅ 已完成（今日更新）

第四阶段全部完成 + 完整测试覆盖 🎉

1. 黑名单系统

• 举报提交功能
• 审核机制（会员权限）
• 黑名单检查API
• 完整的CRUD操作
• ✅ 14个单元测试全部通过

2. 荣誉墙系统

• 创建荣誉记录
• 媒体文件支持
• 时间轴展示（按年份分组）
• 权限控制（管理员/组长）
• ✅ 16个单元测试全部通过

3. 资产管理系统

• 资产创建与管理（账号/物品）
• 账号凭据加密存储（AES-256-CBC）
• 借用/归还机制
• 借还记录追踪
• 权限控制（管理员）
• ✅ 10个单元测试全部通过

4. 积分系统

• 积分添加/消耗
• 用户积分余额查询
• 积分流水记录
• 小组积分排行榜
• 权限控制（管理员操作）
• ✅ 10个单元测试全部通过

5. 竞猜系统

• 创建竞猜下注
• 积分余额验证
• 竞猜结算（按比例分配奖池）
• 竞猜取消（自动退还积分）
• 下注统计功能
• ✅ 11个单元测试全部通过

🔧 技术改进

• 升级加密算法为 createCipheriv/createDecipheriv
• 添加3个新错误码（资产、积分相关）
• 优化实体类型定义（nullable 字段）
• 完善枚举定义（资产状态、竞猜状态）

📊 项目统计

• 已开发模块: 12个
• 代码行数: ~26,500行
• 新增测试: 61个（全部通过✅）
• 总测试数: 169个（142个通过，27个已知问题）
• 测试覆盖率: ~84%
• API接口数: ~70+

🧪 测试明细

第四阶段模块测试（61个测试，100%通过）：

• BlacklistService: 14个测试 ✅
• HonorsService: 16个测试 ✅
• AssetsService: 10个测试 ✅
• PointsService: 10个测试 ✅
• BetsService: 11个测试 ✅

测试覆盖：

• CRUD操作完整性
• 权限验证逻辑
• 业务规则验证
• 异常处理机制

🎯 下一步重点

进入第五阶段：集成优化

1. 性能优化（查询优化、缓存策略）
2. 修复已知的27个测试失败
3. 集成测试（模块间交互）
4. API文档完善
5. 准备生产环境部署