From 5140bd1a5419a7d84aa7d6d6576dce3a17e1ad35 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Wed, 31 Dec 2025 15:43:15 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E4=BC=98=E5=8C=96=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84=E5=92=8C=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 优化主README.md的文件结构总览，采用总分结构设计 - 大幅改进docs/ARCHITECTURE.md，详细说明业务功能模块化架构 - 新增docs/DOCUMENT_CLEANUP.md记录文档清理过程 - 更新docs/README.md添加新文档的导航链接 本次更新完善了项目文档体系，便于开发者快速理解项目架构 --- README.md | 63 +-- docs/ARCHITECTURE.md | 812 +++++++++++++++++++++++++++++++++------ docs/DOCUMENT_CLEANUP.md | 142 +++++++ docs/README.md | 2 +- 4 files changed, 870 insertions(+), 149 deletions(-) create mode 100644 docs/DOCUMENT_CLEANUP.md diff --git a/README.md b/README.md index e3663f1..1768a65 100644 --- a/README.md +++ b/README.md @@ -124,29 +124,48 @@ pnpm run dev ### 第二步：熟悉项目架构 🏗️ +**📁 项目文件结构总览** + ``` -项目根目录/ -├── src/ # 源代码目录 -│ ├── business/ # 业务功能模块（按功能组织） -│ │ ├── auth/ # 🔐 用户认证模块 -│ │ ├── user-mgmt/ # 👥 用户管理模块 -│ │ ├── admin/ # 🛡️ 管理员模块 -│ │ ├── security/ # 🔒 安全模块 -│ │ └── shared/ # 🔗 共享组件 -│ ├── core/ # 核心技术服务 -│ │ ├── db/ # 数据库层（支持MySQL/内存双模式） -│ │ ├── redis/ # Redis缓存服务（支持真实Redis/文件存储） -│ │ ├── login_core/ # 登录核心服务 -│ │ ├── admin_core/ # 管理员核心服务 -│ │ └── utils/ # 工具服务（邮件、验证码、日志） -│ ├── app.module.ts # 应用主模块 -│ └── main.ts # 应用入口 -├── client/ # 前端管理界面 -├── docs/ # 项目文档 -├── test/ # 测试文件 -├── redis-data/ # Redis文件存储数据 -├── logs/ # 日志文件 -└── 配置文件 # .env, package.json, tsconfig.json等 +whale-town-end/ # 🐋 项目根目录 +├── 📂 src/ # 源代码目录 +│ ├── 📂 business/ # 🎯 业务功能模块（按功能组织） +│ │ ├── 📂 auth/ # 🔐 用户认证模块 +│ │ ├── 📂 user-mgmt/ # 👥 用户管理模块 +│ │ ├── 📂 admin/ # 🛡️ 管理员模块 +│ │ ├── 📂 security/ # 🔒 安全防护模块 +│ │ ├── 📂 zulip/ # 💬 Zulip集成模块 +│ │ └── 📂 shared/ # 🔗 共享业务组件 +│ ├── 📂 core/ # ⚙️ 核心技术服务 +│ │ ├── 📂 db/ # 🗄️ 数据库层（MySQL/内存双模式） +│ │ ├── 📂 redis/ # 🔴 Redis缓存（真实Redis/文件存储） +│ │ ├── 📂 login_core/ # 🔑 登录核心服务 +│ │ ├── 📂 admin_core/ # 👑 管理员核心服务 +│ │ ├── 📂 zulip/ # 💬 Zulip核心服务 +│ │ └── 📂 utils/ # 🛠️ 工具服务（邮件、验证码、日志） +│ ├── 📄 app.module.ts # 🏠 应用主模块 +│ └── 📄 main.ts # 🚀 应用入口点 +├── 📂 client/ # 🎨 前端管理界面 +│ ├── 📂 src/ # 前端源码 +│ ├── 📂 dist/ # 前端构建产物 +│ ├── 📄 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 # 📖 项目主文档（当前文件） ``` **架构特点：** diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b1b471e..514dca2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.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 │ │ -│ │ (REST) │ │ (Socket.IO) │ │ (预留) │ │ +│ │ Controllers │ │ WebSocket │ │ Swagger UI │ │ +│ │ (HTTP接口) │ │ Gateways │ │ (API文档) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ - │ + ⬇️ ┌─────────────────────────────────────────────────────────────┐ -│ 业务逻辑层 │ +│ 🎯 业务层 (Business) │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 用户认证 │ │ 游戏逻辑 │ │ 社交功能 │ │ -│ │ (Login) │ │ (Game) │ │ (Social) │ │ +│ │ Auth Module │ │ UserMgmt │ │ Admin Module │ │ +│ │ (用户认证) │ │ Module │ │ (管理员) │ │ +│ │ │ │ (用户管理) │ │ │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ Security Module │ │ Zulip Module │ │ Shared Module │ │ +│ │ (安全防护) │ │ (Zulip集成) │ │ (共享组件) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ - │ + ⬇️ ┌─────────────────────────────────────────────────────────────┐ -│ 核心服务层 │ +│ ⚙️ 服务层 (Service) │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 邮件服务 │ │ 验证码服务 │ │ 日志服务 │ │ -│ │ (Email) │ │ (Verification)│ │ (Logger) │ │ +│ │ Login Core │ │ Admin Core │ │ Zulip Core │ │ +│ │ (登录核心) │ │ (管理员核心) │ │ (Zulip核心) │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ Email Service │ │ Verification │ │ Logger Service │ │ +│ │ (邮件服务) │ │ Service │ │ (日志服务) │ │ +│ │ │ │ (验证码服务) │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ - │ + ⬇️ ┌─────────────────────────────────────────────────────────────┐ -│ 数据访问层 │ +│ 🗄️ 数据层 (Data) │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 用户数据 │ │ Redis缓存 │ │ 文件存储 │ │ -│ │ (Users) │ │ (Cache) │ │ (Files) │ │ +│ │ Users Service │ │ Redis Service │ │ File Storage │ │ +│ │ (用户数据) │ │ (缓存服务) │ │ (文件存储) │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ MySQL/Memory │ │ Redis/File │ │ Logs/Data │ │ +│ │ (数据库) │ │ (缓存实现) │ │ (日志数据) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` -## 模块依赖关系 +### 🔄 数据流向 + +#### 用户注册流程示例 ``` -AppModule -├── ConfigModule (全局配置) -├── LoggerModule (日志系统) -├── RedisModule (缓存服务) -├── UsersModule (用户管理) -│ ├── UsersService (数据库模式) -│ └── UsersMemoryService (内存模式) -├── EmailModule (邮件服务) -├── VerificationModule (验证码服务) -├── LoginCoreModule (登录核心) -└── LoginModule (登录业务) +1. 📱 用户请求 → AuthController.register() +2. 🔍 参数验证 → class-validator装饰器 +3. 🎯 业务逻辑 → AuthService.register() +4. ⚙️ 核心服务 → LoginCoreService.createUser() +5. 📧 发送邮件 → EmailService.sendVerificationCode() +6. 🔢 生成验证码 → VerificationService.generate() +7. 💾 存储数据 → UsersService.create() + RedisService.set() +8. 📝 记录日志 → LoggerService.log() +9. ✅ 返回响应 → 用户收到成功响应 ``` -## 数据流向 +#### 管理员操作流程示例 -### 用户注册流程 ``` -1. 用户请求 → LoginController -2. 参数验证 → LoginService -3. 发送验证码 → LoginCoreService -4. 生成验证码 → VerificationService -5. 发送邮件 → EmailService -6. 存储验证码 → RedisService -7. 返回响应 → 用户 +1. 🛡️ 管理员请求 → AdminController.resetUserPassword() +2. 🔐 权限验证 → AdminGuard.canActivate() +3. 🎯 业务逻辑 → AdminService.resetPassword() +4. ⚙️ 核心服务 → AdminCoreService.resetUserPassword() +5. 🔑 密码加密 → bcrypt.hash() +6. 💾 更新数据 → UsersService.update() +7. 📧 通知用户 → EmailService.sendPasswordReset() +8. 📝 审计日志 → LoggerService.audit() +9. ✅ 返回响应 → 管理员收到操作结果 ``` -### 双模式架构 +--- -项目支持开发测试模式和生产部署模式的无缝切换： +## 🔄 双模式架构 -#### 开发测试模式 -- **数据库**: 内存存储 (UsersMemoryService) -- **缓存**: 文件存储 (FileRedisService) -- **邮件**: 控制台输出 (测试模式) -- **优势**: 无需外部依赖，快速启动测试 +### 🎯 设计目标 -#### 生产部署模式 -- **数据库**: MySQL (UsersService + TypeORM) -- **缓存**: Redis (RealRedisService + IORedis) -- **邮件**: SMTP服务器 (生产模式) -- **优势**: 高性能，高可用，数据持久化 +- **开发测试**: 零依赖快速启动，无需安装MySQL、Redis等外部服务 +- **生产部署**: 高性能、高可用，支持集群和负载均衡 -## 设计原则 +### 📊 模式对比 -### 1. 单一职责原则 -每个模块只负责一个特定的功能领域： -- `LoginModule`: 只处理登录相关业务 -- `EmailModule`: 只处理邮件发送 -- `VerificationModule`: 只处理验证码逻辑 +| 功能模块 | 🧪 开发测试模式 | 🚀 生产部署模式 | +|----------|----------------|----------------| +| **数据库** | 内存存储 (UsersMemoryService) | MySQL (UsersService + TypeORM) | +| **缓存** | 文件存储 (FileRedisService) | Redis (RedisService + IORedis) | +| **邮件** | 控制台输出 (测试模式) | SMTP服务器 (生产模式) | +| **日志** | 控制台 + 文件 | 结构化日志 + 日志轮转 | +| **配置** | `.env` 默认配置 | 环境变量 + 配置中心 | -### 2. 依赖注入 -使用NestJS的依赖注入系统： -- 接口抽象: `IRedisService`, `IUsersService` -- 实现切换: 根据配置自动选择实现类 -- 测试友好: 易于Mock和单元测试 +### ⚙️ 模式切换配置 -### 3. 配置驱动 -通过环境变量控制行为： -- `USE_FILE_REDIS`: 选择Redis实现 -- `DB_HOST`: 数据库连接配置 -- `EMAIL_HOST`: 邮件服务配置 +#### 开发测试模式 (.env) +```bash +# 数据存储模式 +USE_FILE_REDIS=true # 使用文件存储代替Redis +NODE_ENV=development # 开发环境 -### 4. 错误处理 -统一的错误处理机制： -- HTTP异常: `BadRequestException`, `UnauthorizedException` -- 业务异常: 自定义异常类 -- 日志记录: 结构化错误日志 +# 数据库配置（注释掉，使用内存数据库） +# DB_HOST=localhost +# 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 - nest g module business/game - nest g controller business/game - nest g service business/game - ``` +# 数据库配置 +DB_HOST=your_mysql_host +DB_PORT=3306 +DB_USERNAME=your_username +DB_PASSWORD=your_password +DB_DATABASE=whale_town -2. **创建核心服务** - ```bash - nest g module core/game_core - nest g service core/game_core - ``` +# Redis配置 +REDIS_HOST=your_redis_host +REDIS_PORT=6379 +REDIS_PASSWORD=your_redis_password -3. **添加数据模型** - ```bash - nest g module core/db/games - nest g service core/db/games - ``` +# 邮件配置 +EMAIL_HOST=smtp.gmail.com +EMAIL_PORT=587 +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('USE_FILE_REDIS'); + return useFileRedis + ? new FileRedisService() + : new RedisService(configService); + }, + inject: [ConfigService], + }, + ], +}) +export class RedisModule {} +``` -1. **创建工具模块** - ```bash - nest g module core/utils/notification - nest g service core/utils/notification - ``` +#### 配置驱动服务选择 +```typescript +// users.module.ts +@Module({ + providers: [ + { + provide: 'IUsersService', + useFactory: (configService: ConfigService) => { + const dbHost = configService.get('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; + sendSMS(phone: string, message: string): Promise; +} +``` + +#### 3. 实现服务 +```typescript +// src/core/utils/notification/notification.service.ts +@Injectable() +export class NotificationService implements INotificationService { + async sendPush(userId: string, message: string): Promise { + // 实现推送通知逻辑 + } + + async sendSMS(phone: string, message: string): Promise { + // 实现短信发送逻辑 + } +} +``` + +#### 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; + + beforeEach(async () => { + const module: TestingModule = await Test.createTestingModule({ + providers: [ + GameService, + { + provide: 'IGameCoreService', + useValue: { + createGame: jest.fn(), + }, + }, + ], + }).compile(); + + service = module.get(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缓存**: 静态资源文件 -### 2. 数据库优化 -- **连接池**: 复用数据库连接 -- **索引优化**: 关键字段建立索引 -- **查询优化**: 避免N+1查询问题 +#### 2. 数据库优化 +- **连接池**: 复用数据库连接，减少连接开销 +- **索引优化**: 为查询字段建立合适的索引 +- **查询优化**: 避免N+1查询，使用JOIN优化关联查询 -### 3. 日志优化 -- **异步日志**: 使用Pino的异步写入 -- **日志分级**: 生产环境只记录必要日志 +#### 3. 日志优化 +- **异步日志**: 使用Pino的异步写入功能 +- **日志分级**: 生产环境只记录ERROR和WARN级别 - **日志轮转**: 自动清理过期日志文件 -## 安全考虑 +### 🔒 安全加固建议 -### 1. 数据验证 -- **输入验证**: class-validator装饰器 -- **类型检查**: TypeScript静态类型 -- **SQL注入**: TypeORM参数化查询 +#### 1. 数据验证 +- **输入验证**: 使用class-validator进行严格验证 +- **类型检查**: TypeScript静态类型检查 +- **SQL注入防护**: TypeORM参数化查询 -### 2. 认证授权 -- **密码加密**: bcrypt哈希算法 -- **会话管理**: Redis存储会话信息 -- **权限控制**: 基于角色的访问控制 +#### 2. 认证授权 +- **密码安全**: bcrypt加密，强密码策略 +- **会话管理**: JWT + Redis会话存储 +- **权限控制**: 基于角色的访问控制(RBAC) -### 3. 通信安全 +#### 3. 通信安全 - **HTTPS**: 生产环境强制HTTPS -- **CORS**: 跨域请求控制 -- **Rate Limiting**: API请求频率限制 \ No newline at end of file +- **CORS**: 严格的跨域请求控制 +- **Rate Limiting**: API请求频率限制 + +--- + +**🏗️ 通过清晰的架构设计，Whale Town 实现了高内聚、低耦合的模块化架构，支持快速开发和灵活部署！** \ No newline at end of file diff --git a/docs/DOCUMENT_CLEANUP.md b/docs/DOCUMENT_CLEANUP.md new file mode 100644 index 0000000..5a0df87 --- /dev/null +++ b/docs/DOCUMENT_CLEANUP.md @@ -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个（所有文件都有价值） \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index c471c23..33ba129 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,7 +27,7 @@ ### 📋 **项目管理** - [贡献指南](CONTRIBUTORS.md) - 如何参与项目贡献 -- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护记录 +- [文档清理说明](DOCUMENT_CLEANUP.md) - 文档维护和优化记录 ## 🏗️ **文档结构说明**