docs：添加开发者代码检查规范文档

- 整合AI-Reading的完整7步检查流程
- 提供详细的代码规范标准和检查要求
- 包含游戏服务器特殊要求（WebSocket、双模式架构）
- 添加AI-Reading使用指南和最佳实践

主要内容：
- 命名规范：文件、变量、类、常量命名标准
- 注释规范：文件头、类、方法注释要求
- 代码质量：未使用代码清理、TODO处理
- 架构分层：Core层和Business层职责分离
- 测试覆盖：一对一测试映射、测试分离
- 功能文档：README文档、API接口文档
- 代码提交：Git变更校验、规范化提交

使用指南：
- AI-Reading系统介绍和使用场景
- 详细的使用方法和执行步骤
- 使用技巧和最佳实践建议

docs/ai-reading/README.md

@@ -0,0 +1,304 @@
+# AI代码检查执行指南 - Whale Town 游戏服务器
+
+## 🎯 执行前准备
+
+### 📋 必须收集的用户信息
+在开始任何检查之前，**必须**收集以下信息：
+- **用户当前日期**：用于修改记录和时间戳更新
+- **用户名称**：用于@author字段处理和修改记录
+
+### 🏗️ 项目特性识别
+本项目是**NestJS游戏服务器**，具有以下特点：
+- **双模式架构**：支持数据库模式和内存模式
+- **实时通信**：基于WebSocket的实时双向通信
+- **属性测试**：管理员模块使用fast-check进行随机化测试
+- **分层架构**：Core层（技术实现）+ Business层（业务逻辑）
+
+## 🔄 执行原则
+
+### ⚠️ 强制要求
+- **分步执行**：每次只执行一个步骤，严禁跳步骤或合并执行
+- **等待确认**：每步完成后必须等待用户确认才能进行下一步
+- **修改验证**：每次修改文件后必须重新检查该步骤并提供验证报告
+- **🔥 修改后必须重新执行当前步骤**：如果在当前步骤中发生了任何修改行为（文件修改、重命名、移动等），AI必须立即重新执行该步骤的完整检查，不能直接进入下一步骤
+- **问题修复后重检**：如果当前步骤出现问题需要修改时，AI必须在解决问题后重新执行该步骤，确保没有其他遗漏的问题
+- **用户信息使用**：所有日期字段使用用户提供的真实日期，@author字段正确处理
+
+### 🎯 执行流程
+```
+用户请求代码检查
+    ↓
+收集用户信息（日期、名称）
+    ↓
+识别项目特性
+    ↓
+执行步骤1 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤1 → 验证报告 → 等待确认
+    ↓
+执行步骤2 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤2 → 验证报告 → 等待确认
+    ↓
+执行步骤3 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤3 → 验证报告 → 等待确认
+    ↓
+执行步骤4 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤4 → 验证报告 → 等待确认
+    ↓
+执行步骤5 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤5 → 验证报告 → 等待确认
+    ↓
+执行步骤6 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤6 → 验证报告 → 等待确认
+    ↓
+执行步骤7 → 提供报告 → 等待确认
+    ↓
+[如果发生修改] → 🔥 立即重新执行步骤7 → 验证报告 → 等待确认
+
+⚠️ 关键规则：任何步骤中发生修改行为后，必须立即重新执行该步骤！
+```
+
+## 📚 步骤执行指导
+
+### 步骤1：命名规范检查
+**执行时读取：** `step1-naming-convention.md`
+**重点关注：** 文件夹结构扁平化、游戏服务器特殊文件类型
+**完成后：** 提供检查报告，等待用户确认
+
+### 步骤2：注释规范检查
+**执行时读取：** `step2-comment-standard.md`
+**重点关注：** @author字段处理、修改记录更新、时间戳规则
+**完成后：** 提供检查报告，等待用户确认
+
+### 步骤3：代码质量检查
+**执行时读取：** `step3-code-quality.md`
+**重点关注：** TODO项处理、未使用代码清理
+**完成后：** 提供检查报告，等待用户确认
+
+### 步骤4：架构分层检查
+**执行时读取：** `step4-architecture-layer.md`
+**重点关注：** Core层命名规范、依赖关系检查
+**完成后：** 提供检查报告，等待用户确认
+
+### 步骤5：测试覆盖检查
+**执行时读取：** `step5-test-coverage.md`
+**重点关注：** 严格一对一测试映射、测试文件位置、测试执行验证
+**完成后：** 提供检查报告，等待用户确认
+
+#### 🧪 测试文件调试规范
+**调试测试文件时必须遵循以下流程：**
+
+1. **读取jest.config.js配置**
+   - 查看jest.config.js了解测试环境配置
+   - 确认testRegex模式和文件匹配规则
+   - 了解moduleNameMapper和其他配置项
+
+2. **使用package.json中的已有测试指令**
+   - **禁止自定义jest命令**：必须使用package.json中scripts定义的测试命令
+   - **常用测试指令**：
+     - `npm run test` - 运行所有测试
+     - `npm run test:unit` - 运行单元测试(.spec.ts文件)
+     - `npm run test:integration` - 运行集成测试(.integration.spec.ts文件)
+     - `npm run test:e2e` - 运行端到端测试(.e2e.spec.ts文件)
+     - `npm run test:watch` - 监视模式运行测试
+     - `npm run test:cov` - 运行测试并生成覆盖率报告
+     - `npm run test:debug` - 调试模式运行测试
+     - `npm run test:isolated` - 隔离运行测试
+   
+3. **特定模块测试指令**
+   - **Zulip模块测试**：
+     - `npm run test:zulip` - 运行所有Zulip相关测试
+     - `npm run test:zulip:unit` - 运行Zulip单元测试
+     - `npm run test:zulip:integration` - 运行Zulip集成测试
+     - `npm run test:zulip:e2e` - 运行Zulip端到端测试
+     - `npm run test:zulip:performance` - 运行Zulip性能测试
+
+4. **测试执行验证流程**
+   ```
+   发现测试问题 → 读取jest.config.js → 选择合适的npm run test:xxx指令 → 执行测试 → 分析结果 → 修复问题 → 重新执行测试
+   ```
+
+5. **测试指令选择原则**
+   - **单个文件测试**：使用`npm run test -- 文件路径`
+   - **特定类型测试**：使用对应的test:xxx指令
+   - **调试测试**：优先使用`npm run test:debug`
+   - **CI/CD环境**：使用`npm run test:isolated`
+
+### 步骤6：功能文档生成
+**执行时读取：** `step6-documentation.md`
+**重点关注：** API接口文档、WebSocket事件文档
+**完成后：** 提供检查报告，等待用户确认
+
+### 步骤7：代码提交
+**执行时读取：** `step7-code-commit.md`
+**重点关注：** Git变更校验、修改记录一致性检查、规范化提交流程
+**完成后：** 提供检查报告，等待用户确认
+
+## 📋 统一报告模板
+
+每步完成后使用此模板报告：
+
+```
+## 步骤X：[步骤名称]检查报告
+
+### 🔍 检查结果
+[发现的问题列表]
+
+### 🛠️ 修正方案  
+[具体修正建议]
+
+### ✅ 完成状态
+- 检查项1 ✓/✗
+- 检查项2 ✓/✗
+
+**请确认修正方案，确认后进行下一步骤**
+```
+
+## 🚨 全局约束
+
+### 📝 文件修改记录规范（重要）
+**每次执行完修改后，文件顶部都需要更新修改记录和相关信息**
+
+#### 修改类型定义
+- `代码规范优化` - 命名规范、注释规范、代码清理等
+- `功能新增` - 添加新的功能或方法
+- `功能修改` - 修改现有功能的实现
+- `Bug修复` - 修复代码缺陷
+- `性能优化` - 提升代码性能
+- `重构` - 代码结构调整但功能不变
+
+#### 修改记录格式要求
+```typescript
+/**
+ * 最近修改：
+ * - [用户日期]: 代码规范优化 - 清理未使用的导入 (修改者: [用户名称])
+ * - 2024-01-06: Bug修复 - 修复邮箱验证逻辑错误 (修改者: 李四)
+ * - 2024-01-05: 功能新增 - 添加用户验证码登录功能 (修改者: 王五)
+ * 
+ * @author [处理后的作者名称]
+ * @version x.x.x
+ * @since [创建日期]
+ * @lastModified [用户日期]
+ */
+```
+
+#### 🔢 最近修改记录数量限制
+- **最多保留5条**：最近修改记录最多只保留最新的5条记录
+- **超出自动删除**：当添加新的修改记录时，如果超过5条，自动删除最旧的记录
+- **保持时间顺序**：记录按时间倒序排列，最新的在最上面
+- **完整记录保留**：每条记录必须包含完整的日期、修改类型、描述和修改者信息
+
+#### 版本号递增规则
+- **修订版本+1**：代码规范优化、Bug修复 (1.0.0 → 1.0.1)
+- **次版本+1**：功能新增、功能修改 (1.0.1 → 1.1.0)
+- **主版本+1**：重构、架构变更 (1.1.0 → 2.0.0)
+
+#### 时间更新规则
+- **仅检查不修改**：如果只是检查而没有实际修改文件内容，**不更新**@lastModified字段
+- **实际修改才更新**：只有真正修改了文件内容时才更新@lastModified字段和添加修改记录
+- **Git变更检测**：通过`git status`和`git diff`检查文件是否有实际变更，只有git显示文件被修改时才需要添加修改记录和更新时间戳
+
+### @author字段处理规范
+- **保留原则**：人名必须保留，不得随意修改
+- **AI标识替换**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
+- **判断示例**：`@author kiro` → 可替换，`@author 张三` → 必须保留
+
+### 游戏服务器特殊要求
+- **WebSocket文件**：Gateway文件必须有完整的连接、消息处理测试
+- **双模式服务**：内存服务和数据库服务都需要完整测试覆盖
+- **属性测试**：管理员模块使用fast-check进行属性测试
+- **测试分离**：严格区分单元测试、集成测试、E2E测试、性能测试
+
+## 🔧 修改验证流程
+
+### 🔥 修改后立即重新执行规则（重要）
+**任何步骤中发生修改行为后，AI必须立即重新执行该步骤，不能直接进入下一步骤！**
+
+#### 修改行为包括但不限于：
+- 文件内容修改（代码、注释、配置等）
+- 文件重命名
+- 文件移动
+- 文件删除
+- 新建文件
+- 文件夹结构调整
+
+#### 强制执行流程：
+```
+步骤执行中 → 发现问题 → 执行修改 → 🔥 立即重新执行该步骤 → 验证无遗漏 → 用户确认 → 下一步骤
+```
+
+### 问题修复后的重检流程
+当在任何步骤中发现问题并进行修改后，必须遵循以下流程：
+
+1. **执行修改操作**
+   - 根据发现的问题进行具体修改
+   - 确保修改内容准确无误
+   - **更新文件顶部的修改记录、版本号和@lastModified字段**
+
+2. **🔥 立即重新执行当前步骤**
+   - **不能跳过这一步！**
+   - 完整重新执行该步骤的所有检查项
+   - 不能只检查修改的部分，必须全面重检
+
+3. **提供验证报告**
+   - 确认之前发现的问题已解决
+   - 确认没有引入新的问题
+   - 确认没有遗漏其他问题
+
+4. **等待用户确认**
+   - 提供完整的验证报告
+   - 等待用户确认后才能进行下一步骤
+
+### 验证报告模板
+```
+## 步骤X：修改验证报告
+
+### 🔧 已执行的修改操作
+- 修改类型：[文件修改/重命名/移动/删除等]
+- 修改内容：[具体修改描述]
+- 影响文件：[受影响的文件列表]
+
+### 📝 已更新的修改记录
+- 添加修改记录：[用户日期]: [修改类型] - [修改内容] (修改者: [用户名称])
+- 更新版本号：[旧版本] → [新版本]
+- 更新时间戳：@lastModified [用户日期]
+
+### 🔍 重新执行步骤X的完整检查结果
+[完整重新执行该步骤的所有检查项的结果]
+
+### ✅ 验证状态
+- 原问题已解决 ✓
+- 修改记录已更新 ✓
+- 无新问题引入 ✓
+- 无其他遗漏问题 ✓
+- 步骤X检查完全通过 ✓
+
+**🔥 重要：本步骤已完成修改并重新验证，请确认后进行下一步骤**
+```
+
+### 重检的重要性
+- **确保完整性**：避免修改过程中遗漏其他问题
+- **防止新问题**：确保修改没有引入新的问题
+- **保证质量**：每个步骤都达到完整的检查标准
+- **维护一致性**：确保整个检查过程的严谨性
+- **🔥 强制执行**：修改后必须重新执行，不能跳过这个环节
+
+## ⚡ 关键成功要素
+
+- **严格按步骤执行**：不跳步骤，不合并执行
+- **🔥 修改后立即重新执行**：任何修改行为后必须立即重新执行当前步骤，不能直接进入下一步
+- **问题修复后必须重检**：修改文件后必须重新执行整个步骤，确保无遗漏
+- **修改记录必须更新**：每次修改文件后都必须更新文件顶部的修改记录、版本号和时间戳
+- **真实修改验证**：通过工具验证修改效果
+- **用户信息准确使用**：日期和名称信息正确应用
+- **项目特性适配**：针对游戏服务器特点优化检查
+- **完整报告提供**：每步都提供详细的检查报告
+
+---
+
+**开始执行前，请确认已收集用户日期和名称信息！**

