whale-town-end/docs/ai-reading/step2-comment-standard.md

# 步骤2：注释规范检查

## ⚠️ 执行前必读规范

**🔥 重要：在执行本步骤之前，AI必须先完整阅读同级目录下的 `README.md` 文件！**

该README文件包含：
- 🎯 执行前准备和用户信息收集要求
- 🔄 强制执行原则和分步执行流程  
- 🔥 修改后立即重新执行当前步骤的强制规则
- 📝 文件修改记录规范和版本号递增规则
- 🧪 测试文件调试规范和测试指令使用规范
- 🚨 全局约束和游戏服务器特殊要求

**不阅读README直接执行步骤将导致执行不规范，违反项目要求！**

---

## 🎯 检查目标
检查和完善所有注释规范，确保文件头、类、方法注释的完整性和准确性。

## 📋 注释规范标准

### 文件头注释（必须包含）
```typescript
/**
 * 文件功能描述
 * 
 * 功能描述：
 * - 主要功能点1
 * - 主要功能点2
 * - 主要功能点3
 * 
 * 职责分离：
 * - 职责描述1
 * - 职责描述2
 * 
 * 最近修改：
 * - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
 * - [历史日期]: 修改类型 - 修改内容 (修改者: 历史修改者)
 * 
 * @author [处理后的作者名称]
 * @version x.x.x
 * @since [创建日期]
 * @lastModified [用户日期]
 */
```

### 类注释（必须包含）
```typescript
/**
 * 类功能描述
 * 
 * 职责：
 * - 主要职责1
 * - 主要职责2
 * 
 * 主要方法：
 * - method1() - 方法1功能
 * - method2() - 方法2功能
 * 
 * 使用场景：
 * - 场景描述
 */
@Injectable()
export class ExampleService {
  // 类实现
}
```

### 方法注释（必须包含）
```typescript
/**
 * 方法功能描述
 * 
 * 业务逻辑：
 * 1. 步骤1描述
 * 2. 步骤2描述
 * 3. 步骤3描述
 * 
 * @param paramName 参数描述
 * @returns 返回值描述
 * @throws ExceptionType 异常情况描述
 * 
 * @example
 * ```typescript
 * const result = await service.methodName(param);
 * ```
 */
async methodName(paramName: ParamType): Promise<ReturnType> {
  // 方法实现
}
```

## 🔧 @author字段处理规范

### 处理原则
- **保留人名**：如果@author是人名，必须保留不变
- **替换AI标识**：只有AI标识才可替换为用户名称

### 判断标准
```typescript
// ✅ 可以替换的AI标识
@author kiro          → 替换为 @author [用户名称]
@author ChatGPT       → 替换为 @author [用户名称]
@author Claude        → 替换为 @author [用户名称]
@author AI            → 替换为 @author [用户名称]

// ❌ 必须保留的人名
@author 张三          → 保留为 @author 张三
@author John Smith    → 保留为 @author John Smith
@author 李四          → 保留为 @author 李四
```

## 📝 修改记录规范

### 检查要点
步骤2需要检查文件头注释中的修改记录是否符合全局规范（详见README.md全局约束部分）：

- ✅ 修改记录格式是否正确
- ✅ 修改类型是否准确
- ✅ 用户日期和名称是否正确使用
- ✅ 版本号是否按规则递增
- ✅ @lastModified字段是否正确更新

### 常见检查项
```typescript
// ✅ 检查修改记录格式
/**
 * 最近修改：
 * - [用户日期]: 代码规范优化 - 清理未使用的导入 (修改者: [用户名称])
 * - 历史记录...
 */

// ✅ 检查版本号递增
@version 1.0.1  // 代码规范优化应该递增修订版本

// ✅ 检查时间戳更新
@lastModified [用户日期]  // 只有实际修改才更新
```

**注意：具体的修改记录规范请参考README.md中的全局约束部分**

## 📊 版本号递增规则

### 检查要点
步骤2需要检查版本号是否按照全局规范正确递增（详见README.md全局约束部分）：

- ✅ 代码规范优化、Bug修复 → 修订版本+1
- ✅ 功能新增、功能修改 → 次版本+1  
- ✅ 重构、架构变更 → 主版本+1

