# Pixel Game Server

一个基于 NestJS 的 2D 像素风游戏后端服务

## 技术栈

- **NestJS** `^10.4.20` - 渐进式 Node.js 框架
- **TypeScript** `^5.9.3` - 类型安全
- **Socket.IO** - WebSocket 实时通信支持
- **RxJS** `^7.8.2` - 响应式编程库
- **Pino** `^10.1.0` - 高性能日志库
- **Jest** `^29.7.0` - 测试框架

### 核心依赖

**生产环境：**
- `@nestjs/common` `^10.4.20` - NestJS 核心功能
- `@nestjs/core` `^10.4.20` - NestJS 核心模块
- `@nestjs/config` `^4.0.2` - 配置管理
- `@nestjs/platform-express` `^10.4.20` - Express 平台适配器
- `@nestjs/websockets` `^10.4.20` - WebSocket 支持
- `@nestjs/platform-socket.io` `^10.4.20` - Socket.IO 适配器
- `nestjs-pino` `^4.5.0` - Pino 日志集成
- `pino` `^10.1.0` - 高性能日志库
- `reflect-metadata` `^0.1.14` - 装饰器元数据支持
- `rxjs` `^7.8.2` - 响应式编程

**开发环境：**
- `@nestjs/cli` `^10.4.9` - NestJS 命令行工具
- `@nestjs/schematics` `^10.2.3` - NestJS 代码生成器
- `@nestjs/testing` `^10.4.20` - 测试工具
- `@types/jest` `^29.5.14` - Jest 类型定义
- `@types/node` `^20.19.26` - Node.js 类型定义
- `jest` `^29.7.0` - 测试框架
- `ts-jest` `^29.2.5` - TypeScript Jest 支持
- `ts-node` `^10.9.2` - TypeScript 运行时
- `typescript` `^5.9.3` - TypeScript 编译器
- `pino-pretty` `^13.1.3` - Pino 美化输出

## 开发规范

### 命名规范

项目采用统一的命名规范，确保代码风格一致：

- **文件/文件夹**：下划线分隔（如 `order_controller.ts`）
- **变量/函数**：小驼峰命名（如 `userName`、`async queryUserInfo()`）
- **类/构造函数**：大驼峰命名（如 `UserModel`、`OrderService`）
- **常量**：全大写 + 下划线（如 `PORT`、`DB_HOST`）
- **接口路由**：全小写 + 短横线（如 `/user/get-info`、`/order/create-order`）

详细规范请查看：[命名规范文档](./docs/naming_convention.md)

### Git 提交规范

项目采用约定式提交规范，提交信息格式：`<类型>：<简短描述>`

**常用提交类型：**

- `feat` - 新增功能
- `fix` - 修复 Bug
- `docs` - 文档更新
- `style` - 代码格式调整
- `refactor` - 代码重构
- `perf` - 性能优化
- `test` - 测试相关
- `chore` - 构建/工具变动

**后端特定类型：**

- `api` - API 接口
- `db` - 数据库
- `websocket` - WebSocket
- `auth` - 认证授权
- `dto` - 数据传输对象
- `service` - 服务层

**核心原则：**

- ⭐ 一次提交只做一件事
- 使用中文冒号 `：`
- 简短明确（不超过 50 字符）
- 能拆分就拆分，保持提交历史清晰

**示例：**

```bash
git commit -m "feat：实现玩家注册和登录功能"
git commit -m "fix：修复房间加入时的并发问题"
git commit -m "api：添加玩家信息查询接口"
```

详细规范请查看：[Git 提交规范文档](./docs/git_commit_guide.md)

### 后端开发规范

项目要求严格的代码质量和可维护性标准：

**核心要求：**

- **完整注释**：每个模块、类、方法都必须有详细注释
- **全面业务逻辑**：考虑所有可能情况，包括异常和边界条件
- **关键日志记录**：重要操作必须记录日志，便于问题排查
- **防御性编程**：对所有输入进行验证，实现健壮的错误处理

