whale-town-end/docs/开发者代码检查规范.md

开发者代码检查规范

🎯 规范目标

本规范旨在确保代码质量、提升开发效率、维护项目一致性。通过系统化的代码检查流程，保障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（小驼峰命名）
• 示例：

  ✅ 正确：const userName = 'test'; function getUserInfo() {}
  ❌ 错误：const UserName = 'test'; function GetUserInfo() {}
  

类和接口命名

• 规则：PascalCase（大驼峰命名）
• 示例：

  ✅ 正确：class UserService {} interface GameConfig {}
  ❌ 错误：class userService {} interface gameConfig {}
  

常量命名

• 规则：SCREAMING_SNAKE_CASE（全大写+下划线）
• 示例：

  ✅ 正确：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：注释规范检查

文件头注释（必须包含）

/**
 * 文件功能描述
 * 
 * 功能描述：
 * - 主要功能点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：测试覆盖检查

严格一对一测试映射

• 强制要求：每个测试文件必须严格对应一个源文件
• 禁止多对一：不允许一个测试文件测试多个源文件
• 命名对应：测试文件名必须与源文件名完全对应

需要测试文件的类型

✅ 必须有测试文件：
- *.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状态和变更内容
• 校验文件修改记录与实际修改内容一致性
• 确认修改记录、版本号、时间戳正确更新

分支管理规范

# 代码规范优化分支
feature/code-standard-optimization-[日期]

# Bug修复分支  
fix/[具体问题描述]

# 功能新增分支
feature/[功能名称]

# 重构分支
refactor/[模块名称]

提交信息规范

<类型>：<简短描述>

[可选的详细描述]

提交类型：

• 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步流程执行，不要跳过任何步骤，确保每一步都得到充分验证后再进行下一步。