whale-town-end/AI代码检查规范_简洁版.md

AI代码检查规范（简洁版）- Whale Town 游戏服务器专用

执行原则

• 分步执行：每次只执行一个步骤，完成后等待用户确认
• 用户信息收集：开始前必须收集用户当前日期和名称
• 修改验证：每次修改后必须重新检查该步骤
• 项目特性适配：针对NestJS游戏服务器的双模式架构和实时通信特点优化

检查步骤

步骤1：命名规范检查

• 文件/文件夹：snake_case（下划线分隔），保持项目一致性
• 变量/函数：camelCase
• 类/接口：PascalCase
• 常量：SCREAMING_SNAKE_CASE
• 路由：kebab-case
• 文件夹优化：删除单文件文件夹，扁平化结构
• Core层命名：业务支撑模块用_core后缀，通用工具模块不用
• 游戏服务器特殊规范：
  • WebSocket Gateway文件：*.gateway.ts
  • 实时通信相关：websocket_*, realtime_*
  • 双模式服务：*_memory.service.ts, *_database.service.ts
  • 属性测试：*.property.spec.ts
  • 集成测试：*.integration.spec.ts
  • E2E测试：*.e2e.spec.ts

文件夹结构检查要求

必须使用listDirectory工具详细检查每个文件夹的内容：

1. 使用listDirectory(path, depth=2)获取完整文件夹结构
2. 统计每个文件夹内的文件数量
3. 识别只有1个文件的文件夹（单文件文件夹）
4. 将单文件文件夹中的文件移动到上级目录
5. 更新所有相关的import路径引用

检查标准：

• 不超过3个文件的文件夹：必须扁平化处理
• 4个以上文件：通常保持独立文件夹
• 完整功能模块：即使文件较少也可以保持独立（需特殊说明）
• 测试文件位置：测试文件必须与对应源文件放在同一目录，不允许单独的tests文件夹

测试文件位置规范（重要）：

• ✅ 正确位置：测试文件必须与对应源文件放在同一目录
• ❌ 错误位置：测试文件放在单独的tests/、test/、spec/、tests/等文件夹中
• 游戏服务器测试分类：
  • 单元测试：*.spec.ts - 基础功能测试
  • 集成测试：*.integration.spec.ts - 模块间交互测试
  • 属性测试：*.property.spec.ts - 基于属性的随机测试（适用于管理员模块）
  • E2E测试：*.e2e.spec.ts - 端到端业务流程测试
  • 性能测试：*.perf.spec.ts - WebSocket和实时通信性能测试

常见错误：

• 只看文件夹名称，不检查内容
• 凭印象判断，不使用工具获取准确数据
• 遗漏3个文件以下文件夹的识别
• 忽略测试文件夹：认为tests文件夹是"标准结构"而不进行扁平化检查

步骤2：注释规范检查

• 文件头注释：功能描述、职责分离、修改记录、@author、@version、@since、@lastModified
• 类注释：职责、主要方法、使用场景
• 方法注释：业务逻辑步骤、@param、@returns、@throws、@example
• 修改记录：使用用户提供的日期和名称，格式"日期: 类型 - 内容 (修改者: 名称)"
• @author处理规范：
  • 保留原则：人名必须保留，不得随意修改
  • AI标识替换：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
  • 判断示例：@author kiro → 可替换，@author 张三 → 必须保留
• 版本号递增：规范优化/Bug修复→修订版本+1，功能变更→次版本+1，重构→主版本+1
• 时间更新规则：
  • 仅检查不修改：如果只是进行代码检查而没有实际修改文件内容，不更新@lastModified字段
  • 实际修改才更新：只有真正修改了文件内容（功能代码、注释内容、结构调整等）时才更新@lastModified字段
  • 检查规范强调：注释规范检查本身不是修改，除非发现需要修正的问题并进行了实际修改
  • Git变更检测：通过git status和git diff检查文件是否有实际变更，只有git显示文件被修改时才需要添加修改记录和更新时间戳

步骤3：代码质量检查

• 清理未使用：导入、变量、方法
• 常量定义：使用SCREAMING_SNAKE_CASE
• 方法长度：建议不超过50行
• 代码重复：识别并消除重复代码
• 魔法数字：提取为常量定义
• 工具函数：抽象重复逻辑为可复用函数
• TODO项处理：最终文件不能包含TODO项，必须真正实现功能或删除未完成代码

步骤4：架构分层检查

