docs：优化README中的AI代码检查指南

- 将快速开始改为简洁的prompt模板 - 移除详细的检查步骤列表 - 简化使用说明，突出AI自动化流程 - 保留文档链接供开发者查看详细规范
2026-01-14 15:11:54 +08:00
parent 23bb3e0274
commit ff996b0dea
1 changed files with 122 additions and 368 deletions
--- 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. **<EFBFBD> Bug修复**  - 发现并修复问题
-2. **✨ 新功能** - 添加有价值的功能  
-3. **<EFBFBD> 文档改馈进** - 完善项目文档
-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)

 ---

 <div align="center">

-**🐋 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)

-</div>
+</div>