whale-town-end/docs/ARCHITECTURE.md

# 🏗️ Whale Town 项目架构设计

> 基于四层架构（Gateway-Business-Core-Data）的现代化后端设计，支持双模式运行，开发测试零依赖，生产部署高性能。

## 📋 目录

- [架构概述](#架构概述)
- [四层架构设计](#四层架构设计)
- [目录结构](#目录结构)
- [双模式架构](#双模式架构)
- [模块依赖关系](#模块依赖关系)
- [数据流向](#数据流向)
- [扩展指南](#扩展指南)

---

## 架构概述

Whale Town 采用**四层架构设计**（Gateway-Business-Core-Data），将协议处理、业务逻辑、技术基础设施和数据存储清晰分离。

### 核心设计理念

- **职责分离** - 每层职责明确，互不干扰
- **双模式支持** - 开发测试零依赖，生产部署高性能
- **依赖单向** - 上层依赖下层，下层不依赖上层
- **模块化设计** - 每个模块独立完整，可单独测试
- **配置驱动** - 通过环境变量控制运行模式

### 技术栈

**后端：** NestJS 11 + TypeScript 5 + MySQL + Redis + 原生WebSocket  
**前端：** React 18 + Vite 7 + Ant Design 5  
**测试：** Jest + Supertest（99个测试用例）  
**部署：** Docker + PM2 + Nginx

---

## 四层架构设计

### 架构层次图

```
┌─────────────────────────────────────────────────────────────┐
│                  🌐 Gateway Layer (网关层)                   │
│  HTTP/WebSocket协议处理、数据验证、路由管理、认证守卫       │
└─────────────────────────────────────────────────────────────┘
                            ⬇️
┌─────────────────────────────────────────────────────────────┐
│                  🎯 Business Layer (业务层)                  │
│  业务逻辑实现、服务协调、业务规则验证、事务管理             │
└─────────────────────────────────────────────────────────────┘
                            ⬇️
┌─────────────────────────────────────────────────────────────┐
│                  ⚙️ Core Layer (核心层)                     │
│  技术基础设施、数据访问、外部系统集成、工具服务             │
└─────────────────────────────────────────────────────────────┘
                            ⬇️
┌─────────────────────────────────────────────────────────────┐
│                  🗄️ Data Layer (数据层)                    │
│  数据持久化、缓存管理、文件存储                             │
└─────────────────────────────────────────────────────────────┘
```

### 各层职责

#### 🌐 Gateway Layer（网关层）

**位置：** `src/gateway/`

**职责：**
- HTTP/WebSocket协议处理
- 请求参数验证（DTO）
- 路由管理
- 认证守卫（JWT验证）
- 错误转换（业务错误 → HTTP状态码）
- API文档（Swagger）

**原则：**
- ✅ 只做协议转换，不做业务逻辑
- ✅ 使用DTO进行数据验证
- ✅ 统一的错误处理
- ❌ 不直接访问数据库
- ❌ 不包含业务规则

**示例模块：**
- `gateway/auth/` - 认证网关（登录、注册接口）
- `gateway/location_broadcast/` - 位置广播网关（WebSocket）

#### 🎯 Business Layer（业务层）

**位置：** `src/business/`

**职责：**
- 业务逻辑实现
- 业务流程控制
- 服务协调
- 业务规则验证
- 事务管理

**原则：**
- ✅ 实现所有业务逻辑
- ✅ 协调多个Core层服务
- ✅ 返回统一的业务响应
- ❌ 不处理HTTP协议
- ❌ 不直接访问数据库

**示例模块：**
- `business/auth/` - 用户认证业务
- `business/user_mgmt/` - 用户管理业务
- `business/admin/` - 管理员业务
- `business/zulip/` - Zulip集成业务
- `business/location_broadcast/` - 位置广播业务
- `business/notice/` - 公告业务

#### ⚙️ Core Layer（核心层）

**位置：** `src/core/`

**职责：**
- 数据访问（数据库、缓存）
- 基础设施（Redis、消息队列）
- 外部系统集成（Zulip API）
- 技术实现细节
- 工具服务（邮件、验证码、日志）

**原则：**
- ✅ 提供技术基础设施
- ✅ 数据持久化和缓存
- ✅ 外部API集成
- ❌ 不包含业务逻辑
- ❌ 不处理HTTP协议

**示例模块：**
- `core/db/users/` - 用户数据服务
- `core/redis/` - Redis缓存服务
- `core/login_core/` - 登录核心服务
- `core/admin_core/` - 管理员核心服务
- `core/zulip_core/` - Zulip核心服务
- `core/security_core/` - 安全核心服务
- `core/utils/` - 工具服务（邮件、验证码、日志）

#### <20>️ Data Layer（数据层）

**位置：** 数据库、Redis、文件系统

**职责：**
- 数据持久化
- 缓存管理
- 文件存储

**实现：**
- MySQL / 内存数据库
- Redis / 文件存储
- 日志文件 / 数据文件

---

## 目录结构

### 整体结构

```
whale-town-end/
├── src/
│   ├── gateway/          # 🌐 网关层
│   │   ├── auth/         # 认证网关
│   │   └── location_broadcast/  # 位置广播网关
│   ├── business/         # 🎯 业务层
│   │   ├── auth/         # 用户认证业务
│   │   ├── user_mgmt/    # 用户管理业务
│   │   ├── admin/        # 管理员业务
│   │   ├── zulip/        # Zulip集成业务
│   │   ├── location_broadcast/  # 位置广播业务
│   │   └── notice/       # 公告业务
│   ├── core/             # ⚙️ 核心层
│   │   ├── db/users/     # 用户数据服务
│   │   ├── redis/        # Redis缓存服务
│   │   ├── login_core/   # 登录核心服务
│   │   ├── admin_core/   # 管理员核心服务
│   │   ├── zulip_core/   # Zulip核心服务
│   │   ├── security_core/  # 安全核心服务
│   │   └── utils/        # 工具服务
│   ├── app.module.ts     # 应用主模块
│   └── main.ts           # 应用入口
├── client/               # 🎨 前端管理界面
├── docs/                 # 📚 项目文档
├── test/                 # 🧪 测试文件
└── config/               # ⚙️ 配置文件
```

### 网关层结构

```
src/gateway/
├── auth/                 # 认证网关
│   ├── login.controller.ts
│   ├── register.controller.ts
│   ├── jwt_auth.guard.ts
│   ├── current_user.decorator.ts
│   ├── dto/
│   └── auth.gateway.module.ts
└── location_broadcast/   # 位置广播网关
    ├── location_broadcast.gateway.ts
    └── location_broadcast.gateway.module.ts
```

### 业务层结构

```
src/business/
├── auth/                 # 用户认证业务
│   ├── login.service.ts
│   ├── register.service.ts
│   └── auth.module.ts
├── user_mgmt/            # 用户管理业务
│   ├── user_management.service.ts
│   ├── dto/
│   ├── enums/
│   └── user_mgmt.module.ts
├── admin/                # 管理员业务
│   ├── admin.service.ts
│   └── admin.module.ts
├── zulip/                # Zulip集成业务
│   ├── zulip.service.ts
│   ├── services/
│   └── zulip.module.ts
├── location_broadcast/   # 位置广播业务
│   ├── location_broadcast.service.ts
│   └── location_broadcast.module.ts
└── notice/               # 公告业务
    ├── notice.service.ts
    └── notice.module.ts
```

### 核心层结构

```
src/core/
├── db/users/             # 用户数据服务
│   ├── users.service.ts  # MySQL实现
│   ├── users_memory.service.ts  # 内存实现
│   ├── users.entity.ts
│   └── users.module.ts
├── redis/                # Redis缓存服务
│   ├── real_redis.service.ts
│   ├── file_redis.service.ts
│   └── redis.module.ts
├── login_core/           # 登录核心服务
│   ├── login_core.service.ts
│   └── login_core.module.ts
├── admin_core/           # 管理员核心服务
│   ├── admin_core.service.ts
│   └── admin_core.module.ts
├── zulip_core/           # Zulip核心服务
│   ├── services/
│   ├── config/
│   └── zulip_core.module.ts
├── security_core/        # 安全核心服务
│   ├── guards/
│   ├── interceptors/
│   ├── middleware/
│   └── security_core.module.ts
└── utils/                # 工具服务
    ├── email/
    ├── verification/
    └── logger/
```

---

## 双模式架构

### 模式对比

| 功能 | 开发模式 | 生产模式 |
|------|---------|---------|
| 数据库 | 内存存储 | MySQL |
| 缓存 | 文件存储 | Redis |
| 邮件 | 控制台输出 | SMTP服务器 |
| 日志 | 控制台+文件 | 结构化日志 |

### 配置示例

**开发模式：**
```bash
USE_FILE_REDIS=true
NODE_ENV=development
# 无需配置数据库和邮件
```

**生产模式：**
```bash
USE_FILE_REDIS=false
NODE_ENV=production
DB_HOST=your_mysql_host
REDIS_HOST=your_redis_host
EMAIL_HOST=smtp.163.com
```

### 实现机制

通过依赖注入和工厂模式实现自动切换：

```typescript
@Module({
  providers: [
    {
      provide: 'IRedisService',
      useFactory: (config: ConfigService) => {
        return config.get('USE_FILE_REDIS')
          ? new FileRedisService()
          : new RealRedisService(config);
      },
      inject: [ConfigService],
    },
  ],
})
export class RedisModule {}
```

---

## 模块依赖关系

### 依赖方向

```
Gateway Layer
    ↓ 依赖
Business Layer
    ↓ 依赖
Core Layer
    ↓ 依赖
Data Layer
```

### 模块依赖图

```
AppModule
├── ConfigModule (全局配置)
├── LoggerModule (日志系统)
├── RedisModule (缓存服务)
├── UsersModule (用户数据)
├── EmailModule (邮件服务)
├── VerificationModule (验证码服务)
├── LoginCoreModule (登录核心)
├── AdminCoreModule (管理员核心)
├── ZulipCoreModule (Zulip核心)
├── SecurityCoreModule (安全核心)
│
├── Gateway Layer
│   ├── AuthGatewayModule
│   └── LocationBroadcastGatewayModule
│
└── Business Layer
    ├── AuthModule
    ├── UserMgmtModule
    ├── AdminModule
    ├── ZulipModule
    ├── LocationBroadcastModule
    └── NoticeModule
```

---

## 数据流向

### 用户登录流程

```
1. 用户请求 → LoginController (Gateway)
2. 参数验证 → DTO Validation
3. 业务逻辑 → LoginService (Business)
4. 核心服务 → LoginCoreService (Core)
5. 数据访问 → UsersService + RedisService (Core)
6. 数据存储 → MySQL/Memory + Redis/File (Data)
7. 返回响应 → 用户收到结果
```

### WebSocket消息流程

```
1. WebSocket连接 → LocationBroadcastGateway (Gateway)
2. 消息验证 → JWT验证
3. 业务处理 → LocationBroadcastService (Business)
4. 房间管理 → 地图分组逻辑
5. 消息广播 → 同地图用户
6. Zulip同步 → ZulipService (Business)
```

### 管理员操作流程

```
1. 管理员请求 → AdminController (Gateway)
2. 权限验证 → AdminGuard
3. 业务逻辑 → AdminService (Business)
4. 核心服务 → AdminCoreService (Core)
5. 数据更新 → UsersService (Core)
6. 审计日志 → LoggerService (Core)
7. 返回响应 → 管理员收到结果
```

---

## 扩展指南

### 添加新的业务模块

1. **创建目录结构**
```bash
mkdir -p src/gateway/game
mkdir -p src/business/game
mkdir -p src/core/game_core
```

2. **实现网关层**
```typescript
// src/gateway/game/game.controller.ts
@Controller('game')
export class GameController {
  constructor(private readonly gameService: GameService) {}
  
  @Post()
  async createGame(@Body() dto: CreateGameDto) {
    return this.gameService.create(dto);
  }
}
```

3. **实现业务层**
```typescript
// src/business/game/game.service.ts
@Injectable()
export class GameService {
  constructor(
    @Inject('IGameCoreService')
    private readonly gameCoreService: IGameCoreService,
  ) {}
  
  async create(dto: CreateGameDto) {
    // 业务逻辑
    return this.gameCoreService.createGame(dto);
  }
}
```

4. **实现核心层**
```typescript
// src/core/game_core/game_core.service.ts
@Injectable()
export class GameCoreService {
  async createGame(dto: CreateGameDto) {
    // 数据访问逻辑
  }
}
```

5. **注册模块**
```typescript
// src/app.module.ts
@Module({
  imports: [
    // ...
    GameGatewayModule,
    GameModule,
    GameCoreModule,
  ],
})
export class AppModule {}
```

### 性能优化建议

1. **缓存策略**
   - 用户会话 → Redis
   - 验证码 → Redis（短期）
   - 配置信息 → 内存缓存

2. **数据库优化**
   - 添加索引
   - 使用连接池
   - 避免N+1查询

3. **日志优化**
   - 异步写入
   - 日志分级
   - 日志轮转

### 安全加固建议

1. **数据验证**
   - 使用class-validator
   - TypeScript类型检查
   - SQL注入防护

2. **认证授权**
   - JWT认证
   - 角色权限控制
   - 会话管理

3. **通信安全**
   - HTTPS强制
   - CORS配置
   - 频率限制

---

## 参考文档

- [架构重构文档](./ARCHITECTURE_REFACTORING.md) - 四层架构迁移指南
- [网关层README](../src/gateway/auth/README.md) - 网关层详细说明
- [开发规范](./development/backend_development_guide.md) - 代码规范
- [部署指南](./deployment/DEPLOYMENT.md) - 生产环境部署

---

**🏗️ 通过清晰的四层架构设计，Whale Town 实现了职责分离、高内聚、低耦合的现代化架构！**