docs: 重构文档结构和组织
- 重新组织docs目录结构，按功能模块分类 - 新增deployment和development目录 - 更新API文档结构 - 添加客户端README文档 - 移除过时的文档文件
This commit is contained in:
moyin
101
README.md
101
README.md
@@ -1,23 +1,24 @@
|
||||
# 🐋 Whale Town - 像素游戏后端服务
|
||||
|
||||
> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，支持实时通信、用户认证、邮箱验证等完整功能。
|
||||
> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，采用业务功能模块化架构，支持用户认证、管理员后台、安全防护等完整功能。
|
||||
|
||||
[](https://nodejs.org/)
|
||||
[](https://nestjs.com/)
|
||||
[](https://nestjs.com/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](./LICENSE)
|
||||
|
||||
## 🎯 项目简介
|
||||
|
||||
Whale Town 是一个功能完整的像素游戏后端服务，提供：
|
||||
Whale Town 是一个功能完整的像素游戏后端服务，采用业务功能模块化架构设计：
|
||||
|
||||
- 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
|
||||
- 🎛️ **管理员后台系统** - React + Ant Design，用户管理、日志监控、权限控制
|
||||
- 🔐 **用户认证模块** - 完整的登录、注册、密码管理、邮箱验证系统
|
||||
- 👥 **用户管理模块** - 用户状态管理、批量操作、状态统计功能
|
||||
- 🛡️ **管理员模块** - 管理员认证、用户管理、密码重置、日志查看
|
||||
- 🔒 **安全模块** - 频率限制、维护模式、超时控制、内容类型检查
|
||||
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
|
||||
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
|
||||
- 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
|
||||
- 📚 **完整API文档** - Swagger UI + OpenAPI规范
|
||||
- 🧪 **全面测试覆盖** - 154个单元测试用例全部通过
|
||||
- 📚 **完整API文档** - Swagger UI + OpenAPI规范，17个接口完整覆盖
|
||||
- 🧪 **全面测试覆盖** - 140个单元测试用例全部通过
|
||||
|
||||
---
|
||||
|
||||
@@ -47,9 +48,9 @@ pnpm run dev
|
||||
|
||||
🎉 **服务启动成功！** 访问 http://localhost:3000
|
||||
|
||||
### 🧑💻 管理员后台系统
|
||||
### 🧑💻 前端管理界面
|
||||
|
||||
项目包含一个功能完整的管理员后台系统，基于 React + Ant Design 构建：
|
||||
项目包含一个功能完整的前端管理界面，位于 `client/` 目录：
|
||||
|
||||
**🎛️ 核心功能：**
|
||||
- 管理员身份认证（独立Token系统）
|
||||
@@ -58,23 +59,20 @@ pnpm run dev
|
||||
- 运行时日志查看与下载
|
||||
- 响应式界面设计
|
||||
|
||||
**📚 详细文档：** [docs/systems/admin-dashboard/README.md](docs/systems/admin-dashboard/README.md)
|
||||
|
||||
**🚀 快速启动：**
|
||||
|
||||
```bash
|
||||
# 1. 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 2. 启动后端服务
|
||||
# 1. 启动后端服务
|
||||
pnpm run dev
|
||||
|
||||
# 3. 启动前端管理界面
|
||||
pnpm -C client dev
|
||||
# 2. 启动前端管理界面
|
||||
cd client
|
||||
pnpm install
|
||||
pnpm run dev
|
||||
|
||||
# 4. 访问管理后台
|
||||
# 3. 访问管理后台
|
||||
# 地址: http://localhost:5173
|
||||
# 账号: admin / Admin123456
|
||||
# 默认账号: admin / Admin123456
|
||||
```
|
||||
|
||||
### 🧪 快速测试
|
||||
@@ -120,25 +118,22 @@ pnpm -C client dev
|
||||
```
|
||||
项目根目录/
|
||||
├── src/ # 源代码目录
|
||||
│ ├── api/ # API接口层（预留，用于游戏相关控制器）
|
||||
│ ├── business/ # 业务逻辑层
|
||||
│ │ └── login/ # 登录业务模块
|
||||
│ ├── core/ # 核心功能模块
|
||||
│ │ ├── db/ # 数据库层
|
||||
│ │ │ └── users/ # 用户数据模型（支持MySQL/内存双模式）
|
||||
│ ├── business/ # 业务功能模块（按功能组织）
|
||||
│ │ ├── auth/ # 🔐 用户认证模块
|
||||
│ │ ├── user-mgmt/ # 👥 用户管理模块
|
||||
│ │ ├── admin/ # 🛡️ 管理员模块
|
||||
│ │ ├── security/ # 🔒 安全模块
|
||||
│ │ └── shared/ # 🔗 共享组件
|
||||
│ ├── core/ # 核心技术服务
|
||||
│ │ ├── db/ # 数据库层（支持MySQL/内存双模式）
|
||||
│ │ ├── redis/ # Redis缓存服务（支持真实Redis/文件存储）
|
||||
│ │ ├── login_core/ # 登录核心服务
|
||||
│ │ └── utils/ # 工具服务
|
||||
│ │ ├── email/ # 邮件服务（支持SMTP/测试模式）
|
||||
│ │ ├── verification/ # 验证码服务
|
||||
│ │ └── logger/ # 日志系统
|
||||
│ ├── dto/ # 数据传输对象
|
||||
│ ├── types/ # TypeScript类型定义
|
||||
│ │ ├── admin_core/ # 管理员核心服务
|
||||
│ │ └── utils/ # 工具服务（邮件、验证码、日志）
|
||||
│ ├── app.module.ts # 应用主模块
|
||||
│ └── main.ts # 应用入口
|
||||
├── client/ # 前端管理界面
|
||||
├── docs/ # 项目文档
|
||||
│ ├── api/ # API文档
|
||||
│ └── systems/ # 系统设计文档
|
||||
├── test/ # 测试文件
|
||||
├── redis-data/ # Redis文件存储数据
|
||||
├── logs/ # 日志文件
|
||||
@@ -146,9 +141,9 @@ pnpm -C client dev
|
||||
```
|
||||
|
||||
**架构特点：**
|
||||
- 🏗️ **分层架构** - API层 → 业务层 → 核心层 → 数据层
|
||||
- 🏗️ **业务功能模块化** - 按业务功能而非技术组件组织代码
|
||||
- 🔄 **双模式支持** - 开发测试模式 + 生产部署模式
|
||||
- 📦 **模块化设计** - 每个功能独立模块，便于维护扩展
|
||||
- 📦 **清晰分层** - 业务层 → 核心层 → 数据层
|
||||
- 🧪 **测试友好** - 完整的单元测试和集成测试覆盖
|
||||
|
||||
### 第三步：体验核心功能 🎮
|
||||
@@ -244,19 +239,30 @@ pnpm -C client dev
|
||||
|
||||
## 🏗️ 核心功能
|
||||
|
||||
### 🔐 用户认证系统
|
||||
### 🔐 用户认证模块 (business/auth/)
|
||||
- **多方式登录** - 用户名/邮箱/手机号
|
||||
- **邮箱验证** - 完整的验证码流程
|
||||
- **密码安全** - bcrypt加密 + 强度验证
|
||||
- **第三方登录** - GitHub OAuth支持
|
||||
- **权限控制** - 基于角色的访问控制
|
||||
- **密码管理** - 忘记密码、重置密码、修改密码
|
||||
|
||||
### 🎛️ 管理员后台系统
|
||||
### 👥 用户管理模块 (business/user-mgmt/)
|
||||
- **用户状态管理** - 6种状态控制（active、inactive、locked、banned、deleted、pending）
|
||||
- **批量操作** - 批量修改用户状态
|
||||
- **状态统计** - 各状态用户数量统计
|
||||
- **状态变更日志** - 完整的审计日志
|
||||
|
||||
### 🛡️ 管理员模块 (business/admin/)
|
||||
- **独立认证** - 专用Token系统，与用户系统隔离
|
||||
- **用户管理** - 用户列表、搜索、密码重置
|
||||
- **日志监控** - 实时日志查看、历史日志下载
|
||||
- **权限控制** - 管理员角色验证（role=9）
|
||||
- **现代界面** - React + Ant Design响应式设计
|
||||
|
||||
### 🔒 安全模块 (business/security/)
|
||||
- **频率限制** - 基于IP的请求频率控制
|
||||
- **维护模式** - 系统维护期间的访问控制
|
||||
- **内容类型验证** - HTTP请求内容类型检查
|
||||
- **超时控制** - 可配置的请求超时机制
|
||||
|
||||
### 📧 智能邮件服务
|
||||
- **测试模式** - 控制台输出，无需SMTP服务器
|
||||
@@ -277,7 +283,7 @@ pnpm -C client dev
|
||||
- **实时更新** - 代码变更自动同步文档
|
||||
|
||||
### 🧪 全面测试覆盖
|
||||
- **单元测试** - 114个测试用例全部通过
|
||||
- **单元测试** - 140个测试用例全部通过
|
||||
- **API测试** - 跨平台测试脚本
|
||||
- **集成测试** - 完整业务流程验证
|
||||
- **测试模式** - 无依赖快速测试
|
||||
@@ -324,8 +330,8 @@ pnpm run test:cov
|
||||
|
||||
### 📈 测试覆盖率
|
||||
|
||||
- **单元测试**: 154个测试用例 ✅
|
||||
- **功能测试**: 用户认证、邮件验证、数据存储、管理员后台 ✅
|
||||
- **单元测试**: 140个测试用例 ✅
|
||||
- **功能测试**: 用户认证、用户管理、管理员后台、安全防护 ✅
|
||||
- **集成测试**: 完整业务流程 ✅
|
||||
|
||||
---
|
||||
@@ -379,12 +385,11 @@ EMAIL_PASS=your_app_password
|
||||
- **[Postman集合](./docs/api/postman-collection.json)** - 测试集合
|
||||
|
||||
### 🏗️ 系统设计
|
||||
- **[用户认证系统](./docs/systems/user-auth/README.md)** - 认证架构设计
|
||||
- **[邮件验证系统](./docs/systems/email-verification/README.md)** - 验证流程设计
|
||||
- **[日志系统](./docs/systems/logger/README.md)** - 日志架构设计
|
||||
- **[架构文档](./docs/ARCHITECTURE.md)** - 系统架构设计
|
||||
- **[部署指南](./docs/deployment/DEPLOYMENT.md)** - 生产环境部署
|
||||
|
||||
### 🧪 测试指南
|
||||
- **[测试指南](./TESTING.md)** - 完整测试说明
|
||||
- **[测试指南](./docs/development/TESTING.md)** - 完整测试说明
|
||||
- **[单元测试](./src/**/*.spec.ts)** - 测试用例参考
|
||||
|
||||
---
|
||||
@@ -398,7 +403,7 @@ EMAIL_PASS=your_app_password
|
||||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
||||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
||||
|
||||
查看完整贡献者名单：[CONTRIBUTORS.md](./CONTRIBUTORS.md)
|
||||
查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md)
|
||||
|
||||
### 🌟 如何贡献
|
||||
|
||||
|
||||
Reference in New Issue
Block a user