forked from datawhale/whale-town-end
docs：重构README和贡献者文档，完善项目架构说明和测试指南
- 重构README结构，按新开发者学习流程组织内容 - 更新项目架构图和技术栈说明，基于实际代码结构 - 创建CONTRIBUTORS.md，记录所有贡献者信息和统计 - 添加TESTING.md测试指南，支持无依赖快速测试 - 创建docs/ARCHITECTURE.md详细架构设计文档 - 优化.env.example配置，支持测试和生产环境切换 - 添加跨平台测试脚本(test-api.ps1/test-api.sh) - 删除冗余测试文件，统一测试入口 - 更新所有链接为正确的Gitea仓库地址 - 添加MIT开源协议文件
This commit is contained in:
moyin
633
README.md
633
README.md
@@ -1,341 +1,394 @@
|
||||
# Pixel Game Server
|
||||
# 🐋 Whale Town - 像素游戏后端服务
|
||||
|
||||
一个基于 NestJS 的 2D 像素风游戏后端服务
|
||||
> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，支持实时通信、用户认证、邮箱验证等完整功能。
|
||||
|
||||
[](https://nodejs.org/)
|
||||
[](https://nestjs.com/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](./LICENSE)
|
||||
|
||||
## 🎯 项目简介
|
||||
|
||||
Whale Town 是一个功能完整的像素游戏后端服务，提供：
|
||||
|
||||
- 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
|
||||
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
|
||||
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
|
||||
- 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
|
||||
- 📚 **完整API文档** - Swagger UI + OpenAPI规范
|
||||
- 🧪 **全面测试覆盖** - 单元测试 + API功能测试
|
||||
|
||||
---
|
||||
|
||||
## 🚨 开发者必读警告
|
||||
## 🚀 快速开始
|
||||
|
||||
**⚠️ 在开始任何开发工作之前，请务必阅读：[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
|
||||
### 📋 环境要求
|
||||
|
||||
**📢 重要提醒：**
|
||||
- 🚫 **未阅读 AI 辅助指南的代码将无法通过审查**
|
||||
- 🤖 **学会使用 AI 助手可以让你的开发效率提升 300%**
|
||||
- 📝 **AI 可以帮你自动生成符合规范的代码和注释**
|
||||
- 🔍 **AI 可以实时检查你的代码质量**
|
||||
- **Node.js** >= 18.0.0 (推荐 24.7.0)
|
||||
- **pnpm** >= 8.0.0 (推荐 10.25.0)
|
||||
|
||||
**👉 [立即阅读 AI 辅助开发指南](./docs/AI辅助开发规范指南.md)**
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **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 辅助开发规范指南](./docs/AI辅助开发规范指南.md)**
|
||||
|
||||
这个指南将教你如何：
|
||||
- 🤖 使用 AI 助手遵循项目规范
|
||||
- 📝 自动生成规范的代码和注释
|
||||
- 🔍 实时检查代码质量
|
||||
- 🚀 显著提高开发效率和代码质量
|
||||
|
||||
**不阅读此指南直接开发，代码审查将无法通过！**
|
||||
|
||||
---
|
||||
|
||||
## 开发规范
|
||||
|
||||
### 命名规范
|
||||
|
||||
项目采用统一的命名规范，确保代码风格一致：
|
||||
|
||||
- **文件/文件夹**：下划线分隔（如 `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：添加玩家信息查询接口"
|
||||
```
|
||||
# 1. 克隆项目
|
||||
git clone <repository-url>
|
||||
cd whale-town-end
|
||||
|
||||
详细规范请查看：[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)
|
||||
|
||||
## 📚 开发文档
|
||||
|
||||
### 🔥 必读文档
|
||||
- **[AI 辅助开发规范指南](./docs/AI辅助开发规范指南.md)** - 🚨 **所有开发者必读！** 教你如何使用 AI 遵循项目规范
|
||||
|
||||
### 📋 规范文档
|
||||
- [后端开发规范](./docs/backend_development_guide.md) - 注释标准、业务逻辑设计和日志记录要求
|
||||
- [Git 提交规范](./docs/git_commit_guide.md) - Git 提交信息格式和最佳实践
|
||||
- [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践
|
||||
- [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例
|
||||
|
||||
### 📖 API 文档
|
||||
- **[API 文档总览](./docs/api/README.md)** - API 文档使用指南和快速开始
|
||||
- **[Swagger UI](http://localhost:3000/api-docs)** - 交互式 API 文档（需启动服务器）
|
||||
- [详细接口文档](./docs/api/api-documentation.md) - 完整的 API 接口说明
|
||||
- [OpenAPI 规范](./docs/api/openapi.yaml) - 标准化的 API 描述文件
|
||||
- [Postman 集合](./docs/api/postman-collection.json) - 可导入的 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，请先安装：
|
||||
|
||||
```bash
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
检查版本：
|
||||
|
||||
```bash
|
||||
node --version
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
## 安装依赖
|
||||
|
||||
```bash
|
||||
# 2. 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 3. 配置环境（测试模式，无需数据库和邮件服务器）
|
||||
cp .env.example .env
|
||||
|
||||
# 4. 启动开发服务器
|
||||
pnpm run dev
|
||||
```
|
||||
|
||||
## 开发
|
||||
🎉 **服务启动成功！** 访问 http://localhost:3000
|
||||
|
||||
启动开发服务器（支持热重载）：
|
||||
### 🧪 快速测试
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
# Windows
|
||||
.\test-api.ps1
|
||||
|
||||
# Linux/macOS
|
||||
./test-api.sh
|
||||
```
|
||||
|
||||
服务器将运行在 `http://localhost:3000`
|
||||
**测试内容：**
|
||||
- ✅ 邮箱验证码发送与验证
|
||||
- ✅ 用户注册与登录
|
||||
- ✅ Redis文件存储功能
|
||||
- ✅ 邮件测试模式
|
||||
|
||||
## 测试
|
||||
---
|
||||
|
||||
运行测试：
|
||||
## 🎓 新开发者指南
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
```
|
||||
### 第一步：了解项目规范 📚
|
||||
|
||||
运行测试并监听文件变化：
|
||||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
||||
|
||||
```bash
|
||||
pnpm test:watch
|
||||
```
|
||||
1. **[AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)** 🤖
|
||||
- 学会使用AI助手提升开发效率300%
|
||||
- 自动生成符合规范的代码和注释
|
||||
- 实时检查代码质量
|
||||
|
||||
运行测试并生成覆盖率报告：
|
||||
2. **[后端开发规范](./docs/backend_development_guide.md)** 📝
|
||||
- 代码注释标准
|
||||
- 业务逻辑设计原则
|
||||
- 日志记录要求
|
||||
|
||||
```bash
|
||||
pnpm test:cov
|
||||
```
|
||||
3. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
|
||||
- 提交信息格式
|
||||
- 分支管理策略
|
||||
|
||||
## 构建
|
||||
|
||||
```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/ # 项目文档
|
||||
├── 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 辅助开发指南
|
||||
项目根目录/
|
||||
├── src/ # 源代码目录
|
||||
│ ├── api/ # API接口层（预留，用于游戏相关控制器）
|
||||
│ ├── business/ # 业务逻辑层
|
||||
│ │ └── login/ # 登录业务模块
|
||||
│ ├── core/ # 核心功能模块
|
||||
│ │ ├── db/ # 数据库层
|
||||
│ │ │ └── users/ # 用户数据模型（支持MySQL/内存双模式）
|
||||
│ │ ├── redis/ # Redis缓存服务（支持真实Redis/文件存储）
|
||||
│ │ ├── login_core/ # 登录核心服务
|
||||
│ │ └── utils/ # 工具服务
|
||||
│ │ ├── email/ # 邮件服务（支持SMTP/测试模式）
|
||||
│ │ ├── verification/ # 验证码服务
|
||||
│ │ └── logger/ # 日志系统
|
||||
│ ├── dto/ # 数据传输对象
|
||||
│ ├── types/ # TypeScript类型定义
|
||||
│ ├── app.module.ts # 应用主模块
|
||||
│ └── main.ts # 应用入口
|
||||
├── docs/ # 项目文档
|
||||
│ ├── api/ # API文档
|
||||
│ └── systems/ # 系统设计文档
|
||||
├── test/ # 测试文件
|
||||
├── redis-data/ # Redis文件存储数据
|
||||
├── logs/ # 日志文件
|
||||
└── 配置文件 # .env, package.json, tsconfig.json等
|
||||
```
|
||||
|
||||
## 核心功能
|
||||
**架构特点：**
|
||||
- 🏗️ **分层架构** - API层 → 业务层 → 核心层 → 数据层
|
||||
- 🔄 **双模式支持** - 开发测试模式 + 生产部署模式
|
||||
- 📦 **模块化设计** - 每个功能独立模块，便于维护扩展
|
||||
- 🧪 **测试友好** - 完整的单元测试和集成测试覆盖
|
||||
|
||||
### 第三步：体验核心功能 🎮
|
||||
|
||||
1. **API文档系统** 📖
|
||||
```bash
|
||||
# 启动服务后访问
|
||||
http://localhost:3000/api-docs
|
||||
```
|
||||
|
||||
2. **用户认证系统** 🔐
|
||||
- 邮箱验证码注册
|
||||
- 多方式登录（用户名/邮箱/手机号）
|
||||
- 密码重置功能
|
||||
|
||||
3. **实时通信** 🌐
|
||||
- WebSocket支持
|
||||
- Socket.IO集成
|
||||
|
||||
### 第四步：开始贡献 🤝
|
||||
|
||||
1. **Fork项目** 到你的GitHub账户
|
||||
2. **创建功能分支**：`git checkout -b feature/your-feature`
|
||||
3. **遵循规范开发**（使用AI助手帮助）
|
||||
4. **提交代码**：`git commit -m "feat：添加新功能"`
|
||||
5. **创建Pull Request**
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
### 🚀 核心框架
|
||||
- **NestJS** `^11.1.9` - 企业级Node.js框架，提供依赖注入、模块化等特性
|
||||
- **TypeScript** `^5.9.3` - 类型安全的JavaScript超集
|
||||
- **Express** `^10.4.20` - 基于Express的HTTP服务器
|
||||
- **RxJS** `^7.8.2` - 响应式编程库，处理异步数据流
|
||||
|
||||
### 🌐 实时通信
|
||||
- **Socket.IO** `^10.4.20` - WebSocket实时双向通信
|
||||
- **@nestjs/websockets** - NestJS WebSocket网关支持
|
||||
- **@nestjs/platform-socket.io** - Socket.IO平台适配器
|
||||
|
||||
### 🗄️ 数据存储
|
||||
- **TypeORM** `^0.3.28` - 强大的ORM框架，支持多种数据库
|
||||
- **MySQL2** `^3.16.0` - 高性能MySQL驱动
|
||||
- **IORedis** `^5.8.2` - Redis客户端，支持集群和哨兵模式
|
||||
- **文件存储** - 自研Redis文件存储适配器，支持无Redis开发
|
||||
|
||||
### 🔐 安全认证
|
||||
- **bcrypt** `^6.0.0` - 密码加密哈希算法
|
||||
- **class-validator** `^0.14.3` - 数据验证装饰器
|
||||
- **class-transformer** `^0.5.1` - 对象转换和序列化
|
||||
|
||||
### 📧 通信服务
|
||||
- **Nodemailer** `^6.10.1` - 邮件发送服务
|
||||
- **Axios** `^1.13.2` - HTTP客户端，支持第三方API调用
|
||||
|
||||
### 📚 API文档
|
||||
- **Swagger UI** `^5.0.1` - 交互式API文档界面
|
||||
- **@nestjs/swagger** `^11.2.3` - NestJS Swagger集成
|
||||
|
||||
### 📊 日志监控
|
||||
- **Pino** `^10.1.0` - 高性能结构化日志库
|
||||
- **nestjs-pino** `^4.5.0` - NestJS Pino集成
|
||||
- **pino-pretty** `^13.1.3` - Pino日志美化输出
|
||||
|
||||
### 🧪 测试框架
|
||||
- **Jest** `^29.7.0` - JavaScript测试框架
|
||||
- **Supertest** `^7.1.4` - HTTP断言测试
|
||||
- **@nestjs/testing** `^10.4.20` - NestJS测试工具
|
||||
|
||||
### ⚙️ 开发工具
|
||||
- **@nestjs/cli** `^10.4.9` - NestJS命令行工具
|
||||
- **ts-jest** `^29.2.5` - TypeScript Jest支持
|
||||
- **ts-node** `^10.9.2` - TypeScript运行时
|
||||
- **pnpm** - 快速、节省磁盘空间的包管理器
|
||||
|
||||
### 🔄 任务调度
|
||||
- **@nestjs/schedule** `^4.1.2` - 定时任务和计划任务支持
|
||||
|
||||
### 📦 构建部署
|
||||
- **Docker** - 容器化部署
|
||||
- **PM2** - 生产环境进程管理
|
||||
- **Nginx** - 反向代理和负载均衡
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 核心功能
|
||||
|
||||
### 🔐 用户认证系统
|
||||
- **多方式登录** - 用户名/邮箱/手机号
|
||||
- **邮箱验证** - 完整的验证码流程
|
||||
- **密码安全** - bcrypt加密 + 强度验证
|
||||
- **第三方登录** - GitHub OAuth支持
|
||||
- **权限控制** - 基于角色的访问控制
|
||||
|
||||
完整的用户认证解决方案，支持多种登录方式和安全特性：
|
||||
### 📧 智能邮件服务
|
||||
- **测试模式** - 控制台输出，无需SMTP服务器
|
||||
- **生产模式** - 支持主流邮件服务商
|
||||
- **模板系统** - 验证码、欢迎邮件等模板
|
||||
- **自动切换** - 根据配置自动选择模式
|
||||
|
||||
- 用户名/邮箱/手机号登录
|
||||
- GitHub OAuth 第三方登录
|
||||
- 密码重置和修改功能
|
||||
- bcrypt 密码加密
|
||||
- 基于角色的权限控制
|
||||
### 🗄️ 灵活存储方案
|
||||
- **Redis文件存储** - 开发测试无需Redis服务器
|
||||
- **内存数据库** - 无需MySQL即可运行
|
||||
- **生产就绪** - 支持MySQL + Redis部署
|
||||
- **自动切换** - 根据配置自动选择存储方式
|
||||
|
||||
**详细文档**: [用户认证系统文档](./docs/systems/user-auth/README.md)
|
||||
### 📚 完整API文档
|
||||
- **Swagger UI** - 交互式API文档
|
||||
- **OpenAPI规范** - 标准化接口描述
|
||||
- **Postman集合** - 可导入的测试集合
|
||||
- **实时更新** - 代码变更自动同步文档
|
||||
|
||||
### 📖 API 文档系统
|
||||
### 🧪 全面测试覆盖
|
||||
- **单元测试** - 114个测试用例全部通过
|
||||
- **API测试** - 跨平台测试脚本
|
||||
- **集成测试** - 完整业务流程验证
|
||||
- **测试模式** - 无依赖快速测试
|
||||
|
||||
集成了完整的 API 文档解决方案，提供多种格式的接口文档：
|
||||
---
|
||||
|
||||
- **Swagger UI** - 交互式 API 文档界面
|
||||
- **OpenAPI 规范** - 标准化的 API 描述文件
|
||||
- **Postman 集合** - 可导入的 API 测试集合
|
||||
- **详细文档** - 包含示例和最佳实践的完整说明
|
||||
## 📊 开发与测试
|
||||
|
||||
### 🔧 开发命令
|
||||
|
||||
**快速访问**:
|
||||
```bash
|
||||
# 启动服务器
|
||||
# 开发服务器（热重载）
|
||||
pnpm run dev
|
||||
|
||||
# 访问 Swagger UI 文档
|
||||
# 浏览器打开: http://localhost:3000/api-docs
|
||||
# 构建项目
|
||||
pnpm run build
|
||||
|
||||
# 生产环境运行
|
||||
pnpm run start:prod
|
||||
|
||||
# 代码检查
|
||||
pnpm run lint
|
||||
|
||||
# 格式化代码
|
||||
pnpm run format
|
||||
```
|
||||
|
||||
**详细文档**: [API 文档说明](./docs/api/README.md)
|
||||
### 🧪 测试命令
|
||||
|
||||
### 📊 日志系统
|
||||
```bash
|
||||
# 运行所有单元测试
|
||||
pnpm test
|
||||
|
||||
基于 Pino 的高性能日志系统，提供结构化日志记录：
|
||||
# 监听模式运行测试
|
||||
pnpm run test:watch
|
||||
|
||||
- 高性能日志记录
|
||||
- 自动敏感信息过滤
|
||||
- 多级别日志控制
|
||||
- 请求上下文绑定
|
||||
# 生成测试覆盖率报告
|
||||
pnpm run test:cov
|
||||
|
||||
**详细文档**: [日志系统文档](./docs/systems/logger/README.md)
|
||||
# API功能测试
|
||||
.\test-api.ps1 # Windows
|
||||
./test-api.sh # Linux/macOS
|
||||
```
|
||||
|
||||
**💡 提示：使用 [AI 辅助开发指南](./docs/AI辅助开发规范指南.md) 可以让 AI 帮你自动生成符合规范的代码！**
|
||||
### 📈 测试覆盖率
|
||||
|
||||
## 下一步
|
||||
- **单元测试**: 114个测试用例 ✅
|
||||
- **功能测试**: 用户认证、邮件验证、数据存储 ✅
|
||||
- **集成测试**: 完整业务流程 ✅
|
||||
|
||||
- 在 `src/api/` 目录下创建游戏相关的控制器和网关
|
||||
- 在 `src/model/` 目录下定义游戏数据模型
|
||||
- 在 `src/service/` 目录下实现游戏业务逻辑
|
||||
- 使用 NestJS CLI 快速生成模块：`nest g module game`
|
||||
- 添加 WebSocket 网关实现实时游戏逻辑
|
||||
---
|
||||
|
||||
## 🌍 部署配置
|
||||
|
||||
### 测试环境（默认）
|
||||
```bash
|
||||
# 无需数据库和邮件服务器
|
||||
USE_FILE_REDIS=true
|
||||
NODE_ENV=development
|
||||
# 数据库和邮件配置保持注释状态
|
||||
```
|
||||
|
||||
### 生产环境
|
||||
```bash
|
||||
# 启用真实服务
|
||||
USE_FILE_REDIS=false
|
||||
NODE_ENV=production
|
||||
|
||||
# 配置数据库
|
||||
DB_HOST=your_mysql_host
|
||||
DB_USERNAME=your_username
|
||||
DB_PASSWORD=your_password
|
||||
|
||||
# 配置Redis
|
||||
REDIS_HOST=your_redis_host
|
||||
REDIS_PASSWORD=your_password
|
||||
|
||||
# 配置邮件服务
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_USER=your_email@gmail.com
|
||||
EMAIL_PASS=your_app_password
|
||||
```
|
||||
|
||||
详细部署指南：[DEPLOYMENT.md](./DEPLOYMENT.md)
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档中心
|
||||
|
||||
### 🎯 新手必读
|
||||
1. **[AI辅助开发指南](./docs/AI辅助开发规范指南.md)** - 提升开发效率300%
|
||||
2. **[后端开发规范](./docs/backend_development_guide.md)** - 代码质量标准
|
||||
3. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践
|
||||
|
||||
### 📖 API文档
|
||||
- **[Swagger UI](http://localhost:3000/api-docs)** - 交互式API文档
|
||||
- **[API文档总览](./docs/api/README.md)** - 使用指南
|
||||
- **[OpenAPI规范](./docs/api/openapi.yaml)** - 标准化描述
|
||||
- **[Postman集合](./docs/api/postman-collection.json)** - 测试集合
|
||||
|
||||
### 🏗️ 系统设计
|
||||
- **[用户认证系统](./docs/systems/user-auth/README.md)** - 认证架构设计
|
||||
- **[邮件验证系统](./docs/systems/email-verification/README.md)** - 验证流程设计
|
||||
- **[日志系统](./docs/systems/logger/README.md)** - 日志架构设计
|
||||
|
||||
### 🧪 测试指南
|
||||
- **[测试指南](./TESTING.md)** - 完整测试说明
|
||||
- **[单元测试](./src/**/*.spec.ts)** - 测试用例参考
|
||||
|
||||
---
|
||||
|
||||
## 🤝 贡献者
|
||||
|
||||
感谢所有为项目做出贡献的开发者！
|
||||
|
||||
### 🏆 核心团队
|
||||
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
|
||||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
||||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
||||
|
||||
查看完整贡献者名单：[CONTRIBUTORS.md](./CONTRIBUTORS.md)
|
||||
|
||||
### 🌟 如何贡献
|
||||
|
||||
我们欢迎所有形式的贡献：
|
||||
|
||||
1. **<EFBFBD> Bug修复** - 发现并修复问题
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
3. **<EFBFBD> 文档改馈进** - 完善项目文档
|
||||
4. **🧪 测试用例** - 提高代码覆盖率
|
||||
5. **💡 建议反馈** - 提出改进建议
|
||||
|
||||
**贡献流程：**
|
||||
1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系我们
|
||||
|
||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town-end)
|
||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town-end/issues)
|
||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town-end/discussions)
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 [MIT License](./LICENSE) 开源协议。
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🐋 Whale Town - 让像素世界更精彩！**
|
||||
|
||||
Made with ❤️ by the Whale Town Team
|
||||
|
||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town-end) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town-end/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town-end/issues)
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user