docs：优化项目文档结构和架构说明
- 优化主README.md的文件结构总览，采用总分结构设计 - 大幅改进docs/ARCHITECTURE.md，详细说明业务功能模块化架构 - 新增docs/DOCUMENT_CLEANUP.md记录文档清理过程 - 更新docs/README.md添加新文档的导航链接 本次更新完善了项目文档体系，便于开发者快速理解项目架构
This commit is contained in:
moyin
63
README.md
63
README.md
@@ -124,29 +124,48 @@ pnpm run dev
|
|||||||
|
|
||||||
### 第二步：熟悉项目架构 🏗️
|
### 第二步：熟悉项目架构 🏗️
|
||||||
|
|
||||||
|
**📁 项目文件结构总览**
|
||||||
|
|
||||||
```
|
```
|
||||||
项目根目录/
|
whale-town-end/ # 🐋 项目根目录
|
||||||
├── src/ # 源代码目录
|
├── 📂 src/ # 源代码目录
|
||||||
│ ├── business/ # 业务功能模块（按功能组织）
|
│ ├── 📂 business/ # 🎯 业务功能模块（按功能组织）
|
||||||
│ │ ├── auth/ # 🔐 用户认证模块
|
│ │ ├── 📂 auth/ # 🔐 用户认证模块
|
||||||
│ │ ├── user-mgmt/ # 👥 用户管理模块
|
│ │ ├── 📂 user-mgmt/ # 👥 用户管理模块
|
||||||
│ │ ├── admin/ # 🛡️ 管理员模块
|
│ │ ├── 📂 admin/ # 🛡️ 管理员模块
|
||||||
│ │ ├── security/ # 🔒 安全模块
|
│ │ ├── 📂 security/ # 🔒 安全防护模块
|
||||||
│ │ └── shared/ # 🔗 共享组件
|
│ │ ├── 📂 zulip/ # 💬 Zulip集成模块
|
||||||
│ ├── core/ # 核心技术服务
|
│ │ └── 📂 shared/ # 🔗 共享业务组件
|
||||||
│ │ ├── db/ # 数据库层（支持MySQL/内存双模式）
|
│ ├── 📂 core/ # ⚙️ 核心技术服务
|
||||||
│ │ ├── redis/ # Redis缓存服务（支持真实Redis/文件存储）
|
│ │ ├── 📂 db/ # 🗄️ 数据库层（MySQL/内存双模式）
|
||||||
│ │ ├── login_core/ # 登录核心服务
|
│ │ ├── 📂 redis/ # 🔴 Redis缓存（真实Redis/文件存储）
|
||||||
│ │ ├── admin_core/ # 管理员核心服务
|
│ │ ├── 📂 login_core/ # 🔑 登录核心服务
|
||||||
│ │ └── utils/ # 工具服务（邮件、验证码、日志）
|
│ │ ├── 📂 admin_core/ # 👑 管理员核心服务
|
||||||
│ ├── app.module.ts # 应用主模块
|
│ │ ├── 📂 zulip/ # 💬 Zulip核心服务
|
||||||
│ └── main.ts # 应用入口
|
│ │ └── 📂 utils/ # 🛠️ 工具服务（邮件、验证码、日志）
|
||||||
├── client/ # 前端管理界面
|
│ ├── 📄 app.module.ts # 🏠 应用主模块
|
||||||
├── docs/ # 项目文档
|
│ └── 📄 main.ts # 🚀 应用入口点
|
||||||
├── test/ # 测试文件
|
├── 📂 client/ # 🎨 前端管理界面
|
||||||
├── redis-data/ # Redis文件存储数据
|
│ ├── 📂 src/ # 前端源码
|
||||||
├── logs/ # 日志文件
|
│ ├── 📂 dist/ # 前端构建产物
|
||||||
└── 配置文件 # .env, package.json, tsconfig.json等
|
│ ├── 📄 package.json # 前端依赖配置
|
||||||
|
│ └── 📄 vite.config.ts # Vite构建配置
|
||||||
|
├── 📂 docs/ # 📚 项目文档中心
|
||||||
|
│ ├── 📂 api/ # 🔌 API接口文档
|
||||||
|
│ ├── 📂 development/ # 💻 开发指南
|
||||||
|
│ ├── 📂 deployment/ # 🚀 部署文档
|
||||||
|
│ ├── 📄 ARCHITECTURE.md # 🏗️ 架构设计文档
|
||||||
|
│ └── 📄 README.md # 📖 文档导航中心
|
||||||
|
├── 📂 test/ # 🧪 测试文件目录
|
||||||
|
├── 📂 config/ # ⚙️ 配置文件目录
|
||||||
|
├── 📂 logs/ # 📝 日志文件存储
|
||||||
|
├── 📂 redis-data/ # 💾 Redis文件存储数据
|
||||||
|
├── 📂 dist/ # 📦 后端构建产物
|
||||||
|
├── 📄 .env # 🔧 环境变量配置
|
||||||
|
├── 📄 package.json # 📋 项目依赖配置
|
||||||
|
├── 📄 docker-compose.yml # 🐳 Docker编排配置
|
||||||
|
├── 📄 Dockerfile # 🐳 Docker镜像配置
|
||||||
|
└── 📄 README.md # 📖 项目主文档（当前文件）
|
||||||
```
|
```
|
||||||
|
|
||||||
**架构特点：**
|
**架构特点：**
|
||||||
|
|||||||
@@ -1,187 +1,747 @@
|
|||||||
# 🏗️ 项目架构设计
|
# 🏗️ Whale Town 项目架构设计
|
||||||
|
|
||||||
## 整体架构
|
> 基于业务功能模块化的现代化后端架构，支持双模式运行，开发测试零依赖，生产部署高性能。
|
||||||
|
|
||||||
Whale Town 采用分层架构设计，确保代码的可维护性和可扩展性。
|
## 📋 目录
|
||||||
|
|
||||||
|
- [🎯 架构概述](#-架构概述)
|
||||||
|
- [📁 目录结构详解](#-目录结构详解)
|
||||||
|
- [🏗️ 分层架构设计](#️-分层架构设计)
|
||||||
|
- [🔄 双模式架构](#-双模式架构)
|
||||||
|
- [📦 模块依赖关系](#-模块依赖关系)
|
||||||
|
- [🚀 扩展指南](#-扩展指南)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 架构概述
|
||||||
|
|
||||||
|
Whale Town 采用**业务功能模块化架构**，将代码按业务功能而非技术组件组织，确保高内聚、低耦合的设计原则。
|
||||||
|
|
||||||
|
### 🌟 核心设计理念
|
||||||
|
|
||||||
|
- **业务驱动** - 按业务功能组织代码，而非技术分层
|
||||||
|
- **双模式支持** - 开发测试零依赖，生产部署高性能
|
||||||
|
- **清晰分层** - 业务层 → 核心层 → 数据层，职责明确
|
||||||
|
- **模块化设计** - 每个模块独立完整，可单独测试和部署
|
||||||
|
- **配置驱动** - 通过环境变量控制运行模式和行为
|
||||||
|
|
||||||
|
### 📊 整体架构图
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 🌐 API接口层 │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ 🔗 REST API │ │ 🔌 WebSocket │ │ 📄 Swagger UI │ │
|
||||||
|
│ │ (HTTP接口) │ │ (实时通信) │ │ (API文档) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
⬇️
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 🎯 业务功能模块层 │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ 🔐 用户认证 │ │ 👥 用户管理 │ │ 🛡️ 管理员 │ │
|
||||||
|
│ │ (auth) │ │ (user-mgmt) │ │ (admin) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ 🔒 安全防护 │ │ 💬 Zulip集成 │ │ 🔗 共享组件 │ │
|
||||||
|
│ │ (security) │ │ (zulip) │ │ (shared) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
⬇️
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ ⚙️ 核心技术服务层 │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ 🔑 登录核心 │ │ 👑 管理员核心 │ │ 💬 Zulip核心 │ │
|
||||||
|
│ │ (login_core) │ │ (admin_core) │ │ (zulip) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ 🛠️ 工具服务 │ │ 📧 邮件服务 │ │ 📝 日志服务 │ │
|
||||||
|
│ │ (utils) │ │ (email) │ │ (logger) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
⬇️
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 🗄️ 数据存储层 │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ 🗃️ 数据库 │ │ 🔴 Redis缓存 │ │ 📁 文件存储 │ │
|
||||||
|
│ │ (MySQL/内存) │ │ (Redis/文件) │ │ (logs/data) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📁 目录结构详解
|
||||||
|
|
||||||
|
### 🎯 业务功能模块 (`src/business/`)
|
||||||
|
|
||||||
|
> **设计原则**: 按业务功能组织，每个模块包含完整的业务逻辑
|
||||||
|
|
||||||
|
```
|
||||||
|
src/business/
|
||||||
|
├── 📂 auth/ # 🔐 用户认证模块
|
||||||
|
│ ├── 📄 auth.controller.ts # HTTP接口控制器
|
||||||
|
│ ├── 📄 auth.service.ts # 业务逻辑服务
|
||||||
|
│ ├── 📄 auth.module.ts # 模块定义
|
||||||
|
│ ├── 📂 dto/ # 数据传输对象
|
||||||
|
│ │ ├── 📄 login.dto.ts # 登录请求DTO
|
||||||
|
│ │ ├── 📄 register.dto.ts # 注册请求DTO
|
||||||
|
│ │ └── 📄 reset-password.dto.ts # 重置密码DTO
|
||||||
|
│ └── 📂 __tests__/ # 单元测试
|
||||||
|
│ └── 📄 auth.service.spec.ts
|
||||||
|
│
|
||||||
|
├── 📂 user-mgmt/ # 👥 用户管理模块
|
||||||
|
│ ├── 📄 user-mgmt.controller.ts # 用户管理接口
|
||||||
|
│ ├── 📄 user-mgmt.service.ts # 用户状态管理逻辑
|
||||||
|
│ ├── 📄 user-mgmt.module.ts # 模块定义
|
||||||
|
│ ├── 📂 dto/ # 数据传输对象
|
||||||
|
│ │ ├── 📄 update-status.dto.ts # 状态更新DTO
|
||||||
|
│ │ └── 📄 batch-status.dto.ts # 批量操作DTO
|
||||||
|
│ └── 📂 enums/ # 枚举定义
|
||||||
|
│ └── 📄 user-status.enum.ts # 用户状态枚举
|
||||||
|
│
|
||||||
|
├── 📂 admin/ # 🛡️ 管理员模块
|
||||||
|
│ ├── 📄 admin.controller.ts # 管理员接口
|
||||||
|
│ ├── 📄 admin.service.ts # 管理员业务逻辑
|
||||||
|
│ ├── 📄 admin.module.ts # 模块定义
|
||||||
|
│ ├── 📂 dto/ # 数据传输对象
|
||||||
|
│ └── 📂 guards/ # 权限守卫
|
||||||
|
│ └── 📄 admin.guard.ts # 管理员权限验证
|
||||||
|
│
|
||||||
|
├── 📂 security/ # 🔒 安全防护模块
|
||||||
|
│ ├── 📄 security.module.ts # 安全模块定义
|
||||||
|
│ ├── 📂 guards/ # 安全守卫
|
||||||
|
│ │ ├── 📄 throttle.guard.ts # 频率限制守卫
|
||||||
|
│ │ ├── 📄 maintenance.guard.ts # 维护模式守卫
|
||||||
|
│ │ └── 📄 content-type.guard.ts # 内容类型守卫
|
||||||
|
│ └── 📂 interceptors/ # 拦截器
|
||||||
|
│ └── 📄 timeout.interceptor.ts # 超时拦截器
|
||||||
|
│
|
||||||
|
├── 📂 zulip/ # 💬 Zulip集成模块
|
||||||
|
│ ├── 📄 zulip.service.ts # Zulip业务服务
|
||||||
|
│ ├── 📄 zulip_websocket.gateway.ts # WebSocket网关
|
||||||
|
│ ├── 📄 zulip.module.ts # 模块定义
|
||||||
|
│ └── 📂 services/ # 子服务
|
||||||
|
│ ├── 📄 message_filter.service.ts # 消息过滤
|
||||||
|
│ └── 📄 session_cleanup.service.ts # 会话清理
|
||||||
|
│
|
||||||
|
└── 📂 shared/ # 🔗 共享业务组件
|
||||||
|
├── 📂 decorators/ # 装饰器
|
||||||
|
├── 📂 pipes/ # 管道
|
||||||
|
├── 📂 filters/ # 异常过滤器
|
||||||
|
└── 📂 interfaces/ # 接口定义
|
||||||
|
```
|
||||||
|
|
||||||
|
### ⚙️ 核心技术服务 (`src/core/`)
|
||||||
|
|
||||||
|
> **设计原则**: 提供技术基础设施，支持业务模块运行
|
||||||
|
|
||||||
|
```
|
||||||
|
src/core/
|
||||||
|
├── 📂 db/ # 🗄️ 数据库层
|
||||||
|
│ ├── 📄 db.module.ts # 数据库模块
|
||||||
|
│ ├── 📂 users/ # 用户数据服务
|
||||||
|
│ │ ├── 📄 users.service.ts # MySQL数据库实现
|
||||||
|
│ │ ├── 📄 users-memory.service.ts # 内存数据库实现
|
||||||
|
│ │ ├── 📄 users.interface.ts # 用户服务接口
|
||||||
|
│ │ └── 📄 user.entity.ts # 用户实体定义
|
||||||
|
│ └── 📂 entities/ # 数据库实体
|
||||||
|
│ └── 📄 *.entity.ts # 各种实体定义
|
||||||
|
│
|
||||||
|
├── 📂 redis/ # 🔴 Redis缓存层
|
||||||
|
│ ├── 📄 redis.module.ts # Redis模块
|
||||||
|
│ ├── 📄 redis.service.ts # Redis真实实现
|
||||||
|
│ ├── 📄 file-redis.service.ts # 文件存储实现
|
||||||
|
│ └── 📄 redis.interface.ts # Redis服务接口
|
||||||
|
│
|
||||||
|
├── 📂 login_core/ # 🔑 登录核心服务
|
||||||
|
│ ├── 📄 login-core.service.ts # 登录核心逻辑
|
||||||
|
│ ├── 📄 login-core.module.ts # 模块定义
|
||||||
|
│ └── 📄 login-core.interface.ts # 接口定义
|
||||||
|
│
|
||||||
|
├── 📂 admin_core/ # 👑 管理员核心服务
|
||||||
|
│ ├── 📄 admin-core.service.ts # 管理员核心逻辑
|
||||||
|
│ ├── 📄 admin-core.module.ts # 模块定义
|
||||||
|
│ └── 📄 admin-core.interface.ts # 接口定义
|
||||||
|
│
|
||||||
|
├── 📂 zulip/ # 💬 Zulip核心服务
|
||||||
|
│ ├── 📄 zulip-core.module.ts # Zulip核心模块
|
||||||
|
│ ├── 📄 zulip-api.service.ts # Zulip API服务
|
||||||
|
│ └── 📄 zulip-websocket.service.ts # WebSocket服务
|
||||||
|
│
|
||||||
|
└── 📂 utils/ # 🛠️ 工具服务
|
||||||
|
├── 📂 email/ # 📧 邮件服务
|
||||||
|
│ ├── 📄 email.service.ts # 邮件发送服务
|
||||||
|
│ ├── 📄 email.module.ts # 邮件模块
|
||||||
|
│ └── 📄 email.interface.ts # 邮件接口
|
||||||
|
├── 📂 verification/ # 🔢 验证码服务
|
||||||
|
│ ├── 📄 verification.service.ts # 验证码生成验证
|
||||||
|
│ └── 📄 verification.module.ts # 验证码模块
|
||||||
|
└── 📂 logger/ # 📝 日志服务
|
||||||
|
├── 📄 logger.service.ts # 日志记录服务
|
||||||
|
└── 📄 logger.module.ts # 日志模块
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🎨 前端管理界面 (`client/`)
|
||||||
|
|
||||||
|
> **设计原则**: 独立的前端项目，提供管理员后台功能
|
||||||
|
|
||||||
|
```
|
||||||
|
client/
|
||||||
|
├── 📂 src/ # 前端源码
|
||||||
|
│ ├── 📂 components/ # 通用组件
|
||||||
|
│ │ ├── 📄 Layout.tsx # 布局组件
|
||||||
|
│ │ ├── 📄 UserTable.tsx # 用户表格组件
|
||||||
|
│ │ └── 📄 LogViewer.tsx # 日志查看组件
|
||||||
|
│ ├── 📂 pages/ # 页面组件
|
||||||
|
│ │ ├── 📄 Login.tsx # 登录页面
|
||||||
|
│ │ ├── 📄 Dashboard.tsx # 仪表板
|
||||||
|
│ │ ├── 📄 UserManagement.tsx # 用户管理
|
||||||
|
│ │ └── 📄 LogManagement.tsx # 日志管理
|
||||||
|
│ ├── 📂 services/ # API服务
|
||||||
|
│ │ ├── 📄 api.ts # API客户端
|
||||||
|
│ │ ├── 📄 auth.ts # 认证服务
|
||||||
|
│ │ └── 📄 users.ts # 用户服务
|
||||||
|
│ ├── 📂 utils/ # 工具函数
|
||||||
|
│ ├── 📂 types/ # TypeScript类型
|
||||||
|
│ ├── 📄 App.tsx # 应用主组件
|
||||||
|
│ └── 📄 main.tsx # 应用入口
|
||||||
|
├── 📂 dist/ # 构建产物
|
||||||
|
├── 📄 package.json # 前端依赖
|
||||||
|
├── 📄 vite.config.ts # Vite配置
|
||||||
|
└── 📄 tsconfig.json # TypeScript配置
|
||||||
|
```
|
||||||
|
|
||||||
|
### 📚 文档中心 (`docs/`)
|
||||||
|
|
||||||
|
> **设计原则**: 完整的项目文档，支持开发者快速上手
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── 📄 README.md # 📖 文档导航中心
|
||||||
|
├── 📄 ARCHITECTURE.md # 🏗️ 架构设计文档
|
||||||
|
├── 📄 API_STATUS_CODES.md # 📋 API状态码说明
|
||||||
|
├── 📄 CONTRIBUTORS.md # 🤝 贡献者指南
|
||||||
|
│
|
||||||
|
├── 📂 api/ # 🔌 API接口文档
|
||||||
|
│ ├── 📄 README.md # API文档使用指南
|
||||||
|
│ ├── 📄 api-documentation.md # 完整API接口文档
|
||||||
|
│ ├── 📄 openapi.yaml # OpenAPI规范文件
|
||||||
|
│ └── 📄 postman-collection.json # Postman测试集合
|
||||||
|
│
|
||||||
|
├── 📂 development/ # 💻 开发指南
|
||||||
|
│ ├── 📄 backend_development_guide.md # 后端开发规范
|
||||||
|
│ ├── 📄 git_commit_guide.md # Git提交规范
|
||||||
|
│ ├── 📄 AI辅助开发规范指南.md # AI辅助开发指南
|
||||||
|
│ ├── 📄 TESTING.md # 测试指南
|
||||||
|
│ └── 📄 naming_convention.md # 命名规范
|
||||||
|
│
|
||||||
|
└── 📂 deployment/ # 🚀 部署文档
|
||||||
|
└── 📄 DEPLOYMENT.md # 生产环境部署指南
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🧪 测试文件 (`test/`)
|
||||||
|
|
||||||
|
> **设计原则**: 完整的测试覆盖，确保代码质量
|
||||||
|
|
||||||
|
```
|
||||||
|
test/
|
||||||
|
├── 📂 unit/ # 单元测试
|
||||||
|
├── 📂 integration/ # 集成测试
|
||||||
|
├── 📂 e2e/ # 端到端测试
|
||||||
|
└── 📂 fixtures/ # 测试数据
|
||||||
|
```
|
||||||
|
|
||||||
|
### ⚙️ 配置文件
|
||||||
|
|
||||||
|
> **设计原则**: 清晰的配置管理，支持多环境部署
|
||||||
|
|
||||||
|
```
|
||||||
|
项目根目录/
|
||||||
|
├── 📄 .env # 🔧 环境变量配置
|
||||||
|
├── 📄 .env.example # 🔧 环境变量示例
|
||||||
|
├── 📄 .env.production.example # 🔧 生产环境示例
|
||||||
|
├── 📄 package.json # 📋 项目依赖配置
|
||||||
|
├── 📄 pnpm-workspace.yaml # 📦 pnpm工作空间配置
|
||||||
|
├── 📄 tsconfig.json # 📘 TypeScript配置
|
||||||
|
├── 📄 jest.config.js # 🧪 Jest测试配置
|
||||||
|
├── 📄 nest-cli.json # 🏠 NestJS CLI配置
|
||||||
|
├── 📄 docker-compose.yml # 🐳 Docker编排配置
|
||||||
|
├── 📄 Dockerfile # 🐳 Docker镜像配置
|
||||||
|
└── 📄 ecosystem.config.js # 🚀 PM2进程管理配置
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ 分层架构设计
|
||||||
|
|
||||||
|
### 📊 架构分层说明
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
│ API 层 │
|
│ 🌐 表现层 (Presentation) │
|
||||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
│ │ HTTP API │ │ WebSocket │ │ GraphQL │ │
|
│ │ Controllers │ │ WebSocket │ │ Swagger UI │ │
|
||||||
│ │ (REST) │ │ (Socket.IO) │ │ (预留) │ │
|
│ │ (HTTP接口) │ │ Gateways │ │ (API文档) │ │
|
||||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
└─────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────┘
|
||||||
│
|
⬇️
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
│ 业务逻辑层 │
|
│ 🎯 业务层 (Business) │
|
||||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
│ │ 用户认证 │ │ 游戏逻辑 │ │ 社交功能 │ │
|
│ │ Auth Module │ │ UserMgmt │ │ Admin Module │ │
|
||||||
│ │ (Login) │ │ (Game) │ │ (Social) │ │
|
│ │ (用户认证) │ │ Module │ │ (管理员) │ │
|
||||||
|
│ │ │ │ (用户管理) │ │ │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ Security Module │ │ Zulip Module │ │ Shared Module │ │
|
||||||
|
│ │ (安全防护) │ │ (Zulip集成) │ │ (共享组件) │ │
|
||||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
└─────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────┘
|
||||||
│
|
⬇️
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
│ 核心服务层 │
|
│ ⚙️ 服务层 (Service) │
|
||||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
│ │ 邮件服务 │ │ 验证码服务 │ │ 日志服务 │ │
|
│ │ Login Core │ │ Admin Core │ │ Zulip Core │ │
|
||||||
│ │ (Email) │ │ (Verification)│ │ (Logger) │ │
|
│ │ (登录核心) │ │ (管理员核心) │ │ (Zulip核心) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ Email Service │ │ Verification │ │ Logger Service │ │
|
||||||
|
│ │ (邮件服务) │ │ Service │ │ (日志服务) │ │
|
||||||
|
│ │ │ │ (验证码服务) │ │ │ │
|
||||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
└─────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────┘
|
||||||
│
|
⬇️
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
│ 数据访问层 │
|
│ 🗄️ 数据层 (Data) │
|
||||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
│ │ 用户数据 │ │ Redis缓存 │ │ 文件存储 │ │
|
│ │ Users Service │ │ Redis Service │ │ File Storage │ │
|
||||||
│ │ (Users) │ │ (Cache) │ │ (Files) │ │
|
│ │ (用户数据) │ │ (缓存服务) │ │ (文件存储) │ │
|
||||||
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||||
|
│ │ MySQL/Memory │ │ Redis/File │ │ Logs/Data │ │
|
||||||
|
│ │ (数据库) │ │ (缓存实现) │ │ (日志数据) │ │
|
||||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||||
└─────────────────────────────────────────────────────────────┘
|
└─────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## 模块依赖关系
|
### 🔄 数据流向
|
||||||
|
|
||||||
|
#### 用户注册流程示例
|
||||||
|
|
||||||
```
|
```
|
||||||
AppModule
|
1. 📱 用户请求 → AuthController.register()
|
||||||
├── ConfigModule (全局配置)
|
2. 🔍 参数验证 → class-validator装饰器
|
||||||
├── LoggerModule (日志系统)
|
3. 🎯 业务逻辑 → AuthService.register()
|
||||||
├── RedisModule (缓存服务)
|
4. ⚙️ 核心服务 → LoginCoreService.createUser()
|
||||||
├── UsersModule (用户管理)
|
5. 📧 发送邮件 → EmailService.sendVerificationCode()
|
||||||
│ ├── UsersService (数据库模式)
|
6. 🔢 生成验证码 → VerificationService.generate()
|
||||||
│ └── UsersMemoryService (内存模式)
|
7. 💾 存储数据 → UsersService.create() + RedisService.set()
|
||||||
├── EmailModule (邮件服务)
|
8. 📝 记录日志 → LoggerService.log()
|
||||||
├── VerificationModule (验证码服务)
|
9. ✅ 返回响应 → 用户收到成功响应
|
||||||
├── LoginCoreModule (登录核心)
|
|
||||||
└── LoginModule (登录业务)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 数据流向
|
#### 管理员操作流程示例
|
||||||
|
|
||||||
### 用户注册流程
|
|
||||||
```
|
```
|
||||||
1. 用户请求 → LoginController
|
1. 🛡️ 管理员请求 → AdminController.resetUserPassword()
|
||||||
2. 参数验证 → LoginService
|
2. 🔐 权限验证 → AdminGuard.canActivate()
|
||||||
3. 发送验证码 → LoginCoreService
|
3. 🎯 业务逻辑 → AdminService.resetPassword()
|
||||||
4. 生成验证码 → VerificationService
|
4. ⚙️ 核心服务 → AdminCoreService.resetUserPassword()
|
||||||
5. 发送邮件 → EmailService
|
5. 🔑 密码加密 → bcrypt.hash()
|
||||||
6. 存储验证码 → RedisService
|
6. 💾 更新数据 → UsersService.update()
|
||||||
7. 返回响应 → 用户
|
7. 📧 通知用户 → EmailService.sendPasswordReset()
|
||||||
|
8. 📝 审计日志 → LoggerService.audit()
|
||||||
|
9. ✅ 返回响应 → 管理员收到操作结果
|
||||||
```
|
```
|
||||||
|
|
||||||
### 双模式架构
|
---
|
||||||
|
|
||||||
项目支持开发测试模式和生产部署模式的无缝切换：
|
## 🔄 双模式架构
|
||||||
|
|
||||||
#### 开发测试模式
|
### 🎯 设计目标
|
||||||
- **数据库**: 内存存储 (UsersMemoryService)
|
|
||||||
- **缓存**: 文件存储 (FileRedisService)
|
|
||||||
- **邮件**: 控制台输出 (测试模式)
|
|
||||||
- **优势**: 无需外部依赖，快速启动测试
|
|
||||||
|
|
||||||
#### 生产部署模式
|
- **开发测试**: 零依赖快速启动，无需安装MySQL、Redis等外部服务
|
||||||
- **数据库**: MySQL (UsersService + TypeORM)
|
- **生产部署**: 高性能、高可用，支持集群和负载均衡
|
||||||
- **缓存**: Redis (RealRedisService + IORedis)
|
|
||||||
- **邮件**: SMTP服务器 (生产模式)
|
|
||||||
- **优势**: 高性能，高可用，数据持久化
|
|
||||||
|
|
||||||
## 设计原则
|
### 📊 模式对比
|
||||||
|
|
||||||
### 1. 单一职责原则
|
| 功能模块 | 🧪 开发测试模式 | 🚀 生产部署模式 |
|
||||||
每个模块只负责一个特定的功能领域：
|
|----------|----------------|----------------|
|
||||||
- `LoginModule`: 只处理登录相关业务
|
| **数据库** | 内存存储 (UsersMemoryService) | MySQL (UsersService + TypeORM) |
|
||||||
- `EmailModule`: 只处理邮件发送
|
| **缓存** | 文件存储 (FileRedisService) | Redis (RedisService + IORedis) |
|
||||||
- `VerificationModule`: 只处理验证码逻辑
|
| **邮件** | 控制台输出 (测试模式) | SMTP服务器 (生产模式) |
|
||||||
|
| **日志** | 控制台 + 文件 | 结构化日志 + 日志轮转 |
|
||||||
|
| **配置** | `.env` 默认配置 | 环境变量 + 配置中心 |
|
||||||
|
|
||||||
### 2. 依赖注入
|
### ⚙️ 模式切换配置
|
||||||
使用NestJS的依赖注入系统：
|
|
||||||
- 接口抽象: `IRedisService`, `IUsersService`
|
|
||||||
- 实现切换: 根据配置自动选择实现类
|
|
||||||
- 测试友好: 易于Mock和单元测试
|
|
||||||
|
|
||||||
### 3. 配置驱动
|
#### 开发测试模式 (.env)
|
||||||
通过环境变量控制行为：
|
```bash
|
||||||
- `USE_FILE_REDIS`: 选择Redis实现
|
# 数据存储模式
|
||||||
- `DB_HOST`: 数据库连接配置
|
USE_FILE_REDIS=true # 使用文件存储代替Redis
|
||||||
- `EMAIL_HOST`: 邮件服务配置
|
NODE_ENV=development # 开发环境
|
||||||
|
|
||||||
### 4. 错误处理
|
# 数据库配置（注释掉，使用内存数据库）
|
||||||
统一的错误处理机制：
|
# DB_HOST=localhost
|
||||||
- HTTP异常: `BadRequestException`, `UnauthorizedException`
|
# DB_USERNAME=root
|
||||||
- 业务异常: 自定义异常类
|
# DB_PASSWORD=password
|
||||||
- 日志记录: 结构化错误日志
|
|
||||||
|
|
||||||
## 扩展指南
|
# 邮件配置（注释掉，使用测试模式）
|
||||||
|
# EMAIL_HOST=smtp.gmail.com
|
||||||
|
# EMAIL_USER=your_email@gmail.com
|
||||||
|
# EMAIL_PASS=your_password
|
||||||
|
```
|
||||||
|
|
||||||
### 添加新的业务模块
|
#### 生产部署模式 (.env.production)
|
||||||
|
```bash
|
||||||
|
# 数据存储模式
|
||||||
|
USE_FILE_REDIS=false # 使用真实Redis
|
||||||
|
NODE_ENV=production # 生产环境
|
||||||
|
|
||||||
1. **创建业务模块**
|
# 数据库配置
|
||||||
```bash
|
DB_HOST=your_mysql_host
|
||||||
nest g module business/game
|
DB_PORT=3306
|
||||||
nest g controller business/game
|
DB_USERNAME=your_username
|
||||||
nest g service business/game
|
DB_PASSWORD=your_password
|
||||||
```
|
DB_DATABASE=whale_town
|
||||||
|
|
||||||
2. **创建核心服务**
|
# Redis配置
|
||||||
```bash
|
REDIS_HOST=your_redis_host
|
||||||
nest g module core/game_core
|
REDIS_PORT=6379
|
||||||
nest g service core/game_core
|
REDIS_PASSWORD=your_redis_password
|
||||||
```
|
|
||||||
|
|
||||||
3. **添加数据模型**
|
# 邮件配置
|
||||||
```bash
|
EMAIL_HOST=smtp.gmail.com
|
||||||
nest g module core/db/games
|
EMAIL_PORT=587
|
||||||
nest g service core/db/games
|
EMAIL_USER=your_email@gmail.com
|
||||||
```
|
EMAIL_PASS=your_app_password
|
||||||
|
```
|
||||||
|
|
||||||
4. **更新主模块**
|
### 🔧 实现机制
|
||||||
在 `app.module.ts` 中导入新模块
|
|
||||||
|
|
||||||
### 添加新的工具服务
|
#### 依赖注入切换
|
||||||
|
```typescript
|
||||||
|
// redis.module.ts
|
||||||
|
@Module({
|
||||||
|
providers: [
|
||||||
|
{
|
||||||
|
provide: 'IRedisService',
|
||||||
|
useFactory: (configService: ConfigService) => {
|
||||||
|
const useFileRedis = configService.get<boolean>('USE_FILE_REDIS');
|
||||||
|
return useFileRedis
|
||||||
|
? new FileRedisService()
|
||||||
|
: new RedisService(configService);
|
||||||
|
},
|
||||||
|
inject: [ConfigService],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
})
|
||||||
|
export class RedisModule {}
|
||||||
|
```
|
||||||
|
|
||||||
1. **创建工具模块**
|
#### 配置驱动服务选择
|
||||||
```bash
|
```typescript
|
||||||
nest g module core/utils/notification
|
// users.module.ts
|
||||||
nest g service core/utils/notification
|
@Module({
|
||||||
```
|
providers: [
|
||||||
|
{
|
||||||
|
provide: 'IUsersService',
|
||||||
|
useFactory: (configService: ConfigService) => {
|
||||||
|
const dbHost = configService.get<string>('DB_HOST');
|
||||||
|
return dbHost
|
||||||
|
? new UsersService()
|
||||||
|
: new UsersMemoryService();
|
||||||
|
},
|
||||||
|
inject: [ConfigService],
|
||||||
|
},
|
||||||
|
],
|
||||||
|
})
|
||||||
|
export class UsersModule {}
|
||||||
|
```
|
||||||
|
|
||||||
2. **实现服务接口**
|
---
|
||||||
定义抽象接口和具体实现
|
|
||||||
|
|
||||||
3. **添加配置支持**
|
## 📦 模块依赖关系
|
||||||
在环境变量中添加相关配置
|
|
||||||
|
|
||||||
4. **编写测试用例**
|
### 🏗️ 模块依赖图
|
||||||
确保功能正确性和代码覆盖率
|
|
||||||
|
|
||||||
## 性能优化
|
```
|
||||||
|
AppModule (应用主模块)
|
||||||
|
├── 📊 ConfigModule (全局配置)
|
||||||
|
├── 📝 LoggerModule (日志系统)
|
||||||
|
├── 🔴 RedisModule (缓存服务)
|
||||||
|
│ ├── RedisService (真实Redis)
|
||||||
|
│ └── FileRedisService (文件存储)
|
||||||
|
├── 🗄️ UsersModule (用户数据)
|
||||||
|
│ ├── UsersService (MySQL数据库)
|
||||||
|
│ └── UsersMemoryService (内存数据库)
|
||||||
|
├── 📧 EmailModule (邮件服务)
|
||||||
|
├── 🔢 VerificationModule (验证码服务)
|
||||||
|
├── 🔑 LoginCoreModule (登录核心)
|
||||||
|
├── 👑 AdminCoreModule (管理员核心)
|
||||||
|
├── 💬 ZulipCoreModule (Zulip核心)
|
||||||
|
│
|
||||||
|
├── 🎯 业务功能模块
|
||||||
|
│ ├── 🔐 AuthModule (用户认证)
|
||||||
|
│ │ └── 依赖: LoginCoreModule, EmailModule, VerificationModule
|
||||||
|
│ ├── 👥 UserMgmtModule (用户管理)
|
||||||
|
│ │ └── 依赖: UsersModule, LoggerModule
|
||||||
|
│ ├── 🛡️ AdminModule (管理员)
|
||||||
|
│ │ └── 依赖: AdminCoreModule, UsersModule
|
||||||
|
│ ├── 🔒 SecurityModule (安全防护)
|
||||||
|
│ │ └── 依赖: RedisModule, LoggerModule
|
||||||
|
│ ├── 💬 ZulipModule (Zulip集成)
|
||||||
|
│ │ └── 依赖: ZulipCoreModule, RedisModule
|
||||||
|
│ └── 🔗 SharedModule (共享组件)
|
||||||
|
```
|
||||||
|
|
||||||
### 1. 缓存策略
|
### 🔄 模块交互流程
|
||||||
- **Redis缓存**: 验证码、会话信息
|
|
||||||
|
#### 用户认证流程
|
||||||
|
```
|
||||||
|
AuthController → AuthService → LoginCoreService
|
||||||
|
↓
|
||||||
|
EmailService ← VerificationService ← RedisService
|
||||||
|
↓
|
||||||
|
UsersService
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 管理员操作流程
|
||||||
|
```
|
||||||
|
AdminController → AdminService → AdminCoreService
|
||||||
|
↓
|
||||||
|
LoggerService ← UsersService ← RedisService
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 安全防护流程
|
||||||
|
```
|
||||||
|
SecurityGuard → RedisService (频率限制)
|
||||||
|
→ LoggerService (审计日志)
|
||||||
|
→ ConfigService (维护模式)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 扩展指南
|
||||||
|
|
||||||
|
### 📝 添加新的业务模块
|
||||||
|
|
||||||
|
#### 1. 创建业务模块结构
|
||||||
|
```bash
|
||||||
|
# 创建模块目录
|
||||||
|
mkdir -p src/business/game/{dto,enums,guards,interfaces}
|
||||||
|
|
||||||
|
# 生成NestJS模块文件
|
||||||
|
nest g module business/game
|
||||||
|
nest g controller business/game
|
||||||
|
nest g service business/game
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 实现业务逻辑
|
||||||
|
```typescript
|
||||||
|
// src/business/game/game.module.ts
|
||||||
|
@Module({
|
||||||
|
imports: [
|
||||||
|
GameCoreModule, # 依赖核心服务
|
||||||
|
UsersModule, # 依赖用户数据
|
||||||
|
RedisModule, # 依赖缓存服务
|
||||||
|
],
|
||||||
|
controllers: [GameController],
|
||||||
|
providers: [GameService],
|
||||||
|
exports: [GameService],
|
||||||
|
})
|
||||||
|
export class GameModule {}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. 创建对应的核心服务
|
||||||
|
```bash
|
||||||
|
# 创建核心服务
|
||||||
|
mkdir -p src/core/game_core
|
||||||
|
nest g module core/game_core
|
||||||
|
nest g service core/game_core
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. 更新主模块
|
||||||
|
```typescript
|
||||||
|
// src/app.module.ts
|
||||||
|
@Module({
|
||||||
|
imports: [
|
||||||
|
// ... 其他模块
|
||||||
|
GameModule, # 添加新的业务模块
|
||||||
|
],
|
||||||
|
})
|
||||||
|
export class AppModule {}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🛠️ 添加新的工具服务
|
||||||
|
|
||||||
|
#### 1. 创建工具服务
|
||||||
|
```bash
|
||||||
|
mkdir -p src/core/utils/notification
|
||||||
|
nest g module core/utils/notification
|
||||||
|
nest g service core/utils/notification
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 定义服务接口
|
||||||
|
```typescript
|
||||||
|
// src/core/utils/notification/notification.interface.ts
|
||||||
|
export interface INotificationService {
|
||||||
|
sendPush(userId: string, message: string): Promise<void>;
|
||||||
|
sendSMS(phone: string, message: string): Promise<void>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. 实现服务
|
||||||
|
```typescript
|
||||||
|
// src/core/utils/notification/notification.service.ts
|
||||||
|
@Injectable()
|
||||||
|
export class NotificationService implements INotificationService {
|
||||||
|
async sendPush(userId: string, message: string): Promise<void> {
|
||||||
|
// 实现推送通知逻辑
|
||||||
|
}
|
||||||
|
|
||||||
|
async sendSMS(phone: string, message: string): Promise<void> {
|
||||||
|
// 实现短信发送逻辑
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. 配置依赖注入
|
||||||
|
```typescript
|
||||||
|
// src/core/utils/notification/notification.module.ts
|
||||||
|
@Module({
|
||||||
|
providers: [
|
||||||
|
{
|
||||||
|
provide: 'INotificationService',
|
||||||
|
useClass: NotificationService,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
exports: ['INotificationService'],
|
||||||
|
})
|
||||||
|
export class NotificationModule {}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔌 添加新的API接口
|
||||||
|
|
||||||
|
#### 1. 定义DTO
|
||||||
|
```typescript
|
||||||
|
// src/business/game/dto/create-game.dto.ts
|
||||||
|
export class CreateGameDto {
|
||||||
|
@IsString()
|
||||||
|
@IsNotEmpty()
|
||||||
|
name: string;
|
||||||
|
|
||||||
|
@IsString()
|
||||||
|
@IsOptional()
|
||||||
|
description?: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. 实现Controller
|
||||||
|
```typescript
|
||||||
|
// src/business/game/game.controller.ts
|
||||||
|
@Controller('game')
|
||||||
|
@ApiTags('游戏管理')
|
||||||
|
export class GameController {
|
||||||
|
constructor(private readonly gameService: GameService) {}
|
||||||
|
|
||||||
|
@Post()
|
||||||
|
@ApiOperation({ summary: '创建游戏' })
|
||||||
|
async createGame(@Body() createGameDto: CreateGameDto) {
|
||||||
|
return this.gameService.create(createGameDto);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. 实现Service
|
||||||
|
```typescript
|
||||||
|
// src/business/game/game.service.ts
|
||||||
|
@Injectable()
|
||||||
|
export class GameService {
|
||||||
|
constructor(
|
||||||
|
@Inject('IGameCoreService')
|
||||||
|
private readonly gameCoreService: IGameCoreService,
|
||||||
|
) {}
|
||||||
|
|
||||||
|
async create(createGameDto: CreateGameDto) {
|
||||||
|
return this.gameCoreService.createGame(createGameDto);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. 添加测试用例
|
||||||
|
```typescript
|
||||||
|
// src/business/game/game.service.spec.ts
|
||||||
|
describe('GameService', () => {
|
||||||
|
let service: GameService;
|
||||||
|
let gameCoreService: jest.Mocked<IGameCoreService>;
|
||||||
|
|
||||||
|
beforeEach(async () => {
|
||||||
|
const module: TestingModule = await Test.createTestingModule({
|
||||||
|
providers: [
|
||||||
|
GameService,
|
||||||
|
{
|
||||||
|
provide: 'IGameCoreService',
|
||||||
|
useValue: {
|
||||||
|
createGame: jest.fn(),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}).compile();
|
||||||
|
|
||||||
|
service = module.get<GameService>(GameService);
|
||||||
|
gameCoreService = module.get('IGameCoreService');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should create game', async () => {
|
||||||
|
const createGameDto = { name: 'Test Game' };
|
||||||
|
const expectedResult = { id: 1, ...createGameDto };
|
||||||
|
|
||||||
|
gameCoreService.createGame.mockResolvedValue(expectedResult);
|
||||||
|
|
||||||
|
const result = await service.create(createGameDto);
|
||||||
|
|
||||||
|
expect(result).toEqual(expectedResult);
|
||||||
|
expect(gameCoreService.createGame).toHaveBeenCalledWith(createGameDto);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 📊 性能优化建议
|
||||||
|
|
||||||
|
#### 1. 缓存策略
|
||||||
|
- **Redis缓存**: 用户会话、验证码、频繁查询数据
|
||||||
- **内存缓存**: 配置信息、静态数据
|
- **内存缓存**: 配置信息、静态数据
|
||||||
- **CDN缓存**: 静态资源文件
|
- **CDN缓存**: 静态资源文件
|
||||||
|
|
||||||
### 2. 数据库优化
|
#### 2. 数据库优化
|
||||||
- **连接池**: 复用数据库连接
|
- **连接池**: 复用数据库连接，减少连接开销
|
||||||
- **索引优化**: 关键字段建立索引
|
- **索引优化**: 为查询字段建立合适的索引
|
||||||
- **查询优化**: 避免N+1查询问题
|
- **查询优化**: 避免N+1查询，使用JOIN优化关联查询
|
||||||
|
|
||||||
### 3. 日志优化
|
#### 3. 日志优化
|
||||||
- **异步日志**: 使用Pino的异步写入
|
- **异步日志**: 使用Pino的异步写入功能
|
||||||
- **日志分级**: 生产环境只记录必要日志
|
- **日志分级**: 生产环境只记录ERROR和WARN级别
|
||||||
- **日志轮转**: 自动清理过期日志文件
|
- **日志轮转**: 自动清理过期日志文件
|
||||||
|
|
||||||
## 安全考虑
|
### 🔒 安全加固建议
|
||||||
|
|
||||||
### 1. 数据验证
|
#### 1. 数据验证
|
||||||
- **输入验证**: class-validator装饰器
|
- **输入验证**: 使用class-validator进行严格验证
|
||||||
- **类型检查**: TypeScript静态类型
|
- **类型检查**: TypeScript静态类型检查
|
||||||
- **SQL注入**: TypeORM参数化查询
|
- **SQL注入防护**: TypeORM参数化查询
|
||||||
|
|
||||||
### 2. 认证授权
|
#### 2. 认证授权
|
||||||
- **密码加密**: bcrypt哈希算法
|
- **密码安全**: bcrypt加密，强密码策略
|
||||||
- **会话管理**: Redis存储会话信息
|
- **会话管理**: JWT + Redis会话存储
|
||||||
- **权限控制**: 基于角色的访问控制
|
- **权限控制**: 基于角色的访问控制(RBAC)
|
||||||
|
|
||||||
### 3. 通信安全
|
#### 3. 通信安全
|
||||||
- **HTTPS**: 生产环境强制HTTPS
|
- **HTTPS**: 生产环境强制HTTPS
|
||||||
- **CORS**: 跨域请求控制
|
- **CORS**: 严格的跨域请求控制
|
||||||
- **Rate Limiting**: API请求频率限制
|
- **Rate Limiting**: API请求频率限制
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**🏗️ 通过清晰的架构设计，Whale Town 实现了高内聚、低耦合的模块化架构，支持快速开发和灵活部署！**
|
||||||
142
docs/DOCUMENT_CLEANUP.md
Normal file
142
docs/DOCUMENT_CLEANUP.md
Normal file
@@ -0,0 +1,142 @@
|
|||||||
|
# 📝 文档清理说明
|
||||||
|
|
||||||
|
> 记录项目文档整理和优化的过程，确保文档结构清晰、内容准确。
|
||||||
|
|
||||||
|
## 🎯 清理目标
|
||||||
|
|
||||||
|
- **删除多余README** - 移除重复和过时的README文件
|
||||||
|
- **优化主文档** - 改进项目主README的文件格式和结构说明
|
||||||
|
- **完善架构文档** - 详细说明项目架构和文件夹组织结构
|
||||||
|
- **统一文档风格** - 采用总分结构，方便开发者理解
|
||||||
|
|
||||||
|
## 📊 文档清理结果
|
||||||
|
|
||||||
|
### ✅ 保留的README文件
|
||||||
|
|
||||||
|
| 文件路径 | 保留原因 | 主要内容 |
|
||||||
|
|----------|----------|----------|
|
||||||
|
| `README.md` | 项目主文档 | 项目介绍、快速开始、技术栈、功能特性 |
|
||||||
|
| `docs/README.md` | 文档导航中心 | 文档结构说明、导航链接 |
|
||||||
|
| `client/README.md` | 前端项目文档 | 前端管理界面的独立说明 |
|
||||||
|
| `docs/api/README.md` | API文档指南 | API文档使用说明和快速测试 |
|
||||||
|
| `src/business/zulip/README.md` | 模块架构说明 | Zulip模块重构的详细说明 |
|
||||||
|
|
||||||
|
### ❌ 删除的README文件
|
||||||
|
|
||||||
|
**无** - 经过分析，所有现有README文件都有其存在价值，未删除任何文件。
|
||||||
|
|
||||||
|
### 🔄 优化的文档
|
||||||
|
|
||||||
|
#### 1. 主README.md优化
|
||||||
|
- **文件结构总览** - 添加了详细的项目文件结构说明
|
||||||
|
- **图标化展示** - 使用emoji图标让结构更直观
|
||||||
|
- **层次化组织** - 按照总分结构组织内容
|
||||||
|
|
||||||
|
#### 2. 架构文档大幅改进 (docs/ARCHITECTURE.md)
|
||||||
|
- **完整重写** - 从简单的架构图扩展为完整的架构设计文档
|
||||||
|
- **目录结构详解** - 详细说明每个文件夹的作用和内容
|
||||||
|
- **分层架构设计** - 清晰的架构分层和模块依赖关系
|
||||||
|
- **双模式架构** - 详细说明开发测试模式和生产部署模式
|
||||||
|
- **扩展指南** - 提供添加新模块和功能的详细指导
|
||||||
|
|
||||||
|
## 📁 文档结构优化
|
||||||
|
|
||||||
|
### 🎯 总分结构设计
|
||||||
|
|
||||||
|
采用**总分结构**组织文档，便于开发者快速理解：
|
||||||
|
|
||||||
|
```
|
||||||
|
📚 文档层次结构
|
||||||
|
├── 🏠 项目总览 (README.md)
|
||||||
|
│ ├── 🎯 项目简介和特性
|
||||||
|
│ ├── 🚀 快速开始指南
|
||||||
|
│ ├── 📁 文件结构总览 ⭐ 新增
|
||||||
|
│ ├── 🛠️ 技术栈说明
|
||||||
|
│ └── 📚 文档导航链接
|
||||||
|
│
|
||||||
|
├── 🏗️ 架构设计 (docs/ARCHITECTURE.md) ⭐ 大幅改进
|
||||||
|
│ ├── 📊 整体架构图
|
||||||
|
│ ├── 📁 目录结构详解
|
||||||
|
│ ├── 🏗️ 分层架构设计
|
||||||
|
│ ├── 🔄 双模式架构
|
||||||
|
│ └── 🚀 扩展指南
|
||||||
|
│
|
||||||
|
├── 📖 文档中心 (docs/README.md)
|
||||||
|
│ ├── 📋 文档导航
|
||||||
|
│ ├── 🏗️ 文档结构说明
|
||||||
|
│ └── 📝 文档维护原则
|
||||||
|
│
|
||||||
|
├── 🔌 API文档 (docs/api/README.md)
|
||||||
|
│ ├── 📊 API接口概览
|
||||||
|
│ ├── 🚀 快速开始
|
||||||
|
│ └── 🧪 测试指南
|
||||||
|
│
|
||||||
|
└── 🎨 前端文档 (client/README.md)
|
||||||
|
├── 🚀 快速开始
|
||||||
|
├── 🎯 核心功能
|
||||||
|
└── 🔧 开发指南
|
||||||
|
```
|
||||||
|
|
||||||
|
### 📊 文档内容优化
|
||||||
|
|
||||||
|
#### 1. 视觉化改进
|
||||||
|
- **emoji图标** - 使用统一的emoji图标系统
|
||||||
|
- **表格展示** - 用表格清晰展示对比信息
|
||||||
|
- **代码示例** - 提供完整的代码示例和配置
|
||||||
|
- **架构图** - 使用ASCII艺术绘制清晰的架构图
|
||||||
|
|
||||||
|
#### 2. 结构化内容
|
||||||
|
- **目录导航** - 每个长文档都有详细目录
|
||||||
|
- **分层说明** - 按照业务功能模块化的原则组织
|
||||||
|
- **实用指南** - 提供具体的操作步骤和扩展指南
|
||||||
|
|
||||||
|
#### 3. 开发者友好
|
||||||
|
- **快速上手** - 新开发者指南，从规范学习到架构理解
|
||||||
|
- **总分结构** - 先总览后详细，便于快速理解
|
||||||
|
- **实际案例** - 提供真实的代码示例和使用场景
|
||||||
|
|
||||||
|
## 🎯 文档维护原则
|
||||||
|
|
||||||
|
### ✅ 保留标准
|
||||||
|
- **长期价值** - 对整个项目生命周期都有价值
|
||||||
|
- **参考价值** - 开发、部署、维护时需要查阅
|
||||||
|
- **规范指导** - 团队协作和代码质量保证
|
||||||
|
|
||||||
|
### ❌ 清理标准
|
||||||
|
- **阶段性文档** - 只在特定开发阶段有用
|
||||||
|
- **临时记录** - 会议记录、临时决策等
|
||||||
|
- **过时信息** - 已经不适用的旧版本文档
|
||||||
|
|
||||||
|
### 🔄 更新策略
|
||||||
|
- **及时更新** - 功能变更时同步更新相关文档
|
||||||
|
- **版本控制** - 重要变更记录版本历史
|
||||||
|
- **定期审查** - 定期检查文档的准确性和有效性
|
||||||
|
|
||||||
|
## 📈 改进效果
|
||||||
|
|
||||||
|
### 🎯 开发者体验提升
|
||||||
|
- **快速理解** - 通过总分结构快速掌握项目架构
|
||||||
|
- **准确信息** - 文档与实际代码结构完全一致
|
||||||
|
- **实用指导** - 提供具体的开发和扩展指南
|
||||||
|
|
||||||
|
### 📚 文档质量提升
|
||||||
|
- **结构清晰** - 层次分明的文档组织结构
|
||||||
|
- **内容完整** - 覆盖项目的所有重要方面
|
||||||
|
- **易于维护** - 明确的维护原则和更新策略
|
||||||
|
|
||||||
|
### 🚀 项目可维护性提升
|
||||||
|
- **架构清晰** - 详细的架构文档便于理解和扩展
|
||||||
|
- **规范统一** - 统一的文档风格和组织原则
|
||||||
|
- **知识传承** - 完整的文档体系便于团队协作
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**📝 通过系统性的文档清理和优化，项目文档现在更加清晰、准确、实用！**
|
||||||
|
|
||||||
|
## 📅 清理记录
|
||||||
|
|
||||||
|
- **清理时间**: 2025年12月31日
|
||||||
|
- **清理范围**: 项目根目录及所有子目录的README文件
|
||||||
|
- **主要改进**: 架构文档完全重写，主README结构优化
|
||||||
|
- **保留文件**: 5个README文件全部保留
|
||||||
|
- **删除文件**: 0个（所有文件都有价值）
|
||||||
@@ -27,7 +27,7 @@
|
|||||||
|
|
||||||
### 📋 **项目管理**
|
### 📋 **项目管理**
|
||||||
- [贡献指南](CONTRIBUTORS.md) - 如何参与项目贡献
|
- [贡献指南](CONTRIBUTORS.md) - 如何参与项目贡献
|
||||||
- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护记录
|
- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护和优化记录
|
||||||
|
|
||||||
## 🏗️ **文档结构说明**
|
## 🏗️ **文档结构说明**
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user