refactor:重构安全模块架构,将security模块迁移至core层

- 将src/business/security模块迁移至src/core/security_core
- 更新模块导入路径和依赖关系
- 统一安全相关组件的命名规范(content_type.middleware.ts)
- 清理过时的配置文件和文档
- 更新架构文档以反映新的模块结构

此次重构符合业务功能模块化架构设计原则,将技术基础设施
服务统一放置在core层,提高代码组织的清晰度和可维护性。
This commit is contained in:
moyin
2026-01-04 19:34:16 +08:00
parent 67ade48ad7
commit 70c020a97c
25 changed files with 174 additions and 1215 deletions

View File

@@ -25,6 +25,29 @@ Whale Town 采用**业务功能模块化架构**,将代码按业务功能而
- **模块化设计** - 每个模块独立完整,可单独测试和部署
- **配置驱动** - 通过环境变量控制运行模式和行为
### 🛠️ 技术栈
#### 后端技术栈
- **框架**: NestJS 11.x (基于Express)
- **语言**: TypeScript 5.x
- **数据库**: MySQL + TypeORM (生产) / 内存数据库 (开发)
- **缓存**: Redis + IORedis (生产) / 文件存储 (开发)
- **认证**: JWT + bcrypt
- **验证**: class-validator + class-transformer
- **文档**: Swagger/OpenAPI
- **测试**: Jest + Supertest
- **日志**: Pino + nestjs-pino
- **WebSocket**: Socket.IO
- **邮件**: Nodemailer
- **集成**: Zulip API
#### 前端技术栈
- **框架**: React 18.x
- **构建工具**: Vite 7.x
- **UI库**: Ant Design 5.x
- **路由**: React Router DOM 6.x
- **语言**: TypeScript 5.x
### 📊 整体架构图
```
@@ -40,11 +63,11 @@ Whale Town 采用**业务功能模块化架构**,将代码按业务功能而
│ 🎯 业务功能模块层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔐 用户认证 │ │ 👥 用户管理 │ │ 🛡️ 管理员 │ │
│ │ (auth) │ │ (user-mgmt) │ │ (admin) │ │
│ │ (auth) │ │ (user_mgmt) │ │ (admin) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔒 安全防护 │ │ 💬 Zulip集成 │ │ 🔗 共享组件 │ │
│ │ (security) │ │ (zulip) │ │ (shared) │ │
│ │ 💬 Zulip集成 │ │ 🔗 共享组件 │ │ │
│ │ (zulip) │ │ (shared) │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
⬇️
@@ -52,11 +75,11 @@ Whale Town 采用**业务功能模块化架构**,将代码按业务功能而
│ ⚙️ 核心技术服务层 │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔑 登录核心 │ │ 👑 管理员核心 │ │ 💬 Zulip核心 │ │
│ │ (login_core) │ │ (admin_core) │ │ (zulip) │ │
│ │ (auth_core) │ │ (admin_core) │ │ (zulip) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🛠 工具服务 │ │ 📧 邮件服务 │ │ 📝 日志服务 │ │
│ │ (utils) │ │ (email) │ │ (logger) │
│ │ 🛡 安全核心 │ │ 🛠️ 工具服务 │ │ 📧 邮件服务 │ │
│ │ (security_core)│ │ (utils) │ │ (email) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
⬇️
@@ -80,56 +103,50 @@ Whale Town 采用**业务功能模块化架构**,将代码按业务功能而
```
src/business/
├── 📂 auth/ # 🔐 用户认证模块
│ ├── 📄 auth.controller.ts # HTTP接口控制器
│ ├── 📄 auth.service.ts # 业务逻辑服务
│ ├── 📄 auth.module.ts # 模块定义
│ ├── 📂 controllers/ # 控制器
│ │ └── 📄 login.controller.ts # 登录接口控制器
│ ├── 📂 services/ # 业务服务
│ │ ├── 📄 login.service.ts # 登录业务逻辑
│ │ └── 📄 login.service.spec.ts # 登录服务测试
│ ├── 📂 dto/ # 数据传输对象
│ │ ├── 📄 login.dto.ts # 登录请求DTO
│ │ ── 📄 register.dto.ts # 注册请求DTO
│ └── 📄 reset-password.dto.ts # 重置密码DTO
│ └── 📂 __tests__/ # 单元测试
│ └── 📄 auth.service.spec.ts
│ │ ── 📄 login_response.dto.ts # 登录响应DTO
│ └── 📂 guards/ # 权限守卫(预留)
├── 📂 user-mgmt/ # 👥 用户管理模块
│ ├── 📄 user-mgmt.controller.ts # 用户管理接口
│ ├── 📄 user-mgmt.service.ts # 用户状态管理逻辑
│ ├── 📄 user-mgmt.module.ts # 模块定义
│ ├── 📂 controllers/ # 控制器
│ │ └── 📄 user-status.controller.ts # 用户状态管理接口
│ ├── 📂 services/ # 业务服务
│ │ └── 📄 user-management.service.ts # 用户管理逻辑
│ ├── 📂 dto/ # 数据传输对象
│ │ ├── 📄 update-status.dto.ts # 状态更新DTO
│ │ └── 📄 batch-status.dto.ts # 批量操作DTO
── 📂 enums/ # 枚举定义
└── 📄 user-status.enum.ts # 用户状态枚举
│ │ ├── 📄 user-status.dto.ts # 用户状态DTO
│ │ └── 📄 user-status-response.dto.ts # 状态响应DTO
── 📂 enums/ # 枚举定义
└── 📄 user-status.enum.ts # 用户状态枚举
│ └── 📂 tests/ # 测试文件(预留)
├── 📂 admin/ # 🛡️ 管理员模块
│ ├── 📄 admin.controller.ts # 管理员接口
│ ├── 📄 admin.service.ts # 管理员业务逻辑
│ ├── 📄 admin.module.ts # 模块定义
│ ├── 📄 admin.service.spec.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 # 模块定义
│ ├── 📂 interfaces/ # 接口定义
│ └── 📂 services/ # 子服务
│ ├── 📄 message_filter.service.ts # 消息过滤
│ └── 📄 session_cleanup.service.ts # 会话清理
└── 📂 shared/ # 🔗 共享业务组件
├── 📂 decorators/ # 装饰器
── 📂 pipes/ # 管道
├── 📂 filters/ # 异常过滤器
└── 📂 interfaces/ # 接口定义
├── 📂 dto/ # 共享数据传输对象
── 📄 index.ts # 导出文件
```
### ⚙️ 核心技术服务 (`src/core/`)
@@ -139,72 +156,84 @@ src/business/
```
src/core/
├── 📂 db/ # 🗄️ 数据库层
── 📄 db.module.ts # 数据库模块
│ ├── 📂 users/ # 用户数据服务
├── 📄 users.service.ts # MySQL数据库实现
├── 📄 users-memory.service.ts # 内存数据库实现
├── 📄 users.interface.ts # 用户服务接口
── 📄 user.entity.ts # 用户实体定义
└── 📂 entities/ # 数据库实体
│ └── 📄 *.entity.ts # 各种实体定义
── 📂 users/ # 用户数据服务
├── 📄 users.service.ts # MySQL数据库实现
├── 📄 users_memory.service.ts # 内存数据库实现
├── 📄 users.dto.ts # 用户数据传输对象
├── 📄 users.entity.ts # 用户实体定义
── 📄 users.module.ts # 用户数据模块
└── 📄 users.service.spec.ts # 用户服务测试
├── 📂 redis/ # 🔴 Redis缓存层
│ ├── 📄 redis.module.ts # Redis模块
│ ├── 📄 redis.service.ts # Redis真实实现
│ ├── 📄 real-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 # 接口定义
│ ├── 📄 login_core.service.ts # 登录核心逻辑
│ ├── 📄 login_core.module.ts # 模块定义
│ └── 📄 login_core.service.spec.ts # 登录核心测试
├── 📂 admin_core/ # 👑 管理员核心服务
│ ├── 📄 admin-core.service.ts # 管理员核心逻辑
│ ├── 📄 admin-core.module.ts # 模块定义
│ └── 📄 admin-core.interface.ts # 接口定义
│ ├── 📄 admin_core.service.ts # 管理员核心逻辑
│ ├── 📄 admin_core.module.ts # 模块定义
│ └── 📄 admin_core.service.spec.ts # 管理员核心测试
├── 📂 zulip/ # 💬 Zulip核心服务
│ ├── 📄 zulip-core.module.ts # Zulip核心模块
│ ├── 📄 zulip-api.service.ts # Zulip API服务
── 📄 zulip-websocket.service.ts # WebSocket服务
│ ├── 📂 config/ # 配置文件
── 📂 interfaces/ # 接口定义
│ ├── 📂 services/ # 核心服务
│ ├── 📂 types/ # 类型定义
│ └── 📄 index.ts # 导出文件
├── 📂 security_core/ # 🛡️ 安全核心模块
│ ├── 📄 security_core.module.ts # 安全模块定义
│ ├── 📂 guards/ # 安全守卫
│ │ └── 📄 throttle.guard.ts # 频率限制守卫
│ ├── 📂 interceptors/ # 拦截器
│ │ └── 📄 timeout.interceptor.ts # 超时拦截器
│ ├── 📂 middleware/ # 中间件
│ │ ├── 📄 maintenance.middleware.ts # 维护模式中间件
│ │ └── 📄 content_type.middleware.ts # 内容类型中间件
│ └── 📂 decorators/ # 装饰器
│ ├── 📄 throttle.decorator.ts # 频率限制装饰器
│ └── 📄 timeout.decorator.ts # 超时装饰器
└── 📂 utils/ # 🛠️ 工具服务
├── 📂 email/ # 📧 邮件服务
│ ├── 📄 email.service.ts # 邮件发送服务
│ ├── 📄 email.module.ts # 邮件模块
│ └── 📄 email.interface.ts # 邮件接口
│ └── 📄 email.service.spec.ts # 邮件服务测试
├── 📂 verification/ # 🔢 验证码服务
│ ├── 📄 verification.service.ts # 验证码生成验证
── 📄 verification.module.ts # 验证码模块
── 📄 verification.module.ts # 验证码模块
│ └── 📄 verification.service.spec.ts # 验证码服务测试
└── 📂 logger/ # 📝 日志服务
├── 📄 logger.service.ts # 日志记录服务
── 📄 logger.module.ts # 日志模块
── 📄 logger.module.ts # 日志模块
├── 📄 logger.config.ts # 日志配置
└── 📄 log_management.service.ts # 日志管理服务
```
### 🎨 前端管理界面 (`client/`)
> **设计原则**: 独立的前端项目,提供管理员后台功能
> **设计原则**: 独立的前端项目,提供管理员后台功能基于React + Vite + Ant Design
```
client/
├── 📂 src/ # 前端源码
│ ├── 📂 components/ # 用组件
│ │ ├── 📄 Layout.tsx # 布局组件
│ │ ── 📄 UserTable.tsx # 用户表格组件
│ │ └── 📄 LogViewer.tsx # 日志查看组件
│ ├── 📂 app/ # 用组件
│ │ ├── 📄 App.tsx # 应用主组件
│ │ ── 📄 AdminLayout.tsx # 管理员布局组件
│ ├── 📂 pages/ # 页面组件
│ │ ├── 📄 Login.tsx # 登录页面
│ │ ├── 📄 Dashboard.tsx # 仪表板
│ │ ── 📄 UserManagement.tsx # 用户管理
│ └── 📄 LogManagement.tsx # 日志管理
│ ├── 📂 services/ # API服务
│ │ ├── 📄 LoginPage.tsx # 登录页面
│ │ ├── 📄 UsersPage.tsx # 用户管理页面
│ │ ── 📄 LogsPage.tsx # 日志管理页面
├── 📂 lib/ # 工具库
│ │ ├── 📄 api.ts # API客户端
│ │ ── 📄 auth.ts # 认证服务
│ │ └── 📄 users.ts # 用户服务
│ ├── 📂 utils/ # 工具函数
│ ├── 📂 types/ # TypeScript类型
│ ├── 📄 App.tsx # 应用主组件
│ │ ── 📄 adminAuth.ts # 管理员认证服务
│ └── 📄 main.tsx # 应用入口
├── 📂 dist/ # 构建产物
├── 📄 package.json # 前端依赖
@@ -220,21 +249,17 @@ client/
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测试集合
── 📄 api-documentation.md # 完整API接口文档
├── 📂 development/ # 💻 开发指南
│ ├── 📄 backend_development_guide.md # 后端开发规范
│ ├── 📄 git_commit_guide.md # Git提交规范
│ ├── 📄 AI辅助开发规范指南.md # AI辅助开发指南
── 📄 TESTING.md # 测试指南
│ └── 📄 naming_convention.md # 命名规范
── 📄 TESTING.md # 测试指南
└── 📂 deployment/ # 🚀 部署文档
└── 📄 DEPLOYMENT.md # 生产环境部署指南
@@ -261,14 +286,17 @@ test/
├── 📄 .env # 🔧 环境变量配置
├── 📄 .env.example # 🔧 环境变量示例
├── 📄 .env.production.example # 🔧 生产环境示例
├── 📄 package.json # 📋 项目依赖配置
├── 📄 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进程管理配置
client/
├── 📄 package.json # 📋 前端项目依赖配置
├── 📄 vite.config.ts # ⚡ Vite构建配置
└── 📄 tsconfig.json # 📘 前端TypeScript配置
```
---
@@ -327,18 +355,17 @@ test/
### 🔄 数据流向
#### 用户注册流程示例
#### 用户登录流程示例
```
1. 📱 用户请求 → AuthController.register()
1. 📱 用户请求 → LoginController.login()
2. 🔍 参数验证 → class-validator装饰器
3. 🎯 业务逻辑 → AuthService.register()
4. ⚙️ 核心服务 → LoginCoreService.createUser()
5. 📧 发送邮件 → EmailService.sendVerificationCode()
6. 🔢 生成验证码 → VerificationService.generate()
7. 💾 存储数据 → UsersService.create() + RedisService.set()
8. 📝 记录日志 → LoggerService.log()
9. ✅ 返回响应 → 用户收到成功响应
3. 🎯 业务逻辑 → LoginService.login()
4. ⚙️ 核心服务 → LoginCoreService.validateUser()
5. 📧 发送验证码 → VerificationService.generate()
6. 💾 存储数据 → UsersService.findByEmail() + RedisService.set()
7. 📝 记录日志 → LoggerService.log()
8. ✅ 返回响应 → 用户收到登录结果
```
#### 管理员操作流程示例
@@ -369,7 +396,7 @@ test/
| 功能模块 | 🧪 开发测试模式 | 🚀 生产部署模式 |
|----------|----------------|----------------|
| **数据库** | 内存存储 (UsersMemoryService) | MySQL (UsersService + TypeORM) |
| **缓存** | 文件存储 (FileRedisService) | Redis (RedisService + IORedis) |
| **缓存** | 文件存储 (FileRedisService) | Redis (RealRedisService + IORedis) |
| **邮件** | 控制台输出 (测试模式) | SMTP服务器 (生产模式) |
| **日志** | 控制台 + 文件 | 结构化日志 + 日志轮转 |
| **配置** | `.env` 默认配置 | 环境变量 + 配置中心 |
@@ -431,7 +458,7 @@ EMAIL_PASS=your_app_password
const useFileRedis = configService.get<boolean>('USE_FILE_REDIS');
return useFileRedis
? new FileRedisService()
: new RedisService(configService);
: new RealRedisService(configService);
},
inject: [ConfigService],
},
@@ -471,7 +498,7 @@ AppModule (应用主模块)
├── 📊 ConfigModule (全局配置)
├── 📝 LoggerModule (日志系统)
├── 🔴 RedisModule (缓存服务)
│ ├── RedisService (真实Redis)
│ ├── RealRedisService (真实Redis)
│ └── FileRedisService (文件存储)
├── 🗄️ UsersModule (用户数据)
│ ├── UsersService (MySQL数据库)
@@ -481,16 +508,15 @@ AppModule (应用主模块)
├── 🔑 LoginCoreModule (登录核心)
├── 👑 AdminCoreModule (管理员核心)
├── 💬 ZulipCoreModule (Zulip核心)
├── 🔒 SecurityCoreModule (安全核心)
├── 🎯 业务功能模块
│ ├── 🔐 AuthModule (用户认证)
│ │ └── 依赖: LoginCoreModule, EmailModule, VerificationModule
│ │ └── 依赖: LoginCoreModule, EmailModule, VerificationModule, SecurityCoreModule
│ ├── 👥 UserMgmtModule (用户管理)
│ │ └── 依赖: UsersModule, LoggerModule
│ │ └── 依赖: UsersModule, LoggerModule, SecurityCoreModule
│ ├── 🛡️ AdminModule (管理员)
│ │ └── 依赖: AdminCoreModule, UsersModule
│ ├── 🔒 SecurityModule (安全防护)
│ │ └── 依赖: RedisModule, LoggerModule
│ │ └── 依赖: AdminCoreModule, UsersModule, SecurityCoreModule
│ ├── 💬 ZulipModule (Zulip集成)
│ │ └── 依赖: ZulipCoreModule, RedisModule
│ └── 🔗 SharedModule (共享组件)
@@ -500,7 +526,7 @@ AppModule (应用主模块)
#### 用户认证流程
```
AuthController → AuthService → LoginCoreService
AuthController → LoginService → LoginCoreService
EmailService ← VerificationService ← RedisService