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（小驼峰命名）
- **示例**：
  ```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步流程执行，不要跳过任何步骤，确保每一步都得到充分验证后再进行下一步。