# 🏗️ 项目架构设计

## 整体架构

Whale Town 采用分层架构设计，确保代码的可维护性和可扩展性。

```
┌─────────────────────────────────────────────────────────────┐
│                        API 层                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   HTTP API      │  │   WebSocket     │  │   GraphQL       │ │
│  │   (REST)        │  │   (Socket.IO)   │  │   (预留)        │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                      业务逻辑层                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   用户认证      │  │   游戏逻辑      │  │   社交功能      │ │
│  │   (Login)       │  │   (Game)        │  │   (Social)      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                      核心服务层                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   邮件服务      │  │   验证码服务    │  │   日志服务      │ │
│  │   (Email)       │  │   (Verification)│  │   (Logger)      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                                │
┌─────────────────────────────────────────────────────────────┐
│                      数据访问层                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   用户数据      │  │   Redis缓存     │  │   文件存储      │ │
│  │   (Users)       │  │   (Cache)       │  │   (Files)       │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

## 模块依赖关系

```
AppModule
├── ConfigModule (全局配置)
├── LoggerModule (日志系统)
├── RedisModule (缓存服务)
├── UsersModule (用户管理)
│   ├── UsersService (数据库模式)
│   └── UsersMemoryService (内存模式)
├── EmailModule (邮件服务)
├── VerificationModule (验证码服务)
├── LoginCoreModule (登录核心)
└── LoginModule (登录业务)
```

## 数据流向

### 用户注册流程
```
1. 用户请求 → LoginController
2. 参数验证 → LoginService
3. 发送验证码 → LoginCoreService
4. 生成验证码 → VerificationService
5. 发送邮件 → EmailService
6. 存储验证码 → RedisService
7. 返回响应 → 用户
```

### 双模式架构

项目支持开发测试模式和生产部署模式的无缝切换：

#### 开发测试模式
- **数据库**: 内存存储 (UsersMemoryService)
- **缓存**: 文件存储 (FileRedisService)
- **邮件**: 控制台输出 (测试模式)
- **优势**: 无需外部依赖，快速启动测试

#### 生产部署模式
- **数据库**: MySQL (UsersService + TypeORM)
- **缓存**: Redis (RealRedisService + IORedis)
- **邮件**: SMTP服务器 (生产模式)
- **优势**: 高性能，高可用，数据持久化

## 设计原则

### 1. 单一职责原则
每个模块只负责一个特定的功能领域：
- `LoginModule`: 只处理登录相关业务
- `EmailModule`: 只处理邮件发送
- `VerificationModule`: 只处理验证码逻辑

### 2. 依赖注入
使用NestJS的依赖注入系统：
- 接口抽象: `IRedisService`, `IUsersService`
- 实现切换: 根据配置自动选择实现类
- 测试友好: 易于Mock和单元测试

### 3. 配置驱动
通过环境变量控制行为：
- `USE_FILE_REDIS`: 选择Redis实现
- `DB_HOST`: 数据库连接配置
- `EMAIL_HOST`: 邮件服务配置

### 4. 错误处理
统一的错误处理机制：
- HTTP异常: `BadRequestException`, `UnauthorizedException`
- 业务异常: 自定义异常类
- 日志记录: 结构化错误日志

## 扩展指南

### 添加新的业务模块

1. **创建业务模块**
   ```bash
   nest g module business/game
   nest g controller business/game
   nest g service business/game
   ```

2. **创建核心服务**
   ```bash
   nest g module core/game_core
   nest g service core/game_core
   ```

3. **添加数据模型**
   ```bash
   nest g module core/db/games
   nest g service core/db/games
   ```

4. **更新主模块**
   在 `app.module.ts` 中导入新模块

### 添加新的工具服务

1. **创建工具模块**
   ```bash
   nest g module core/utils/notification
   nest g service core/utils/notification
   ```

2. **实现服务接口**
   定义抽象接口和具体实现

3. **添加配置支持**
   在环境变量中添加相关配置

4. **编写测试用例**
   确保功能正确性和代码覆盖率

## 性能优化

### 1. 缓存策略
- **Redis缓存**: 验证码、会话信息
- **内存缓存**: 配置信息、静态数据
- **CDN缓存**: 静态资源文件

### 2. 数据库优化
- **连接池**: 复用数据库连接
- **索引优化**: 关键字段建立索引
- **查询优化**: 避免N+1查询问题

### 3. 日志优化
- **异步日志**: 使用Pino的异步写入
- **日志分级**: 生产环境只记录必要日志
- **日志轮转**: 自动清理过期日志文件

## 安全考虑

### 1. 数据验证
- **输入验证**: class-validator装饰器
- **类型检查**: TypeScript静态类型
- **SQL注入**: TypeORM参数化查询

### 2. 认证授权
- **密码加密**: bcrypt哈希算法
- **会话管理**: Redis存储会话信息
- **权限控制**: 基于角色的访问控制

### 3. 通信安全
- **HTTPS**: 生产环境强制HTTPS
- **CORS**: 跨域请求控制
- **Rate Limiting**: API请求频率限制