From ff996b0dea237cc2549b86d4117b52638408ed18 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Wed, 14 Jan 2026 15:11:54 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs=EF=BC=9A=E4=BC=98=E5=8C=96README?= =?UTF-8?q?=E4=B8=AD=E7=9A=84AI=E4=BB=A3=E7=A0=81=E6=A3=80=E6=9F=A5?= =?UTF-8?q?=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将快速开始改为简洁的prompt模板 - 移除详细的检查步骤列表 - 简化使用说明，突出AI自动化流程 - 保留文档链接供开发者查看详细规范 --- README.md | 490 ++++++++++++++---------------------------------------- 1 file changed, 122 insertions(+), 368 deletions(-) diff --git a/README.md b/README.md index 1768a65..f8c0ebc 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,30 @@ # 🐋 Whale Town - 像素游戏后端服务 -> 一个基于 NestJS 的现代化 2D 像素风游戏后端服务，采用业务功能模块化架构，支持用户认证、管理员后台、安全防护等完整功能。 +> 基于 NestJS 的现代化 2D 像素游戏后端，采用四层架构（Gateway-Business-Core-Data），支持用户认证、实时通信、Zulip集成、管理员后台。 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/) [![NestJS](https://img.shields.io/badge/NestJS-11.1-red.svg)](https://nestjs.com/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/) -[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) +[![React](https://img.shields.io/badge/React-18.3-61dafb.svg)](https://reactjs.org/) +[![Tests](https://img.shields.io/badge/Tests-99%20passing-brightgreen.svg)](#) -## 🎯 项目简介 +## 🎯 核心特性 -Whale Town 是一个功能完整的像素游戏后端服务，采用业务功能模块化架构设计： - -- 🔐 **用户认证模块** - 完整的登录、注册、密码管理、邮箱验证系统 -- 👥 **用户管理模块** - 用户状态管理、批量操作、状态统计功能 -- 🛡️ **管理员模块** - 管理员认证、用户管理、密码重置、日志查看 -- 🔒 **安全模块** - 频率限制、维护模式、超时控制、内容类型检查 -- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换 -- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试 -- 📚 **完整API文档** - Swagger UI + OpenAPI规范，17个接口完整覆盖 -- 🧪 **全面测试覆盖** - 140个单元测试用例全部通过 - ---- +- 🔐 用户认证：多方式登录、验证码登录、GitHub OAuth +- 🌐 实时通信：原生WebSocket、位置广播、地图房间管理 +- 💬 Zulip集成：游戏内聊天与Zulip社群双向同步 +- 👑 管理员后台：React界面、用户管理、日志监控 +- 🛡️ 安全防护：频率限制、维护模式、JWT认证 +- 🗄️ 灵活存储：MySQL/内存双模式、Redis/文件双模式 +- 📚 完整文档：Swagger UI、WebSocket测试工具 ## 🚀 快速开始 -### 📋 环境要求 +### 环境要求 +- Node.js >= 18.0.0 +- pnpm >= 8.0.0 -- **Node.js** >= 18.0.0 (推荐 24.7.0) -- **pnpm** >= 8.0.0 (推荐 10.25.0) - -### 🛠️ 安装与运行 +### 安装运行 ```bash # 1. 克隆项目 @@ -39,432 +34,191 @@ cd whale-town-end # 2. 安装依赖 pnpm install -# 3. 配置环境（测试模式，无需数据库和邮件服务器） +# 3. 配置环境（测试模式，无需数据库） cp .env.example .env -# 4. 启动开发服务器 +# 4. 启动服务 pnpm run dev ``` -🎉 **服务启动成功！** 访问 http://localhost:3000 +访问：http://localhost:3000 -### 🧑‍💻 前端管理界面 - -项目包含一个功能完整的前端管理界面，位于 `client/` 目录： - -**🎛️ 核心功能：** -- 管理员身份认证（独立Token系统） -- 用户列表管理与搜索 -- 用户密码重置功能 -- 运行时日志查看与下载 -- 响应式界面设计 - -**🚀 快速启动：** +### 前端管理界面 ```bash -# 1. 启动后端服务 -pnpm run dev - -# 2. 启动前端管理界面 +# 启动管理后台 cd client pnpm install pnpm run dev - -# 3. 访问管理后台 -# 地址: http://localhost:5173 -# 默认账号: admin / Admin123456 ``` -### 🧪 快速测试 +访问：http://localhost:5173 +默认账号：admin / Admin123456 -```bash -# 运行综合测试（推荐） -.\test-comprehensive.ps1 +### 在线体验 -# 跳过限流测试（更快） -.\test-comprehensive.ps1 -SkipThrottleTest +- API文档：https://whaletownend.xinghangee.icu/api-docs +- WebSocket测试：https://whaletownend.xinghangee.icu/websocket-test -# 测试远程服务器 -.\test-comprehensive.ps1 -BaseUrl "https://your-server.com" -``` +## 🏗️ 项目架构 -**测试内容：** -- ✅ 应用状态检查 -- ✅ 邮箱验证码发送与验证 -- ✅ 用户注册与登录 -- ✅ 验证码登录功能 -- ✅ 密码重置流程 -- ✅ 邮箱冲突检测 -- ✅ 验证码冷却时间清除 -- ✅ 限流保护机制 -- ✅ Redis文件存储功能 -- ✅ 邮件测试模式 - ---- - -## 🎓 新开发者指南 - -### 第一步：了解项目规范 📚 - -**⚠️ 重要：在开始开发前，请务必阅读以下文档** - -1. **[AI辅助开发规范指南](./docs/AI辅助开发规范指南.md)** 🤖 - - 学会使用AI助手提升开发效率300% - - 自动生成符合规范的代码和注释 - - 实时检查代码质量 - -2. **[后端开发规范](./docs/backend_development_guide.md)** 📝 - - 代码注释标准 - - 业务逻辑设计原则 - - 日志记录要求 - -3. **[Git提交规范](./docs/git_commit_guide.md)** 🔄 - - 提交信息格式 - - 分支管理策略 - -### 第二步：熟悉项目架构 🏗️ - -**📁 项目文件结构总览** +### 四层架构设计 ``` -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 # 📖 项目主文档（当前文件） +Gateway Layer (网关层) + ↓ HTTP/WebSocket协议处理、数据验证 +Business Layer (业务层) + ↓ 业务逻辑实现、服务协调 +Core Layer (核心层) + ↓ 技术基础设施、数据访问 +Data Layer (数据层) + ↓ 数据持久化、缓存管理 ``` -**架构特点：** -- 🏗️ **业务功能模块化** - 按业务功能而非技术组件组织代码 -- 🔄 **双模式支持** - 开发测试模式 + 生产部署模式 -- 📦 **清晰分层** - 业务层 → 核心层 → 数据层 -- 🧪 **测试友好** - 完整的单元测试和集成测试覆盖 +### 目录结构 -### 第三步：体验核心功能 🎮 +``` +whale-town-end/ +├── src/ +│ ├── gateway/ # 网关层：auth, location_broadcast +│ ├── business/ # 业务层：auth, user_mgmt, admin, zulip, notice +│ ├── core/ # 核心层：db, redis, login_core, admin_core, utils +│ ├── app.module.ts +│ └── main.ts +├── client/ # React管理界面 +├── docs/ # 项目文档 +├── test/ # 测试文件 +└── config/ # 配置文件 +``` -1. **API文档系统** 📖 - ```bash - # 启动服务后访问 - http://localhost:3000/api-docs - ``` - -2. **用户认证系统** 🔐 - - 邮箱验证码注册 - - 多方式登录（用户名/邮箱/手机号） - - 密码重置功能 - -3. **实时通信** 🌐 - - WebSocket支持 - - Socket.IO集成 - -### 第四步：开始贡献 🤝 - -1. **Fork项目** 到你的Gitea账户 -2. **创建功能分支**：`git checkout -b feature/your-feature` -3. **遵循规范开发**（使用AI助手帮助） -4. **提交代码**：`git commit -m "feat：添加新功能"` -5. **创建Pull Request** - ---- +详细架构：[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) ## 🛠️ 技术栈 -### 🚀 核心框架 -- **NestJS** `^11.1.9` - 企业级Node.js框架，提供依赖注入、模块化等特性 -- **TypeScript** `^5.9.3` - 类型安全的JavaScript超集 -- **Express** `^10.4.20` - 基于Express的HTTP服务器 -- **RxJS** `^7.8.2` - 响应式编程库，处理异步数据流 +**后端：** NestJS 11 + TypeScript 5 + MySQL + Redis + WebSocket +**前端：** React 18 + Vite 7 + Ant Design 5 +**测试：** Jest + Supertest（99个测试用例） +**部署：** Docker + PM2 + Nginx -### 🌐 实时通信 -- **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集成 - -### 🧑‍💻 管理员后台（前端） -- **Vite** - 前端构建工具（本项目 admin dashboard 使用） -- **React** - 前端 UI 框架 -- **React Router** - 前端路由 -- **Ant Design** - 企业级 UI 组件库 - -### 📊 日志监控 -- **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** - 反向代理和负载均衡 - ---- - -## 🏗️ 核心功能 - -### 🔐 用户认证模块 (business/auth/) -- **多方式登录** - 用户名/邮箱/手机号 -- **邮箱验证** - 完整的验证码流程 -- **密码安全** - bcrypt加密 + 强度验证 -- **第三方登录** - GitHub OAuth支持 -- **密码管理** - 忘记密码、重置密码、修改密码 - -### 👥 用户管理模块 (business/user-mgmt/) -- **用户状态管理** - 6种状态控制（active、inactive、locked、banned、deleted、pending） -- **批量操作** - 批量修改用户状态 -- **状态统计** - 各状态用户数量统计 -- **状态变更日志** - 完整的审计日志 - -### 🛡️ 管理员模块 (business/admin/) -- **独立认证** - 专用Token系统，与用户系统隔离 -- **用户管理** - 用户列表、搜索、密码重置 -- **日志监控** - 实时日志查看、历史日志下载 -- **权限控制** - 管理员角色验证（role=9） - -### 🔒 安全模块 (business/security/) -- **频率限制** - 基于IP的请求频率控制 -- **维护模式** - 系统维护期间的访问控制 -- **内容类型验证** - HTTP请求内容类型检查 -- **超时控制** - 可配置的请求超时机制 - -### 📧 智能邮件服务 -- **测试模式** - 控制台输出，无需SMTP服务器 -- **生产模式** - 支持主流邮件服务商 -- **模板系统** - 验证码、欢迎邮件等模板 -- **自动切换** - 根据配置自动选择模式 - -### 🗄️ 灵活存储方案 -- **Redis文件存储** - 开发测试无需Redis服务器 -- **内存数据库** - 无需MySQL即可运行 -- **生产就绪** - 支持MySQL + Redis部署 -- **自动切换** - 根据配置自动选择存储方式 - -### 📚 完整API文档 -- **Swagger UI** - 交互式API文档 -- **OpenAPI规范** - 标准化接口描述 -- **Postman集合** - 可导入的测试集合 -- **实时更新** - 代码变更自动同步文档 - -### 🧪 全面测试覆盖 -- **单元测试** - 140个测试用例全部通过 -- **API测试** - 跨平台测试脚本 -- **集成测试** - 完整业务流程验证 -- **测试模式** - 无依赖快速测试 - ---- - -## 📊 开发与测试 - -### 🔧 开发命令 +## 📊 开发命令 ```bash -# 开发服务器（热重载） -pnpm run dev +# 开发 +pnpm run dev # 启动开发服务器 +pnpm run build # 构建项目 +pnpm run start:prod # 生产环境运行 -# 构建项目 -pnpm run build - -# 生产环境运行 -pnpm run start:prod - -# 代码检查 -pnpm run lint - -# 格式化代码 -pnpm run format +# 测试 +pnpm test # 运行单元测试 +pnpm run test:cov # 测试覆盖率 +.\test-comprehensive.ps1 # API功能测试 ``` -### 🧪 测试命令 +## 🌍 环境配置 +### 开发环境（默认） ```bash -# 运行所有单元测试 -pnpm test - -# 监听模式运行测试 -pnpm run test:watch - -# 生成测试覆盖率报告 -pnpm run test:cov - -# API功能测试（综合测试脚本） -.\test-comprehensive.ps1 -``` - -### 📈 测试覆盖率 - -- **单元测试**: 140个测试用例 ✅ -- **功能测试**: 用户认证、用户管理、管理员后台、安全防护 ✅ -- **集成测试**: 完整业务流程 ✅ - ---- - -## 🌍 部署配置 - -### 测试环境（默认） -```bash -# 无需数据库和邮件服务器 -USE_FILE_REDIS=true +USE_FILE_REDIS=true # 使用文件存储（无需Redis） 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 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 +# 邮件 +EMAIL_HOST=smtp.163.com +EMAIL_USER=your_email@163.com +EMAIL_PASS=your_password + +# Zulip +ZULIP_SERVER_URL=https://your-zulip.com/ +ZULIP_BOT_API_KEY=your_api_key ``` -详细部署指南：[DEPLOYMENT.md](./DEPLOYMENT.md) +详细配置：[docs/deployment/DEPLOYMENT.md](./docs/deployment/DEPLOYMENT.md) ---- +## 📚 文档 -## 📚 文档中心 +- [架构设计](./docs/ARCHITECTURE.md) - 四层架构详解 +- [开发规范](./docs/development/backend_development_guide.md) - 代码规范 +- [Git规范](./docs/development/git_commit_guide.md) - 提交规范 +- [API文档](http://localhost:3000/api-docs) - Swagger UI +- [测试指南](./docs/development/TESTING.md) - 测试说明 -### 🎯 新手必读 -1. **[AI辅助开发指南](./docs/AI辅助开发规范指南.md)** - 提升开发效率300% -2. **[后端开发规范](./docs/backend_development_guide.md)** - 代码质量标准 -3. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践 +### 🤖 AI代码检查指南 -### 📖 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)** - 测试集合 +项目提供了完整的AI辅助代码检查流程，帮助确保代码质量和规范性。 -### 🏗️ 系统设计 -- **[架构文档](./docs/ARCHITECTURE.md)** - 系统架构设计 -- **[部署指南](./docs/deployment/DEPLOYMENT.md)** - 生产环境部署 +**快速开始：** -### 🧪 测试指南 -- **[测试指南](./docs/development/TESTING.md)** - 完整测试说明 -- **[单元测试](./src/**/*.spec.ts)** - 测试用例参考 +向AI发送以下prompt开始代码检查： ---- +``` +请使用 docs/ai-reading 中readme的规范对 [模块路径] 进行完整的代码检查。 +``` -## 🤝 贡献者 +**如何使用：** +- AI会按照7个步骤逐步执行检查（命名规范、注释标准、代码质量、架构层级、测试覆盖、文档生成、代码提交） +- 每个步骤完成后会提供检查报告，等待确认后继续下一步 +- 如有问题会自动修复并重新验证 +- 这里建议每个步骤结束后，人工确认是否执行了修复，如果进行了修复，请告诉他：请重新执行一遍该步骤，看看是否有遗漏。 -感谢所有为项目做出贡献的开发者！ +详细说明：[docs/ai-reading/README.md](./docs/ai-reading/README.md) | 开发者规范：[docs/开发者代码检查规范.md](./docs/开发者代码检查规范.md) -### 🏆 核心团队 -- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者 -- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者 -- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者 +## 🤝 参与贡献 -查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md) +### 贡献流程 +1. Fork项目 +2. 创建分支：`git checkout -b feature/your-feature` +3. 开发功能（遵循开发规范） +4. 运行测试：`pnpm test` +5. 提交代码：`git commit -m "feat: 添加新功能"` +6. 创建Pull Request -### 🌟 如何贡献 +### 核心团队 +- [moyin](https://gitea.xinghangee.icu/moyin) +- [jianuo](https://gitea.xinghangee.icu/jianuo) +- [angjustinl](https://gitea.xinghangee.icu/ANGJustinl) -我们欢迎所有形式的贡献： +完整贡献者：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md) -1. **� Bug修复** - 发现并修复问题 -2. **✨ 新功能** - 添加有价值的功能 -3. **� 文档改馈进** - 完善项目文档 -4. **🧪 测试用例** - 提高代码覆盖率 -5. **💡 建议反馈** - 提出改进建议 +## 📝 版本历史 -**贡献流程：** -1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR +- **v2.1.0** (2026-01) - WebSocket架构升级、地图房间管理 +- **v2.0.0** (2025-12) - 四层架构重构、Zulip集成、管理员后台 +- **v1.2.0** (2025-11) - 用户管理、安全防护、邮件服务 +- **v1.0.0** (2025-10) - 项目初始化、用户认证、双模式存储 ---- +## 📞 联系方式 -## 📞 联系我们 - -- **项目地址**: [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) +- 项目地址：[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) 开源协议。 +[MIT License](./LICENSE) ---
-**🐋 Whale Town - 让像素世界更精彩！** +**🐋 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) -
\ No newline at end of file + -- 2.25.1 From cc1b081c3aae430409c504e3639095a09a8a3830 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Wed, 14 Jan 2026 15:12:15 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs=EF=BC=9A=E6=A0=B9=E6=8D=AEgit=E8=AE=B0?= =?UTF-8?q?=E5=BD=95=E6=9B=B4=E6=96=B0=E8=B4=A1=E7=8C=AE=E8=80=85=E5=90=8D?= =?UTF-8?q?=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新提交统计：moyin 166次，jianuo 10次，angjustinl 9次 - 调整贡献者排序，按提交数量重新组织 - 细化每位贡献者的具体工作内容 - 更新最新重要贡献（2026年1月的工作） - 重新整理项目里程碑，按时间倒序排列 - 修正文档链接路径 --- docs/CONTRIBUTORS.md | 214 +++++++++++++++++++++++++------------------ 1 file changed, 124 insertions(+), 90 deletions(-) diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md index 9e4f6a4..c533b32 100644 --- a/docs/CONTRIBUTORS.md +++ b/docs/CONTRIBUTORS.md @@ -4,116 +4,149 @@ ## 核心贡献者 +### � 项目维护者 + +**moyin** - 项目维护者 +- Gitea: [@moyin](https://gitea.xinghangee.icu/moyin) +- Email: xinghang_a@proton.me +- 提交数: **166 commits** (不含合并提交) +- 主要贡献： + - 🚀 **项目架构设计** - 四层架构（Gateway-Business-Core-Data）设计与实现 + - � **用户认证系统** - 完整的登录、注册、JWT认证、验证码登录 + - 📧 **邮箱验证系统** - 邮件服务、验证码服务、冷却时间机制 + - �️ **双模式架构** - Redis缓存（文件/真实）、用户服务（内存/数据库） + - � **API文档系统** - Swagger UI、OpenAPI规范、WebSocket文档 + - 🧪 **测试框架** - Jest配置、507+测试用例、集成测试、E2E测试 + - � **日志系统** - Pino高性能日志、结构化日志、日志管理 + - 🏗️ **架构重构** - Zulip模块重构、认证模块分层、安全模块迁移 + - 📚 **文档体系** - 架构文档、开发规范、AI代码检查指南、部署文档 + - 🎮 **游戏功能** - 位置广播系统、通知系统、地图房间管理 + - 🔧 **项目配置** - TypeScript配置、构建配置、环境配置、Docker部署 + - 🐛 **问题修复** - 验证码TTL重置、依赖注入、HTTP状态码、数据库管理 + ### 🌟 核心开发者 +**jianuo** - 核心开发者 +- Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo) +- Email: 32106500027@e.gzhu.edu.cn +- 提交数: **10 commits** (不含合并提交) +- 主要贡献： + - 🎛️ **管理员后台系统** - React前端界面、Ant Design组件、完整CRUD功能 + - 📊 **日志管理功能** - 运行时日志查看、日志下载、日志分析 + - � **管理员认证** - 独立Token认证、权限控制、会话管理 + - 🧪 **单元测试** - 管理员功能测试用例、测试覆盖率提升 + - ⚙️ **TypeScript配置** - Node16模块解析、编译配置优化 + - 🐳 **Docker部署** - 容器化部署问题修复、部署脚本优化 + - 📖 **文档维护** - 技术栈文档、部署文档、错误修复文档 + **angjustinl** - 核心开发者 - Gitea: [@ANGJustinl](https://gitea.xinghangee.icu/ANGJustinl) - GitHub: [@ANGJustinl](https://github.com/ANGJustinl) - Email: 96008766+ANGJustinl@users.noreply.github.com -- 提交数: **7 commits** +- 提交数: **9 commits** (不含合并提交) - 主要贡献： - - 🔄 邮箱验证流程重构与优化 - - 💾 基于内存的用户服务实现 - - 🛠️ API响应处理改进 - - 🧪 测试用例完善与错误修复 - - 📚 系统架构优化 - - 💬 **Zulip集成系统** - 完整的Zulip实时通信系统开发 - - 🔧 **E2E测试修复** - Zulip集成的端到端测试优化 - - 🎯 **验证码登录测试** - 验证码登录功能测试用例编写 - -**jianuo** - 核心开发者 -- Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo) -- Email: 32106500027@e.gzhu.edu.cn -- 提交数: **11 commits** -- 主要贡献： - - 🎛️ **管理员后台系统** - 完整的前后端管理界面开发 - - 📊 **日志管理功能** - 运行时日志查看与下载系统 - - 🔐 **管理员认证系统** - 独立Token认证与权限控制 - - 🧪 **单元测试完善** - 管理员功能测试用例编写 - - ⚙️ **TypeScript配置优化** - Node16模块解析配置 - - 🐳 **Docker部署优化** - 容器化部署问题修复 - - 📖 **技术栈文档更新** - 项目技术栈说明完善 - - 🔧 **项目配置优化** - 构建和开发环境配置改进 - -### 🏆 主要维护者 - -**moyin** - 主要维护者 -- Gitea: [@moyin](https://gitea.xinghangee.icu/moyin) -- Email: xinghang_a@proton.me -- 提交数: **112 commits** -- 主要贡献： - - 🚀 项目架构设计与初始化 - - 🔐 完整用户认证系统实现 - - 📧 邮箱验证系统设计与开发 - - 🗄️ Redis缓存服务（文件存储+真实Redis双模式） - - 📝 完整的API文档系统（Swagger UI + OpenAPI） - - 🧪 测试框架搭建与507个测试用例编写 - - 📊 高性能日志系统集成（Pino） - - 🔧 项目配置优化与部署方案 - - 🐛 验证码TTL重置关键问题修复 - - 📚 完整的项目文档体系建设 - - 🏗️ **Zulip模块架构重构** - 业务功能模块化架构设计与实现 - - 📖 **架构文档重写** - 详细的架构设计文档和开发者指南 - - 🔄 **验证码冷却时间优化** - 自动清除机制设计与实现 - - 📋 **文档清理优化** - 项目文档结构化整理和维护体系建立 + - � **Zulip集成系统** - 完整的Zulip实时通信系统、WebSocket连接、消息同步 + - 🔑 **JWT认证重构** - JWT验证机制、API密钥管理、Token刷新 + - � **邮箱验证重构** - 验证流程优化、内存用户服务、API响应改进 + - � **验证码登录** - 验证码登录功能实现、测试用例编写 + - 🧪 **测试优化** - E2E测试修复、测试断言更新、测试覆盖完善 + - 🏗️ **Zulip账户管理** - Zulip账户创建、绑定、同步机制 ## 贡献统计 | 贡献者 | 提交数 | 主要领域 | 贡献占比 | |--------|--------|----------|----------| -| angjustinl | 7 | Zulip集成、功能优化、测试、重构 | 5% | -| jianuo | 11 | 管理员后台、日志系统、部署优化、配置管理 | 8% | -| moyin | 112 | 架构设计、核心功能、文档、测试、Zulip重构 | 86% | +| moyin | 166 | 架构设计、核心功能、文档、测试、重构 | 89.7% | +| jianuo | 10 | 管理员后台、日志系统、部署优化 | 5.4% | +| angjustinl | 9 | Zulip集成、JWT认证、验证码登录 | 4.9% | ## 🌟 最新重要贡献 -### 🏗️ Zulip模块架构重构 (2025年12月31日) -**主要贡献者**: moyin, angjustinl - -这是项目历史上最重要的架构重构之一： - -- **架构重构**: 实现业务功能模块化架构，将Zulip模块按照业务层和核心层进行清晰分离 -- **代码迁移**: 36个文件的重构和迁移，涉及2773行代码的新增和125行的删除 -- **依赖注入**: 通过接口抽象实现业务层与核心层的完全解耦 -- **测试完善**: 所有507个测试用例通过，确保重构的安全性 - -### 📚 项目文档体系优化 (2025年12月31日) +### 🏗️ 四层架构重构与规范化 (2026年1月) **主要贡献者**: moyin -- **架构文档重写**: `docs/ARCHITECTURE.md` 从简单架构图扩展为800+行的完整架构设计文档 -- **README优化**: 采用总分结构设计，详细的文件结构总览 -- **文档清理**: 新增 `docs/DOCUMENT_CLEANUP.md` 记录文档维护过程 -- **开发者体验**: 建立完整的文档导航体系，提升开发者上手体验 +项目完成了重大的架构升级和代码规范化工作： -### 💬 Zulip集成系统 (2025年12月25日) -**主要贡献者**: angjustinl +- **认证模块重构** (1月14日): 将Gateway层组件从Business层分离，实现清晰的四层架构 +- **依赖注入优化** (1月14日): 修复AuthGatewayModule依赖注入问题，完善NestJS模块系统 +- **AI代码检查体系** (1月14日): 建立完整的AI辅助代码检查流程和规范文档 +- **架构文档完善** (1月14日): 新增架构重构文档、Gateway层规范、NestJS命名规范 +- **代码规范优化** (1月12日): 完善多个核心模块的代码规范和测试覆盖 -- **完整集成**: 实现与Zulip的完整集成，支持实时通信功能 -- **WebSocket支持**: 建立稳定的WebSocket连接和消息处理机制 -- **测试覆盖**: 完善的E2E测试确保集成功能的稳定性 +### 📚 代码质量与测试提升 (2026年1月) +**主要贡献者**: moyin + +- **测试覆盖完善** (1月12日): 完善users、zulip、verification等模块测试覆盖 +- **文档体系建设** (1月12日): 添加开发者代码检查规范、AI代码检查执行指南 +- **性能优化** (1月12日): 集成高性能缓存系统和结构化日志 +- **模块功能扩展** (1月12日): 添加Zulip动态配置控制器和账户业务服务 + +### 🎮 游戏功能扩展 (2026年1月) +**主要贡献者**: moyin + +- **通知系统** (1月10日): 实现完整的通知系统核心功能和数据库支持 +- **WebSocket优化** (1月9日): 统一WebSocket网关配置、增强测试页面用户体验 +- **原生WebSocket** (1月9日): 移除Socket.IO依赖，实现原生WebSocket支持 +- **位置广播系统** (1月8日): 实现位置广播系统和端到端测试 +- **管理员系统** (1月8日): 完善管理员系统核心功能和用户管理模块 + +### 🏗️ Zulip模块架构重构 (2025年12月) +**主要贡献者**: moyin, angjustinl + +- **架构重构** (12月31日): 实现业务功能模块化架构，清晰分离业务层和核心层 +- **Zulip集成** (12月25日): angjustinl开发完整的Zulip实时通信系统 +- **JWT认证** (1月6日): angjustinl引入JWT验证并重构API密钥管理 +- **账户管理** (1月5日): angjustinl添加Zulip账户管理和认证系统集成 ## 项目里程碑 +### 2026年1月 +- **1月14日**: 🏗️ 认证模块四层架构重构，Gateway层与Business层清晰分离 +- **1月14日**: 🔧 修复AuthGatewayModule依赖注入问题，完善模块系统 +- **1月14日**: 📚 建立AI代码检查体系，添加完整的规范文档 +- **1月14日**: 📖 新增架构重构文档和NestJS框架规范说明 +- **1月12日**: ✨ 完善多个核心模块的代码规范和测试覆盖 +- **1月12日**: 🧪 添加Zulip业务模块完整测试覆盖 +- **1月12日**: 📝 添加开发者代码检查规范和AI检查执行指南 +- **1月12日**: ⚡ 集成高性能缓存系统和结构化日志 +- **1月10日**: 🔔 实现通知系统核心功能和数据库支持 +- **1月10日**: 🐛 修复数据库管理服务的关键问题 +- **1月9日**: 🌐 统一WebSocket网关配置，增强测试页面 +- **1月9日**: 🔄 移除Socket.IO依赖，实现原生WebSocket支持 +- **1月8日**: 📍 实现位置广播系统和端到端测试 +- **1月8日**: 👑 完善管理员系统核心功能 +- **1月8日**: 🏗️ 项目架构重构和命名规范化 +- **1月7日**: 📦 升级到v2.0.0版本 +- **1月6日**: 🔑 angjustinl引入JWT验证并重构API密钥管理 +- **1月5日**: 👤 angjustinl添加Zulip账户管理和认证系统集成 +- **1月4日**: 🛡️ 重构安全模块架构，迁移至core层 + ### 2025年12月 -- **12月17日**: 项目初始化，完成基础架构搭建 -- **12月17日**: 实现完整的用户认证系统 -- **12月17日**: 完成API文档系统集成 -- **12月17日**: 实现邮箱验证系统 -- **12月17日**: 修复验证码TTL重置关键问题 -- **12月18日**: angjustinl重构邮箱验证流程，引入内存用户服务 -- **12月18日**: jianuo修复Docker部署问题 -- **12月18日**: 完成测试用例修复和优化 -- **12月19日**: jianuo开发管理员后台系统 -- **12月20日**: jianuo完善日志管理功能 -- **12月21日**: jianuo添加管理员后台单元测试 -- **12月22日**: 管理员后台功能合并到主分支 -- **12月25日**: angjustinl开发完整的Zulip集成系统 -- **12月25日**: 实现验证码冷却时间自动清除机制 -- **12月25日**: 完成邮箱冲突检测优化v1.1.1 -- **12月25日**: 升级项目版本到v1.1.0 -- **12月31日**: **重大架构重构** - 完成Zulip模块业务功能模块化架构重构 -- **12月31日**: **文档体系优化** - 项目文档结构化整理和架构文档重写 -- **12月31日**: **测试覆盖完善** - 所有507个测试用例通过，测试覆盖率达到新高 +- **12月31日**: 🏗️ Zulip模块业务功能模块化架构重构 +- **12月31日**: 📚 项目文档结构化整理和架构文档重写 +- **12月25日**: 💬 angjustinl开发完整的Zulip集成系统 +- **12月25日**: 🔄 实现验证码冷却时间自动清除机制 +- **12月25日**: 📧 完成邮箱冲突检测优化v1.1.1 +- **12月25日**: 🎯 angjustinl实现验证码登录功能 +- **12月25日**: 📈 升级项目版本到v1.1.0 +- **12月24日**: 🐛 修复注册逻辑和HTTP状态码问题 +- **12月24日**: 🔧 修复API状态码和限流配置问题 +- **12月24日**: 🏗️ 重构项目结构和业务模块架构 +- **12月23日**: 📖 全面更新API接口文档 +- **12月22日**: 🎛️ jianuo的管理员后台功能合并到主分支 +- **12月19日**: 👑 jianuo开发管理员后台系统 +- **12月19日**: 📊 jianuo完善日志管理功能 +- **12月19日**: 🧪 jianuo添加管理员后台单元测试 +- **12月19日**: ⚙️ jianuo优化TypeScript配置 +- **12月18日**: 🔄 angjustinl重构邮箱验证流程，引入内存用户服务 +- **12月18日**: 🐳 jianuo修复Docker部署问题 +- **12月18日**: 🧪 完成测试用例修复和优化 +- **12月17日**: 🐛 修复验证码TTL重置关键问题 +- **12月17日**: 📧 实现完整的邮箱验证系统 +- **12月17日**: 🗄️ 实现Redis缓存服务（双模式） +- **12月17日**: 📝 完成API文档系统集成 +- **12月17日**: 🔐 实现完整的用户认证系统 +- **12月17日**: 🚀 项目初始化，完成基础架构搭建 ## 如何成为贡献者 @@ -137,9 +170,10 @@ ### 贡献规范 请在贡献前阅读： -- [AI辅助开发规范指南](./docs/AI辅助开发规范指南.md) -- [后端开发规范](./docs/backend_development_guide.md) -- [Git提交规范](./docs/git_commit_guide.md) +- [开发者代码检查规范](./开发者代码检查规范.md) +- [后端开发规范](./development/backend_development_guide.md) +- [Git提交规范](./development/git_commit_guide.md) +- [AI代码检查指南](./ai-reading/README.md) --- -- 2.25.1 From 260ae2c559da455499a3c96a7a4dc844c2f599f5 Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Wed, 14 Jan 2026 15:13:54 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs=EF=BC=9A=E7=AE=80=E5=8C=96=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E6=96=87=E6=A1=A3=EF=BC=8C=E7=AA=81=E5=87=BA=E5=9B=9B?= =?UTF-8?q?=E5=B1=82=E6=9E=B6=E6=9E=84=E6=A0=B8=E5=BF=83=E8=AE=BE=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 精简ARCHITECTURE.md，移除冗长的目录结构说明 - 突出四层架构的职责和原则 - 保留核心的架构图和依赖关系说明 - 简化双模式架构和模块依赖的描述 - 移除过于详细的扩展指南，保留核心内容 --- docs/ARCHITECTURE.md | 1069 +++++++---------- docs/development/backend_development_guide.md | 823 ++++++++----- 2 files changed, 910 insertions(+), 982 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8469558..5a5cfa3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,464 +1,315 @@ # 🏗️ Whale Town 项目架构设计 -> 基于业务功能模块化的现代化后端架构，支持双模式运行，开发测试零依赖，生产部署高性能。 +> 基于四层架构（Gateway-Business-Core-Data）的现代化后端设计，支持双模式运行，开发测试零依赖，生产部署高性能。 ## 📋 目录 -- [🎯 架构概述](#-架构概述) -- [📁 目录结构详解](#-目录结构详解) -- [🏗️ 分层架构设计](#️-分层架构设计) -- [🔄 双模式架构](#-双模式架构) -- [📦 模块依赖关系](#-模块依赖关系) -- [🚀 扩展指南](#-扩展指南) +- [架构概述](#架构概述) +- [四层架构设计](#四层架构设计) +- [目录结构](#目录结构) +- [双模式架构](#双模式架构) +- [模块依赖关系](#模块依赖关系) +- [数据流向](#数据流向) +- [扩展指南](#扩展指南) --- -## 🎯 架构概述 +## 架构概述 -Whale Town 采用**业务功能模块化架构**，将代码按业务功能而非技术组件组织，确保高内聚、低耦合的设计原则。 +Whale Town 采用**四层架构设计**（Gateway-Business-Core-Data），将协议处理、业务逻辑、技术基础设施和数据存储清晰分离。 -### 🌟 核心设计理念 +### 核心设计理念 -- **业务驱动** - 按业务功能组织代码，而非技术分层 +- **职责分离** - 每层职责明确，互不干扰 - **双模式支持** - 开发测试零依赖，生产部署高性能 -- **清晰分层** - 业务层 → 核心层 → 数据层，职责明确 -- **模块化设计** - 每个模块独立完整，可单独测试和部署 -- **配置驱动** - 通过环境变量控制运行模式和行为 +- **依赖单向** - 上层依赖下层，下层不依赖上层 +- **模块化设计** - 每个模块独立完整，可单独测试 +- **配置驱动** - 通过环境变量控制运行模式 -### 🛠️ 技术栈 +### 技术栈 -#### 后端技术栈 -- **框架**: 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 - -### 📊 整体架构图 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 🌐 API接口层 │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 🔗 REST API │ │ 🔌 WebSocket │ │ 📄 Swagger UI │ │ -│ │ (HTTP接口) │ │ (实时通信) │ │ (API文档) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - ⬇️ -┌─────────────────────────────────────────────────────────────────┐ -│ 🎯 业务功能模块层 │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 🔐 用户认证 │ │ 👥 用户管理 │ │ 🛡️ 管理员 │ │ -│ │ (auth) │ │ (user_mgmt) │ │ (admin) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 💬 Zulip集成 │ │ 🔗 共享组件 │ │ │ │ -│ │ (zulip) │ │ (shared) │ │ │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - ⬇️ -┌─────────────────────────────────────────────────────────────────┐ -│ ⚙️ 核心技术服务层 │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 🔑 登录核心 │ │ 👑 管理员核心 │ │ 💬 Zulip核心 │ │ -│ │ (auth_core) │ │ (admin_core) │ │ (zulip) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 🛡️ 安全核心 │ │ 🛠️ 工具服务 │ │ 📧 邮件服务 │ │ -│ │ (security_core)│ │ (utils) │ │ (email) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - ⬇️ -┌─────────────────────────────────────────────────────────────────┐ -│ 🗄️ 数据存储层 │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ 🗃️ 数据库 │ │ 🔴 Redis缓存 │ │ 📁 文件存储 │ │ -│ │ (MySQL/内存) │ │ (Redis/文件) │ │ (logs/data) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ -``` +**后端：** NestJS 11 + TypeScript 5 + MySQL + Redis + 原生WebSocket +**前端：** React 18 + Vite 7 + Ant Design 5 +**测试：** Jest + Supertest（99个测试用例） +**部署：** Docker + PM2 + Nginx --- -## 📁 目录结构详解 +## 四层架构设计 -### 🎯 业务功能模块 (`src/business/`) +### 架构层次图 -> **设计原则**: 按业务功能组织，每个模块包含完整的业务逻辑 +``` +┌─────────────────────────────────────────────────────────────┐ +│ 🌐 Gateway Layer (网关层) │ +│ HTTP/WebSocket协议处理、数据验证、路由管理、认证守卫 │ +└─────────────────────────────────────────────────────────────┘ + ⬇️ +┌─────────────────────────────────────────────────────────────┐ +│ 🎯 Business Layer (业务层) │ +│ 业务逻辑实现、服务协调、业务规则验证、事务管理 │ +└─────────────────────────────────────────────────────────────┘ + ⬇️ +┌─────────────────────────────────────────────────────────────┐ +│ ⚙️ Core Layer (核心层) │ +│ 技术基础设施、数据访问、外部系统集成、工具服务 │ +└─────────────────────────────────────────────────────────────┘ + ⬇️ +┌─────────────────────────────────────────────────────────────┐ +│ 🗄️ Data Layer (数据层) │ +│ 数据持久化、缓存管理、文件存储 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 各层职责 + +#### 🌐 Gateway Layer（网关层） + +**位置：** `src/gateway/` + +**职责：** +- HTTP/WebSocket协议处理 +- 请求参数验证（DTO） +- 路由管理 +- 认证守卫（JWT验证） +- 错误转换（业务错误 → HTTP状态码） +- API文档（Swagger） + +**原则：** +- ✅ 只做协议转换，不做业务逻辑 +- ✅ 使用DTO进行数据验证 +- ✅ 统一的错误处理 +- ❌ 不直接访问数据库 +- ❌ 不包含业务规则 + +**示例模块：** +- `gateway/auth/` - 认证网关（登录、注册接口） +- `gateway/location_broadcast/` - 位置广播网关（WebSocket） + +#### 🎯 Business Layer（业务层） + +**位置：** `src/business/` + +**职责：** +- 业务逻辑实现 +- 业务流程控制 +- 服务协调 +- 业务规则验证 +- 事务管理 + +**原则：** +- ✅ 实现所有业务逻辑 +- ✅ 协调多个Core层服务 +- ✅ 返回统一的业务响应 +- ❌ 不处理HTTP协议 +- ❌ 不直接访问数据库 + +**示例模块：** +- `business/auth/` - 用户认证业务 +- `business/user_mgmt/` - 用户管理业务 +- `business/admin/` - 管理员业务 +- `business/zulip/` - Zulip集成业务 +- `business/location_broadcast/` - 位置广播业务 +- `business/notice/` - 公告业务 + +#### ⚙️ Core Layer（核心层） + +**位置：** `src/core/` + +**职责：** +- 数据访问（数据库、缓存） +- 基础设施（Redis、消息队列） +- 外部系统集成（Zulip API） +- 技术实现细节 +- 工具服务（邮件、验证码、日志） + +**原则：** +- ✅ 提供技术基础设施 +- ✅ 数据持久化和缓存 +- ✅ 外部API集成 +- ❌ 不包含业务逻辑 +- ❌ 不处理HTTP协议 + +**示例模块：** +- `core/db/users/` - 用户数据服务 +- `core/redis/` - Redis缓存服务 +- `core/login_core/` - 登录核心服务 +- `core/admin_core/` - 管理员核心服务 +- `core/zulip_core/` - Zulip核心服务 +- `core/security_core/` - 安全核心服务 +- `core/utils/` - 工具服务（邮件、验证码、日志） + +#### �️ Data Layer（数据层） + +**位置：** 数据库、Redis、文件系统 + +**职责：** +- 数据持久化 +- 缓存管理 +- 文件存储 + +**实现：** +- MySQL / 内存数据库 +- Redis / 文件存储 +- 日志文件 / 数据文件 + +--- + +## 目录结构 + +### 整体结构 + +``` +whale-town-end/ +├── src/ +│ ├── gateway/ # 🌐 网关层 +│ │ ├── auth/ # 认证网关 +│ │ └── location_broadcast/ # 位置广播网关 +│ ├── business/ # 🎯 业务层 +│ │ ├── auth/ # 用户认证业务 +│ │ ├── user_mgmt/ # 用户管理业务 +│ │ ├── admin/ # 管理员业务 +│ │ ├── zulip/ # Zulip集成业务 +│ │ ├── location_broadcast/ # 位置广播业务 +│ │ └── notice/ # 公告业务 +│ ├── core/ # ⚙️ 核心层 +│ │ ├── db/users/ # 用户数据服务 +│ │ ├── redis/ # Redis缓存服务 +│ │ ├── login_core/ # 登录核心服务 +│ │ ├── admin_core/ # 管理员核心服务 +│ │ ├── zulip_core/ # Zulip核心服务 +│ │ ├── security_core/ # 安全核心服务 +│ │ └── utils/ # 工具服务 +│ ├── app.module.ts # 应用主模块 +│ └── main.ts # 应用入口 +├── client/ # 🎨 前端管理界面 +├── docs/ # 📚 项目文档 +├── test/ # 🧪 测试文件 +└── config/ # ⚙️ 配置文件 +``` + +### 网关层结构 + +``` +src/gateway/ +├── auth/ # 认证网关 +│ ├── login.controller.ts +│ ├── register.controller.ts +│ ├── jwt_auth.guard.ts +│ ├── current_user.decorator.ts +│ ├── dto/ +│ └── auth.gateway.module.ts +└── location_broadcast/ # 位置广播网关 + ├── location_broadcast.gateway.ts + └── location_broadcast.gateway.module.ts +``` + +### 业务层结构 ``` src/business/ -├── 📂 auth/ # 🔐 用户认证模块 -│ ├── 📄 auth.module.ts # 模块定义 -│ ├── 📂 controllers/ # 控制器 -│ │ └── 📄 login.controller.ts # 登录接口控制器 -│ ├── 📂 services/ # 业务服务 -│ │ ├── 📄 login.service.ts # 登录业务逻辑 -│ │ └── 📄 login.service.spec.ts # 登录服务测试 -│ ├── 📂 dto/ # 数据传输对象 -│ │ ├── 📄 login.dto.ts # 登录请求DTO -│ │ └── 📄 login_response.dto.ts # 登录响应DTO -│ └── 📂 guards/ # 权限守卫（预留） -│ -├── 📂 user-mgmt/ # 👥 用户管理模块 -│ ├── 📄 user-mgmt.module.ts # 模块定义 -│ ├── 📂 controllers/ # 控制器 -│ │ └── 📄 user-status.controller.ts # 用户状态管理接口 -│ ├── 📂 services/ # 业务服务 -│ │ └── 📄 user-management.service.ts # 用户管理逻辑 -│ ├── 📂 dto/ # 数据传输对象 -│ │ ├── 📄 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/ # 权限守卫 -│ -├── 📂 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/ # 🔗 共享业务组件 - ├── 📂 dto/ # 共享数据传输对象 - └── 📄 index.ts # 导出文件 +├── auth/ # 用户认证业务 +│ ├── login.service.ts +│ ├── register.service.ts +│ └── auth.module.ts +├── user_mgmt/ # 用户管理业务 +│ ├── user_management.service.ts +│ ├── dto/ +│ ├── enums/ +│ └── user_mgmt.module.ts +├── admin/ # 管理员业务 +│ ├── admin.service.ts +│ └── admin.module.ts +├── zulip/ # Zulip集成业务 +│ ├── zulip.service.ts +│ ├── services/ +│ └── zulip.module.ts +├── location_broadcast/ # 位置广播业务 +│ ├── location_broadcast.service.ts +│ └── location_broadcast.module.ts +└── notice/ # 公告业务 + ├── notice.service.ts + └── notice.module.ts ``` -### ⚙️ 核心技术服务 (`src/core/`) - -> **设计原则**: 提供技术基础设施，支持业务模块运行 +### 核心层结构 ``` src/core/ -├── 📂 db/ # 🗄️ 数据库层 -│ └── 📂 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模块 -│ ├── 📄 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.service.spec.ts # 登录核心测试 -│ -├── 📂 admin_core/ # 👑 管理员核心服务 -│ ├── 📄 admin_core.service.ts # 管理员核心逻辑 -│ ├── 📄 admin_core.module.ts # 模块定义 -│ └── 📄 admin_core.service.spec.ts # 管理员核心测试 -│ -├── 📂 zulip_core/ # 💬 Zulip核心服务 -│ ├── 📄 zulip_core.module.ts # Zulip核心模块 -│ ├── 📂 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.service.spec.ts # 邮件服务测试 - ├── 📂 verification/ # 🔢 验证码服务 - │ ├── 📄 verification.service.ts # 验证码生成验证 - │ ├── 📄 verification.module.ts # 验证码模块 - │ └── 📄 verification.service.spec.ts # 验证码服务测试 - └── 📂 logger/ # 📝 日志服务 - ├── 📄 logger.service.ts # 日志记录服务 - ├── 📄 logger.module.ts # 日志模块 - ├── 📄 logger.config.ts # 日志配置 - └── 📄 log_management.service.ts # 日志管理服务 -``` - -### 🎨 前端管理界面 (`client/`) - -> **设计原则**: 独立的前端项目，提供管理员后台功能，基于React + Vite + Ant Design - -``` -client/ -├── 📂 src/ # 前端源码 -│ ├── 📂 app/ # 应用组件 -│ │ ├── 📄 App.tsx # 应用主组件 -│ │ └── 📄 AdminLayout.tsx # 管理员布局组件 -│ ├── 📂 pages/ # 页面组件 -│ │ ├── 📄 LoginPage.tsx # 登录页面 -│ │ ├── 📄 UsersPage.tsx # 用户管理页面 -│ │ └── 📄 LogsPage.tsx # 日志管理页面 -│ ├── 📂 lib/ # 工具库 -│ │ ├── 📄 api.ts # API客户端 -│ │ └── 📄 adminAuth.ts # 管理员认证服务 -│ └── 📄 main.tsx # 应用入口 -├── 📂 dist/ # 构建产物 -├── 📄 package.json # 前端依赖 -├── 📄 vite.config.ts # Vite配置 -└── 📄 tsconfig.json # TypeScript配置 -``` - -### 📚 文档中心 (`docs/`) - -> **设计原则**: 完整的项目文档，支持开发者快速上手 - -``` -docs/ -├── 📄 README.md # 📖 文档导航中心 -├── 📄 ARCHITECTURE.md # 🏗️ 架构设计文档 -├── 📄 CONTRIBUTORS.md # 🤝 贡献者指南 -│ -├── 📂 api/ # 🔌 API接口文档 -│ ├── 📄 README.md # API文档使用指南 -│ └── 📄 api-documentation.md # 完整API接口文档 -│ -├── 📂 development/ # 💻 开发指南 -│ ├── 📄 backend_development_guide.md # 后端开发规范 -│ ├── 📄 git_commit_guide.md # Git提交规范 -│ ├── 📄 AI辅助开发规范指南.md # AI辅助开发指南 -│ └── 📄 TESTING.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配置 -└── 📄 ecosystem.config.js # 🚀 PM2进程管理配置 - -client/ -├── 📄 package.json # 📋 前端项目依赖配置 -├── 📄 vite.config.ts # ⚡ Vite构建配置 -└── 📄 tsconfig.json # 📘 前端TypeScript配置 +├── db/users/ # 用户数据服务 +│ ├── users.service.ts # MySQL实现 +│ ├── users_memory.service.ts # 内存实现 +│ ├── users.entity.ts +│ └── users.module.ts +├── redis/ # Redis缓存服务 +│ ├── real_redis.service.ts +│ ├── file_redis.service.ts +│ └── redis.module.ts +├── login_core/ # 登录核心服务 +│ ├── login_core.service.ts +│ └── login_core.module.ts +├── admin_core/ # 管理员核心服务 +│ ├── admin_core.service.ts +│ └── admin_core.module.ts +├── zulip_core/ # Zulip核心服务 +│ ├── services/ +│ ├── config/ +│ └── zulip_core.module.ts +├── security_core/ # 安全核心服务 +│ ├── guards/ +│ ├── interceptors/ +│ ├── middleware/ +│ └── security_core.module.ts +└── utils/ # 工具服务 + ├── email/ + ├── verification/ + └── logger/ ``` --- -## 🏗️ 分层架构设计 +## 双模式架构 -### 📊 架构分层说明 +### 模式对比 -``` -┌─────────────────────────────────────────────────────────────┐ -│ 🌐 表现层 (Presentation) │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Controllers │ │ WebSocket │ │ Swagger UI │ │ -│ │ (HTTP接口) │ │ Gateways │ │ (API文档) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ⬇️ -┌─────────────────────────────────────────────────────────────┐ -│ 🎯 业务层 (Business) │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Auth Module │ │ UserMgmt │ │ Admin Module │ │ -│ │ (用户认证) │ │ Module │ │ (管理员) │ │ -│ │ │ │ (用户管理) │ │ │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Security Module │ │ Zulip Module │ │ Shared Module │ │ -│ │ (安全防护) │ │ (Zulip集成) │ │ (共享组件) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ⬇️ -┌─────────────────────────────────────────────────────────────┐ -│ ⚙️ 服务层 (Service) │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Login Core │ │ Admin Core │ │ Zulip Core │ │ -│ │ (登录核心) │ │ (管理员核心) │ │ (Zulip核心) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Email Service │ │ Verification │ │ Logger Service │ │ -│ │ (邮件服务) │ │ Service │ │ (日志服务) │ │ -│ │ │ │ (验证码服务) │ │ │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ⬇️ -┌─────────────────────────────────────────────────────────────┐ -│ 🗄️ 数据层 (Data) │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ Users Service │ │ Redis Service │ │ File Storage │ │ -│ │ (用户数据) │ │ (缓存服务) │ │ (文件存储) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ -│ │ MySQL/Memory │ │ Redis/File │ │ Logs/Data │ │ -│ │ (数据库) │ │ (缓存实现) │ │ (日志数据) │ │ -│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` +| 功能 | 开发模式 | 生产模式 | +|------|---------|---------| +| 数据库 | 内存存储 | MySQL | +| 缓存 | 文件存储 | Redis | +| 邮件 | 控制台输出 | SMTP服务器 | +| 日志 | 控制台+文件 | 结构化日志 | -### 🔄 数据流向 +### 配置示例 -#### 用户登录流程示例 - -``` -1. 📱 用户请求 → LoginController.login() -2. 🔍 参数验证 → class-validator装饰器 -3. 🎯 业务逻辑 → LoginService.login() -4. ⚙️ 核心服务 → LoginCoreService.validateUser() -5. 📧 发送验证码 → VerificationService.generate() -6. 💾 存储数据 → UsersService.findByEmail() + RedisService.set() -7. 📝 记录日志 → LoggerService.log() -8. ✅ 返回响应 → 用户收到登录结果 -``` - -#### 管理员操作流程示例 - -``` -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. ✅ 返回响应 → 管理员收到操作结果 -``` - ---- - -## 🔄 双模式架构 - -### 🎯 设计目标 - -- **开发测试**: 零依赖快速启动，无需安装MySQL、Redis等外部服务 -- **生产部署**: 高性能、高可用，支持集群和负载均衡 - -### 📊 模式对比 - -| 功能模块 | 🧪 开发测试模式 | 🚀 生产部署模式 | -|----------|----------------|----------------| -| **数据库** | 内存存储 (UsersMemoryService) | MySQL (UsersService + TypeORM) | -| **缓存** | 文件存储 (FileRedisService) | Redis (RealRedisService + IORedis) | -| **邮件** | 控制台输出 (测试模式) | SMTP服务器 (生产模式) | -| **日志** | 控制台 + 文件 | 结构化日志 + 日志轮转 | -| **配置** | `.env` 默认配置 | 环境变量 + 配置中心 | - -### ⚙️ 模式切换配置 - -#### 开发测试模式 (.env) +**开发模式：** ```bash -# 数据存储模式 -USE_FILE_REDIS=true # 使用文件存储代替Redis -NODE_ENV=development # 开发环境 - -# 数据库配置（注释掉，使用内存数据库） -# DB_HOST=localhost -# DB_USERNAME=root -# DB_PASSWORD=password - -# 邮件配置（注释掉，使用测试模式） -# EMAIL_HOST=smtp.gmail.com -# EMAIL_USER=your_email@gmail.com -# EMAIL_PASS=your_password +USE_FILE_REDIS=true +NODE_ENV=development +# 无需配置数据库和邮件 ``` -#### 生产部署模式 (.env.production) +**生产模式：** ```bash -# 数据存储模式 -USE_FILE_REDIS=false # 使用真实Redis -NODE_ENV=production # 生产环境 - -# 数据库配置 +USE_FILE_REDIS=false +NODE_ENV=production DB_HOST=your_mysql_host -DB_PORT=3306 -DB_USERNAME=your_username -DB_PASSWORD=your_password -DB_DATABASE=whale_town - -# Redis配置 REDIS_HOST=your_redis_host -REDIS_PORT=6379 -REDIS_PASSWORD=your_redis_password - -# 邮件配置 -EMAIL_HOST=smtp.gmail.com -EMAIL_PORT=587 -EMAIL_USER=your_email@gmail.com -EMAIL_PASS=your_app_password +EMAIL_HOST=smtp.163.com ``` -### 🔧 实现机制 +### 实现机制 + +通过依赖注入和工厂模式实现自动切换： -#### 依赖注入切换 ```typescript -// redis.module.ts @Module({ providers: [ { provide: 'IRedisService', - useFactory: (configService: ConfigService) => { - const useFileRedis = configService.get('USE_FILE_REDIS'); - return useFileRedis - ? new FileRedisService() - : new RealRedisService(configService); + useFactory: (config: ConfigService) => { + return config.get('USE_FILE_REDIS') + ? new FileRedisService() + : new RealRedisService(config); }, inject: [ConfigService], }, @@ -467,220 +318,117 @@ EMAIL_PASS=your_app_password export class RedisModule {} ``` -#### 配置驱动服务选择 -```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 {} -``` - --- -## 📦 模块依赖关系 +## 模块依赖关系 -### 🏗️ 模块依赖图 +### 依赖方向 ``` -AppModule (应用主模块) -├── 📊 ConfigModule (全局配置) -├── 📝 LoggerModule (日志系统) -├── 🔴 RedisModule (缓存服务) -│ ├── RealRedisService (真实Redis) -│ └── FileRedisService (文件存储) -├── 🗄️ UsersModule (用户数据) -│ ├── UsersService (MySQL数据库) -│ └── UsersMemoryService (内存数据库) -├── 📧 EmailModule (邮件服务) -├── 🔢 VerificationModule (验证码服务) -├── 🔑 LoginCoreModule (登录核心) -├── 👑 AdminCoreModule (管理员核心) -├── 💬 ZulipCoreModule (Zulip核心) -├── 🔒 SecurityCoreModule (安全核心) +Gateway Layer + ↓ 依赖 +Business Layer + ↓ 依赖 +Core Layer + ↓ 依赖 +Data Layer +``` + +### 模块依赖图 + +``` +AppModule +├── ConfigModule (全局配置) +├── LoggerModule (日志系统) +├── RedisModule (缓存服务) +├── UsersModule (用户数据) +├── EmailModule (邮件服务) +├── VerificationModule (验证码服务) +├── LoginCoreModule (登录核心) +├── AdminCoreModule (管理员核心) +├── ZulipCoreModule (Zulip核心) +├── SecurityCoreModule (安全核心) │ -├── 🎯 业务功能模块 -│ ├── 🔐 AuthModule (用户认证) -│ │ └── 依赖: LoginCoreModule, EmailModule, VerificationModule, SecurityCoreModule -│ ├── 👥 UserMgmtModule (用户管理) -│ │ └── 依赖: UsersModule, LoggerModule, SecurityCoreModule -│ ├── 🛡️ AdminModule (管理员) -│ │ └── 依赖: AdminCoreModule, UsersModule, SecurityCoreModule -│ ├── 💬 ZulipModule (Zulip集成) -│ │ └── 依赖: ZulipCoreModule, RedisModule -│ └── 🔗 SharedModule (共享组件) -``` - -### 🔄 模块交互流程 - -#### 用户认证流程 -``` -AuthController → LoginService → LoginCoreService - ↓ -EmailService ← VerificationService ← RedisService - ↓ - UsersService -``` - -#### 管理员操作流程 -``` -AdminController → AdminService → AdminCoreService - ↓ -LoggerService ← UsersService ← RedisService -``` - -#### 安全防护流程 -``` -SecurityGuard → RedisService (频率限制) - → LoggerService (审计日志) - → ConfigService (维护模式) +├── Gateway Layer +│ ├── AuthGatewayModule +│ └── LocationBroadcastGatewayModule +│ +└── Business Layer + ├── AuthModule + ├── UserMgmtModule + ├── AdminModule + ├── ZulipModule + ├── LocationBroadcastModule + └── NoticeModule ``` --- -## 🚀 扩展指南 +## 数据流向 -### 📝 添加新的业务模块 +### 用户登录流程 -#### 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 +``` +1. 用户请求 → LoginController (Gateway) +2. 参数验证 → DTO Validation +3. 业务逻辑 → LoginService (Business) +4. 核心服务 → LoginCoreService (Core) +5. 数据访问 → UsersService + RedisService (Core) +6. 数据存储 → MySQL/Memory + Redis/File (Data) +7. 返回响应 → 用户收到结果 ``` -#### 2. 实现业务逻辑 -```typescript -// src/business/game/game.module.ts -@Module({ - imports: [ - GameCoreModule, # 依赖核心服务 - UsersModule, # 依赖用户数据 - RedisModule, # 依赖缓存服务 - ], - controllers: [GameController], - providers: [GameService], - exports: [GameService], -}) -export class GameModule {} +### WebSocket消息流程 + +``` +1. WebSocket连接 → LocationBroadcastGateway (Gateway) +2. 消息验证 → JWT验证 +3. 业务处理 → LocationBroadcastService (Business) +4. 房间管理 → 地图分组逻辑 +5. 消息广播 → 同地图用户 +6. Zulip同步 → ZulipService (Business) ``` -#### 3. 创建对应的核心服务 +### 管理员操作流程 + +``` +1. 管理员请求 → AdminController (Gateway) +2. 权限验证 → AdminGuard +3. 业务逻辑 → AdminService (Business) +4. 核心服务 → AdminCoreService (Core) +5. 数据更新 → UsersService (Core) +6. 审计日志 → LoggerService (Core) +7. 返回响应 → 管理员收到结果 +``` + +--- + +## 扩展指南 + +### 添加新的业务模块 + +1. **创建目录结构** ```bash -# 创建核心服务 +mkdir -p src/gateway/game +mkdir -p src/business/game mkdir -p src/core/game_core -nest g module core/game_core -nest g service core/game_core ``` -#### 4. 更新主模块 +2. **实现网关层** ```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 +// src/gateway/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); + async createGame(@Body() dto: CreateGameDto) { + return this.gameService.create(dto); } } ``` -#### 3. 实现Service +3. **实现业务层** ```typescript // src/business/game/game.service.ts @Injectable() @@ -689,85 +437,82 @@ export class GameService { @Inject('IGameCoreService') private readonly gameCoreService: IGameCoreService, ) {} - - async create(createGameDto: CreateGameDto) { - return this.gameCoreService.createGame(createGameDto); + + async create(dto: CreateGameDto) { + // 业务逻辑 + return this.gameCoreService.createGame(dto); } } ``` -#### 4. 添加测试用例 +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); - }); -}); +// src/core/game_core/game_core.service.ts +@Injectable() +export class GameCoreService { + async createGame(dto: CreateGameDto) { + // 数据访问逻辑 + } +} ``` -### 📊 性能优化建议 +5. **注册模块** +```typescript +// src/app.module.ts +@Module({ + imports: [ + // ... + GameGatewayModule, + GameModule, + GameCoreModule, + ], +}) +export class AppModule {} +``` -#### 1. 缓存策略 -- **Redis缓存**: 用户会话、验证码、频繁查询数据 -- **内存缓存**: 配置信息、静态数据 -- **CDN缓存**: 静态资源文件 +### 性能优化建议 -#### 2. 数据库优化 -- **连接池**: 复用数据库连接，减少连接开销 -- **索引优化**: 为查询字段建立合适的索引 -- **查询优化**: 避免N+1查询，使用JOIN优化关联查询 +1. **缓存策略** + - 用户会话 → Redis + - 验证码 → Redis（短期） + - 配置信息 → 内存缓存 -#### 3. 日志优化 -- **异步日志**: 使用Pino的异步写入功能 -- **日志分级**: 生产环境只记录ERROR和WARN级别 -- **日志轮转**: 自动清理过期日志文件 +2. **数据库优化** + - 添加索引 + - 使用连接池 + - 避免N+1查询 -### 🔒 安全加固建议 +3. **日志优化** + - 异步写入 + - 日志分级 + - 日志轮转 -#### 1. 数据验证 -- **输入验证**: 使用class-validator进行严格验证 -- **类型检查**: TypeScript静态类型检查 -- **SQL注入防护**: TypeORM参数化查询 +### 安全加固建议 -#### 2. 认证授权 -- **密码安全**: bcrypt加密，强密码策略 -- **会话管理**: JWT + Redis会话存储 -- **权限控制**: 基于角色的访问控制(RBAC) +1. **数据验证** + - 使用class-validator + - TypeScript类型检查 + - SQL注入防护 -#### 3. 通信安全 -- **HTTPS**: 生产环境强制HTTPS -- **CORS**: 严格的跨域请求控制 -- **Rate Limiting**: API请求频率限制 +2. **认证授权** + - JWT认证 + - 角色权限控制 + - 会话管理 + +3. **通信安全** + - HTTPS强制 + - CORS配置 + - 频率限制 --- -**🏗️ 通过清晰的架构设计，Whale Town 实现了高内聚、低耦合的模块化架构，支持快速开发和灵活部署！** \ No newline at end of file +## 参考文档 + +- [架构重构文档](./ARCHITECTURE_REFACTORING.md) - 四层架构迁移指南 +- [网关层README](../src/gateway/auth/README.md) - 网关层详细说明 +- [开发规范](./development/backend_development_guide.md) - 代码规范 +- [部署指南](./deployment/DEPLOYMENT.md) - 生产环境部署 + +--- + +**🏗️ 通过清晰的四层架构设计，Whale Town 实现了职责分离、高内聚、低耦合的现代化架构！** diff --git a/docs/development/backend_development_guide.md b/docs/development/backend_development_guide.md index 2bf08ee..035407e 100644 --- a/docs/development/backend_development_guide.md +++ b/docs/development/backend_development_guide.md @@ -1,45 +1,220 @@ # 后端开发规范指南 -本文档定义了后端开发的核心规范，包括注释规范、日志规范、业务逻辑规范等，确保代码质量和团队协作效率。 +本文档定义了基于四层架构的后端开发规范，包括架构规范、注释规范、日志规范、代码质量规范等。 ## 📋 目录 +- [架构规范](#架构规范) - [注释规范](#注释规范) - [日志规范](#日志规范) -- [业务逻辑规范](#业务逻辑规范) - [异常处理规范](#异常处理规范) - [代码质量规范](#代码质量规范) - [最佳实践](#最佳实践) --- -## 📝 注释规范 +## 🏗️ 架构规范 + +### 四层架构原则 + +项目采用 **Gateway-Business-Core-Data** 四层架构，每层职责明确： + +``` +Gateway Layer (网关层) + ↓ 依赖 +Business Layer (业务层) + ↓ 依赖 +Core Layer (核心层) + ↓ 依赖 +Data Layer (数据层) +``` + +### 各层职责 + +#### 🌐 Gateway Layer（网关层） + +**位置：** `src/gateway/` + +**职责：** +- HTTP/WebSocket协议处理 +- 请求参数验证（DTO） +- 路由管理 +- 认证守卫 +- 错误转换 + +**规范：** +```typescript +// ✅ 正确：只做协议转换 +@Controller('auth') +export class LoginController { + constructor(private readonly loginService: LoginService) {} + + @Post('login') + async login(@Body() dto: LoginDto, @Res() res: Response) { + const result = await this.loginService.login(dto); + this.handleResponse(result, res); + } +} + +// ❌ 错误：包含业务逻辑 +@Controller('auth') +export class LoginController { + @Post('login') + async login(@Body() dto: LoginDto) { + const user = await this.usersService.findByEmail(dto.email); + const isValid = await bcrypt.compare(dto.password, user.password); + // ... 更多业务逻辑 + } +} +``` + +#### 🎯 Business Layer（业务层） + +**位置：** `src/business/` + +**职责：** +- 业务逻辑实现 +- 服务协调 +- 业务规则验证 +- 事务管理 + +**规范：** +```typescript +// ✅ 正确：实现业务逻辑 +@Injectable() +export class LoginService { + constructor( + private readonly loginCoreService: LoginCoreService, + private readonly emailService: EmailService, + ) {} + + async login(dto: LoginDto): Promise> { + try { + // 1. 调用核心服务验证 + const user = await this.loginCoreService.validateUser(dto); + + // 2. 业务逻辑：生成Token + const tokens = await this.loginCoreService.generateTokens(user); + + // 3. 业务逻辑：发送登录通知 + await this.emailService.sendLoginNotification(user.email); + + return { success: true, data: tokens }; + } catch (error) { + return { success: false, message: error.message }; + } + } +} + +// ❌ 错误：直接访问数据库 +@Injectable() +export class LoginService { + async login(dto: LoginDto) { + const user = await this.userRepository.findOne({ email: dto.email }); + // ... + } +} +``` + +#### ⚙️ Core Layer（核心层） + +**位置：** `src/core/` + +**职责：** +- 数据访问 +- 基础设施 +- 外部系统集成 +- 工具服务 + +**规范：** +```typescript +// ✅ 正确：提供技术基础设施 +@Injectable() +export class LoginCoreService { + constructor( + @Inject('IUsersService') + private readonly usersService: IUsersService, + @Inject('IRedisService') + private readonly redisService: IRedisService, + ) {} + + async validateUser(dto: LoginDto): Promise { + const user = await this.usersService.findByEmail(dto.email); + if (!user) { + throw new UnauthorizedException('用户不存在'); + } + + const isValid = await bcrypt.compare(dto.password, user.password); + if (!isValid) { + throw new UnauthorizedException('密码错误'); + } + + return user; + } +} + +// ❌ 错误：包含业务逻辑 +@Injectable() +export class LoginCoreService { + async validateUser(dto: LoginDto) { + // 发送邮件通知 - 这是业务逻辑，应该在Business层 + await this.emailService.sendLoginNotification(user.email); + } +} +``` + +### 模块组织规范 + +```typescript +// 模块命名：功能名.module.ts +// 服务命名：功能名.service.ts +// 控制器命名：功能名.controller.ts +// 网关命名：功能名.gateway.ts + +// ✅ 正确的模块结构 +src/ +├── gateway/ +│ └── auth/ +│ ├── login.controller.ts +│ ├── register.controller.ts +│ ├── jwt_auth.guard.ts +│ ├── dto/ +│ └── auth.gateway.module.ts +├── business/ +│ └── auth/ +│ ├── login.service.ts +│ ├── register.service.ts +│ └── auth.module.ts +└── core/ + └── login_core/ + ├── login_core.service.ts + └── login_core.module.ts +``` + +--- + +## � 注释规规范 ### 文件头注释 -每个 TypeScript 文件都必须包含完整的文件头注释： - ```typescript /** - * 文件功能描述 + * 用户登录服务 * * 功能描述： - * - 主要功能点1 - * - 主要功能点2 - * - 主要功能点3 + * - 处理用户登录业务逻辑 + * - 协调登录核心服务和邮件服务 + * - 生成JWT令牌 * - * 职责分离： - * - 职责描述1 - * - 职责描述2 + * 架构层级：Business Layer * - * 最近修改： - * - YYYY-MM-DD: 修改类型 - 具体修改内容描述 - * - YYYY-MM-DD: 修改类型 - 具体修改内容描述 + * 依赖服务： + * - LoginCoreService: 登录核心逻辑 + * - EmailService: 邮件发送服务 * * @author 作者名 - * @version x.x.x - * @since 创建日期 - * @lastModified 最后修改日期 + * @version 1.0.0 + * @since 2025-01-01 */ ``` @@ -47,149 +222,75 @@ ```typescript /** - * 类功能描述 + * 登录业务服务 * * 职责： - * - 主要职责1 - * - 主要职责2 + * - 实现用户登录业务逻辑 + * - 协调核心服务完成登录流程 + * - 处理登录相关的业务规则 * * 主要方法： - * - method1() - 方法1功能 - * - method2() - 方法2功能 - * - * 使用场景： - * - 场景描述 + * - login() - 用户登录 + * - verificationCodeLogin() - 验证码登录 + * - refreshToken() - 刷新令牌 */ @Injectable() -export class ExampleService { - // 类实现 +export class LoginService { + // 实现 } ``` -### 方法注释（三级注释标准） +### 方法注释（三级标准） -**必须包含以下三个级别的注释：** - -#### 1. 功能描述级别 ```typescript /** - * 用户登录验证 - */ -``` - -#### 2. 业务逻辑级别 -```typescript -/** - * 用户登录验证 + * 用户登录 * * 业务逻辑： - * 1. 验证用户名或邮箱格式 - * 2. 查找用户记录 - * 3. 验证密码哈希值 - * 4. 检查用户状态是否允许登录 - * 5. 记录登录日志 - * 6. 返回认证结果 - */ -``` - -#### 3. 技术实现级别 -```typescript -/** - * 用户登录验证 + * 1. 调用核心服务验证用户凭证 + * 2. 生成访问令牌和刷新令牌 + * 3. 发送登录成功通知邮件 + * 4. 记录登录日志 + * 5. 返回登录结果 * - * 业务逻辑： - * 1. 验证用户名或邮箱格式 - * 2. 查找用户记录 - * 3. 验证密码哈希值 - * 4. 检查用户状态是否允许登录 - * 5. 记录登录日志 - * 6. 返回认证结果 - * - * @param loginRequest 登录请求数据 - * @returns 认证结果，包含用户信息和认证状态 - * @throws UnauthorizedException 用户名或密码错误时 - * @throws ForbiddenException 用户状态不允许登录时 + * @param dto 登录请求数据 + * @returns 登录结果，包含用户信息和令牌 + * @throws UnauthorizedException 用户名或密码错误 + * @throws ForbiddenException 用户状态不允许登录 * * @example * ```typescript - * const result = await loginService.validateUser({ + * const result = await loginService.login({ * identifier: 'user@example.com', * password: 'password123' * }); * ``` */ -async validateUser(loginRequest: LoginRequest): Promise { - // 实现代码 +async login(dto: LoginDto): Promise> { + // 实现 } ``` ### 修改记录规范 -#### 修改类型定义 - -- **代码规范优化** - 命名规范、注释规范、代码清理等 -- **功能新增** - 添加新的功能或方法 -- **功能修改** - 修改现有功能的实现 -- **Bug修复** - 修复代码缺陷 -- **性能优化** - 提升代码性能 -- **重构** - 代码结构调整但功能不变 - -#### 修改记录格式 - ```typescript /** * 最近修改： - * - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto) - * - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS) - * - 2025-01-07: 功能新增 - 添加用户验证码登录功能 - * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 + * - 2025-01-15: 架构重构 - 迁移到四层架构，分离网关层和业务层 + * - 2025-01-10: 功能新增 - 添加验证码登录功能 + * - 2025-01-08: Bug修复 - 修复Token刷新逻辑错误 + * - 2025-01-05: 代码规范优化 - 统一异常处理格式 + * - 2025-01-03: 性能优化 - 优化数据库查询性能 * - * @version 1.0.1 (修改后需要递增版本号) - * @lastModified 2025-01-07 + * @version 2.0.0 + * @lastModified 2025-01-15 */ ``` -#### 修改记录长度限制 - -**重要：为保持文件头注释简洁，修改记录只保留最近的5次修改。** - -- ✅ **保留最新5条记录** - 便于快速了解最近变更 -- ✅ **超出时删除最旧记录** - 保持注释简洁 -- ✅ **重要修改可标注** - 重大版本更新可特别标注 - -```typescript -// ✅ 正确示例：保持最新5条记录 -/** - * 最近修改： - * - 2025-01-07: 功能新增 - 添加用户头像上传功能 - * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 - * - 2025-01-05: 代码规范优化 - 统一异常处理格式 - * - 2025-01-04: 功能修改 - 优化用户状态管理逻辑 - * - 2025-01-03: 性能优化 - 优化数据库查询性能 - * - * @version 1.3.0 - */ - -// ❌ 错误示例：记录过多，注释冗长 -/** - * 最近修改： - * - 2025-01-07: 功能新增 - 添加用户头像上传功能 - * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 - * - 2025-01-05: 代码规范优化 - 统一异常处理格式 - * - 2025-01-04: 功能修改 - 优化用户状态管理逻辑 - * - 2025-01-03: 性能优化 - 优化数据库查询性能 - * - 2025-01-02: 重构 - 重构用户认证逻辑 - * - 2025-01-01: 功能新增 - 添加用户权限管理 - * - 2024-12-31: Bug修复 - 修复登录超时问题 - * // ... 更多记录导致注释过长 - */ -``` - -#### 版本号递增规则 - -- **代码规范优化、Bug修复** → 修订版本 +1 (1.0.0 → 1.0.1) -- **功能新增、功能修改** → 次版本 +1 (1.0.1 → 1.1.0) -- **重构、架构变更** → 主版本 +1 (1.1.0 → 2.0.0) +**修改记录原则：** +- 只保留最近5次修改 +- 包含日期、类型、描述 +- 重大版本更新标注版本号 --- @@ -199,22 +300,37 @@ async validateUser(loginRequest: LoginRequest): Promise { ```typescript // ERROR - 系统错误，需要立即处理 -this.logger.error('用户登录失败', { userId, error: error.message }); +this.logger.error('用户登录失败', { + userId, + error: error.message, + stack: error.stack +}); -// WARN - 警告信息，需要关注但不影响系统运行 -this.logger.warn('用户多次登录失败', { userId, attemptCount }); +// WARN - 警告信息，需要关注 +this.logger.warn('用户多次登录失败', { + userId, + attemptCount, + ip: request.ip +}); -// INFO - 重要的业务操作记录 -this.logger.info('用户登录成功', { userId, loginTime: new Date() }); +// INFO - 重要的业务操作 +this.logger.info('用户登录成功', { + userId, + loginTime: new Date(), + ip: request.ip +}); -// DEBUG - 调试信息，仅在开发环境使用 -this.logger.debug('验证用户密码', { userId, hashedPassword: '***' }); +// DEBUG - 调试信息（仅开发环境） +this.logger.debug('验证用户密码', { + userId, + passwordHash: '***' +}); ``` ### 日志格式规范 ```typescript -// ✅ 正确格式 +// ✅ 正确：结构化日志 this.logger.info('操作描述', { userId: 'user123', action: 'login', @@ -222,68 +338,26 @@ this.logger.info('操作描述', { metadata: { ip: '192.168.1.1' } }); -// ❌ 错误格式 -this.logger.info('用户登录'); +// ❌ 错误：字符串拼接 this.logger.info(`用户${userId}登录成功`); ``` ---- - -## 🏗️ 业务逻辑规范 - -### 防御性编程 +### 敏感信息处理 ```typescript -async getUserById(userId: string): Promise { - // 1. 参数验证 - if (!userId) { - throw new BadRequestException('用户ID不能为空'); - } +// ✅ 正确：隐藏敏感信息 +this.logger.info('用户注册', { + email: user.email, + password: '***', // 密码不记录 + apiKey: '***' // API密钥不记录 +}); - // 2. 业务逻辑验证 - const user = await this.usersService.findOne(userId); - if (!user) { - throw new NotFoundException('用户不存在'); - } - - // 3. 状态检查 - if (user.status === UserStatus.DELETED) { - throw new ForbiddenException('用户已被删除'); - } - - // 4. 返回结果 - return user; -} -``` - -### 业务逻辑分层 - -```typescript -// Controller 层 - 只处理HTTP请求和响应 -@Controller('users') -export class UsersController { - @Get(':id') - async getUser(@Param('id') id: string) { - return this.usersService.getUserById(id); - } -} - -// Service 层 - 处理业务逻辑 -@Injectable() -export class UsersService { - async getUserById(id: string): Promise { - // 业务逻辑实现 - return this.usersCoreService.findUserById(id); - } -} - -// Core 层 - 核心业务实现 -@Injectable() -export class UsersCoreService { - async findUserById(id: string): Promise { - // 核心逻辑实现 - } -} +// ❌ 错误：暴露敏感信息 +this.logger.info('用户注册', { + email: user.email, + password: user.password, // 危险！ + apiKey: user.apiKey // 危险！ +}); ``` --- @@ -312,38 +386,66 @@ throw new ConflictException('用户名已存在'); throw new InternalServerErrorException('系统内部错误'); ``` -### 异常处理模式 +### 分层异常处理 ```typescript -async createUser(userData: CreateUserDto): Promise { - try { - // 1. 参数验证 - this.validateUserData(userData); +// Gateway Layer - 转换为HTTP响应 +@Controller('auth') +export class LoginController { + @Post('login') + async login(@Body() dto: LoginDto, @Res() res: Response) { + const result = await this.loginService.login(dto); - // 2. 业务逻辑检查 - await this.checkUserExists(userData.email); + if (result.success) { + res.status(HttpStatus.OK).json(result); + } else { + const statusCode = this.getErrorStatusCode(result); + res.status(statusCode).json(result); + } + } +} + +// Business Layer - 返回业务响应 +@Injectable() +export class LoginService { + async login(dto: LoginDto): Promise> { + try { + const user = await this.loginCoreService.validateUser(dto); + const tokens = await this.loginCoreService.generateTokens(user); + + return { + success: true, + data: tokens, + message: '登录成功' + }; + } catch (error) { + this.logger.error('登录失败', { dto, error: error.message }); + + return { + success: false, + message: error.message, + error_code: 'LOGIN_FAILED' + }; + } + } +} + +// Core Layer - 抛出技术异常 +@Injectable() +export class LoginCoreService { + async validateUser(dto: LoginDto): Promise { + const user = await this.usersService.findByEmail(dto.email); - // 3. 执行创建操作 - const user = await this.usersRepository.create(userData); - - // 4. 记录成功日志 - this.logger.info('用户创建成功', { userId: user.id }); - - return user; - } catch (error) { - // 5. 记录错误日志 - this.logger.error('用户创建失败', { - userData: { ...userData, password: '***' }, - error: error.message - }); - - // 6. 重新抛出业务异常 - if (error instanceof BadRequestException) { - throw error; + if (!user) { + throw new UnauthorizedException('用户不存在'); } - // 7. 转换为系统异常 - throw new InternalServerErrorException('用户创建失败'); + const isValid = await bcrypt.compare(dto.password, user.password); + if (!isValid) { + throw new UnauthorizedException('密码错误'); + } + + return user; } } ``` @@ -354,152 +456,233 @@ async createUser(userData: CreateUserDto): Promise { ### 代码检查清单 -在提交代码前，请确保： +提交代码前确保： + +- [ ] **架构规范** + - [ ] 代码放在正确的架构层 + - [ ] 没有跨层直接调用（如Gateway直接调用Core） + - [ ] 依赖方向正确（上层依赖下层） + - [ ] 模块职责单一明确 - [ ] **注释完整性** - - [ ] 文件头注释包含功能描述、修改记录、作者信息 - - [ ] 类注释包含职责、主要方法、使用场景 - - [ ] 方法注释包含三级注释（功能、业务逻辑、技术实现） - - [ ] 修改现有文件时添加了修改记录和更新版本号 - - [ ] 修改记录只保留最近5次，保持注释简洁 - -- [ ] **业务逻辑完整性** - - [ ] 所有参数都进行了验证 - - [ ] 所有异常情况都进行了处理 - - [ ] 关键操作都记录了日志 - - [ ] 业务逻辑考虑了所有边界情况 + - [ ] 文件头注释包含架构层级说明 + - [ ] 类注释说明职责和主要方法 + - [ ] 方法注释包含业务逻辑和技术实现 + - [ ] 修改记录保持最近5次 - [ ] **代码质量** - [ ] 没有未使用的导入和变量 - - [ ] 常量使用了正确的命名规范 - - [ ] 方法长度合理（建议不超过50行） - - [ ] 单一职责原则，每个方法只做一件事 + - [ ] 常量使用正确命名（UPPER_SNAKE_CASE） + - [ ] 方法长度合理（不超过50行） + - [ ] 单一职责原则 -- [ ] **安全性** - - [ ] 敏感信息不在日志中暴露 - - [ ] 用户输入都进行了验证和清理 - - [ ] 权限检查在适当的位置进行 +- [ ] **日志规范** + - [ ] 关键操作记录日志 + - [ ] 使用结构化日志格式 + - [ ] 敏感信息已隐藏 + - [ ] 日志级别使用正确 + +- [ ] **异常处理** + - [ ] 所有异常情况都处理 + - [ ] 异常类型使用正确 + - [ ] 错误信息清晰明确 + - [ ] 记录了错误日志 --- ## 💡 最佳实践 -### 1. 注释驱动开发 +### 1. 遵循四层架构 ```typescript -/** - * 用户注册功能 - * - * 业务逻辑： - * 1. 验证邮箱格式和唯一性 - * 2. 验证密码强度 - * 3. 生成邮箱验证码 - * 4. 创建用户记录 - * 5. 发送验证邮件 - * 6. 返回注册结果 - * - * @param registerData 注册数据 - * @returns 注册结果 - */ -async registerUser(registerData: RegisterDto): Promise { - // 先写注释，再写实现 - // 这样确保逻辑清晰，不遗漏步骤 +// ✅ 正确：清晰的层次调用 +// Gateway → Business → Core → Data + +// Gateway Layer +@Controller('users') +export class UsersController { + constructor(private readonly usersService: UsersService) {} + + @Get(':id') + async getUser(@Param('id') id: string) { + return this.usersService.getUserById(id); + } +} + +// Business Layer +@Injectable() +export class UsersService { + constructor(private readonly usersCoreService: UsersCoreService) {} + + async getUserById(id: string): Promise> { + try { + const user = await this.usersCoreService.findUserById(id); + return { success: true, data: user }; + } catch (error) { + return { success: false, message: error.message }; + } + } +} + +// Core Layer +@Injectable() +export class UsersCoreService { + constructor( + @Inject('IUsersService') + private readonly usersDataService: IUsersService + ) {} + + async findUserById(id: string): Promise { + const user = await this.usersDataService.findOne(id); + if (!user) { + throw new NotFoundException('用户不存在'); + } + return user; + } } ``` -### 2. 错误优先处理 +### 2. 使用依赖注入接口 ```typescript -async processPayment(paymentData: PaymentDto): Promise { - // 1. 先处理所有可能的错误情况 - if (!paymentData.amount || paymentData.amount <= 0) { - throw new BadRequestException('支付金额必须大于0'); - } - - if (!paymentData.userId) { - throw new BadRequestException('用户ID不能为空'); - } - - const user = await this.usersService.findOne(paymentData.userId); - if (!user) { - throw new NotFoundException('用户不存在'); - } - - // 2. 再处理正常的业务逻辑 - return this.executePayment(paymentData); +// ✅ 正确：使用接口依赖注入 +@Injectable() +export class LoginCoreService { + constructor( + @Inject('IUsersService') + private readonly usersService: IUsersService, + @Inject('IRedisService') + private readonly redisService: IRedisService, + ) {} +} + +// ❌ 错误：直接依赖具体实现 +@Injectable() +export class LoginCoreService { + constructor( + private readonly usersService: UsersService, + private readonly redisService: RealRedisService, + ) {} } ``` -### 3. 日志驱动调试 +### 3. 统一响应格式 ```typescript -async complexBusinessLogic(data: ComplexData): Promise { - this.logger.debug('开始执行复杂业务逻辑', { data }); - +// 定义统一的响应接口 +export interface ApiResponse { + success: boolean; + data?: T; + message: string; + error_code?: string; +} + +// Business Layer 返回统一格式 +async login(dto: LoginDto): Promise> { try { - // 步骤1 - const step1Result = await this.step1(data); - this.logger.debug('步骤1完成', { step1Result }); - - // 步骤2 - const step2Result = await this.step2(step1Result); - this.logger.debug('步骤2完成', { step2Result }); - - // 步骤3 - const finalResult = await this.step3(step2Result); - this.logger.info('复杂业务逻辑执行成功', { finalResult }); - - return finalResult; + const result = await this.loginCoreService.validateUser(dto); + return { + success: true, + data: result, + message: '登录成功' + }; } catch (error) { - this.logger.error('复杂业务逻辑执行失败', { data, error: error.message }); - throw error; + return { + success: false, + message: error.message, + error_code: 'LOGIN_FAILED' + }; } } ``` -### 4. 版本管理最佳实践 +### 4. 防御性编程 ```typescript -/** - * 用户服务 - * - * 最近修改： - * - 2025-01-07: 功能新增 - 添加用户头像上传功能 (v1.2.0) - * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 (v1.1.1) - * - 2025-01-05: 代码规范优化 - 统一异常处理格式 (v1.1.0) - * - 2025-01-04: 功能新增 - 添加用户状态管理 (v1.1.0) - * - 2025-01-03: 重构 - 重构用户认证逻辑 (v2.0.0) - * - * @version 1.2.0 - * @lastModified 2025-01-07 - */ +async processPayment(dto: PaymentDto): Promise> { + // 1. 参数验证 + if (!dto.amount || dto.amount <= 0) { + return { + success: false, + message: '支付金额必须大于0', + error_code: 'INVALID_AMOUNT' + }; + } + + // 2. 业务规则验证 + const user = await this.usersService.findOne(dto.userId); + if (!user) { + return { + success: false, + message: '用户不存在', + error_code: 'USER_NOT_FOUND' + }; + } + + // 3. 状态检查 + if (user.status !== UserStatus.ACTIVE) { + return { + success: false, + message: '用户状态不允许支付', + error_code: 'USER_INACTIVE' + }; + } + + // 4. 执行业务逻辑 + return this.executePayment(dto); +} ``` -**修改记录管理原则：** -- ✅ **保持简洁** - 只保留最近5次修改 -- ✅ **定期清理** - 超出5条时删除最旧记录 -- ✅ **重要标注** - 重大版本更新可特别标注版本号 -- ✅ **描述清晰** - 每条记录都要说明具体改动内容 +### 5. 测试驱动开发 + +```typescript +// 先写测试 +describe('LoginService', () => { + it('should login successfully with valid credentials', async () => { + const dto = { identifier: 'test@example.com', password: 'password123' }; + const result = await loginService.login(dto); + + expect(result.success).toBe(true); + expect(result.data).toHaveProperty('accessToken'); + }); + + it('should return error with invalid credentials', async () => { + const dto = { identifier: 'test@example.com', password: 'wrong' }; + const result = await loginService.login(dto); + + expect(result.success).toBe(false); + expect(result.error_code).toBe('LOGIN_FAILED'); + }); +}); + +// 再写实现 +@Injectable() +export class LoginService { + async login(dto: LoginDto): Promise> { + // 实现逻辑 + } +} +``` --- ## 🎯 总结 -遵循后端开发规范能够： +遵循开发规范能够： -1. **提高代码质量** - 通过完整的注释和规范的实现 -2. **提升团队效率** - 统一的规范减少沟通成本 -3. **降低维护成本** - 清晰的文档和日志便于问题定位 -4. **增强系统稳定性** - 完善的异常处理和防御性编程 -5. **促进知识传承** - 详细的修改记录和版本管理 +1. **清晰的架构** - 四层架构确保职责分离 +2. **高质量代码** - 完整的注释和规范的实现 +3. **易于维护** - 清晰的文档和日志便于问题定位 +4. **团队协作** - 统一的规范减少沟通成本 +5. **系统稳定** - 完善的异常处理和防御性编程 -**记住：好的代码不仅要能运行，更要能被理解、维护和扩展。** +**记住：好的代码不仅要能运行，更要符合架构设计、易于理解、便于维护和扩展。** --- ## 📚 相关文档 -- [命名规范](./naming_convention.md) - 代码命名规范 -- [NestJS 使用指南](./nestjs_guide.md) - 框架最佳实践 -- [Git 提交规范](./git_commit_guide.md) - 版本控制规范 -- [AI 辅助开发规范](./AI辅助开发规范指南.md) - AI 辅助开发指南 \ No newline at end of file +- [架构设计文档](../ARCHITECTURE.md) - 四层架构详解 +- [架构重构文档](../ARCHITECTURE_REFACTORING.md) - 架构迁移指南 +- [Git提交规范](./git_commit_guide.md) - 版本控制规范 +- [测试指南](./TESTING.md) - 测试规范和最佳实践 -- 2.25.1