f7c3983cc1
范围：src/business/auth/ 涉及文件： - src/business/auth/auth.module.ts - src/business/auth/README.md 主要改进： - 移除LoginController和RegisterController的导入和声明 - 调整模块结构，专注于业务逻辑层 - 更新README文档，明确Business Layer职责定位 - 完善依赖关系说明和架构层级描述 - 版本号从1.0.2升级到2.0.0（架构重构）
🐋 Whale Town - 像素游戏后端服务
一个基于 NestJS 的现代化 2D 像素风游戏后端服务，采用业务功能模块化架构，支持用户认证、管理员后台、安全防护等完整功能。
🎯 项目简介
Whale Town 是一个功能完整的像素游戏后端服务，采用业务功能模块化架构设计：
- 🔐 用户认证模块 - 完整的登录、注册、密码管理、邮箱验证系统
- 👥 用户管理模块 - 用户状态管理、批量操作、状态统计功能
- 🛡️ 管理员模块 - 管理员认证、用户管理、密码重置、日志查看
- 🔒 安全模块 - 频率限制、维护模式、超时控制、内容类型检查
- 📧 智能邮件服务 - 支持测试模式和生产模式自动切换
- 🗄️ 灵活存储方案 - Redis文件存储 + 内存数据库，支持无依赖测试
- 📚 完整API文档 - Swagger UI + OpenAPI规范，17个接口完整覆盖
- 🧪 全面测试覆盖 - 140个单元测试用例全部通过
🚀 快速开始
📋 环境要求
- Node.js >= 18.0.0 (推荐 24.7.0)
- pnpm >= 8.0.0 (推荐 10.25.0)
🛠️ 安装与运行
# 1. 克隆项目
git clone <repository-url>
cd whale-town-end
# 2. 安装依赖
pnpm install
# 3. 配置环境（测试模式，无需数据库和邮件服务器）
cp .env.example .env
# 4. 启动开发服务器
pnpm run dev
🎉 服务启动成功！ 访问 http://localhost:3000
🧑💻 前端管理界面
项目包含一个功能完整的前端管理界面，位于 client/ 目录：
🎛️ 核心功能：
- 管理员身份认证（独立Token系统）
- 用户列表管理与搜索
- 用户密码重置功能
- 运行时日志查看与下载
- 响应式界面设计
🚀 快速启动：
# 1. 启动后端服务
pnpm run dev
# 2. 启动前端管理界面
cd client
pnpm install
pnpm run dev
# 3. 访问管理后台
# 地址: http://localhost:5173
# 默认账号: admin / Admin123456
🧪 快速测试
# 运行综合测试（推荐）
.\test-comprehensive.ps1
# 跳过限流测试（更快）
.\test-comprehensive.ps1 -SkipThrottleTest
# 测试远程服务器
.\test-comprehensive.ps1 -BaseUrl "https://your-server.com"
测试内容：
- ✅ 应用状态检查
- ✅ 邮箱验证码发送与验证
- ✅ 用户注册与登录
- ✅ 验证码登录功能
- ✅ 密码重置流程
- ✅ 邮箱冲突检测
- ✅ 验证码冷却时间清除
- ✅ 限流保护机制
- ✅ Redis文件存储功能
- ✅ 邮件测试模式
🎓 新开发者指南
第一步：了解项目规范 📚
⚠️ 重要：在开始开发前，请务必阅读以下文档
第二步：熟悉项目架构 🏗️
📁 项目文件结构总览
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 # 📖 项目主文档（当前文件）
架构特点：
- 🏗️ 业务功能模块化 - 按业务功能而非技术组件组织代码
- 🔄 双模式支持 - 开发测试模式 + 生产部署模式
- 📦 清晰分层 - 业务层 → 核心层 → 数据层
- 🧪 测试友好 - 完整的单元测试和集成测试覆盖
第三步：体验核心功能 🎮
-
API文档系统 📖
# 启动服务后访问 http://localhost:3000/api-docs -
用户认证系统 🔐
- 邮箱验证码注册
- 多方式登录（用户名/邮箱/手机号）
- 密码重置功能
-
实时通信 🌐
- WebSocket支持
- Socket.IO集成
第四步：开始贡献 🤝
- Fork项目 到你的Gitea账户
- 创建功能分支：
git checkout -b feature/your-feature - 遵循规范开发（使用AI助手帮助）
- 提交代码：
git commit -m "feat：添加新功能" - 创建Pull Request
🛠️ 技术栈
🚀 核心框架
- NestJS
^11.1.9- 企业级Node.js框架，提供依赖注入、模块化等特性 - TypeScript
^5.9.3- 类型安全的JavaScript超集 - Express
^10.4.20- 基于Express的HTTP服务器 - RxJS
^7.8.2- 响应式编程库，处理异步数据流
🌐 实时通信
- 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测试 - 跨平台测试脚本
- 集成测试 - 完整业务流程验证
- 测试模式 - 无依赖快速测试
📊 开发与测试
🔧 开发命令
# 开发服务器（热重载）
pnpm run dev
# 构建项目
pnpm run build
# 生产环境运行
pnpm run start:prod
# 代码检查
pnpm run lint
# 格式化代码
pnpm run format
🧪 测试命令
# 运行所有单元测试
pnpm test
# 监听模式运行测试
pnpm run test:watch
# 生成测试覆盖率报告
pnpm run test:cov
# API功能测试（综合测试脚本）
.\test-comprehensive.ps1
📈 测试覆盖率
- 单元测试: 140个测试用例 ✅
- 功能测试: 用户认证、用户管理、管理员后台、安全防护 ✅
- 集成测试: 完整业务流程 ✅
🌍 部署配置
测试环境（默认）
# 无需数据库和邮件服务器
USE_FILE_REDIS=true
NODE_ENV=development
# 数据库和邮件配置保持注释状态
生产环境
# 启用真实服务
USE_FILE_REDIS=false
NODE_ENV=production
# 配置数据库
DB_HOST=your_mysql_host
DB_USERNAME=your_username
DB_PASSWORD=your_password
# 配置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
详细部署指南：DEPLOYMENT.md
📚 文档中心
🎯 新手必读
📖 API文档
- Swagger UI - 交互式API文档
- API文档总览 - 使用指南
- OpenAPI规范 - 标准化描述
- Postman集合 - 测试集合
🏗️ 系统设计
🧪 测试指南
🤝 贡献者
感谢所有为项目做出贡献的开发者！
🏆 核心团队
- moyin - 核心开发者
- jianuo - 核心开发者
- angjustinl - 核心开发者
查看完整贡献者名单：docs/CONTRIBUTORS.md
🌟 如何贡献
我们欢迎所有形式的贡献：
- <EFBFBD> Bug修复 - 发现并修复问题
- ✨ 新功能 - 添加有价值的功能
- <EFBFBD> 文档改馈进 - 完善项目文档
- 🧪 测试用例 - 提高代码覆盖率
- 💡 建议反馈 - 提出改进建议
贡献流程：
- Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
📞 联系我们
- 项目地址: Gitea Repository
- 问题反馈: Issues
- 功能建议: Discussions
📄 许可证
本项目采用 MIT License 开源协议。