docs：添加AI代码检查执行指南文档

- 添加完整的7步代码检查流程指导 - 包含命名规范、注释标准、代码质量等检查标准 - 提供游戏服务器特殊要求和最佳实践 - 支持NestJS双模式架构和WebSocket实时通信检查涉及文件： - docs/ai-reading/README.md - 总体执行指南 - docs/ai-reading/step1-naming-convention.md - 命名规范检查 - docs/ai-reading/step2-comment-standard.md - 注释规范检查 - docs/ai-reading/step3-code-quality.md - 代码质量检查 - docs/ai-reading/step4-architecture-layer.md - 架构分层检查 - docs/ai-reading/step5-test-coverage.md - 测试覆盖检查 - docs/ai-reading/step6-documentation.md - 功能文档生成 - docs/ai-reading/step7-code-commit.md - 代码提交规范
2026-01-12 16:19:01 +08:00
parent c936961280
commit ba8bd9cc7e
8 changed files with 2402 additions and 0 deletions
--- a/docs/ai-reading/step2-comment-standard.md
+++ b/docs/ai-reading/step2-comment-standard.md
@@ -0,0 +1,250 @@
+# 步骤2：注释规范检查
+
+## 🎯 检查目标
+检查和完善所有注释规范，确保文件头、类、方法注释的完整性和准确性。
+
+## 📋 注释规范标准
+
+### 文件头注释（必须包含）
+```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变更检测确认文件是否真正被修改
+
+### Git变更检测检查
+```bash
+git status                    # 检查是否有文件被修改
+git diff [filename]          # 检查具体修改内容
+```
+
+**注意：具体的时间更新规则请参考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（错误做法）
+
+**不能跳过重新检查环节！**