docs/ai-reading/step1-naming-convention.md

@@ -0,0 +1,167 @@
+# 步骤1：命名规范检查
+
+## 🎯 检查目标
+检查和修正所有命名规范问题，确保项目代码命名一致性。
+
+## 📋 命名规范标准
+
+### 文件和文件夹命名
+- **规则**：snake_case（下划线分隔），保持项目一致性
+- **示例**：
+  ```
+  ✅ 正确：user_controller.ts, admin_operation_log_service.ts
+  ❌ 错误：UserController.ts, user-service.ts, adminOperationLog.service.ts
+  ```
+
+### 变量和函数命名
+- **规则**：camelCase（小驼峰命名）
+- **示例**：
+  ```typescript
+  ✅ 正确：const userName = 'test'; function getUserInfo() {}
+  ❌ 错误：const UserName = 'test'; function GetUserInfo() {}
+  ```
+
+### 类和接口命名
+- **规则**：PascalCase（大驼峰命名）
+- **示例**：
+  ```typescript
+  ✅ 正确：class UserService {} interface GameConfig {}
+  ❌ 错误：class userService {} interface gameConfig {}
+  ```
+
+### 常量命名
+- **规则**：SCREAMING_SNAKE_CASE（全大写+下划线）
+- **示例**：
+  ```typescript
+  ✅ 正确：const MAX_RETRY_COUNT = 3; const SALT_ROUNDS = 10;
+  ❌ 错误：const maxRetryCount = 3; const saltRounds = 10;
+  ```
+
+### 路由命名
+- **规则**：kebab-case（短横线分隔）
+- **示例**：
+  ```typescript
+  ✅ 正确：@Get('user/get-info') @Post('room/join-room')
+  ❌ 错误：@Get('user/getInfo') @Post('room/joinRoom')
+  ```
+
+## 🎮 游戏服务器特殊文件类型
+
+### WebSocket相关文件
+```
+✅ 正确命名：
+- location_broadcast.gateway.ts     # WebSocket网关
+- websocket_auth.guard.ts          # WebSocket认证守卫
+- realtime_chat.service.ts         # 实时通信服务
+```
+
+### 双模式服务文件
+```
+✅ 正确命名：
+- users_memory.service.ts          # 内存模式服务
+- users_database.service.ts        # 数据库模式服务
+- file_redis.service.ts            # Redis文件存储
+```
+
+### 测试文件分类
+```
+✅ 正确命名：
+- user.service.spec.ts             # 单元测试
+- admin.integration.spec.ts        # 集成测试
+- location.property.spec.ts        # 属性测试（管理员模块）
+- auth.e2e.spec.ts                 # E2E测试
+- websocket.perf.spec.ts           # 性能测试
+```
+
+## 🏗️ 文件夹结构检查
+
+### 检查方法（必须使用工具）
+1. **使用listDirectory工具**：`listDirectory(path, depth=2)`获取完整结构
+2. **统计文件数量**：逐个文件夹统计文件数量
+3. **识别单文件文件夹**：只有1个文件的文件夹
+4. **执行扁平化**：将文件移动到上级目录
+5. **更新引用路径**：修改所有import语句
+
+### 扁平化标准
+- **≤3个文件**：必须扁平化处理
+- **≥4个文件**：通常保持独立文件夹
+- **完整功能模块**：即使文件较少也可保持独立（需特殊说明）
+
+### 测试文件位置规范（重要）
+- ✅ **正确**：测试文件与源文件放在同一目录
+- ❌ **错误**：测试文件放在单独的tests/、test/、spec/、__tests__/文件夹
+
+```
+✅ 正确结构：
+src/business/auth/
+├── auth.service.ts
+├── auth.service.spec.ts
+├── auth.controller.ts
+└── auth.controller.spec.ts
+
+❌ 错误结构：
+src/business/auth/
+├── auth.service.ts
+├── auth.controller.ts
+└── tests/
+    ├── auth.service.spec.ts
+    └── auth.controller.spec.ts
+```
+
+## 🔧 Core层命名规则
+
+### 业务支撑模块（使用_core后缀）
+专门为特定业务功能提供技术支撑：
+```
+✅ 正确：
+- location_broadcast_core/    # 为位置广播业务提供技术支撑
+- admin_core/                 # 为管理员业务提供技术支撑
+- user_auth_core/            # 为用户认证业务提供技术支撑
+```
+
+### 通用工具模块（不使用后缀）
+提供可复用的数据访问或技术服务：
+```
+✅ 正确：
+- user_profiles/             # 通用用户档案数据访问
+- redis/                     # 通用Redis技术封装
+- logger/                    # 通用日志工具服务
+```
+
+### 判断方法
+```
+1. 模块是否专门为某个特定业务服务？
+   ├─ 是 → 使用_core后缀
+   └─ 否 → 不使用后缀
+
+2. 实际案例：
+   - user_profiles: 通用数据访问 → 不使用后缀 ✓
+   - location_broadcast_core: 专门为位置广播服务 → 使用_core后缀 ✓
+```
+
+## ⚠️ 常见检查错误
+
+1. **只看文件夹名称，不检查内容**
+2. **凭印象判断，不使用工具获取准确数据**
+3. **遗漏≤3个文件文件夹的识别**
+4. **忽略测试文件夹扁平化**：认为tests文件夹是"标准结构"
+
+## 🔍 检查执行步骤
+
+1. **使用listDirectory工具检查目标文件夹结构**
+2. **逐个检查文件和文件夹命名是否符合规范**
+3. **统计每个文件夹的文件数量**
+4. **识别需要扁平化的文件夹（≤3个文件）**
+5. **检查Core层模块命名是否正确**
+6. **执行必要的文件移动和重命名操作**
+7. **更新所有相关的import路径引用**
+8. **验证修改后的结构和命名**
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（文件重命名、移动、删除等），必须立即重新执行步骤1的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤1 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接进入步骤2（错误做法）
+
+**不能跳过重新检查环节！**

docs/ai-reading/step2-comment-standard.md

@@ -0,0 +1,250 @@
+# 步骤2：注释规范检查
+
+## 🎯 检查目标
+检查和完善所有注释规范，确保文件头、类、方法注释的完整性和准确性。
+
+## 📋 注释规范标准
+
+### 文件头注释（必须包含）
+```typescript
+/**
+ * 文件功能描述
+ * 
+ * 功能描述：
+ * - 主要功能点1
+ * - 主要功能点2
+ * - 主要功能点3
+ * 
+ * 职责分离：
+ * - 职责描述1
+ * - 职责描述2
+ * 
+ * 最近修改：
+ * - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
+ * - [历史日期]: 修改类型 - 修改内容 (修改者: 历史修改者)
+ * 
+ * @author [处理后的作者名称]
+ * @version x.x.x
+ * @since [创建日期]
+ * @lastModified [用户日期]
+ */
+```
+
+### 类注释（必须包含）
+```typescript
+/**
+ * 类功能描述
+ * 
+ * 职责：
+ * - 主要职责1
+ * - 主要职责2
+ * 
+ * 主要方法：
+ * - method1() - 方法1功能
+ * - method2() - 方法2功能
+ * 
+ * 使用场景：
+ * - 场景描述
+ */
+@Injectable()
+export class ExampleService {
+  // 类实现
+}
+```
+
+### 方法注释（必须包含）
+```typescript
+/**
+ * 方法功能描述
+ * 
+ * 业务逻辑：
+ * 1. 步骤1描述
+ * 2. 步骤2描述
+ * 3. 步骤3描述
+ * 
+ * @param paramName 参数描述
+ * @returns 返回值描述
+ * @throws ExceptionType 异常情况描述
+ * 
+ * @example
+ * ```typescript
+ * const result = await service.methodName(param);
+ * ```
+ */
+async methodName(paramName: ParamType): Promise<ReturnType> {
+  // 方法实现
+}
+```
+
+## 🔧 @author字段处理规范
+
+### 处理原则
+- **保留人名**：如果@author是人名，必须保留不变
+- **替换AI标识**：只有AI标识才可替换为用户名称
+
+### 判断标准
+```typescript
+// ✅ 可以替换的AI标识
+@author kiro          → 替换为 @author [用户名称]
+@author ChatGPT       → 替换为 @author [用户名称]
+@author Claude        → 替换为 @author [用户名称]
+@author AI            → 替换为 @author [用户名称]
+
+// ❌ 必须保留的人名
+@author 张三          → 保留为 @author 张三
+@author John Smith    → 保留为 @author John Smith
+@author 李四          → 保留为 @author 李四
+```
+
+## 📝 修改记录规范
+
+### 检查要点
+步骤2需要检查文件头注释中的修改记录是否符合全局规范（详见README.md全局约束部分）：
+
+- ✅ 修改记录格式是否正确
+- ✅ 修改类型是否准确
+- ✅ 用户日期和名称是否正确使用
+- ✅ 版本号是否按规则递增
+- ✅ @lastModified字段是否正确更新
+
+### 常见检查项
+```typescript
+// ✅ 检查修改记录格式
+/**
+ * 最近修改：
+ * - [用户日期]: 代码规范优化 - 清理未使用的导入 (修改者: [用户名称])
+ * - 历史记录...
+ */
+
+// ✅ 检查版本号递增
+@version 1.0.1  // 代码规范优化应该递增修订版本
+
+// ✅ 检查时间戳更新
+@lastModified [用户日期]  // 只有实际修改才更新
+```
+
+**注意：具体的修改记录规范请参考README.md中的全局约束部分**
+
+## 📊 版本号递增规则
+
+### 检查要点
+步骤2需要检查版本号是否按照全局规范正确递增（详见README.md全局约束部分）：
+
+- ✅ 代码规范优化、Bug修复 → 修订版本+1
+- ✅ 功能新增、功能修改 → 次版本+1  
+- ✅ 重构、架构变更 → 主版本+1
+
+### 检查示例
+```typescript
+// 检查版本号递增是否正确
+@version 1.0.0 → @version 1.0.1  // 代码规范优化
+@version 1.0.1 → @version 1.1.0  // 功能新增
+@version 1.1.0 → @version 2.0.0  // 重构
+```
+
+## ⏰ 时间更新规则
+
+### 检查要点
+步骤2需要检查时间戳更新是否符合全局规范（详见README.md全局约束部分）：
+
+- ✅ 仅检查不修改时，不更新@lastModified字段
+- ✅ 实际修改文件内容时，才更新@lastModified字段
+- ✅ 使用Git变更检测确认文件是否真正被修改
+
+### Git变更检测检查
+```bash
+git status                    # 检查是否有文件被修改
+git diff [filename]          # 检查具体修改内容
+```
+
+**注意：具体的时间更新规则请参考README.md中的全局约束部分**
+
+## 🎮 游戏服务器特殊注释要求
+
+### WebSocket Gateway注释
+```typescript
+/**
+ * 位置广播WebSocket网关
+ * 
+ * 功能描述：
+ * - 处理客户端WebSocket连接
+ * - 实时广播用户位置更新
+ * - 管理游戏房间成员
+ * 
+ * WebSocket事件：
+ * - connection: 客户端连接事件
+ * - position_update: 位置更新事件
+ * - disconnect: 客户端断开事件
+ */
+```
+
+### 双模式服务注释
+```typescript
+/**
+ * 用户服务（内存模式）
+ * 
+ * 功能描述：
+ * - 提供用户数据的内存存储访问
+ * - 支持开发测试和故障降级场景
+ * - 与数据库模式保持接口一致性
+ * 
+ * 模式特点：
+ * - 数据存储在内存Map中
+ * - 应用重启后数据丢失
+ * - 适用于开发测试环境
+ */
+```
+
+### 属性测试注释
+```typescript
+/**
+ * 管理员服务属性测试
+ * 
+ * 功能描述：
+ * - 使用fast-check进行基于属性的随机测试
+ * - 验证管理员操作的正确性和边界条件
+ * - 自动发现潜在的边界情况问题
+ * 
+ * 测试策略：
+ * - 随机生成用户状态变更
+ * - 验证操作结果的一致性
+ * - 检查异常处理的完整性
+ */
+```
+
+## 🔍 检查执行步骤
+
+1. **检查文件头注释完整性**
+   - 功能描述是否清晰
+   - 职责分离是否明确
+   - 修改记录是否使用用户信息
+   - @author字段是否正确处理
+
+2. **检查类注释完整性**
+   - 职责描述是否清晰
+   - 主要方法是否列出
+   - 使用场景是否说明
+
+3. **检查方法注释完整性**
+   - 业务逻辑步骤是否详细
+   - @param、@returns、@throws是否完整
+   - @example是否提供
+
+4. **验证修改记录和版本号**
+   - 使用git检查文件是否有实际变更
+   - 根据修改类型正确递增版本号
+   - 只有实际修改才更新时间戳
+
+5. **特殊文件类型注释检查**
+   - WebSocket Gateway的事件说明
+   - 双模式服务的模式特点
+   - 属性测试的测试策略
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（添加注释、更新修改记录、修正@author字段等），必须立即重新执行步骤2的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤2 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接进入步骤3（错误做法）
+
+**不能跳过重新检查环节！**

