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/modules/schedules/) - 排班助手模块
- [src/entities/schedule.entity.ts](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](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](src/modules/auth/) - Auth模块测试
- [src/modules/games/*.spec.ts](src/modules/games/) - 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/modules/ledgers/) - 账目模块
- [src/app.module.ts](src/app.module.ts) - 注册账目模块
- [API文档.md](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/modules/appointments/) - 预约模块
- [src/app.module.ts](src/app.module.ts) - 注册预约模块
- [API文档.md](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/modules/games/) - 游戏库模块
- [src/common/interfaces/response.interface.ts](src/common/interfaces/response.interface.ts) - 添加游戏相关错误代码
- [src/app.module.ts](src/app.module.ts) - 注册游戏库模块
- [API文档.md](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/modules/groups/) - 小组模块
- [src/app.module.ts](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/auth/) - 认证模块
- [src/modules/users/](src/modules/users/) - 用户模块
- [src/common/guards/](src/common/guards/) - 守卫
- [src/app.module.ts](src/app.module.ts) - 主模块
- [src/app.controller.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 验证和错误提示

**影响范围**:
- 认证系统完整实现
- 用户管理功能
- 全局认证和权限控制

**测试建议**:
```bash
# 需要先启动 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](README.md) - 项目使用说明
- [init.sql](init.sql) - 数据库初始化
- [src/config/](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/config/) - 配置文件
- [src/entities/](src/entities/) - 数据库实体（12个）
- [src/common/](src/common/) - 公共模块
- [src/main.ts](src/main.ts) - 应用入口
- [src/app.module.ts](src/app.module.ts) - 根模块
- [docker-compose.yml](docker-compose.yml) - Docker 编排
- [Dockerfile](Dockerfile) - Docker 镜像构建
- [.env](.env) - 环境变量
- [.env.example](.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)
- [修改记录.md](修改记录.md)

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

---

## 记录模板

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

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

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

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