• 检查范围：仅检查当前执行检查的文件夹，不考虑其他同层功能模块
• Core层：专注技术实现，不含业务逻辑
• Core层命名规则：
  • 业务支撑模块：为特定业务功能提供技术支撑，使用_core后缀（如：location_broadcast_core）
  • 通用工具模块：提供可复用的数据访问或技术服务，不使用后缀（如：user_profiles、redis_cache）
  • 判断方法：检查模块是否专门为某个业务服务，如果是则使用_core后缀，如果是通用服务则不使用
• Business层：专注业务逻辑，不含技术实现细节
• 依赖关系：Core层不能导入Business层，Business层通过依赖注入使用Core层
• 职责分离：确保各层职责清晰，边界明确

步骤5：测试覆盖检查

• 测试文件存在性：每个Service、Controller、Gateway必须有对应测试文件
• 游戏服务器测试要求：
  • ✅ Service类：文件名包含.service.ts的业务逻辑类
  • ✅ Controller类：文件名包含.controller.ts的控制器类
  • ✅ Gateway类：文件名包含.gateway.ts的WebSocket网关类
  • ✅ Guard类：文件名包含.guard.ts的守卫类（游戏服务器安全重要）
  • ✅ Interceptor类：文件名包含.interceptor.ts的拦截器类（日志监控重要）
  • ✅ Middleware类：文件名包含.middleware.ts的中间件类（性能监控重要）
  • ❌ DTO类：数据传输对象不需要测试文件
  • ❌ Interface文件：接口定义不需要测试文件
  • ❌ Utils工具类：简单工具函数不需要测试文件（复杂工具类需要）
• 测试代码检查严格要求：
  • 一对一映射：每个测试文件必须严格对应一个源文件，不允许一个测试文件测试多个源文件
  • 测试范围限制：测试内容必须严格限于对应源文件的功能测试，不允许跨文件测试
  • 集成测试分离：所有集成测试、E2E测试、性能测试必须移动到顶层test/目录的对应子文件夹
  • 测试文件命名：测试文件名必须与源文件名完全对应（除.spec.ts后缀外）
  • 禁止混合测试：单元测试文件中不允许包含集成测试或E2E测试代码
• 顶层test目录结构：
  • test/integration/ - 所有集成测试文件
  • test/e2e/ - 所有端到端测试文件
  • test/performance/ - 所有性能测试文件
  • test/property/ - 所有属性测试文件（管理员模块）
• 实时通信测试：WebSocket Gateway必须有连接、断开、消息处理的完整测试
• 双模式测试：内存服务和数据库服务都需要完整测试覆盖
• 属性测试应用：管理员模块使用fast-check进行属性测试，放在test/property/目录
• 集成测试要求：复杂Service的集成测试放在test/integration/目录
• E2E测试要求：关键业务流程的端到端测试放在test/e2e/目录
• 测试执行：必须执行测试命令验证通过

步骤6：功能文档生成

• README结构：模块概述、对外接口、内部依赖、核心特性、潜在风险
• 接口描述：每个公共方法一句话功能说明
• API接口列表：如果business模块开放了可访问的API，在README中列出每个API并用一句话解释功能
• WebSocket接口文档：Gateway模块需要详细的WebSocket事件文档
• 双模式说明：Core层模块需要说明数据库模式和内存模式的差异
• 依赖分析：列出所有项目内部依赖及用途
• 特性识别：技术特性、功能特性、质量特性
• 风险评估：技术风险、业务风险、运维风险、安全风险
• 游戏服务器特殊文档：
  • 实时通信协议说明
  • 性能监控指标
  • 双模式切换指南
  • 属性测试策略说明

关键规则

命名规范

// 文件命名（保持项目一致性）
✅ user_service.ts, create_user_dto.ts, admin_operation_log_service.ts
❌ user-service.ts, UserService.ts, adminOperationLog.service.ts

// 游戏服务器特殊文件类型
✅ location_broadcast.gateway.ts, websocket_auth.guard.ts
✅ users_memory.service.ts, file_redis.service.ts
✅ admin.property.spec.ts, zulip_integration.e2e.spec.ts

// 变量命名  
✅ const userName = 'test';
❌ const UserName = 'test';

// 常量命名
✅ const MAX_RETRY_COUNT = 3;
❌ const maxRetryCount = 3;

注释规范

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

@author字段处理规则：

• 保留人名：如果@author是人名，必须保留不变
• 替换AI标识：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换
• 示例：
  • @author kiro → 可替换为 @author [用户名称]
  • @author 张三 → 必须保留为 @author 张三

架构分层

// Core层 - 业务支撑模块（使用_core后缀）
@Injectable()
export class LocationBroadcastCoreService {
  async broadcastPosition(data: PositionData): Promise<void> {
    // 为位置广播业务提供技术支撑
  }
}

