# 测试指南

本项目支持**无数据库和无邮件服务器**的测试模式，让你可以快速验证所有功能！

## 🚀 快速开始

### 1. 环境配置

```bash
# 复制环境配置文件
cp .env.example .env
```

默认配置已经设置为测试模式，无需修改即可使用。

### 2. 启动服务

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

### 3. 运行测试

**Windows (PowerShell):**
```powershell
.\test-api.ps1
```

**Linux/macOS:**
```bash
./test-api.sh
```

**自定义参数:**
```bash
# Windows
.\test-api.ps1 -BaseUrl "http://localhost:3000" -TestEmail "custom@example.com"

# Linux/macOS
./test-api.sh "http://localhost:3000" "custom@example.com"
```

## 🧪 测试功能

### API功能测试
测试脚本会验证以下核心功能：

**用户认证模块：**
- ✅ **邮箱验证码发送** - 生成6位数验证码，测试模式输出到控制台
- ✅ **邮箱验证码验证** - 验证码校验和自动清理
- ✅ **用户注册** - 完整的用户注册流程，包含邮箱验证
- ✅ **用户登录** - 支持用户名/邮箱/手机号多种方式登录

**系统状态测试：**
- ✅ **应用状态检查** - 验证服务器运行状态和系统信息
- ✅ **Redis文件存储** - 验证验证码存储和读取功能
- ✅ **内存数据库** - 验证用户数据存储功能

### 单元测试覆盖

**核心服务测试（7个测试套件，140个测试用例）：**

1. **LoginCoreService** - 登录核心服务（15个测试）
   - 用户登录成功/失败场景
   - 用户注册功能测试
   - GitHub OAuth登录测试
   - 密码重置和修改功能
   - 用户状态验证（active、inactive、locked等）

2. **AdminService** - 管理员服务测试
   - 管理员登录认证
   - 用户列表管理
   - 用户密码重置
   - 日志管理功能

3. **VerificationService** - 验证码服务测试
   - 验证码生成和验证
   - 频率限制机制
   - Redis存储操作
   - 错误处理和边界条件

4. **EmailService** - 邮件服务测试
   - 邮件发送功能（测试模式和生产模式）
   - 验证码邮件模板
   - 连接验证和错误处理
   - SMTP配置测试

5. **UsersService** - 用户数据服务测试
   - 用户CRUD操作
   - 用户查询功能
   - 数据验证和约束

6. **AdminCoreService** - 管理员核心服务测试
   - 管理员认证逻辑
   - 权限验证
   - 管理员引导创建

7. **LoggerService** - 日志服务测试
   - 日志记录功能
   - 敏感信息过滤
   - 日志级别控制

### E2E端到端测试

**登录功能完整流程测试：**
- 用户注册 → 邮箱验证 → 登录验证
- GitHub OAuth登录流程
- 密码重置完整流程
- 错误处理和边界条件测试

## 🔧 测试模式特性

- 🗄️ **Redis 文件存储** - 使用 `redis-data/redis.json` 存储验证码
- 📧 **邮件测试模式** - 邮件内容输出到控制台，无需真实SMTP
- 💾 **内存用户存储** - 无需数据库，用户数据存储在内存中
- 🔄 **自动切换** - 根据配置自动选择存储模式

## 📊 单元测试

### 运行测试命令

```bash
# 运行所有单元测试
npm test

# 监听模式（开发时使用）
npm run test:watch

# 生成覆盖率报告
npm run test:cov

# 运行特定测试文件
npm test -- src/core/login_core/login_core.service.spec.ts
```

### 测试覆盖情况

**测试统计：**
- 测试套件：7个
- 测试用例：140个
- 覆盖率：100%通过