docs/ai-reading/step3-code-quality.md

@@ -0,0 +1,327 @@
+# 步骤3：代码质量检查
+
+## 🎯 检查目标
+清理和优化代码质量，消除未使用代码、规范常量定义、处理TODO项。
+
+## 🧹 未使用代码清理
+
+### 清理未使用的导入
+```typescript
+// ❌ 错误：导入未使用的模块
+import { Injectable, NotFoundException, BadRequestException } from '@nestjs/common';
+import { User, Admin } from './user.entity';
+import * as crypto from 'crypto'; // 未使用
+import { RedisService } from '../redis/redis.service'; // 未使用
+
+// ✅ 正确：只导入使用的模块
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { User } from './user.entity';
+```
+
+### 清理未使用的变量
+```typescript
+// ❌ 错误：定义但未使用的变量
+const unusedVariable = 'test';
+let tempData = [];
+
+// ✅ 正确：删除未使用的变量
+// 只保留实际使用的变量
+```
+
+### 清理未使用的方法
+```typescript
+// ❌ 错误：定义但未调用的私有方法
+private generateVerificationCode(): string {
+  // 如果这个方法没有被调用，应该删除
+}
+
+// ✅ 正确：删除未使用的私有方法
+// 或者确保方法被正确调用
+```
+
+## 📊 常量定义规范
+
+### 使用SCREAMING_SNAKE_CASE
+```typescript
+// ✅ 正确：使用全大写+下划线
+const SALT_ROUNDS = 10;
+const MAX_LOGIN_ATTEMPTS = 5;
+const DEFAULT_PAGE_SIZE = 20;
+const WEBSOCKET_TIMEOUT = 30000;
+const MAX_ROOM_CAPACITY = 100;
+
+// ❌ 错误：使用小驼峰
+const saltRounds = 10;
+const maxLoginAttempts = 5;
+const defaultPageSize = 20;
+```
+
+### 提取魔法数字为常量
+```typescript
+// ❌ 错误：使用魔法数字
+if (attempts > 5) {
+  throw new Error('Too many attempts');
+}
+setTimeout(callback, 30000);
+
+// ✅ 正确：提取为常量
+const MAX_LOGIN_ATTEMPTS = 5;
+const WEBSOCKET_TIMEOUT = 30000;
+
+if (attempts > MAX_LOGIN_ATTEMPTS) {
+  throw new Error('Too many attempts');
+}
+setTimeout(callback, WEBSOCKET_TIMEOUT);
+```
+
+## 📏 方法长度检查
+
+### 长度限制
+- **建议**：方法不超过50行
+- **原则**：一个方法只做一件事
+- **拆分**：复杂方法拆分为多个小方法
+
+### 方法拆分示例
+```typescript
+// ❌ 错误：方法过长（超过50行）
+async processUserRegistration(userData: CreateUserDto): Promise<User> {
+  // 验证用户数据
+  // 检查邮箱是否存在
+  // 生成密码哈希
+  // 创建用户记录
+  // 发送欢迎邮件
+  // 记录操作日志
+  // 返回用户信息
+  // ... 超过50行的复杂逻辑
+}
+
+// ✅ 正确：拆分为多个小方法
+async processUserRegistration(userData: CreateUserDto): Promise<User> {
+  await this.validateUserData(userData);
+  await this.checkEmailExists(userData.email);
+  const hashedPassword = await this.generatePasswordHash(userData.password);
+  const user = await this.createUserRecord({ ...userData, password: hashedPassword });
+  await this.sendWelcomeEmail(user.email);
+  await this.logUserRegistration(user.id);
+  return user;
+}
+
+private async validateUserData(userData: CreateUserDto): Promise<void> {
+  // 验证逻辑
+}
+
+private async checkEmailExists(email: string): Promise<void> {
+  // 邮箱检查逻辑
+}
+```
+
+## 🔄 代码重复消除
+
+### 识别重复代码
+```typescript
+// ❌ 错误：重复的验证逻辑
+async createUser(userData: CreateUserDto): Promise<User> {
+  if (!userData.email || !userData.name) {
+    throw new BadRequestException('Required fields missing');
+  }
+  if (!this.isValidEmail(userData.email)) {
+    throw new BadRequestException('Invalid email format');
+  }
+  // 创建用户逻辑
+}
+
+async updateUser(id: string, userData: UpdateUserDto): Promise<User> {
+  if (!userData.email || !userData.name) {
+    throw new BadRequestException('Required fields missing');
+  }
+  if (!this.isValidEmail(userData.email)) {
+    throw new BadRequestException('Invalid email format');
+  }
+  // 更新用户逻辑
+}
+
+// ✅ 正确：抽象为可复用方法
+async createUser(userData: CreateUserDto): Promise<User> {
+  this.validateUserData(userData);
+  // 创建用户逻辑
+}
+
+async updateUser(id: string, userData: UpdateUserDto): Promise<User> {
+  this.validateUserData(userData);
+  // 更新用户逻辑
+}
+
+private validateUserData(userData: CreateUserDto | UpdateUserDto): void {
+  if (!userData.email || !userData.name) {
+    throw new BadRequestException('Required fields missing');
+  }
+  if (!this.isValidEmail(userData.email)) {
+    throw new BadRequestException('Invalid email format');
+  }
+}
+```
+
+## 🚫 TODO项处理（强制要求）
+
+### 处理原则
+**最终文件不能包含TODO项**，必须：
+1. **真正实现功能**
+2. **删除未完成代码**
+
+### 常见TODO处理
+```typescript
+// ❌ 错误：包含TODO项的代码
+async getUserProfile(id: string): Promise<UserProfile> {
+  // TODO: 实现用户档案查询
+  throw new Error('Not implemented');
+}
+
+async sendSmsVerification(phone: string): Promise<void> {
+  // TODO: 集成短信服务提供商
+  throw new Error('SMS service not implemented');
+}
+
+// ✅ 正确：真正实现功能
+async getUserProfile(id: string): Promise<UserProfile> {
+  const profile = await this.userProfileRepository.findOne({ 
+    where: { userId: id } 
+  });
+  
+  if (!profile) {
+    throw new NotFoundException('用户档案不存在');
+  }
+  
+  return profile;
+}
+
+// ✅ 正确：如果功能不需要，删除方法
+// 删除sendSmsVerification方法及其调用
+```
+
+## 🎮 游戏服务器特殊质量要求
+
+### WebSocket连接管理
+```typescript
+// ✅ 正确：完整的连接管理
+const MAX_CONNECTIONS_PER_ROOM = 100;
+const CONNECTION_TIMEOUT = 30000;
+const HEARTBEAT_INTERVAL = 10000;
+
+@WebSocketGateway()
+export class LocationBroadcastGateway {
+  private readonly connections = new Map<string, Socket>();
+  
+  handleConnection(client: Socket): void {
+    this.validateConnection(client);
+    this.setupHeartbeat(client);
+    this.trackConnection(client);
+  }
+  
+  private validateConnection(client: Socket): void {
+    // 连接验证逻辑
+  }
+  
+  private setupHeartbeat(client: Socket): void {
+    // 心跳检测逻辑
+  }
+}
+```
+
+### 双模式服务质量
+```typescript
+// ✅ 正确：确保两种模式行为一致
+const DEFAULT_USER_STATUS = UserStatus.PENDING;
+const MAX_BATCH_SIZE = 1000;
+
+@Injectable()
+export class UsersMemoryService {
+  private readonly users = new Map<string, User>();
+  
+  async create(userData: CreateUserDto): Promise<User> {
+    this.validateUserData(userData);
+    const user = this.buildUserEntity(userData);
+    this.users.set(user.id, user);
+    return user;
+  }
+  
+  private validateUserData(userData: CreateUserDto): void {
+    // 与数据库模式相同的验证逻辑
+  }
+  
+  private buildUserEntity(userData: CreateUserDto): User {
+    // 与数据库模式相同的实体构建逻辑
+  }
+}
+```
+
+### 属性测试质量
+```typescript
+// ✅ 正确：完整的属性测试实现
+import * as fc from 'fast-check';
+
+const PROPERTY_TEST_RUNS = 1000;
+const MAX_USER_ID = 1000000;
+
+describe('AdminService Properties', () => {
+  it('should handle any valid user status update', () => {
+    fc.assert(fc.property(
+      fc.integer({ min: 1, max: MAX_USER_ID }),
+      fc.constantFrom(...Object.values(UserStatus)),
+      async (userId, status) => {
+        try {
+          const result = await adminService.updateUserStatus(userId, status);
+          expect(result).toBeDefined();
+          expect(result.status).toBe(status);
+        } catch (error) {
+          expect(error).toBeInstanceOf(NotFoundException || BadRequestException);
+        }
+      }
+    ), { numRuns: PROPERTY_TEST_RUNS });
+  });
+});
+```
+
+## 🔍 检查执行步骤
+
+1. **扫描未使用的导入**
+   - 检查每个import语句是否被使用
+   - 删除未使用的导入
+
+2. **扫描未使用的变量和方法**
+   - 检查变量是否被引用
+   - 检查私有方法是否被调用
+   - 删除未使用的代码
+
+3. **检查常量定义**
+   - 识别魔法数字和字符串
+   - 提取为SCREAMING_SNAKE_CASE常量
+   - 确保常量命名清晰
+
+4. **检查方法长度**
+   - 统计每个方法的行数
+   - 识别超过50行的方法
+   - 建议拆分复杂方法
+
+5. **识别重复代码**
+   - 查找相似的代码块
+   - 抽象为可复用的工具方法
+   - 消除代码重复
+
+6. **处理所有TODO项**
+   - 搜索所有TODO注释
+   - 要求真正实现功能或删除代码
+   - 确保最终文件无TODO项
+
+7. **游戏服务器特殊检查**
+   - WebSocket连接管理完整性
+   - 双模式服务行为一致性
+   - 属性测试实现质量
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（删除未使用代码、提取常量、实现TODO项等），必须立即重新执行步骤3的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤3 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接进入步骤4（错误做法）
+
+**不能跳过重新检查环节！**