// Core层 - 通用工具模块（不使用后缀）
@Injectable()
export class UserProfilesService {
  async findByUserId(userId: bigint): Promise<UserProfile> {
    // 通用的用户档案数据访问服务
  }
}

// Business层 - 业务逻辑
@Injectable() 
export class LocationBroadcastService {
  constructor(
    private readonly locationBroadcastCore: LocationBroadcastCoreService,
    private readonly userProfiles: UserProfilesService
  ) {}
  
  async updateUserLocation(userId: string, position: Position): Promise<void> {
    // 业务逻辑：验证、调用Core层、返回结果
  }
}

Core层命名判断标准：

• 业务支撑模块：专门为某个业务功能提供技术支撑 → 使用_core后缀
• 通用工具模块：提供可复用的数据访问或基础服务 → 不使用后缀

测试覆盖

// 游戏服务器测试示例 - 严格一对一映射
describe('LocationBroadcastGateway', () => {
  // 只测试LocationBroadcastGateway的功能，不测试其他类
  describe('handleConnection', () => {
    it('should accept valid WebSocket connection', () => {}); // 正常情况
    it('should reject unauthorized connection', () => {}); // 异常情况  
    it('should handle connection limit exceeded', () => {}); // 边界情况
  });
  
  describe('handlePositionUpdate', () => {
    it('should broadcast position to room members', () => {}); // 实时通信测试
    it('should validate position data format', () => {}); // 数据验证测试
  });
});

// ❌ 错误：在单元测试中包含集成测试代码
describe('LocationBroadcastGateway', () => {
  it('should integrate with database and redis', () => {}); // 应该移到test/integration/
});

// ✅ 正确：集成测试放在顶层test目录
// 文件位置：test/integration/location_broadcast_integration.spec.ts
describe('LocationBroadcast Integration', () => {
  it('should integrate gateway with core service and database', () => {
    // 测试多个模块间的集成
  });
});

// ✅ 正确：E2E测试放在顶层test目录
// 文件位置：test/e2e/location_broadcast_e2e.spec.ts
describe('LocationBroadcast E2E', () => {
  it('should handle complete user position update flow', () => {
    // 端到端业务流程测试
  });
});

// ✅ 正确：属性测试放在顶层test目录
// 文件位置：test/property/admin_property.spec.ts
describe('AdminService Properties', () => {
  it('should handle any valid user status update', 
    fc.property(fc.integer(), fc.constantFrom(...Object.values(UserStatus)), 
    (userId, status) => {
      // 属性测试逻辑
    })
  );
});

// ✅ 正确：性能测试放在顶层test目录
// 文件位置：test/performance/websocket_performance.spec.ts
describe('WebSocket Performance', () => {
  it('should handle 1000 concurrent connections', () => {
    // 性能测试逻辑
  });
});

API文档规范

business模块如开放API接口，README中必须包含：

## 对外API接口

### POST /api/auth/login
用户登录接口，支持用户名/邮箱/手机号多种方式登录。

### GET /api/users/profile
获取当前登录用户的详细档案信息。

### PUT /api/users/:id/status
更新指定用户的状态（激活/禁用/待验证）。

## WebSocket事件接口

### 'position_update'
接收客户端位置更新，广播给房间内其他用户。

### 'join_room'
用户加入游戏房间，建立实时通信连接。

### 'chat_message'
处理聊天消息，支持Zulip集成和消息过滤。

执行模板

每步完成后使用此模板报告：

## 步骤X：[步骤名称]检查报告

### 🔍 检查结果
[发现的问题列表]

### 🛠️ 修正方案  
[具体修正建议]

### ✅ 完成状态
- 检查项1 ✓/✗
- 检查项2 ✓/✗

**请确认修正方案，确认后进行下一步骤**

修改验证流程

修改后必须：

1. 重新执行该步骤检查
2. 提供验证报告
3. 确认问题是否解决
4. 等待用户确认

强制要求

• 用户信息：开始前必须收集用户日期和名称
• 分步执行：严禁一次执行多步骤
• 等待确认：每步完成后必须等待用户确认
• 修改验证：修改后必须重新检查验证
• 测试执行：步骤5必须执行实际测试命令
• 日期使用：所有日期字段使用用户提供的真实日期
• 作者字段保护：@author字段中的人名不得修改，只有AI标识才可替换
• 修改记录强制：每次修改文件必须添加修改记录和更新@lastModified
• API文档强制：business模块如开放API接口，README中必须列出所有API并用一句话解释功能
• 测试代码严格要求：每个测试文件必须严格对应一个源文件，集成测试等必须移动到顶层test/目录统一管理