whale-town-end/docs/ai-reading/README.md

# 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检查完全通过 ✓

**🔥 重要：本步骤已完成修改并重新验证，请确认后进行下一步骤**
```

### 重检的重要性
- **确保完整性**：避免修改过程中遗漏其他问题
- **防止新问题**：确保修改没有引入新的问题
- **保证质量**：每个步骤都达到完整的检查标准
- **维护一致性**：确保整个检查过程的严谨性
- **🔥 强制执行**：修改后必须重新执行，不能跳过这个环节

## ⚡ 关键成功要素

- **严格按步骤执行**：不跳步骤，不合并执行
- **🔥 修改后立即重新执行**：任何修改行为后必须立即重新执行当前步骤，不能直接进入下一步
- **问题修复后必须重检**：修改文件后必须重新执行整个步骤，确保无遗漏
- **修改记录必须更新**：每次修改文件后都必须更新文件顶部的修改记录、版本号和时间戳
- **真实修改验证**：通过工具验证修改效果
- **用户信息准确使用**：日期和名称信息正确应用
- **项目特性适配**：针对游戏服务器特点优化检查
- **完整报告提供**：每步都提供详细的检查报告

---

**开始执行前，请确认已收集用户日期和名称信息！**