forked from datawhale/whale-town-end
cf1b37af78
范围: src/business/chat/ 涉及文件: - chat.module.ts - chat.service.ts 主要功能: - 添加ZulipAccountsModule依赖，支持查询用户Zulip账号 - 实现initializeZulipClientForUser方法，登录时自动初始化Zulip客户端 - 从数据库获取用户Zulip账号信息和API Key - 优化会话创建流程，使用已创建的Zulip客户端队列ID - 移除登出时的API Key删除逻辑，保持持久化 - 支持基于目标地图的消息发送（mapId参数） 技术改进: - 分离Zulip客户端初始化逻辑，提高代码可维护性 - 添加完整的错误处理和日志记录 - 支持用户没有Zulip账号的场景（优雅降级）
🐋 Whale Town - 像素游戏后端服务
基于 NestJS 的现代化 2D 像素游戏后端，采用四层架构（Gateway-Business-Core-Data），支持用户认证、实时通信、Zulip集成、管理员后台。
🎯 核心特性
- 🔐 用户认证：多方式登录、验证码登录、GitHub OAuth
- 🌐 实时通信：原生WebSocket、位置广播、地图房间管理
- 💬 Zulip集成：游戏内聊天与Zulip社群双向同步
- 👑 管理员后台：React界面、用户管理、日志监控
- 🛡️ 安全防护：频率限制、维护模式、JWT认证
- 🗄️ 灵活存储：MySQL/内存双模式、Redis/文件双模式
- 📚 完整文档：Swagger UI、WebSocket测试工具
🚀 快速开始
环境要求
- Node.js >= 18.0.0
- pnpm >= 8.0.0
安装运行
# 1. 克隆项目
git clone <repository-url>
cd whale-town-end
# 2. 安装依赖
pnpm install
# 3. 配置环境（测试模式，无需数据库）
cp .env.example .env
# 4. 启动服务
pnpm run dev
前端管理界面
# 启动管理后台
cd client
pnpm install
pnpm run dev
访问：http://localhost:5173
默认账号：admin / Admin123456
在线体验
- API文档：https://whaletownend.xinghangee.icu/api-docs
- WebSocket测试：https://whaletownend.xinghangee.icu/websocket-test
🏗️ 项目架构
四层架构设计
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/ # 配置文件
详细架构：docs/ARCHITECTURE.md
🛠️ 技术栈
后端： NestJS 11 + TypeScript 5 + MySQL + Redis + WebSocket
前端： React 18 + Vite 7 + Ant Design 5
测试： Jest + Supertest（99个测试用例）
部署： Docker + PM2 + Nginx
📊 开发命令
# 开发
pnpm run dev # 启动开发服务器
pnpm run build # 构建项目
pnpm run start:prod # 生产环境运行
# 测试
pnpm test # 运行单元测试
pnpm run test:cov # 测试覆盖率
.\test-comprehensive.ps1 # API功能测试
🌍 环境配置
开发环境（默认）
USE_FILE_REDIS=true # 使用文件存储（无需Redis）
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.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
详细配置：docs/deployment/DEPLOYMENT.md
📚 文档
🤖 AI代码检查指南
项目提供了完整的AI辅助代码检查流程，帮助确保代码质量和规范性。
快速开始：
向AI发送以下prompt开始代码检查：
请使用 docs/ai-reading 中readme的规范对 [模块路径] 进行完整的代码检查。
如何使用：
- AI会按照7个步骤逐步执行检查（命名规范、注释标准、代码质量、架构层级、测试覆盖、文档生成、代码提交）
- 每个步骤完成后会提供检查报告，等待确认后继续下一步
- 如有问题会自动修复并重新验证
- 这里建议每个步骤结束后，人工确认是否执行了修复，如果进行了修复，请告诉他：请重新执行一遍该步骤，看看是否有遗漏。
详细说明：docs/ai-reading/README.md | 开发者规范：docs/开发者代码检查规范.md
🤝 参与贡献
贡献流程
- Fork项目
- 创建分支：
git checkout -b feature/your-feature - 开发功能（遵循开发规范）
- 运行测试：
pnpm test - 提交代码：
git commit -m "feat: 添加新功能" - 创建Pull Request
核心团队
完整贡献者：docs/CONTRIBUTORS.md
📝 版本历史
- v2.1.0 (2026-01) - WebSocket架构升级、地图房间管理
- v2.0.0 (2025-12) - 四层架构重构、Zulip集成、管理员后台
- v1.2.0 (2025-11) - 用户管理、安全防护、邮件服务
- v1.0.0 (2025-10) - 项目初始化、用户认证、双模式存储
📞 联系方式
- 项目地址：Gitea Repository
- 问题反馈：Issues
- 功能建议：Discussions