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

步骤2：注释规范检查

⚠️ 执行前必读规范

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

该README文件包含：

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

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

---

🎯 检查目标

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

📋 注释规范标准

文件头注释（必须包含）

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

类注释（必须包含）

/**
 * 类功能描述
 * 
 * 职责：
 * - 主要职责1
 * - 主要职责2
 * 
 * 主要方法：
 * - method1() - 方法1功能
 * - method2() - 方法2功能
 * 
 * 使用场景：
 * - 场景描述
 */
@Injectable()
export class ExampleService {
  // 类实现
}

方法注释（必须包含）

/**
 * 方法功能描述
 * 
 * 业务逻辑：
 * 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标识才可替换为用户名称

判断标准

// ✅ 可以替换的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字段是否正确更新

常见检查项

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

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

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

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

📊 版本号递增规则

检查要点

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

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

检查示例

// 检查版本号递增是否正确
@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变更检测检查

git status                    # 检查是否有文件被修改
git diff [filename]          # 检查具体修改内容

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

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

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

WebSocket Gateway注释

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

双模式服务注释

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

属性测试注释

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

🔍 检查执行步骤

1. 检查文件头注释完整性

   • 功能描述是否清晰
   • 职责分离是否明确
   • 修改记录是否使用用户信息
   • @author字段是否正确处理

2. 检查类注释完整性

   • 职责描述是否清晰
   • 主要方法是否列出
   • 使用场景是否说明

3. 检查方法注释完整性

   • 业务逻辑步骤是否详细
   • @param、@returns、@throws是否完整
   • @example是否提供

4. 验证修改记录和版本号

   • 使用git检查文件是否有实际变更
   • 根据修改类型正确递增版本号
   • 只有实际修改才更新时间戳

5. 特殊文件类型注释检查

   • WebSocket Gateway的事件说明
   • 双模式服务的模式特点
   • 属性测试的测试策略

🔥 重要提醒

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

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

不能跳过重新检查环节！