docs/ai-reading/step4-architecture-layer.md

@@ -0,0 +1,310 @@
+# 步骤4：架构分层检查
+
+## 🎯 检查目标
+检查架构分层的合规性，确保Core层和Business层职责清晰、依赖关系正确。
+
+## 🏗️ 架构层级识别
+
+### 项目分层结构
+```
+src/
+├── core/           # Core层：技术实现层
+│   ├── db/         # 数据访问
+│   ├── redis/      # 缓存服务
+│   └── utils/      # 工具服务
+├── business/       # Business层：业务逻辑层
+│   ├── auth/       # 认证业务
+│   ├── users/      # 用户业务
+│   └── admin/      # 管理业务
+└── common/         # 公共层：通用组件
+```
+
+### 检查范围
+- **限制范围**：仅检查当前执行检查的文件夹
+- **不跨模块**：不考虑其他同层功能模块
+- **专注职责**：确保当前模块职责清晰
+
+## 🔧 Core层规范检查
+
+### 职责定义
+**Core层专注技术实现，不包含业务逻辑**
+
+### 命名规范检查
+
+#### 业务支撑模块（使用_core后缀）
+专门为特定业务功能提供技术支撑：
+```typescript
+✅ 正确示例：
+src/core/location_broadcast_core/     # 为位置广播业务提供技术支撑
+src/core/admin_core/                  # 为管理员业务提供技术支撑
+src/core/user_auth_core/              # 为用户认证业务提供技术支撑
+src/core/zulip_core/                  # 为Zulip集成提供技术支撑
+
+❌ 错误示例：
+src/core/location_broadcast/          # 应该是location_broadcast_core
+src/core/admin/                       # 应该是admin_core
+```
+
+#### 通用工具模块（不使用后缀）
+提供可复用的数据访问或技术服务：
+```typescript
+✅ 正确示例：
+src/core/db/user_profiles/            # 通用的用户档案数据访问
+src/core/redis/                       # 通用的Redis技术封装
+src/core/utils/logger/                # 通用的日志工具服务
+src/core/db/zulip_accounts/           # 通用的Zulip账户数据访问
+
+❌ 错误示例：
+src/core/db/user_profiles_core/       # 应该是user_profiles（通用工具）
+src/core/redis_core/                  # 应该是redis（通用工具）
+```
+
+### 命名判断流程
+```
+1. 模块是否专门为某个特定业务功能服务？
+   ├─ 是 → 检查模块名称是否体现业务领域
+   │   ├─ 是 → 使用 _core 后缀
+   │   └─ 否 → 重新设计模块职责
+   └─ 否 → 模块是否提供通用的技术服务？
+       ├─ 是 → 不使用 _core 后缀
+       └─ 否 → 重新评估模块定位
+
+2. 实际案例判断：
+   - user_profiles: 通用的用户档案数据访问 → 不使用后缀 ✓
+   - location_broadcast_core: 专门为位置广播业务服务 → 使用_core后缀 ✓
+   - redis: 通用的缓存技术服务 → 不使用后缀 ✓
+   - zulip_core: 专门为Zulip集成业务服务 → 使用_core后缀 ✓
+```
+
+### Core层技术实现示例
+```typescript
+// ✅ 正确：Core层专注技术实现
+@Injectable()
+export class LocationBroadcastCoreService {
+  /**
+   * 广播位置更新到指定房间
+   * 
+   * 技术实现：
+   * 1. 验证WebSocket连接状态
+   * 2. 序列化位置数据
+   * 3. 通过Socket.IO广播消息
+   * 4. 记录广播性能指标
+   * 5. 处理广播异常和重试
+   */
+  async broadcastToRoom(roomId: string, data: PositionData): Promise<void> {
+    const room = this.server.sockets.adapter.rooms.get(roomId);
+    if (!room) {
+      throw new NotFoundException(`Room ${roomId} not found`);
+    }
+    
+    this.server.to(roomId).emit('position-update', data);
+    this.metricsService.recordBroadcast(roomId, data.userId);
+  }
+}
+
+// ❌ 错误：Core层包含业务逻辑
+@Injectable()
+export class LocationBroadcastCoreService {
+  async broadcastUserPosition(userId: string, position: Position): Promise<void> {
+    // 错误：包含了用户权限检查的业务概念
+    const user = await this.userService.findById(userId);
+    if (user.status !== UserStatus.ACTIVE) {
+      throw new ForbiddenException('用户状态不允许位置广播');
+    }
+  }
+}
+```
+
+### Core层依赖关系检查
+```typescript
+// ✅ 允许的导入
+import { Injectable } from '@nestjs/common';           # NestJS框架
+import { Server } from 'socket.io';                   # 第三方技术库
+import { RedisService } from '../redis/redis.service'; # 其他Core层模块
+import * as crypto from 'crypto';                     # Node.js内置模块
+
+// ❌ 禁止的导入
+import { UserBusinessService } from '../../business/users/user.service'; # Business层模块
+import { AdminController } from '../../business/admin/admin.controller'; # Business层模块
+```
+
+## 💼 Business层规范检查
+
+### 职责定义
+**Business层专注业务逻辑实现，不关心底层技术细节**
+
+### 业务逻辑完备性检查
+```typescript
+// ✅ 正确：完整的业务逻辑
+@Injectable()
+export class UserBusinessService {
+  /**
+   * 用户注册业务流程
+   * 
+   * 业务逻辑：
+   * 1. 验证用户信息完整性
+   * 2. 检查用户名/邮箱是否已存在
+   * 3. 验证邮箱格式和域名白名单
+   * 4. 生成用户唯一标识
+   * 5. 设置默认用户权限
+   * 6. 发送欢迎邮件
+   * 7. 记录注册日志
+   * 8. 返回注册结果
+   */
+  async registerUser(registerData: RegisterUserDto): Promise<UserResult> {
+    await this.validateUserBusinessRules(registerData);
+    const user = await this.userCoreService.create(registerData);
+    await this.emailService.sendWelcomeEmail(user.email);
+    await this.logService.recordUserRegistration(user.id);
+    return this.buildUserResult(user);
+  }
+}
+
+// ❌ 错误：业务逻辑不完整
+@Injectable()
+export class UserBusinessService {
+  async registerUser(registerData: RegisterUserDto): Promise<User> {
+    // 只是简单调用数据库保存，缺少业务验证和流程
+    return this.userRepository.save(registerData);
+  }
+}
+```
+
+### Business层依赖关系检查
+```typescript
+// ✅ 允许的导入
+import { UserCoreService } from '../../core/user_auth_core/user_core.service';     # 对应Core层业务支撑
+import { CacheService } from '../../core/redis/cache.service';                     # Core层通用工具
+import { EmailService } from '../../core/utils/email.service';                     # Core层通用工具
+import { OtherBusinessService } from '../other/other.service';                     # 其他Business层（谨慎）
+
+// ❌ 禁止的导入
+import { createConnection } from 'typeorm';                                        # 直接技术实现
+import * as Redis from 'ioredis';                                                 # 直接技术实现
+import { DatabaseConnection } from '../../core/db/connection';                     # 底层技术细节
+```
+
+## 🚨 常见架构违规
+
+### Business层违规示例
+```typescript
+// ❌ 错误：Business层包含技术实现细节
+@Injectable()
+export class UserBusinessService {
+  async createUser(userData: CreateUserDto): Promise<User> {
+    // 违规：直接操作Redis连接
+    const redis = new Redis({ host: 'localhost', port: 6379 });
+    await redis.set(`user:${userData.id}`, JSON.stringify(userData));
+    
+    // 违规：直接写SQL语句
+    const sql = 'INSERT INTO users (name, email) VALUES (?, ?)';
+    await this.database.query(sql, [userData.name, userData.email]);
+  }
+}
+```
+
+### Core层违规示例
+```typescript
+// ❌ 错误：Core层包含业务逻辑
+@Injectable()
+export class DatabaseService {
+  async saveUser(userData: CreateUserDto): Promise<User> {
+    // 违规：包含用户注册的业务验证
+    if (userData.age < 18) {
+      throw new BadRequestException('用户年龄必须大于18岁');
+    }
+    
+    // 违规：包含业务规则
+    if (userData.email.endsWith('@competitor.com')) {
+      throw new ForbiddenException('不允许竞争对手注册');
+    }
+  }
+}
+```
+
+## 🎮 游戏服务器架构特殊检查
+
+### WebSocket Gateway分层
+```typescript
+// ✅ 正确：Gateway在Business层，调用Core层服务
+@WebSocketGateway()
+export class LocationBroadcastGateway {
+  constructor(
+    private readonly locationBroadcastCore: LocationBroadcastCoreService,
+    private readonly userProfiles: UserProfilesService,
+  ) {}
+  
+  @SubscribeMessage('position_update')
+  async handlePositionUpdate(client: Socket, data: PositionData): Promise<void> {
+    // 业务逻辑：验证、权限检查
+    await this.validateUserPermission(client.userId);
+    
+    // 调用Core层技术实现
+    await this.locationBroadcastCore.broadcastToRoom(client.roomId, data);
+  }
+}
+```
+
+### 双模式服务分层
+```typescript
+// ✅ 正确：Business层统一接口，Core层不同实现
+@Injectable()
+export class UsersBusinessService {
+  constructor(
+    @Inject('USERS_SERVICE') 
+    private readonly usersCore: UsersMemoryService | UsersDatabaseService,
+  ) {}
+  
+  async createUser(userData: CreateUserDto): Promise<User> {
+    // 业务逻辑：验证、权限、流程
+    await this.validateUserBusinessRules(userData);
+    
+    // 调用Core层（内存或数据库模式）
+    const user = await this.usersCore.create(userData);
+    
+    // 业务逻辑：后续处理
+    await this.sendWelcomeNotification(user);
+    return user;
+  }
+}
+```
+
+## 🔍 检查执行步骤
+
+1. **识别当前模块的层级**
+   - 确定是Core层还是Business层
+   - 检查文件夹路径和命名
+
+2. **检查Core层命名规范**
+   - 业务支撑模块是否使用_core后缀
+   - 通用工具模块是否不使用后缀
+   - 根据模块职责判断命名正确性
+
+3. **检查职责分离**
+   - Core层是否只包含技术实现
+   - Business层是否只包含业务逻辑
+   - 是否有跨层职责混乱
+
+4. **检查依赖关系**
+   - Core层是否导入了Business层模块
+   - Business层是否直接使用底层技术实现
+   - 依赖注入是否正确使用
+
+5. **检查架构违规**
+   - 识别常见的分层违规模式
+   - 检查技术实现和业务逻辑的边界
+   - 确保架构清晰度
+
+6. **游戏服务器特殊检查**
+   - WebSocket Gateway的分层正确性
+   - 双模式服务的架构设计
+   - 实时通信组件的职责分离
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（调整分层结构、修正依赖关系、重构代码等），必须立即重新执行步骤4的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤4 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接进入步骤5（错误做法）
+
+**不能跳过重新检查环节！**

docs/ai-reading/step5-test-coverage.md

