gamegroup/doc/development/修改记录.md

GameGroup 后端修改记录

记录所有开发过程中的修改、新增、删除操作

---

2025-12-19

完成排班助手模块开发和测试

时间: 2025-12-19 16:30
操作类型: 新增
操作人: GitHub Copilot
详细内容:

排班助手模块（Schedules Module）

• ✅ 创建 DTO:

  • TimeSlotDto - 时间段定义（开始时间、结束时间、备注）
  • CreateScheduleDto - 创建排班（小组ID、标题、描述、空闲时间段数组）
  • UpdateScheduleDto - 更新排班信息
  • QuerySchedulesDto - 查询条件（小组ID、用户ID、时间范围、分页）
  • FindCommonSlotsDto - 查找共同空闲时间（小组ID、时间范围、最少参与人数）

• ✅ 创建 Service (447行):

  • create() - 创建排班（验证小组成员、时间段有效性）
  • findAll() - 查询排班列表（支持小组/用户/时间筛选）
  • findOne() - 获取排班详情
  • update() - 更新排班（仅创建者）
  • remove() - 删除排班（仅创建者）
  • findCommonSlots() - 查找共同空闲时间（核心算法）
  • calculateCommonSlots() - 扫描线算法计算时间交集
  • mergeAdjacentSlots() - 合并相邻时间段
  • validateTimeSlots() - 时间段验证

• ✅ 创建 Controller:

  • POST /schedules - 创建排班
  • GET /schedules - 获取排班列表
  • POST /schedules/common-slots - 查找共同空闲时间
  • GET /schedules/:id - 获取排班详情
  • PUT /schedules/:id - 更新排班
  • DELETE /schedules/:id - 删除排班

• ✅ 编写单元测试:

  • schedules.service.spec.ts - 19个测试用例
  • 覆盖：CRUD、权限控制、时间交集计算、异常处理

核心算法：共同空闲时间计算

使用扫描线算法（Sweep Line Algorithm）：

1. 收集所有用户的时间段起止点
2. 按时间排序所有事件点（start/end）
3. 维护活跃用户集合，扫描线移动时记录满足条件的时间段
4. 合并相邻且参与者相同的时间段
5. 按参与人数降序返回结果

时间复杂度: O(n log n)，n为时间段总数

业务规则:

• 用户只能为所在小组创建排班
• 只有创建者可以修改/删除排班
• 时间段必须有效（结束>开始）
• 至少提供一个时间段
• 查找共同时间默认要求至少2人参与

技术要点:

• Schedule实体使用simple-json存储时间段数组
• TypeORM关联User和Group实体
• 支持跨小组查询（用户所在所有小组）
• 前端友好的时间交集API返回

相关文件:

• src/modules/schedules/ - 排班助手模块
• src/entities/schedule.entity.ts - Schedule实体

---

完成Users模块单元测试

时间: 2025-12-19 16:25
操作类型: 新增
操作人: GitHub Copilot
详细内容:

Users模块测试

• ✅ users.service.spec.ts - 11个测试用例

  • findOne() - 获取用户信息（2个用例）
  • update() - 更新用户（4个用例：成功、不存在、邮箱冲突、手机号冲突）
  • changePassword() - 修改密码（3个用例：成功、旧密码错误、用户不存在）
  • getCreatedGroupsCount() - 创建的小组数量
  • getJoinedGroupsCount() - 加入的小组数量

• ✅ 测试技术：

  • Mock CryptoUtil工具类
  • Mock QueryBuilder（for changePassword）
  • 模拟多次findOne调用（邮箱/手机号冲突检测）

测试覆盖:

• ✅ 用户信息查询和更新
• ✅ 密码修改流程
• ✅ 邮箱/手机号唯一性检查
• ✅ 用户小组数量统计

相关文件:

• src/modules/users/users.service.spec.ts

---

完成单元测试框架搭建

时间: 2025-12-19 16:10
操作类型: 新增
操作人: GitHub Copilot
详细内容:

测试基础设施

• ✅ 安装测试依赖:

  • @nestjs/testing - NestJS测试工具
  • jest - 测试框架
  • ts-jest - TypeScript支持
  • supertest - HTTP测试

• ✅ 编写Auth模块单元测试:

  • auth.service.spec.ts - Service层测试（13个测试用例）
  • auth.controller.spec.ts - Controller E2E测试（3个测试用例）
  • 覆盖：注册、登录、Token刷新、用户验证等功能