**注释要求：**

```typescript
/**
 * 玩家服务类
 * 
 * 职责：处理玩家相关的业务逻辑
 * 主要方法：createPlayer(), updatePlayerInfo(), getPlayerById()
 * 使用场景：玩家注册登录流程、个人陈列室数据管理
 */
@Injectable()
export class PlayerService {
  /**
   * 创建新玩家
   * @param email 玩家邮箱地址
   * @param nickname 玩家昵称
   * @returns Promise<Player> 创建成功的玩家对象
   * @throws BadRequestException 当邮箱格式错误时
   */
  async createPlayer(email: string, nickname: string): Promise<Player> {
    // 详细的业务逻辑实现...
  }
}
```

详细规范请查看：[后端开发规范指南](./docs/backend_development_guide.md)

## 文档

- [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例
- [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践
- [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践
- [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求

## 前置要求

- **Node.js** >= 18.0.0
- **pnpm** >= 8.0.0（推荐）

如果还没有安装 pnpm，请先安装：

```bash
npm install -g pnpm
```

检查版本：

```bash
node --version
pnpm --version
```

## 安装依赖

```bash
pnpm install
```

## 开发

启动开发服务器（支持热重载）：

```bash
pnpm dev
```

服务器将运行在 `http://localhost:3000`

## 测试

运行测试：

```bash
pnpm test
```

运行测试并监听文件变化：

```bash
pnpm test:watch
```

运行测试并生成覆盖率报告：

```bash
pnpm test:cov
```

## 构建

```bash
pnpm build
```

## 生产环境运行

```bash
pnpm start:prod
```

## 项目结构

```
src/
├── api/              # API 接口层（控制器、网关）
├── business/         # 业务逻辑层
├── core/             # 核心功能模块
│   ├── db/           # 数据库相关
│   └── utils/        # 工具函数
│       └── logger/   # 日志系统
├── main.ts           # 应用入口
├── app.module.ts     # 根模块
├── app.controller.ts # 根控制器
└── app.service.ts    # 根服务
test/
├── api/              # API 测试
└── service/          # 服务测试
docs/                 # 项目文档
├── backend_development_guide.md  # 后端开发规范
├── git_commit_guide.md          # Git 提交规范
├── naming_convention.md         # 命名规范
└── nestjs_guide.md             # NestJS 使用指南
```

## 核心功能

### 日志系统

项目集成了完整的日志系统，基于 Pino 高性能日志库：

**特性：**
- 🚀 高性能日志记录
- 🔒 自动敏感信息过滤
- 🎯 多级别日志控制
- 🔍 请求上下文绑定
- 📊 结构化日志输出

**使用示例：**

```typescript
import { AppLoggerService } from './core/utils/logger/logger.service';

@Injectable()
export class UserService {
  constructor(private readonly logger: AppLoggerService) {}

  async createUser(userData: CreateUserDto) {
    this.logger.info('开始创建用户', {
      operation: 'createUser',
      email: userData.email,
      timestamp: new Date().toISOString()
    });

    try {
      const user = await this.userRepository.save(userData);
      
      this.logger.info('用户创建成功', {
        operation: 'createUser',
        userId: user.id,
        email: userData.email
      });

      return user;
    } catch (error) {
      this.logger.error('用户创建失败', {
        operation: 'createUser',
        email: userData.email,
        error: error.message
      }, error.stack);
      
      throw error;
    }
  }
}
```

详细使用方法请参考：[后端开发规范指南 - 日志系统使用指南](./docs/backend_development_guide.md#四日志系统使用指南)

## 下一步

- 在 `src/api/` 目录下创建游戏相关的控制器和网关
- 在 `src/model/` 目录下定义游戏数据模型
- 在 `src/service/` 目录下实现游戏业务逻辑
- 使用 NestJS CLI 快速生成模块：`nest g module game`
- 添加 WebSocket 网关实现实时游戏逻辑