@@ -0,0 +1,349 @@
+# 步骤5：测试覆盖检查
+
+## 🎯 检查目标
+检查测试文件的完整性和覆盖率，确保严格的一对一测试映射和测试分离。
+
+## 📋 测试文件存在性检查
+
+### 需要测试文件的类型
+```typescript
+✅ 必须有测试文件：
+- *.service.ts        # Service类 - 业务逻辑类
+- *.controller.ts     # Controller类 - 控制器类
+- *.gateway.ts        # Gateway类 - WebSocket网关类
+- *.guard.ts          # Guard类 - 守卫类（游戏服务器安全重要）
+- *.interceptor.ts    # Interceptor类 - 拦截器类（日志监控重要）
+- *.middleware.ts     # Middleware类 - 中间件类（性能监控重要）
+
+❌ 不需要测试文件：
+- *.dto.ts           # DTO类 - 数据传输对象
+- *.interface.ts     # Interface文件 - 接口定义
+- *.constants.ts     # Constants文件 - 常量定义
+- *.config.ts        # Config文件 - 配置文件
+- *.utils.ts         # 简单Utils工具类（复杂工具类需要）
+```
+
+### 测试文件命名规范
+```typescript
+✅ 正确的一对一映射：
+src/business/auth/auth.service.ts
+src/business/auth/auth.service.spec.ts
+
+src/core/location_broadcast_core/location_broadcast_core.service.ts
+src/core/location_broadcast_core/location_broadcast_core.service.spec.ts
+
+src/business/admin/admin.gateway.ts
+src/business/admin/admin.gateway.spec.ts
+
+❌ 错误的命名：
+src/business/auth/auth_services.spec.ts     # 测试多个service，违反一对一原则
+src/business/auth/auth_test.spec.ts         # 命名不对应
+```
+
+## 🔥 严格一对一测试映射（重要）
+
+### 强制要求
+- **严格对应**：每个测试文件必须严格对应一个源文件
+- **禁止多对一**：不允许一个测试文件测试多个源文件
+- **禁止一对多**：不允许一个源文件的测试分散在多个测试文件
+- **命名对应**：测试文件名必须与源文件名完全对应（除.spec.ts后缀外）
+
+### 测试范围严格限制
+```typescript
+// ✅ 正确：只测试LoginService的功能
+// 文件：src/business/auth/login.service.spec.ts
+describe('LoginService', () => {
+  describe('validateUser', () => {
+    it('should validate user credentials', () => {
+      // 只测试LoginService.validateUser方法
+      // 使用Mock隔离UserRepository等外部依赖
+    });
+    
+    it('should throw error for invalid credentials', () => {
+      // 测试异常情况
+    });
+  });
+  
+  describe('generateToken', () => {
+    it('should generate valid JWT token', () => {
+      // 只测试LoginService.generateToken方法
+    });
+  });
+});
+
+// ❌ 错误：在LoginService测试中测试其他服务
+describe('LoginService', () => {
+  it('should integrate with UserRepository', () => {
+    // 错误：这是集成测试，应该移到test/integration/
+  });
+  
+  it('should work with EmailService', () => {
+    // 错误：测试了EmailService的功能，违反范围限制
+  });
+});
+```
+
+## 🏗️ 测试分离架构（强制要求）
+
+### 顶层test目录结构
+```
+test/
+├── integration/          # 集成测试 - 测试多个模块间的交互
+│   ├── auth_integration.spec.ts
+│   ├── location_broadcast_integration.spec.ts
+│   └── zulip_integration.spec.ts
+├── e2e/                 # 端到端测试 - 完整业务流程测试
+│   ├── user_registration_e2e.spec.ts
+│   ├── location_broadcast_e2e.spec.ts
+│   └── admin_operations_e2e.spec.ts
+├── performance/         # 性能测试 - WebSocket和高并发测试
+│   ├── websocket_performance.spec.ts
+│   ├── database_performance.spec.ts
+│   └── memory_usage.spec.ts
+├── property/           # 属性测试 - 基于属性的随机测试
+│   ├── admin_property.spec.ts
+│   ├── user_validation_property.spec.ts
+│   └── position_update_property.spec.ts
+└── fixtures/           # 测试数据和工具
+    ├── test_data.ts
+    └── test_helpers.ts
+```
+
+### 测试类型分离要求
+```typescript
+// ✅ 正确：单元测试只在源文件同目录
+// 文件位置：src/business/auth/login.service.spec.ts
+describe('LoginService Unit Tests', () => {
+  // 只测试LoginService的单个方法功能
+  // 使用Mock隔离所有外部依赖
+});
+
+// ✅ 正确：集成测试统一在test/integration/
+// 文件位置：test/integration/auth_integration.spec.ts
+describe('Auth Integration Tests', () => {
+  it('should integrate LoginService with UserRepository and TokenService', () => {
+    // 测试多个模块间的真实交互
+  });
+});
+
+// ✅ 正确：E2E测试统一在test/e2e/
+// 文件位置：test/e2e/user_auth_e2e.spec.ts
+describe('User Authentication E2E Tests', () => {
+  it('should handle complete user login flow', () => {
+    // 端到端完整业务流程测试
+  });
+});
+```
+
+## 🎮 游戏服务器特殊测试要求
+
+### WebSocket Gateway测试
+```typescript
+// ✅ 正确：完整的WebSocket测试
+// 文件：src/business/location/location_broadcast.gateway.spec.ts
+describe('LocationBroadcastGateway', () => {
+  let gateway: LocationBroadcastGateway;
+  let mockServer: jest.Mocked<Server>;
+
+  beforeEach(async () => {
+    // 设置Mock服务器和依赖
+  });
+
+  describe('handleConnection', () => {
+    it('should accept valid WebSocket connection with JWT token', () => {
+      // 正常连接测试
+    });
+    
+    it('should reject connection with invalid JWT token', () => {
+      // 异常连接测试
+    });
+    
+    it('should handle connection when room is at capacity limit', () => {
+      // 边界情况测试
+    });
+  });
+
+  describe('handlePositionUpdate', () => {
+    it('should broadcast position to all room members', () => {
+      // 实时通信测试
+    });
+    
+    it('should validate position data format', () => {
+      // 数据验证测试
+    });
+  });
+
+  describe('handleDisconnect', () => {
+    it('should clean up user resources on disconnect', () => {
+      // 断开连接测试
+    });
+  });
+});
+```
+
+### 双模式服务测试
+```typescript
+// ✅ 正确：内存服务测试
+// 文件：src/core/users/users_memory.service.spec.ts
+describe('UsersMemoryService', () => {
+  it('should create user in memory storage', () => {
+    // 测试内存模式特定功能
+  });
+  
+  it('should handle concurrent access correctly', () => {
+    // 测试内存模式并发处理
+  });
+});
+
+// ✅ 正确：数据库服务测试
+// 文件：src/core/users/users_database.service.spec.ts
+describe('UsersDatabaseService', () => {
+  it('should create user in database', () => {
+    // 测试数据库模式特定功能
+  });
+  
+  it('should handle database transaction correctly', () => {
+    // 测试数据库事务处理
+  });
+});
+
+// ✅ 正确：双模式一致性测试（集成测试）
+// 文件：test/integration/users_dual_mode_integration.spec.ts
+describe('Users Dual Mode Integration', () => {
+  it('should have identical behavior for user creation', () => {
+    // 测试两种模式行为一致性
+  });
+});
+```
+
+### 属性测试（管理员模块）
+```typescript
+// ✅ 正确：属性测试
+// 文件：test/property/admin_property.spec.ts
+import * as fc from 'fast-check';
+
+describe('AdminService Properties', () => {
+  it('should handle any valid user status update', () => {
+    fc.assert(fc.property(
+      fc.integer({ min: 1, max: 1000000 }), // userId
+      fc.constantFrom(...Object.values(UserStatus)), // status
+      async (userId, status) => {
+        try {
+          const result = await adminService.updateUserStatus(userId, status);
+          expect(result).toBeDefined();
+          expect(result.status).toBe(status);
+        } catch (error) {
+          expect(error).toBeInstanceOf(NotFoundException || BadRequestException);
+        }
+      }
+    ));
+  });
+});
+```
+
+## 📍 测试文件位置规范
+
+### 正确位置
+```
+✅ 正确：测试文件与源文件同目录
+src/business/auth/
+├── auth.service.ts
+├── auth.service.spec.ts      # 单元测试
+├── auth.controller.ts
+└── auth.controller.spec.ts   # 单元测试
+
+src/core/location_broadcast_core/
+├── location_broadcast_core.service.ts
+└── location_broadcast_core.service.spec.ts
+```
+
+### 错误位置（必须修正）
+```
+❌ 错误：测试文件在单独文件夹
+src/business/auth/
+├── auth.service.ts
+├── auth.controller.ts
+└── tests/                    # 错误：单独的测试文件夹
+    ├── auth.service.spec.ts  # 应该移到上级目录
+    └── auth.controller.spec.ts
+
+src/business/auth/
+├── auth.service.ts
+├── auth.controller.ts
+└── __tests__/               # 错误：单独的测试文件夹
+    └── auth.spec.ts         # 应该拆分并移到上级目录
+```
+
+## 🧪 测试执行验证（强制要求）
+
+### 测试命令执行
+```bash
+# 单元测试（严格限制：只执行.spec.ts文件）
+npm run test:unit
+# 等价于: jest --testPathPattern=spec.ts --testPathIgnorePatterns="integration|e2e|performance|property"
+
+# 集成测试（统一在test/integration/目录执行）
+npm run test:integration
+# 等价于: jest test/integration/
+
+# E2E测试（统一在test/e2e/目录执行）
+npm run test:e2e
+# 等价于: jest test/e2e/
+
+# 属性测试（统一在test/property/目录执行）
+npm run test:property
+# 等价于: jest test/property/
+
+# 性能测试（统一在test/performance/目录执行）
+npm run test:performance
+# 等价于: jest test/performance/
+```
+
+### 测试执行顺序
+1. **第一阶段**：单元测试（快速反馈）
+2. **第二阶段**：集成测试（模块协作）
+3. **第三阶段**：E2E测试（业务流程）
+4. **第四阶段**：性能测试（系统性能）
+
+## 🔍 检查执行步骤
+
+1. **扫描需要测试的文件类型**
+   - 识别所有.service.ts、.controller.ts、.gateway.ts等文件
+   - 检查是否有对应的.spec.ts测试文件
+
+2. **验证一对一测试映射**
+   - 确保每个测试文件严格对应一个源文件
+   - 检查测试文件命名是否正确对应
+
+3. **检查测试范围限制**
+   - 确保测试内容严格限于对应源文件功能
+   - 识别跨文件测试和混合测试
+
+4. **检查测试文件位置**
+   - 确保单元测试与源文件在同一目录
+   - 识别需要扁平化的测试文件夹
+
+5. **分离集成测试和E2E测试**
+   - 将集成测试移动到test/integration/
+   - 将E2E测试移动到test/e2e/
+   - 将性能测试移动到test/performance/
+   - 将属性测试移动到test/property/
+
+6. **执行测试验证**
+   - 运行单元测试命令验证通过
+   - 确保测试覆盖率达标
+   - 验证测试质量和有效性
+
+7. **游戏服务器特殊检查**
+   - WebSocket Gateway的完整测试覆盖
+   - 双模式服务的一致性测试
+   - 属性测试的正确实现
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（创建测试文件、移动测试文件、修正测试内容等），必须立即重新执行步骤5的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤5 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接进入步骤6（错误做法）
+
+**不能跳过重新检查环节！**

docs/ai-reading/step6-documentation.md