• ✅ 编写Games模块单元测试:

  • games.service.spec.ts - Service层测试（13个测试用例）
  • 覆盖：CRUD、搜索、筛选、标签、平台等功能

测试策略:

1. 单元测试: 使用Mock Repository和Service
2. E2E测试: 使用Supertest进行HTTP请求测试
3. 测试覆盖: Service层逻辑和Controller层接口

相关文件:

• src/modules/auth/*.spec.ts - Auth模块测试
• src/modules/games/*.spec.ts - Games模块测试

---

完成账目模块开发

时间: 2025-12-19 16:00
操作类型: 新增
操作人: GitHub Copilot
详细内容:

账目模块（Ledgers Module）

• ✅ 创建 DTO：

  • CreateLedgerDto - 创建账目（小组ID、类型、金额、描述、分类、日期）
  • UpdateLedgerDto - 更新账目信息
  • QueryLedgersDto - 查询账目（支持按小组、类型、分类、时间范围筛选）
  • MonthlyStatisticsDto - 月度统计参数

• ✅ 实现 LedgersService 核心功能：

  • 创建账目（需小组成员权限）
  • 获取账目列表（支持多条件筛选和分页）
  • 获取账目详情
  • 更新账目（需创建者或管理员权限）
  • 删除账目（需创建者或管理员权限）
  • 月度统计（收入/支出/分类统计）
  • 层级汇总（大组+子组汇总）

• ✅ 创建 LedgersController API 端点（需认证）：

  • POST /api/ledgers - 创建账目
  • GET /api/ledgers - 获取账目列表（支持筛选）
  • GET /api/ledgers/:id - 获取账目详情
  • PUT /api/ledgers/:id - 更新账目
  • DELETE /api/ledgers/:id - 删除账目
  • GET /api/ledgers/statistics/monthly - 月度统计
  • GET /api/ledgers/statistics/hierarchical/:groupId - 层级汇总

相关文件:

• src/modules/ledgers/ - 账目模块
• src/app.module.ts - 注册账目模块
• API文档.md - 更新账目API文档（6个接口）

业务规则:

1. 账目类型:

   • income: 收入
   • expense: 支出

2. 权限控制:

   • 创建：小组成员
   • 查看：小组成员
   • 修改/删除：创建者或小组管理员

3. 统计功能:

   • 月度统计：按月统计收入、支出、分类明细
   • 层级汇总：大组和所有子组的账目汇总

---

完成预约模块开发

时间: 2025-12-19 15:45
操作类型: 新增
操作人: GitHub Copilot
详细内容:

预约模块（Appointments Module）

• ✅ 创建 DTO：

  • CreateAppointmentDto - 创建预约（小组ID、游戏ID、标题、描述、时间、最大参与人数）
  • UpdateAppointmentDto - 更新预约信息
  • QueryAppointmentsDto - 查询预约（支持按小组、游戏、状态、时间范围筛选）
  • JoinAppointmentDto - 加入预约
  • PollOptionDto, CreatePollDto, VoteDto - 投票相关（待实现）

• ✅ 实现 AppointmentsService 核心功能：

  • 创建预约（需在小组中、创建者自动加入）
  • 加入预约（检查小组成员、预约状态、是否已满员）
  • 退出预约（创建者不能退出）
  • 获取预约列表（支持多条件筛选和分页）
  • 获取我参与的预约
  • 获取预约详情
  • 更新预约（需创建者或管理员权限）
  • 确认预约（检查参与人数）
  • 完成预约
  • 取消预约
  • 权限检查（创建者、小组管理员、组长）

• ✅ 创建 AppointmentsController API 端点（需认证）：

  • POST /api/appointments - 创建预约
  • GET /api/appointments - 获取预约列表（支持筛选）
  • GET /api/appointments/my - 获取我参与的预约
  • GET /api/appointments/:id - 获取预约详情
  • POST /api/appointments/join - 加入预约
  • DELETE /api/appointments/:id/leave - 退出预约
  • PUT /api/appointments/:id - 更新预约
  • PUT /api/appointments/:id/confirm - 确认预约
  • PUT /api/appointments/:id/complete - 完成预约
  • DELETE /api/appointments/:id - 取消预约

相关文件:

• src/modules/appointments/ - 预约模块
• src/app.module.ts - 注册预约模块
• API文档.md - 更新预约API文档（10个接口）

业务规则:

1. 创建预约:

   • 必须是小组成员才能创建
   • 创建者自动加入预约
   • 预约状态默认为 open

2. 加入预约:

   • 必须是小组成员
   • 不能重复加入
   • 预约已满或已取消/已完成不能加入
   • 加入后检查是否达到最大人数，自动变更状态

3. 退出预约:

   • 创建者不能退出
   • 其他成员可随时退出

4. 权限控制:

   • 创建者：完全控制权
   • 小组管理员/组长：可以更新、取消、确认、完成预约
   • 普通成员：只能加入和退出

5. 状态流转:

   • open（开放中）→ full（已满员）
   • open/full → cancelled（已取消）
   • open/full → finished（已完成）

预约状态:

• open: 开放中
• full: 已满员
• cancelled: 已取消
• finished: 已完成

---

完成游戏库模块开发

时间: 2025-12-19 15:40
操作类型: 新增
操作人: GitHub Copilot
详细内容:

游戏库模块（Games Module）

• ✅ 创建 DTO：

  • CreateGameDto - 创建游戏（游戏名称、封面、描述、玩家数、平台、标签）
  • UpdateGameDto - 更新游戏信息
  • SearchGameDto - 搜索游戏（关键词、平台、标签、分页）

• ✅ 实现 GamesService 核心功能：

  • 创建游戏（唯一性校验）
  • 获取游戏列表（支持关键词搜索、平台和标签筛选、分页）
  • 获取游戏详情
  • 更新游戏信息（名称唯一性校验）
  • 删除游戏（软删除）
  • 获取热门游戏
  • 获取所有标签
  • 获取所有平台

• ✅ 创建 GamesController API 端点（公开访问）：

  • GET /api/games - 获取游戏列表（支持搜索和筛选）
  • GET /api/games/popular - 获取热门游戏
  • GET /api/games/tags - 获取所有游戏标签
  • GET /api/games/platforms - 获取所有游戏平台
  • GET /api/games/:id - 获取游戏详情
  • POST /api/games - 创建游戏（需要认证）
  • PUT /api/games/:id - 更新游戏信息（需要认证）
  • DELETE /api/games/:id - 删除游戏（需要认证）

相关文件:

• src/modules/games/ - 游戏库模块
• src/common/interfaces/response.interface.ts - 添加游戏相关错误代码
• src/app.module.ts - 注册游戏库模块
• API文档.md - 更新游戏库API文档（8个接口）

业务规则:

1. 游戏管理:

   • 游戏名称必须唯一
   • 最大玩家数不能小于1
   • 最小玩家数默认为1
   • 标签为字符串数组，可以为空

2. 搜索功能:

   • 支持按关键词搜索（匹配游戏名称和描述）
   • 支持按平台筛选
   • 支持按标签筛选
   • 支持分页查询

3. 权限控制:

   • 游戏列表、详情、热门游戏、标签、平台查询公开访问
   • 创建、更新、删除游戏需要认证（管理员功能）

错误代码:

• 40001: 游戏不存在
• 40002: 游戏已存在

---

完成小组模块开发

时间: 2025-12-19 15:50
操作类型: 新增
操作人: GitHub Copilot
详细内容:

小组模块（Groups Module）

• ✅ 创建 DTO：

  • CreateGroupDto - 创建小组
  • UpdateGroupDto - 更新小组信息
  • JoinGroupDto - 加入小组
  • UpdateMemberRoleDto - 更新成员角色
  • KickMemberDto - 踢出成员

• ✅ 实现 GroupsService 核心功能：

  • 创建小组（权限校验：非会员最多1个，会员最多10个）
  • 加入小组（权限校验：非会员最多3个）
  • 退出小组
  • 获取小组详情（包含成员列表）
  • 获取用户的小组列表
  • 更新小组信息（组长和管理员权限）
  • 设置成员角色（仅组长）
  • 踢出成员（组长和管理员）
  • 解散小组（仅组长）
  • 子组功能（会员专属）

• ✅ 创建 GroupsController API 端点：

  • POST /api/groups - 创建小组
  • POST /api/groups/join - 加入小组
  • GET /api/groups/my - 获取我的小组列表
  • GET /api/groups/:id - 获取小组详情
  • PUT /api/groups/:id - 更新小组信息
  • PUT /api/groups/:id/members/role - 设置成员角色
  • DELETE /api/groups/:id/members - 踢出成员
  • DELETE /api/groups/:id/leave - 退出小组
  • DELETE /api/groups/:id - 解散小组

相关文件:

• src/modules/groups/ - 小组模块
• src/app.module.ts - 注册小组模块

业务规则:

1. 创建限制:

   • 非会员：最多创建 1 个小组
   • 会员：最多创建 10 个小组
   • 子组：仅会员可创建

2. 加入限制:

   • 非会员：最多加入 3 个小组
   • 会员：无限制
   • 小组满员时无法加入

3. 权限管理:

   • 组长：所有权限
   • 管理员：修改信息、踢人（由组长设置）
   • 普通成员：查看信息

4. 特殊规则:

   • 组长不能直接退出，需先转让或解散
   • 不能踢出组长
   • 解散小组后，小组变为不活跃状态

API 端点总览:

小组管理：
- POST   /api/groups              创建小组
- GET    /api/groups/my           获取我的小组
- GET    /api/groups/:id          获取小组详情
- PUT    /api/groups/:id          更新小组信息
- DELETE /api/groups/:id          解散小组

成员管理：
- POST   /api/groups/join         加入小组
- DELETE /api/groups/:id/leave    退出小组
- PUT    /api/groups/:id/members/role    设置成员角色
- DELETE /api/groups/:id/members  踢出成员

技术亮点:

1. 完善的权限控制: 三级权限（组长、管理员、成员）
2. 灵活的限制规则: 区分会员和非会员
3. 子组支持: 支持大公会内部分组
4. 成员数管理: 自动维护小组当前成员数
5. 关联查询: 返回详细的成员信息

影响范围:

• 小组管理功能完整实现
• 成员管理功能
• 权限控制体系

备注:

• ✅ 编译测试通过
• ⏭️ 下一步：开发游戏库模块（Games Module）

---

2025-12-19

完成认证模块和用户模块开发

时间: 2025-12-19 15:40
操作类型: 新增
操作人: GitHub Copilot
详细内容:

认证模块（Auth Module）

• ✅ 创建 DTO：RegisterDto、LoginDto、RefreshTokenDto
• ✅ 实现 AuthService：
  • 用户注册功能（邮箱/手机号验证）
  • 用户登录功能（支持用户名/邮箱/手机号登录）
  • Token 刷新机制
  • JWT Token 生成
• ✅ 创建 AuthController：
  • POST /api/auth/register - 用户注册
  • POST /api/auth/login - 用户登录
  • POST /api/auth/refresh - 刷新令牌
• ✅ 实现 JWT 策略（JwtStrategy）
• ✅ 创建认证守卫（JwtAuthGuard）
• ✅ 创建角色守卫（RolesGuard）

用户模块（Users Module）

• ✅ 创建 DTO：UpdateUserDto、ChangePasswordDto
• ✅ 实现 UsersService：
  • 获取用户信息
  • 更新用户信息
  • 修改密码
  • 获取用户创建的小组数量
  • 获取用户加入的小组数量
• ✅ 创建 UsersController：
  • GET /api/users/me - 获取当前用户信息
  • GET /api/users/:id - 获取指定用户信息
  • PUT /api/users/me - 更新当前用户信息
  • PUT /api/users/me/password - 修改密码

系统集成

• ✅ 在 AppModule 中注册认证和用户模块
• ✅ 配置全局 JWT 认证守卫
• ✅ 配置全局角色守卫
• ✅ 更新 AppController 添加健康检查接口
• ✅ 修复 User 实体的 lastLoginIp 类型问题

相关文件:

• src/modules/auth/ - 认证模块
• src/modules/users/ - 用户模块
• src/common/guards/ - 守卫
• src/app.module.ts - 主模块
• src/app.controller.ts - 主控制器

API 端点:

认证相关：
- POST /api/auth/register     用户注册
- POST /api/auth/login        用户登录  
- POST /api/auth/refresh      刷新令牌

用户相关：
- GET  /api/users/me          获取当前用户信息
- GET  /api/users/:id         获取用户信息
- PUT  /api/users/me          更新用户信息
- PUT  /api/users/me/password 修改密码

系统相关：
- GET  /api                   健康检查
- GET  /api/health            健康检查

技术亮点:

1. JWT 认证: 完整的 JWT Token + Refresh Token 机制
2. 多方式登录: 支持用户名、邮箱、手机号登录
3. 密码加密: 使用 bcrypt 加密存储
4. 全局守卫: 默认所有接口需要认证，使用 @Public() 装饰器开放
5. 角色控制: 基于 RBAC 的权限管理
6. 数据验证: 完善的 DTO 验证和错误提示

影响范围:

• 认证系统完整实现
• 用户管理功能
• 全局认证和权限控制

测试建议:

# 需要先启动 MySQL 数据库
# 方式1：使用 Docker
docker compose up -d mysql

# 方式2：使用本地 MySQL
# 确保 .env 中配置正确

# 启动应用
npm run start:dev

# 访问 Swagger 文档测试 API
http://localhost:3000/docs

备注:

• ✅ 编译测试通过
• ⏭️ 下一步：开发小组模块（Groups Module）

---

2025-12-19

完成项目基础架构并创建项目文档

时间: 2025-12-19 15:30
操作类型: 新增 + 修改
操作人: GitHub Copilot
详细内容:

• 修复 TypeScript 类型错误（配置文件中的 parseInt 参数）
• 项目编译测试通过（npm run build）
• 创建 README.md 项目说明文档
• 创建 init.sql 数据库初始化脚本
• 更新修改记录文档

相关文件:

• README.md - 项目使用说明
• init.sql - 数据库初始化
• src/config/ - 修复的配置文件

影响范围:

• 项目文档完善
• 配置文件类型安全

备注:

• 项目基础架构搭建完成 ✅
• 编译测试通过 ✅
• 下一步：需要本地安装 MySQL 和 Redis，或使用 Docker 启动数据库服务
• 然后开始开发认证模块和用户模块

---

2025-12-19

项目基础架构搭建

时间: 2025-12-19 15:10
操作类型: 新增
操作人: GitHub Copilot
详细内容:

• 初始化 NestJS 项目
• 安装所有核心依赖包：
  • @nestjs/typeorm, typeorm, mysql2
  • @nestjs/config
  • @nestjs/passport, passport, passport-jwt
  • @nestjs/jwt, bcrypt
  • class-validator, class-transformer
  • @nestjs/swagger
  • dayjs, @nestjs/schedule
• 创建项目目录结构（common, config, entities, modules）
• 创建环境配置文件（.env, .env.example）
• 创建 Docker 配置文件（docker-compose.yml, Dockerfile, .gitignore）
• 创建所有数据库实体（User, Group, Game, Appointment 等共 12 个实体）
• 创建公共模块：
  • 异常过滤器（HttpExceptionFilter）
  • 响应拦截器（TransformInterceptor, LoggingInterceptor）
  • 验证管道（ValidationPipe）
  • 装饰器（CurrentUser, Roles, Public）
  • 工具类（CryptoUtil, DateUtil, PaginationUtil）
  • 枚举定义（用户角色、小组角色、预约状态等）
  • 响应接口定义（ApiResponse, ErrorCode 等）
• 配置主模块（AppModule）和启动文件（main.ts）

相关文件:

• src/config/ - 配置文件
• src/entities/ - 数据库实体（12个）
• src/common/ - 公共模块
• src/main.ts - 应用入口
• src/app.module.ts - 根模块
• docker-compose.yml - Docker 编排
• Dockerfile - Docker 镜像构建
• .env - 环境变量
• .env.example - 环境变量示例

影响范围:

• 项目整体架构
• 数据库结构设计
• 统一响应格式
• 错误处理机制
• 日志系统
• 参数验证

技术亮点:

1. 统一响应格式: 所有 API 返回统一的 JSON 格式
2. 全局异常处理: 自动捕获并格式化所有异常
3. 请求日志: 自动记录所有请求和响应信息
4. 类型安全: 完整的 TypeScript 类型定义
5. ORM 映射: 12 个实体完整覆盖业务需求
6. 装饰器增强: 自定义装饰器简化开发

备注:

• 下一步需要启动 MySQL 和 Redis 服务
• 然后开始开发各个业务模块（认证、用户、小组等）

---

2025-12-19

初始化项目文档

时间: 2025-12-19 13:30
操作类型: 新增
操作人: GitHub Copilot
详细内容:

• 创建 开发步骤文档.md
• 创建 修改记录.md
• 规划项目整体架构和开发步骤

相关文件:

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

备注:

• 后续所有开发操作都将在此文档记录
• 按时间倒序排列，最新记录在最上方

---

记录模板

### [功能/模块名称]
**时间**: YYYY-MM-DD HH:mm  
**操作类型**: 新增 / 修改 / 删除 / 重构  
**操作人**: [开发者]  
**详细内容**:
- 操作描述1
- 操作描述2

**相关文件**:
- [文件路径](文件路径)

**影响范围**:
- 影响的模块或功能

**备注**:
- 特殊说明或注意事项