Pixel Game Server

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

---

🚨 开发者必读警告

⚠️ 在开始任何开发工作之前，请务必阅读：AI 辅助开发规范指南

📢 重要提醒：

• 🚫 未阅读 AI 辅助指南的代码将无法通过审查
• 🤖 学会使用 AI 助手可以让你的开发效率提升 300%
• 📝 AI 可以帮你自动生成符合规范的代码和注释
• 🔍 AI 可以实时检查你的代码质量

👉 立即阅读 AI 辅助开发指南

---

技术栈

• 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 美化输出

🚨 重要：开发前必读

⚠️ 所有开发者必须先阅读 AI 辅助开发指南

在开始任何开发工作之前，请务必阅读：AI 辅助开发规范指南

这个指南将教你如何：

• 🤖 使用 AI 助手遵循项目规范
• 📝 自动生成规范的代码和注释
• 🔍 实时检查代码质量
• 🚀 显著提高开发效率和代码质量

不阅读此指南直接开发，代码审查将无法通过！

---

开发规范

命名规范

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

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

详细规范请查看：命名规范文档

Git 提交规范

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

常用提交类型：

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

后端特定类型：

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

核心原则：

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

示例：

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

详细规范请查看：Git 提交规范文档

后端开发规范

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

核心要求：

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

注释要求：

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

详细规范请查看：后端开发规范指南

📚 开发文档

🔥 必读文档

• AI 辅助开发规范指南 - 🚨 所有开发者必读！ 教你如何使用 AI 遵循项目规范

📋 规范文档

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

📖 API 文档

• API 文档总览 - API 文档使用指南和快速开始
• Swagger UI - 交互式 API 文档（需启动服务器）
• 详细接口文档 - 完整的 API 接口说明
• OpenAPI 规范 - 标准化的 API 描述文件
• Postman 集合 - 可导入的 API 测试集合

💡 使用建议

1. 开发前：先读 AI 辅助指南，了解如何用 AI 帮助遵循规范
2. 开发中：参考具体规范文档，使用 AI 实时检查代码质量
3. API 开发：使用 Swagger UI 进行接口测试，参考 API 文档进行开发
4. 提交前：用 AI 检查代码和提交信息是否符合规范

前置要求

• Node.js >= 18.0.0 默认：24.7.0
• pnpm >= 8.0.0（推荐）默认：10.25.0

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

npm install -g pnpm

检查版本：

node --version
pnpm --version

安装依赖

pnpm install

开发

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

pnpm dev

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

测试

运行测试：

pnpm test

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

pnpm test:watch

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

pnpm test:cov

构建

pnpm build

生产环境运行

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/                 # 项目文档
├── api/                         # API 接口文档
│   ├── README.md               # API 文档使用指南
│   ├── api-documentation.md    # 详细接口文档
│   ├── openapi.yaml           # OpenAPI 规范文件
│   └── postman-collection.json # Postman 测试集合
├── systems/                     # 系统设计文档
│   ├── logger/                 # 日志系统文档
│   └── user-auth/             # 用户认证系统文档
├── backend_development_guide.md  # 后端开发规范
├── git_commit_guide.md          # Git 提交规范
├── naming_convention.md         # 命名规范
├── nestjs_guide.md             # NestJS 使用指南
└── AI辅助开发规范指南.md        # AI 辅助开发指南

核心功能

🔐 用户认证系统

完整的用户认证解决方案，支持多种登录方式和安全特性：

• 用户名/邮箱/手机号登录
• GitHub OAuth 第三方登录
• 密码重置和修改功能
• bcrypt 密码加密
• 基于角色的权限控制

详细文档: 用户认证系统文档

📖 API 文档系统

集成了完整的 API 文档解决方案，提供多种格式的接口文档：

• Swagger UI - 交互式 API 文档界面
• OpenAPI 规范 - 标准化的 API 描述文件
• Postman 集合 - 可导入的 API 测试集合
• 详细文档 - 包含示例和最佳实践的完整说明

快速访问:

# 启动服务器
pnpm run dev

# 访问 Swagger UI 文档
# 浏览器打开: http://localhost:3000/api-docs

详细文档: API 文档说明

📊 日志系统

基于 Pino 的高性能日志系统，提供结构化日志记录：

• 高性能日志记录
• 自动敏感信息过滤
• 多级别日志控制
• 请求上下文绑定

详细文档: 日志系统文档

💡 提示：使用 AI 辅助开发指南 可以让 AI 帮你自动生成符合规范的代码！

下一步

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