@@ -0,0 +1,327 @@
+# 步骤6：功能文档生成
+
+## 🎯 检查目标
+生成和维护功能模块的README文档，确保文档内容完整、准确、实用。
+
+## 📚 README文档结构
+
+### 必须包含的章节
+每个功能模块文件夹都必须有README.md文档，包含以下结构：
+
+```markdown
+# [模块名称] [中文描述]
+
+[模块名称] 是 [一段话总结文件夹的整体功能和作用，说明其在项目中的定位和价值]。
+
+## 对外提供的接口
+
+### create()
+创建新用户记录，支持数据验证和唯一性检查。
+
+### findByEmail()
+根据邮箱地址查询用户，用于登录验证和账户找回。
+
+## 对外API接口（如适用）
+
+### POST /api/auth/login
+用户登录接口，支持用户名/邮箱/手机号多种方式登录。
+
+### GET /api/users/:id
+根据用户ID获取用户详细信息。
+
+## WebSocket事件接口（如适用）
+
+### 'connection'
+客户端建立WebSocket连接，需要提供JWT认证token。
+
+### 'position_update'
+接收客户端位置更新，广播给房间内其他用户。
+
+## 使用的项目内部依赖
+
+### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
+用户状态枚举，定义用户的激活、禁用、待验证等状态值。
+
+## 核心特性
+
+### 双存储模式支持
+- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
+- 内存模式：使用Map存储，适用于开发测试和故障降级
+
+## 潜在风险
+
+### 内存模式数据丢失风险
+- 内存存储在应用重启后数据会丢失
+- 建议仅在开发测试环境使用
+```
+
+## 🔌 对外接口文档
+
+### 公共方法描述
+每个公共方法必须有一句话功能说明：
+
+```markdown
+## 对外提供的接口
+
+### create(userData: CreateUserDto): Promise<User>
+创建新用户记录，支持数据验证和唯一性检查。
+
+### findById(id: string): Promise<User>
+根据用户ID查询用户信息，用于身份验证和数据获取。
+
+### updateStatus(id: string, status: UserStatus): Promise<User>
+更新用户状态，支持激活、禁用、待验证等状态切换。
+
+### delete(id: string): Promise<void>
+删除用户记录及相关数据，执行软删除保留审计信息。
+
+### findByEmail(email: string): Promise<User>
+根据邮箱地址查询用户，用于登录验证和账户找回。
+```
+
+## 🌐 API接口文档（Business模块）
+
+### HTTP API接口
+如果business模块开放了可访问的API，必须列出所有API：
+
+```markdown
+## 对外API接口
+
+### POST /api/auth/login
+用户登录接口，支持用户名/邮箱/手机号多种方式登录。
+
+### GET /api/users/:id
+根据用户ID获取用户详细信息。
+
+### PUT /api/users/:id/status
+更新指定用户的状态（激活/禁用/待验证）。
+
+### DELETE /api/users/:id
+删除指定用户账户及相关数据。
+
+### GET /api/users/search
+根据条件搜索用户，支持邮箱、用户名、状态等筛选。
+
+### POST /api/users/batch
+批量创建用户，支持Excel导入和数据验证。
+```
+
+## 🔌 WebSocket接口文档（Gateway模块）
+
+### WebSocket事件接口
+Gateway模块需要详细的WebSocket事件文档：
+
+```markdown
+## WebSocket事件接口
+
+### 'connection'
+客户端建立WebSocket连接，需要提供JWT认证token。
+- 输入: `{ token: string }`
+- 输出: 连接成功确认
+
+### 'position_update'
+接收客户端位置更新，广播给房间内其他用户。
+- 输入: `{ x: number, y: number, timestamp: number }`
+- 输出: 广播给房间成员
+
+### 'join_room'
+用户加入游戏房间，建立实时通信连接。
+- 输入: `{ roomId: string }`
+- 输出: `{ success: boolean, members: string[] }`
+
+### 'chat_message'
+处理聊天消息，支持Zulip集成和消息过滤。
+- 输入: `{ message: string, roomId: string }`
+- 输出: 广播给房间成员或转发到Zulip
+
+### 'disconnect'
+客户端断开连接，清理相关资源和通知其他用户。
+- 输入: 无
+- 输出: 通知房间其他成员
+```
+
+## 🔗 内部依赖分析
+
+### 依赖列表格式
+```markdown
+## 使用的项目内部依赖
+
+### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
+用户状态枚举，定义用户的激活、禁用、待验证等状态值。
+
+### CreateUserDto (本模块)
+用户创建数据传输对象，提供完整的数据验证规则和类型定义。
+
+### LoggerService (来自 core/utils/logger)
+日志服务，用于记录用户操作和系统事件。
+
+### CacheService (来自 core/redis)
+缓存服务，用于提升用户查询性能和会话管理。
+
+### EmailService (来自 core/utils/email)
+邮件服务，用于发送用户注册验证和通知邮件。
+```
+
+## ⭐ 核心特性识别
+
+### 技术特性
+```markdown
+## 核心特性
+
+### 双存储模式支持
+- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
+- 内存模式：使用Map存储，适用于开发测试和故障降级
+- 动态模块配置：通过UsersModule.forDatabase()和forMemory()灵活切换
+- 自动检测：根据环境变量自动选择存储模式
+
+### 实时通信能力
+- WebSocket支持：基于Socket.IO的实时双向通信
+- 房间管理：支持用户加入/离开游戏房间
+- 位置广播：实时广播用户位置更新给房间成员
+- 连接管理：自动处理连接断开和重连机制
+
+### 数据完整性保障
+- 唯一性约束检查：用户名、邮箱、手机号、GitHub ID
+- 数据验证：使用class-validator进行输入验证
+- 事务支持：批量操作支持回滚机制
+- 双模式一致性：确保内存模式和数据库模式行为一致
+
+### 性能优化与监控
+- 查询优化：使用索引和查询缓存
+- 批量操作：支持批量创建和更新
+- 内存缓存：热点数据缓存机制
+- 性能监控：WebSocket连接数、消息处理延迟等指标
+- 属性测试：使用fast-check进行随机化测试
+```
+
+## ⚠️ 潜在风险评估
+
+### 风险分类和描述
+```markdown
+## 潜在风险
+
+### 内存模式数据丢失风险
+- 内存存储在应用重启后数据会丢失
+- 不适用于生产环境的持久化需求
+- 建议仅在开发测试环境使用
+- 缓解措施：提供数据导出/导入功能
+
+### WebSocket连接管理风险
+- 大量并发连接可能导致内存泄漏
+- 网络不稳定时连接频繁断开重连
+- 房间成员过多时广播性能下降
+- 缓解措施：连接数限制、心跳检测、分片广播
+
+### 实时通信性能风险
+- 高频位置更新可能导致服务器压力
+- 消息广播延迟影响游戏体验
+- WebSocket消息丢失或重复
+- 缓解措施：消息限流、优先级队列、消息确认机制
+
+### 双模式一致性风险
+- 内存模式和数据库模式行为可能不一致
+- 模式切换时数据同步问题
+- 测试覆盖不完整导致隐藏差异
+- 缓解措施：统一接口抽象、完整的对比测试
+
+### 安全风险
+- WebSocket连接缺少足够的认证验证
+- 用户位置信息泄露风险
+- 管理员权限过度集中
+- 缓解措施：JWT认证、数据脱敏、权限细分
+```
+
+## 🎮 游戏服务器特殊文档要求
+
+### 实时通信协议说明
+```markdown
+### 实时通信协议
+- 协议类型：WebSocket (Socket.IO)
+- 认证方式：JWT Token验证
+- 心跳间隔：10秒
+- 超时设置：30秒无响应自动断开
+- 重连策略：指数退避，最大重试5次
+```
+
+### 双模式切换指南
+```markdown
+### 双模式切换指南
+- 环境变量：`STORAGE_MODE=database|memory`
+- 切换命令：`npm run switch:database` 或 `npm run switch:memory`
+- 数据迁移：提供内存到数据库的数据导出/导入工具
+- 性能对比：内存模式响应时间<1ms，数据库模式<10ms
+```
+
+### 属性测试策略说明
+```markdown
+### 属性测试策略
+- 测试框架：fast-check
+- 测试范围：管理员操作、用户状态变更、权限验证
+- 随机化参数：用户ID(1-1000000)、状态枚举、权限级别
+- 执行次数：每个属性测试运行1000次随机用例
+- 失败处理：自动收集失败用例，生成最小化复现案例
+```
+
+## 📝 文档质量标准
+
+### 内容质量要求
+- **准确性**：所有信息必须与代码实现一致
+- **完整性**：覆盖所有公共接口和重要功能
+- **简洁性**：每个说明控制在一句话内，突出核心要点
+- **实用性**：提供对开发者有价值的信息和建议
+
+### 语言表达规范
+- 使用中文进行描述，专业术语可保留英文
+- 语言简洁明了，避免冗长的句子
+- 统一术语使用，保持前后一致
+- 避免主观评价，客观描述功能和特性
+
+## 🔍 检查执行步骤
+
+1. **检查README文件存在性**
+   - 确保每个功能模块文件夹都有README.md
+   - 检查文档结构是否完整
+
+2. **验证对外接口文档**
+   - 列出所有公共方法
+   - 为每个方法提供一句话功能说明
+   - 确保接口描述准确
+
+3. **检查API接口文档**
+   - 如果是business模块且开放API，必须列出所有API
+   - 每个API提供一句话功能说明
+   - 包含请求方法和路径
+
+4. **检查WebSocket接口文档**
+   - Gateway模块必须详细说明WebSocket事件
+   - 包含输入输出格式
+   - 说明事件处理逻辑
+
+5. **验证内部依赖分析**
+   - 列出所有项目内部依赖
+   - 说明每个依赖的用途
+   - 确保依赖关系准确
+
+6. **检查核心特性描述**
+   - 识别技术特性、功能特性、质量特性
+   - 突出游戏服务器特殊特性
+   - 描述双模式、实时通信等特点
+
+7. **评估潜在风险**
+   - 识别技术风险、业务风险、运维风险、安全风险
+   - 提供风险缓解措施
+   - 特别关注游戏服务器特有风险
+
+8. **验证文档与代码一致性**
+   - 确保文档内容与实际代码实现一致
+   - 检查接口签名、参数类型等准确性
+   - 验证特性描述的真实性
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（创建README文件、更新文档内容、修正接口描述等），必须立即重新执行步骤6的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤6 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接结束检查（错误做法）
+
+**不能跳过重新检查环节！**

docs/ai-reading/step7-code-commit.md