### 检查示例
```typescript
// 检查版本号递增是否正确
@version 1.0.0 → @version 1.0.1  // 代码规范优化
@version 1.0.1 → @version 1.1.0  // 功能新增
@version 1.1.0 → @version 2.0.0  // 重构
```

## ⏰ 时间更新规则

### 检查要点
步骤2需要检查时间戳更新是否符合全局规范（详见README.md全局约束部分）：

- ✅ 仅检查不修改时，不更新@lastModified字段
- ✅ 实际修改文件内容时，才更新@lastModified字段
- ✅ 使用Git变更检测确认文件是否真正被修改

### 🚨 重要强调：纯检查不更新修改记录
**步骤2注释规范检查时，如果发现注释已经符合规范，无需任何修改，则：**

#### 禁止的操作
- ❌ **禁止添加检查记录**：不要添加"AI代码检查步骤2：注释规范检查和优化"
- ❌ **禁止更新时间戳**：不要修改@lastModified字段
- ❌ **禁止递增版本号**：不要修改@version字段
- ❌ **禁止修改任何现有内容**：包括修改记录、作者信息等

#### 正确的做法
- ✅ **仅进行检查**：验证注释规范是否符合要求
- ✅ **提供检查报告**：说明检查结果和符合情况
- ✅ **保持文件不变**：如果符合规范就不修改任何内容

### 实际修改才更新的情况
**只有在以下情况下才需要更新修改记录：**
- 添加了缺失的文件头注释
- 补充了不完整的类注释
- 完善了缺失的方法注释
- 修正了错误的@author字段（AI标识替换为用户名）
- 修复了格式错误的注释结构

### Git变更检测检查
```bash
git status                    # 检查是否有文件被修改
git diff [filename]          # 检查具体修改内容
```

**只有git显示文件被修改时，才需要添加修改记录和更新时间戳**

**注意：具体的时间更新规则请参考README.md中的全局约束部分**

## 🎮 游戏服务器特殊注释要求

### WebSocket Gateway注释
```typescript
/**
 * 位置广播WebSocket网关
 * 
 * 功能描述：
 * - 处理客户端WebSocket连接
 * - 实时广播用户位置更新
 * - 管理游戏房间成员
 * 
 * WebSocket事件：
 * - connection: 客户端连接事件
 * - position_update: 位置更新事件
 * - disconnect: 客户端断开事件
 */
```

### 双模式服务注释
```typescript
/**
 * 用户服务（内存模式）
 * 
 * 功能描述：
 * - 提供用户数据的内存存储访问
 * - 支持开发测试和故障降级场景
 * - 与数据库模式保持接口一致性
 * 
 * 模式特点：
 * - 数据存储在内存Map中
 * - 应用重启后数据丢失
 * - 适用于开发测试环境
 */
```

### 属性测试注释
```typescript
/**
 * 管理员服务属性测试
 * 
 * 功能描述：
 * - 使用fast-check进行基于属性的随机测试
 * - 验证管理员操作的正确性和边界条件
 * - 自动发现潜在的边界情况问题
 * 
 * 测试策略：
 * - 随机生成用户状态变更
 * - 验证操作结果的一致性
 * - 检查异常处理的完整性
 */
```

## 🔍 检查执行步骤

1. **检查文件头注释完整性**
   - 功能描述是否清晰
   - 职责分离是否明确
   - 修改记录是否使用用户信息
   - @author字段是否正确处理

2. **检查类注释完整性**
   - 职责描述是否清晰
   - 主要方法是否列出
   - 使用场景是否说明

3. **检查方法注释完整性**
   - 业务逻辑步骤是否详细
   - @param、@returns、@throws是否完整
   - @example是否提供

4. **验证修改记录和版本号**
   - 使用git检查文件是否有实际变更
   - 根据修改类型正确递增版本号
   - 只有实际修改才更新时间戳

5. **特殊文件类型注释检查**
   - WebSocket Gateway的事件说明
   - 双模式服务的模式特点
   - 属性测试的测试策略

## 🔥 重要提醒

**如果在本步骤中执行了任何修改操作（添加注释、更新修改记录、修正@author字段等），必须立即重新执行步骤2的完整检查！**

- ✅ 执行修改 → 🔥 立即重新执行步骤2 → 提供验证报告 → 等待用户确认
- ❌ 执行修改 → 直接进入步骤3（错误做法）

**不能跳过重新检查环节！**