Files

- 新增多个模块的单元测试文件，提升测试覆盖率
- 完善AI-Reading文档系统，包含7步代码检查流程
- 新增集成测试和属性测试框架
- 优化项目结构和配置文件
- 清理过时的规范文档，统一使用新的检查标准

2026-01-12 20:09:03 +08:00

14 KiB

Raw Blame History

AI代码检查执行指南 - Whale Town 游戏服务器

🎯 执行前准备

📋 必须收集的用户信息

在开始任何检查之前，必须收集以下信息：

用户当前日期：用于修改记录和时间戳更新
用户名称：用于@author字段处理和修改记录

🏗️ 项目特性识别

本项目是NestJS游戏服务器，具有以下特点：

双模式架构：支持数据库模式和内存模式
实时通信：基于WebSocket的实时双向通信
属性测试：管理员模块使用fast-check进行随机化测试
分层架构：Core层（技术实现）+ Business层（业务逻辑）

🔄 执行原则

🚨 中间步骤开始规范（重要）

如果AI从任何中间步骤开始执行（非步骤1开始），必须首先完成以下准备工作：

📋 强制信息收集

在执行任何中间步骤之前，AI必须：

收集用户当前日期：用于修改记录和时间戳更新
收集用户名称：用于@author字段处理和修改记录
确认项目特性：识别这是NestJS游戏服务器项目的特点

🔍 全局上下文获取

AI必须先了解：

项目架构：双模式架构（数据库+内存）、分层结构（Core+Business）
技术栈：NestJS、WebSocket、Jest测试、fast-check属性测试
文件结构：当前项目的整体文件组织方式
已有规范：项目中已建立的命名、注释、测试等规范

🎯 执行流程约束

中间步骤开始请求
    ↓
🚨 强制收集用户信息（日期、名称）
    ↓
🚨 强制识别项目特性和上下文
    ↓
🚨 强制了解目标步骤的具体要求
    ↓
开始执行指定步骤

⚠️ 违规处理：如果AI跳过信息收集直接执行中间步骤，用户应要求AI重新开始并完成准备工作。

⚠️ 强制要求

分步执行：每次只执行一个步骤，严禁跳步骤或合并执行
等待确认：每步完成后必须等待用户确认才能进行下一步
修改验证：每次修改文件后必须重新检查该步骤并提供验证报告
🔥 修改后必须重新执行当前步骤：如果在当前步骤中发生了任何修改行为（文件修改、重命名、移动等），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 重点关注： 严格一对一测试映射、测试文件位置、测试执行验证 完成后： 提供检查报告，等待用户确认

🧪 测试文件调试规范

调试测试文件时必须遵循以下流程：

读取jest.config.js配置
- 查看jest.config.js了解测试环境配置
- 确认testRegex模式和文件匹配规则
- 了解moduleNameMapper和其他配置项
使用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 - 隔离运行测试
特定模块测试指令
- 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性能测试

测试执行验证流程

发现测试问题 → 读取jest.config.js → 选择合适的npm run test:xxx指令 → 执行测试 → 分析结果 → 修复问题 → 重新执行测试

测试指令选择原则
- 单个文件测试：使用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修复 - 修复代码缺陷
性能优化 - 提升代码性能
重构 - 代码结构调整但功能不变

修改记录格式要求

/**
 * 最近修改：
 * - [用户日期]: 代码规范优化 - 清理未使用的导入 (修改者: [用户名称])
 * - 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显示文件被修改时才需要添加修改记录和更新时间戳

🚨 重要强调：纯检查步骤不更新修改记录

AI在执行代码检查步骤时，如果发现代码已经符合规范，无需任何修改，则：

禁止添加修改记录：不要添加类似"AI代码检查步骤X：XXX检查和优化"的记录
禁止更新时间戳：不要更新@lastModified字段
禁止递增版本号：不要修改@version字段
只有实际修改了代码内容、注释内容、结构等才需要更新修改记录

错误示例：

// ❌ 错误：仅检查无修改却添加了修改记录
/**
 * 最近修改：
 * - 2026-01-12: 代码规范优化 - AI代码检查步骤2：注释规范检查和优化 (修改者: moyin)  // 这是错误的！
 * - 2026-01-07: 功能新增 - 添加用户验证功能 (修改者: 张三)
 */

正确示例：

// ✅ 正确：检查发现符合规范，不添加修改记录
/**
 * 最近修改：
 * - 2026-01-07: 功能新增 - 添加用户验证功能 (修改者: 张三)  // 保持原有记录不变
 */

@author字段处理规范

保留原则：人名必须保留，不得随意修改
AI标识替换：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
判断示例：@author kiro → 可替换，@author 张三 → 必须保留

游戏服务器特殊要求

WebSocket文件：Gateway文件必须有完整的连接、消息处理测试
双模式服务：内存服务和数据库服务都需要完整测试覆盖
属性测试：管理员模块使用fast-check进行属性测试
测试分离：严格区分单元测试、集成测试、E2E测试、性能测试

🔧 修改验证流程

🔥 修改后立即重新执行规则（重要）

任何步骤中发生修改行为后，AI必须立即重新执行该步骤，不能直接进入下一步骤！

修改行为包括但不限于：

文件内容修改（代码、注释、配置等）
文件重命名
文件移动
文件删除
新建文件
文件夹结构调整

强制执行流程：

步骤执行中 → 发现问题 → 执行修改 → 🔥 立即重新执行该步骤 → 验证无遗漏 → 用户确认 → 下一步骤

问题修复后的重检流程

当在任何步骤中发现问题并进行修改后，必须遵循以下流程：

执行修改操作
- 根据发现的问题进行具体修改
- 确保修改内容准确无误
- 更新文件顶部的修改记录、版本号和@lastModified字段
🔥 立即重新执行当前步骤
- 不能跳过这一步！
- 完整重新执行该步骤的所有检查项
- 不能只检查修改的部分，必须全面重检
提供验证报告
- 确认之前发现的问题已解决
- 确认没有引入新的问题
- 确认没有遗漏其他问题
等待用户确认
- 提供完整的验证报告
- 等待用户确认后才能进行下一步骤

验证报告模板

## 步骤X：修改验证报告

### 🔧 已执行的修改操作
- 修改类型：[文件修改/重命名/移动/删除等]
- 修改内容：[具体修改描述]
- 影响文件：[受影响的文件列表]

### 📝 已更新的修改记录
- 添加修改记录：[用户日期]: [修改类型] - [修改内容] (修改者: [用户名称])
- 更新版本号：[旧版本] → [新版本]
- 更新时间戳：@lastModified [用户日期]

### 🔍 重新执行步骤X的完整检查结果
[完整重新执行该步骤的所有检查项的结果]

### ✅ 验证状态
- 原问题已解决 ✓
- 修改记录已更新 ✓
- 无新问题引入 ✓
- 无其他遗漏问题 ✓
- 步骤X检查完全通过 ✓

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

重检的重要性

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

⚡ 关键成功要素

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

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

14 KiB Raw Blame History Unescape Escape