docs：添加AI代码检查执行指南文档

- 添加完整的7步代码检查流程指导 - 包含命名规范、注释标准、代码质量等检查标准 - 提供游戏服务器特殊要求和最佳实践 - 支持NestJS双模式架构和WebSocket实时通信检查涉及文件： - docs/ai-reading/README.md - 总体执行指南 - docs/ai-reading/step1-naming-convention.md - 命名规范检查 - docs/ai-reading/step2-comment-standard.md - 注释规范检查 - docs/ai-reading/step3-code-quality.md - 代码质量检查 - docs/ai-reading/step4-architecture-layer.md - 架构分层检查 - docs/ai-reading/step5-test-coverage.md - 测试覆盖检查 - docs/ai-reading/step6-documentation.md - 功能文档生成 - docs/ai-reading/step7-code-commit.md - 代码提交规范
2026-01-12 16:19:01 +08:00
parent c936961280
commit ba8bd9cc7e
8 changed files with 2402 additions and 0 deletions
--- a/docs/ai-reading/README.md
+++ b/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检查完全通过 ✓
+
+**🔥 重要：本步骤已完成修改并重新验证，请确认后进行下一步骤**
+```
+
+### 重检的重要性
+- **确保完整性**：避免修改过程中遗漏其他问题
+- **防止新问题**：确保修改没有引入新的问题
+- **保证质量**：每个步骤都达到完整的检查标准
+- **维护一致性**：确保整个检查过程的严谨性
+- **🔥 强制执行**：修改后必须重新执行，不能跳过这个环节
+
+## ⚡ 关键成功要素
+
+- **严格按步骤执行**：不跳步骤，不合并执行
+- **🔥 修改后立即重新执行**：任何修改行为后必须立即重新执行当前步骤，不能直接进入下一步
+- **问题修复后必须重检**：修改文件后必须重新执行整个步骤，确保无遗漏
+- **修改记录必须更新**：每次修改文件后都必须更新文件顶部的修改记录、版本号和时间戳
+- **真实修改验证**：通过工具验证修改效果
+- **用户信息准确使用**：日期和名称信息正确应用
+- **项目特性适配**：针对游戏服务器特点优化检查
+- **完整报告提供**：每步都提供详细的检查报告
+
+---
+
+**开始执行前，请确认已收集用户日期和名称信息！**