**测试文件列表：**
```
src/core/login_core/login_core.service.spec.ts          # 登录核心服务
src/business/admin/admin.service.spec.ts                # 管理员服务
src/core/utils/verification/verification.service.spec.ts # 验证码服务
src/core/utils/email/email.service.spec.ts             # 邮件服务
src/core/db/users/users.service.spec.ts                # 用户数据服务
src/core/admin_core/admin_core.service.spec.ts         # 管理员核心服务
src/core/utils/logger/logger.service.spec.ts           # 日志服务
test/business/login.e2e-spec.ts                        # E2E端到端测试
```

### 测试场景覆盖

**正常流程测试：**
- 用户注册、登录、密码管理
- 邮箱验证码发送和验证
- 管理员认证和用户管理
- 系统状态和日志功能

**异常情况测试：**
- 无效输入和参数验证
- 网络连接失败处理
- 权限验证和访问控制
- 频率限制和安全防护

**边界条件测试：**
- 密码强度验证
- 验证码过期处理
- 用户状态变更
- 数据库连接异常

## 🌐 生产环境配置

要切换到生产环境，编辑 `.env` 文件：

```bash
# 启用数据库（取消注释并填入真实数据）
DB_HOST=your_mysql_host
DB_PORT=3306
DB_USERNAME=your_db_username
DB_PASSWORD=your_db_password
DB_NAME=your_db_name

# 启用真实Redis（取消注释并设置）
USE_FILE_REDIS=false
REDIS_HOST=your_redis_host
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# 启用邮件服务（取消注释并填入真实数据）
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>

# 生产环境设置
NODE_ENV=production
LOG_LEVEL=info
```

## 🔍 故障排除

### 服务启动失败
- **端口占用**：检查端口3000是否被占用，使用 `netstat -ano | findstr :3000` 查看
- **Node.js版本**：确认Node.js版本 >= 18.0.0，使用 `node --version` 检查
- **依赖问题**：运行 `npm install` 或 `pnpm install` 重新安装依赖
- **权限问题**：确保有足够的文件读写权限

### 测试脚本执行失败
- **服务器状态**：确认服务器正在运行，访问 http://localhost:3000 检查
- **网络连接**：检查防火墙设置，确保端口3000可访问
- **脚本权限**：在Linux/macOS上确保脚本有执行权限：`chmod +x test-api.sh`
- **PowerShell策略**：Windows上可能需要设置执行策略：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

### 单元测试失败
- **依赖冲突**：清理node_modules并重新安装：`rm -rf node_modules && npm install`
- **TypeScript错误**：运行 `npm run build` 检查编译错误
- **环境变量**：确保测试环境变量配置正确
- **数据库连接**：测试模式下应该使用内存数据库，检查配置

### Redis文件存储问题
- **目录权限**：检查 `redis-data` 目录的读写权限
- **配置设置**：确认 `USE_FILE_REDIS=true` 设置正确
- **文件锁定**：确保redis.json文件没有被其他进程锁定
- **磁盘空间**：检查磁盘空间是否充足

### 邮件测试模式问题
- **配置检查**：确认邮件配置为注释状态（测试模式）
- **控制台输出**：检查服务器控制台是否有邮件内容输出
- **日志级别**：确保日志级别设置为info或debug以查看详细输出

### 常见错误解决

**EADDRINUSE错误：**
```bash
# 查找占用端口的进程
netstat -ano | findstr :3000
# 结束进程（Windows）
taskkill /PID <进程ID> /F
```

**权限错误：**
```bash
# Linux/macOS设置权限
chmod +x test-api.sh
chmod 755 redis-data/
```

**模块未找到错误：**
```bash
# 清理并重新安装
rm -rf node_modules package-lock.json
npm install
```

## 📝 测试数据

测试完成后，你可以查看：

- `redis-data/redis.json` - 验证码存储数据
- 服务器控制台 - 邮件内容输出
- 测试脚本输出 - API响应结果

## 🎯 下一步

- 查看 [API 文档](http://localhost:3000/api-docs) 了解更多接口
- 阅读 [开发规范](./docs/backend_development_guide.md) 开始开发
- 使用 [AI 辅助指南](./docs/AI辅助开发规范指南.md) 提高开发效率