@@ -0,0 +1,368 @@
+# 步骤7：代码提交
+
+## 🎯 检查目标
+完成代码修改后的规范化提交流程，确保代码变更记录清晰、分支管理规范、提交信息符合项目标准。
+
+## 📋 执行前置条件
+- 已完成前6个步骤的代码检查和修改
+- 所有修改的文件已更新修改记录和版本信息
+- 代码能够正常运行且通过测试
+
+## 🔍 Git变更检查与校验
+
+### 1. 检查Git状态和变更内容
+```bash
+# 查看当前工作区状态
+git status
+
+# 查看具体变更内容
+git diff
+
+# 查看已暂存的变更
+git diff --cached
+```
+
+### 2. 文件修改记录校验
+**重要**：检查每个修改文件的头部信息是否与实际修改内容一致
+
+#### 校验内容包括：
+- **修改记录**：最新的修改记录是否准确描述了本次变更
+- **修改类型**：记录的修改类型（代码规范优化、功能新增等）是否与实际修改匹配
+- **修改者信息**：是否使用了正确的用户名称
+- **修改日期**：是否使用了用户提供的真实日期
+- **版本号**：是否按照规则正确递增
+- **@lastModified**：是否更新为当前修改日期
+
+#### 校验方法：
+1. 逐个检查修改文件的头部注释
+2. 对比git diff显示的实际修改内容
+3. 确认修改记录描述与实际变更一致
+4. 如发现不一致，立即修正文件头部信息
+
+### 3. 修改记录不一致的处理
+如果发现文件头部的修改记录与实际修改内容不符：
+
+```typescript
+// ❌ 错误示例：记录说是"功能新增"，但实际只是代码清理
+/**
+ * 最近修改：
+ * - 2024-01-12: 功能新增 - 添加新的用户验证功能 (修改者: 张三)
+ */
+// 实际修改：只是删除了未使用的导入和注释优化
+
+// ✅ 正确修正：
+/**
+ * 最近修改：
+ * - 2024-01-12: 代码规范优化 - 清理未使用导入和优化注释 (修改者: 张三)
+ */
+```
+
+## 🌿 分支管理规范
+
+### 分支命名规范
+根据修改类型创建对应的分支：
+
+```bash
+# 代码规范优化分支
+feature/code-standard-optimization-[日期]
+# 示例：feature/code-standard-optimization-20240112
+
+# Bug修复分支  
+fix/[具体问题描述]
+# 示例：fix/room-concurrency-issue
+
+# 功能新增分支
+feature/[功能名称]
+# 示例：feature/user-authentication
+
+# 重构分支
+refactor/[模块名称]
+# 示例：refactor/room-management
+
+# 性能优化分支
+perf/[优化内容]
+# 示例：perf/database-query-optimization
+
+# 文档更新分支
+docs/[文档类型]
+# 示例：docs/api-documentation
+```
+
+### 创建和切换分支
+```bash
+# 确保在主分支上
+git checkout main
+# 或者
+git checkout develop
+
+# 拉取最新代码
+git pull origin main
+
+# 创建并切换到新分支
+git checkout -b feature/code-standard-optimization-20240112
+```
+
+## 📝 提交信息规范
+
+### 提交类型映射
+根据实际修改内容选择正确的提交类型：
+
+| 修改内容 | 提交类型 | 示例 |
+|---------|---------|------|
+| 命名规范调整、注释优化、代码清理 | `style` | `style：统一TypeScript代码风格和注释规范` |
+| 清理未使用代码、优化导入 | `refactor` | `refactor：清理未使用的导入和死代码` |
+| 添加新功能、新方法 | `feat` | `feat：添加用户身份验证功能` |
+| 修复Bug、错误处理 | `fix` | `fix：修复用户登录时的并发问题` |
+| 性能改进、算法优化 | `perf` | `perf：优化数据库查询性能` |
+| 代码结构调整、重构 | `refactor` | `refactor：重构用户管理服务架构` |
+| 添加或修改测试 | `test` | `test：添加用户服务单元测试` |
+| 更新文档、README | `docs` | `docs：更新API接口文档` |
+| API接口相关 | `api` | `api：添加用户信息查询接口` |
+| 数据库相关 | `db` | `db：创建用户表结构` |
+| WebSocket相关 | `websocket` | `websocket：实现实时消息推送` |
+| 认证授权相关 | `auth` | `auth：实现JWT身份验证机制` |
+| 配置文件相关 | `config` | `config：添加Redis缓存配置` |
+
+### 提交信息格式
+```bash
+<类型>：<简短描述>
+
+[可选的详细描述]
+
+[可选的关联信息]
+```
+
+### 提交信息示例
+
+#### 单一类型修改
+```bash
+# 代码规范优化
+git commit -m "style：统一命名规范和注释格式
+
+- 调整文件和变量命名符合项目规范
+- 优化注释格式和内容完整性
+- 清理代码格式和缩进问题"
+
+# Bug修复
+git commit -m "fix：修复用户注册时的邮箱验证问题
+
+- 修复邮箱格式验证逻辑错误
+- 添加重复邮箱检查机制
+- 优化错误提示信息"
+
+# 功能新增
+git commit -m "feat：实现用户权限管理系统
+
+- 添加角色和权限定义
+- 实现权限验证中间件
+- 支持动态权限分配"
+```
+
+#### 多文件相关修改
+```bash
+git commit -m "refactor：重构用户管理模块架构
+
+涉及文件：
+- src/business/user-mgmt/user.service.ts
+- src/business/user-mgmt/user.controller.ts  
+- src/core/db/users/users.repository.ts
+
+主要改进：
+- 分离业务逻辑和数据访问层
+- 优化服务接口设计
+- 提升代码可维护性"
+```
+
+## 🔄 提交执行流程
+
+### 1. 分阶段提交（推荐）
+将不同类型的修改分别提交，保持提交历史清晰：
+
+```bash
+# 第一步：提交代码规范优化
+git add src/business/auth/
+git commit -m "style：优化auth模块代码规范
+
+- 统一命名规范和注释格式
+- 清理未使用的导入
+- 调整代码结构和缩进"
+
+# 第二步：提交功能改进（如果有）
+git add src/business/user-mgmt/
+git commit -m "feat：添加用户状态管理功能
+
+- 实现用户激活/禁用功能
+- 添加状态变更日志记录
+- 支持批量状态操作"
+
+# 第三步：提交测试相关（如果有）
+git add test/
+git commit -m "test：完善用户管理模块测试覆盖
+
+- 添加缺失的单元测试
+- 补充集成测试用例
+- 提升测试覆盖率到95%以上"
+
+# 第四步：提交文档更新（如果有）
+git add docs/ src/**/README.md
+git commit -m "docs：更新用户管理模块文档
+
+- 完善API接口文档
+- 更新功能模块README
+- 添加使用示例和注意事项"
+```
+
+### 2. 使用交互式暂存（精确控制）
+```bash
+# 交互式选择要提交的代码块
+git add -p src/business/auth/login.service.ts
+
+# 选择代码规范相关的修改
+# 提交第一部分
+git commit -m "style：优化login.service代码规范"
+
+# 暂存剩余的功能修改
+git add src/business/auth/login.service.ts
+git commit -m "feat：添加多因素认证支持"
+```
+
+### 3. 提交前最终检查
+```bash
+# 检查暂存区内容
+git diff --cached
+
+# 确认提交信息准确性
+git commit --dry-run
+
+# 执行提交
+git commit -m "提交信息"
+```
+
+## 📄 合并文档生成
+
+### 合并请求文档模板
+完成所有提交后，生成合并文档：
+
+```markdown
+# 代码规范优化合并请求
+
+## 📋 变更概述
+本次合并请求包含对 [具体模块/功能] 的代码规范优化和质量提升。
+
+## 🔍 主要变更内容
+
+### 代码规范优化
+- **命名规范**：调整文件、类、方法命名符合项目规范
+- **注释规范**：完善注释内容，统一注释格式
+- **代码清理**：移除未使用的导入、变量和死代码
+- **格式统一**：统一代码缩进、换行和空格使用
+
+### 功能改进（如适用）
+- **新增功能**：[具体描述新增的功能]
+- **Bug修复**：[具体描述修复的问题]
+- **性能优化**：[具体描述优化的内容]
+
+### 测试完善（如适用）
+- **测试覆盖**：补充缺失的单元测试和集成测试
+- **测试质量**：提升测试用例的完整性和准确性
+
+### 文档更新（如适用）
+- **API文档**：更新接口文档和使用说明
+- **README文档**：完善功能模块说明和使用指南
+
+## 📊 影响范围
+- **修改文件数量**：[数量] 个文件
+- **新增代码行数**：+[数量] 行
+- **删除代码行数**：-[数量] 行
+- **测试覆盖率**：从 [原覆盖率]% 提升到 [新覆盖率]%
+
+## 🧪 测试验证
+- [ ] 所有单元测试通过
+- [ ] 集成测试通过  
+- [ ] E2E测试通过
+- [ ] 性能测试通过（如适用）
+- [ ] 手动功能验证通过
+
+## 🔗 相关链接
+- 相关Issue：#[Issue编号]
+- 设计文档：[链接]
+- API文档：[链接]
+
+## 📝 审查要点
+请重点关注以下方面：
+1. **代码规范**：命名、注释、格式是否符合项目标准
+2. **功能正确性**：新增或修改的功能是否按预期工作
+3. **测试完整性**：测试用例是否充分覆盖变更内容
+4. **文档准确性**：文档是否与代码实现保持一致
+5. **性能影响**：变更是否对系统性能产生负面影响
+
+## ⚠️ 注意事项
+- 本次变更主要为代码质量提升，不涉及业务逻辑重大变更
+- 所有修改都经过充分测试验证
+- 建议在非高峰期进行合并部署
+
+## 🚀 部署说明
+- **部署环境**：[测试环境/生产环境]
+- **部署时间**：[建议的部署时间]
+- **回滚方案**：如有问题可快速回滚到上一版本
+- **监控要点**：关注 [具体的监控指标]
+```
+
+## 🔧 执行步骤总结
+
+### 完整执行流程
+1. **Git变更检查**
+   - 执行 `git status` 和 `git diff` 查看变更
+   - 确认所有修改文件都在预期范围内
+
+2. **修改记录校验**
+   - 逐个检查修改文件的头部注释
+   - 确认修改记录与实际变更内容一致
+   - 如有不一致，立即修正
+
+3. **创建功能分支**
+   - 根据修改类型创建合适的分支
+   - 使用规范的分支命名格式
+
+4. **分类提交代码**
+   - 按修改类型分别提交（style、feat、fix、docs等）
+   - 使用规范的提交信息格式
+   - 每次提交保持原子性（一次提交只做一件事）
+
+5. **生成合并文档**
+   - 创建详细的合并请求文档
+   - 说明变更内容、影响范围、测试情况
+   - 提供审查要点和部署说明
+
+6. **推送和创建PR**
+   - 推送分支到远程仓库
+   - 创建Pull Request并关联合并文档
+
+## ⚠️ 重要注意事项
+
+### 提交原则
+- **原子性**：每次提交只包含一个逻辑改动
+- **完整性**：每次提交的代码都应该能正常运行
+- **描述性**：提交信息要清晰描述改动内容和原因
+- **一致性**：文件修改记录必须与实际修改内容一致
+
+### 质量保证
+- 提交前必须验证代码能正常运行
+- 确保所有测试通过
+- 检查代码格式和规范符合项目标准
+- 验证文档与代码实现保持一致
+
+### 协作规范
+- 遵循项目的分支管理策略
+- 提供清晰的合并请求说明
+- 及时响应代码审查意见
+- 保持提交历史的清晰和可追溯性
+
+## 🔥 重要提醒
+
+**如果在本步骤中执行了任何修改操作（修正文件头部信息、调整提交内容、更新文档等），必须立即重新执行步骤7的完整检查！**
+
+- ✅ 执行修改 → 🔥 立即重新执行步骤7 → 提供验证报告 → 等待用户确认
+- ❌ 执行修改 → 直接结束检查（错误做法）
+
+**不能跳过重新检查环节！**

docs/开发者代码检查规范.md

@@ -0,0 +1,399 @@
+# 开发者代码检查规范
+
+## 🎯 规范目标
+
+本规范旨在确保代码质量、提升开发效率、维护项目一致性。通过系统化的代码检查流程，保障Whale Town游戏服务器项目的代码标准和技术质量。
+
+## 📋 检查流程概述
+
+代码检查分为7个步骤，必须按顺序执行，每步完成后等待确认才能进行下一步：
+
+1. **步骤1：命名规范检查** - 文件、变量、类、常量命名规范
+2. **步骤2：注释规范检查** - 文件头、类、方法注释完整性
+3. **步骤3：代码质量检查** - 清理未使用代码、处理TODO项
+4. **步骤4：架构分层检查** - Core层和Business层职责分离
+5. **步骤5：测试覆盖检查** - 一对一测试映射、测试分离
+6. **步骤6：功能文档生成** - README文档、API接口文档
+7. **步骤7：代码提交** - Git变更校验、规范化提交
+
+## 🔄 执行原则
+
+### ⚠️ 强制要求
+- **分步执行**：每次只执行一个步骤，严禁跳步骤或合并执行
+- **等待确认**：每步完成后必须等待确认才能进行下一步
+- **修改验证**：每次修改文件后必须重新检查该步骤并提供验证报告
+- **🔥 修改后必须重新执行当前步骤**：如果在当前步骤中发生了任何修改行为，必须立即重新执行该步骤的完整检查
+- **问题修复后重检**：如果当前步骤出现问题需要修改时，必须在解决问题后重新执行该步骤
+
+## 📚 详细检查标准
+
+### 步骤1：命名规范检查
+
+#### 文件和文件夹命名
+- **规则**：snake_case（下划线分隔）
+- **示例**：
+  ```
+  ✅ 正确：user_controller.ts, admin_operation_log_service.ts
+  ❌ 错误：UserController.ts, user-service.ts
+  ```
+
+#### 变量和函数命名
+- **规则**：camelCase（小驼峰命名）
+- **示例**：
+  ```typescript
+  ✅ 正确：const userName = 'test'; function getUserInfo() {}
+  ❌ 错误：const UserName = 'test'; function GetUserInfo() {}
+  ```
+
+#### 类和接口命名
+- **规则**：PascalCase（大驼峰命名）
+- **示例**：
+  ```typescript
+  ✅ 正确：class UserService {} interface GameConfig {}
+  ❌ 错误：class userService {} interface gameConfig {}
+  ```
+
+#### 常量命名
+- **规则**：SCREAMING_SNAKE_CASE（全大写+下划线）
+- **示例**：
+  ```typescript
+  ✅ 正确：const MAX_RETRY_COUNT = 3; const SALT_ROUNDS = 10;
+  ❌ 错误：const maxRetryCount = 3; const saltRounds = 10;
+  ```
+
+#### 文件夹结构扁平化
+- **≤3个文件**：必须扁平化处理
+- **≥4个文件**：通常保持独立文件夹
+- **测试文件位置**：测试文件与源文件放在同一目录
+
+#### Core层命名规则
+- **业务支撑模块**：使用_core后缀（如location_broadcast_core/）
+- **通用工具模块**：不使用后缀（如redis/、logger/）
+
+### 步骤2：注释规范检查
+
+#### 文件头注释（必须包含）
+```typescript
+/**
+ * 文件功能描述
+ * 
+ * 功能描述：
+ * - 主要功能点1
+ * - 主要功能点2
+ * 
+ * 职责分离：
+ * - 职责描述1
+ * - 职责描述2
+ * 
+ * 最近修改：
+ * - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
+ * - [历史日期]: 修改类型 - 修改内容 (修改者: 历史修改者)
+ * 
+ * @author [处理后的作者名称]
+ * @version x.x.x
+ * @since [创建日期]
+ * @lastModified [用户日期]
+ */
+```
+
+#### @author字段处理规范
+- **保留人名**：如果@author是人名，必须保留不变
+- **替换AI标识**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
+
+#### 修改记录规范
+- **修改类型**：代码规范优化、功能新增、功能修改、Bug修复、性能优化、重构
+- **最多保留5条**：超出时自动删除最旧记录
+- **版本号递增**：
+  - 修订版本+1：代码规范优化、Bug修复
+  - 次版本+1：功能新增、功能修改
+  - 主版本+1：重构、架构变更
+
+### 步骤3：代码质量检查
+
+#### 未使用代码清理
+- 清理未使用的导入
+- 清理未使用的变量和方法
+- 删除未调用的私有方法
+
+#### 常量定义规范
+- 使用SCREAMING_SNAKE_CASE
+- 提取魔法数字为常量
+- 统一常量命名
+
+#### TODO项处理（强制要求）
+- **最终文件不能包含TODO项**
+- 必须真正实现功能或删除未完成代码
+
+#### 方法长度检查
+- **建议**：方法不超过50行
+- **原则**：一个方法只做一件事
+- **拆分**：复杂方法拆分为多个小方法
+
+### 步骤4：架构分层检查
+
+#### Core层规范
+- **职责**：专注技术实现，不包含业务逻辑
+- **命名**：业务支撑模块使用_core后缀，通用工具模块不使用后缀
+- **依赖**：只能导入其他Core层模块和第三方技术库
+
+#### Business层规范
+- **职责**：专注业务逻辑实现，不关心底层技术细节
+- **依赖**：可以导入Core层模块和其他Business层模块
+- **禁止**：不能直接使用底层技术实现
+
+### 步骤5：测试覆盖检查
+
+#### 严格一对一测试映射
+- **强制要求**：每个测试文件必须严格对应一个源文件
+- **禁止多对一**：不允许一个测试文件测试多个源文件
+- **命名对应**：测试文件名必须与源文件名完全对应
+
+#### 需要测试文件的类型
+```typescript
+✅ 必须有测试文件：
+- *.service.ts        # Service类
+- *.controller.ts     # Controller类
+- *.gateway.ts        # Gateway类
+- *.guard.ts          # Guard类
+- *.interceptor.ts    # Interceptor类
+- *.middleware.ts     # Middleware类
+
+❌ 不需要测试文件：
+- *.dto.ts           # DTO类
+- *.interface.ts     # Interface文件
+- *.constants.ts     # Constants文件
+```
+
+#### 测试分离架构
+```
+test/
+├── integration/          # 集成测试
+├── e2e/                 # 端到端测试
+├── performance/         # 性能测试
+├── property/           # 属性测试
+└── fixtures/           # 测试数据和工具
+```
+
+### 步骤6：功能文档生成
+
+#### README文档结构
+每个功能模块文件夹都必须有README.md文档，包含：
+- 模块功能描述
+- 对外提供的接口
+- 对外API接口（如适用）
+- WebSocket事件接口（如适用）
+- 使用的项目内部依赖
+- 核心特性
+- 潜在风险
+
+#### 游戏服务器特殊要求
+- **WebSocket Gateway**：详细的事件接口文档
+- **双模式服务**：模式特点和切换指南
+- **属性测试**：测试策略说明
+
+### 步骤7：代码提交
+
+#### Git变更检查
+- 检查Git状态和变更内容
+- 校验文件修改记录与实际修改内容一致性
+- 确认修改记录、版本号、时间戳正确更新
+
+#### 分支管理规范
+```bash
+# 代码规范优化分支
+feature/code-standard-optimization-[日期]
+
+# Bug修复分支  
+fix/[具体问题描述]
+
+# 功能新增分支
+feature/[功能名称]
+
+# 重构分支
+refactor/[模块名称]
+```
+
+#### 提交信息规范
+```bash
+<类型>：<简短描述>
+
+[可选的详细描述]
+```
+
+提交类型：
+- `style`：代码规范优化
+- `refactor`：代码重构
+- `feat`：新功能
+- `fix`：Bug修复
+- `perf`：性能优化
+- `test`：测试相关
+- `docs`：文档更新
+
+## 🎮 游戏服务器特殊要求
+
+### WebSocket相关
+- **Gateway文件**：必须有完整的连接、消息处理测试
+- **实时通信**：心跳检测、重连机制、性能监控
+- **事件文档**：详细的输入输出格式说明
+
+### 双模式架构
+- **内存服务和数据库服务**：都需要完整测试覆盖
+- **行为一致性**：确保两种模式行为完全一致
+- **切换机制**：提供模式切换指南和数据迁移工具
+
+### 属性测试
+- **管理员模块**：使用fast-check进行属性测试
+- **随机化测试**：验证边界条件和异常处理
+- **测试策略**：详细的属性测试实现说明
+
+## 📋 统一报告模板
+
+每步完成后使用此模板报告：
+
+```
+## 步骤X：[步骤名称]检查报告
+
+### 🔍 检查结果
+[发现的问题列表]
+
+### 🛠️ 修正方案  
+[具体修正建议]
+
+### ✅ 完成状态
+- 检查项1 ✓/✗
+- 检查项2 ✓/✗
+
+**请确认修正方案，确认后进行下一步骤**
+```
+
+## 🚨 全局约束
+
+### 文件修改记录规范
+每次执行完修改后，文件顶部都需要更新：
+- 添加修改记录（最多保留5条）
+- 更新版本号（按规则递增）
+- 更新@lastModified字段
+- 正确处理@author字段
+
+### 时间更新规则
+- **仅检查不修改**：不更新@lastModified字段
+- **实际修改才更新**：只有真正修改了文件内容时才更新
+- **Git变更检测**：通过git检查文件是否有实际变更
+
+### 修改验证流程
+任何步骤中发生修改行为后，必须立即重新执行该步骤：
+```
+步骤执行中 → 发现问题 → 执行修改 → 🔥 立即重新执行该步骤 → 验证无遗漏 → 用户确认 → 下一步骤
+```
+
+## 🔧 AI-Reading使用指南
+
+### 什么是AI-Reading
+
+AI-Reading是一套系统化的代码检查执行指南，专门为Whale Town游戏服务器项目设计。它提供了完整的7步代码检查流程，确保代码质量和项目规范的一致性。
+
+### 使用场景
+
+#### 适用情况
+- **新功能开发完成后**：确保新代码符合项目规范
+- **Bug修复后**：验证修复代码的质量和规范性
+- **代码重构时**：保证重构后代码的一致性和质量
+- **代码审查前**：提前发现和解决规范问题
+- **项目维护期**：定期检查和优化代码质量
+
+#### 不适用情况
+- **紧急热修复**：紧急生产问题修复时可简化流程
+- **实验性代码**：概念验证或原型开发阶段
+- **第三方代码集成**：外部库或组件的集成
+
+### 使用方法
+
+#### 1. 准备阶段
+在开始检查前，必须收集以下信息：
+- **用户当前日期**：用于修改记录和时间戳更新
+- **用户名称**：用于@author字段处理和修改记录
+
+#### 2. 执行流程
+```
+用户请求代码检查
+    ↓
+收集用户信息（日期、名称）
+    ↓
+识别项目特性（NestJS游戏服务器）
+    ↓
+按顺序执行7个步骤
+    ↓
+每步完成后等待用户确认
+    ↓
+如有修改立即重新执行当前步骤
+```
+
+#### 3. 使用AI-Reading的具体步骤
+
+**第一步：启动检查**
+```
+请使用ai-reading对[模块名称]进行代码检查
+当前日期：[YYYY-MM-DD]
+用户名称：[您的名称]
+```
+
+**第二步：逐步执行**
+AI会按照以下顺序执行：
+1. 读取对应步骤的详细指导文档
+2. 执行该步骤的所有检查项
+3. 提供详细的检查报告
+4. 等待用户确认后进行下一步
+
+**第三步：处理修改**
+如果某步骤需要修改代码：
+1. AI会执行必要的修改操作
+2. 更新文件的修改记录和版本信息
+3. 立即重新执行该步骤进行验证
+4. 提供验证报告确认无遗漏问题
+
+**第四步：完成检查**
+所有7个步骤完成后：
+1. 提供完整的检查总结报告
+2. 确认所有问题已解决
+3. 代码已准备好进行提交或部署
+
+### 使用技巧
+
+#### 高效使用
+- **批量检查**：可以一次性检查整个模块或功能
+- **增量检查**：只检查修改的文件和相关依赖
+- **定期检查**：建议每周对核心模块进行一次完整检查
+
+#### 注意事项
+- **不要跳步骤**：必须按顺序完成所有步骤
+- **确认每一步**：每步完成后仔细检查报告再确认
+- **保存检查记录**：保留检查报告用于后续参考
+- **及时处理问题**：发现问题立即修复，不要积累
+
+#### 常见问题处理
+- **检查时间过长**：可以分模块进行，不必一次性检查整个项目
+- **修改冲突**：如果与其他开发者的修改冲突，先解决冲突再继续检查
+- **测试失败**：如果测试不通过，必须先修复测试再继续后续步骤
+
+### 最佳实践
+
+#### 团队协作
+- **统一标准**：团队成员都使用相同的AI-Reading流程
+- **代码审查**：在代码审查前先完成AI-Reading检查
+- **知识分享**：定期分享AI-Reading发现的问题和解决方案
+
+#### 质量保证
+- **持续改进**：根据检查结果不断优化代码规范
+- **文档同步**：确保文档与代码实现保持一致
+- **测试覆盖**：通过AI-Reading确保测试覆盖率达标
+
+#### 效率提升
+- **自动化集成**：考虑将AI-Reading集成到CI/CD流程
+- **模板使用**：使用标准模板减少重复工作
+- **工具辅助**：结合IDE插件和代码格式化工具
+
+通过正确使用AI-Reading，可以显著提升代码质量，减少bug数量，提高开发效率，确保项目的长期可维护性。
+
+---
+
+**重要提醒**：使用AI-Reading时，请严格按照7步流程执行，不要跳过任何步骤，确保每一步都得到充分验证后再进行下一步。