whale-town-end/docs/ai-reading/step1-naming-convention.md

步骤1：命名规范检查

🎯 检查目标

检查和修正所有命名规范问题，确保项目代码命名一致性。

📋 命名规范标准

文件和文件夹命名

• 规则：snake_case（下划线分隔），保持项目一致性
• 示例：

  ✅ 正确：user_controller.ts, admin_operation_log_service.ts
  ❌ 错误：UserController.ts, user-service.ts, adminOperationLog.service.ts
  

变量和函数命名

• 规则：camelCase（小驼峰命名）
• 示例：

  ✅ 正确：const userName = 'test'; function getUserInfo() {}
  ❌ 错误：const UserName = 'test'; function GetUserInfo() {}
  

类和接口命名

• 规则：PascalCase（大驼峰命名）
• 示例：

  ✅ 正确：class UserService {} interface GameConfig {}
  ❌ 错误：class userService {} interface gameConfig {}
  

常量命名

• 规则：SCREAMING_SNAKE_CASE（全大写+下划线）
• 示例：

  ✅ 正确：const MAX_RETRY_COUNT = 3; const SALT_ROUNDS = 10;
  ❌ 错误：const maxRetryCount = 3; const saltRounds = 10;
  

路由命名

• 规则：kebab-case（短横线分隔）
• 示例：

  ✅ 正确：@Get('user/get-info') @Post('room/join-room')
  ❌ 错误：@Get('user/getInfo') @Post('room/joinRoom')
  

🎮 游戏服务器特殊文件类型

WebSocket相关文件

✅ 正确命名：
- location_broadcast.gateway.ts     # WebSocket网关
- websocket_auth.guard.ts          # WebSocket认证守卫
- realtime_chat.service.ts         # 实时通信服务

双模式服务文件

✅ 正确命名：
- users_memory.service.ts          # 内存模式服务
- users_database.service.ts        # 数据库模式服务
- file_redis.service.ts            # Redis文件存储

测试文件分类

✅ 正确命名：
- user.service.spec.ts             # 单元测试
- admin.integration.spec.ts        # 集成测试
- location.property.spec.ts        # 属性测试（管理员模块）
- auth.e2e.spec.ts                 # E2E测试
- websocket.perf.spec.ts           # 性能测试

🏗️ 文件夹结构检查

检查方法（必须使用工具）

1. 使用listDirectory工具：listDirectory(path, depth=2)获取完整结构
2. 统计文件数量：逐个文件夹统计文件数量
3. 识别单文件文件夹：只有1个文件的文件夹
4. 执行扁平化：将文件移动到上级目录
5. 更新引用路径：修改所有import语句

扁平化标准

• ≤3个文件：必须扁平化处理
• ≥4个文件：通常保持独立文件夹
• 完整功能模块：即使文件较少也可保持独立（需特殊说明）

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

• ✅ 正确：测试文件与源文件放在同一目录
• ❌ 错误：测试文件放在单独的tests/、test/、spec/、tests/文件夹

✅ 正确结构：
src/business/auth/
├── auth.service.ts
├── auth.service.spec.ts
├── auth.controller.ts
└── auth.controller.spec.ts

❌ 错误结构：
src/business/auth/
├── auth.service.ts
├── auth.controller.ts
└── tests/
    ├── auth.service.spec.ts
    └── auth.controller.spec.ts

🔧 Core层命名规则

业务支撑模块（使用_core后缀）

专门为特定业务功能提供技术支撑：

✅ 正确：
- location_broadcast_core/    # 为位置广播业务提供技术支撑
- admin_core/                 # 为管理员业务提供技术支撑
- user_auth_core/            # 为用户认证业务提供技术支撑

通用工具模块（不使用后缀）

提供可复用的数据访问或技术服务：

✅ 正确：
- user_profiles/             # 通用用户档案数据访问
- redis/                     # 通用Redis技术封装
- logger/                    # 通用日志工具服务

判断方法

1. 模块是否专门为某个特定业务服务？
   ├─ 是 → 使用_core后缀
   └─ 否 → 不使用后缀

2. 实际案例：
   - user_profiles: 通用数据访问 → 不使用后缀 ✓
   - location_broadcast_core: 专门为位置广播服务 → 使用_core后缀 ✓

⚠️ 常见检查错误

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

🔍 检查执行步骤

1. 使用listDirectory工具检查目标文件夹结构
2. 逐个检查文件和文件夹命名是否符合规范
3. 统计每个文件夹的文件数量
4. 识别需要扁平化的文件夹（≤3个文件）
5. 检查Core层模块命名是否正确
6. 执行必要的文件移动和重命名操作
7. 更新所有相关的import路径引用
8. 验证修改后的结构和命名

🔥 重要提醒

如果在本步骤中执行了任何修改操作（文件重命名、移动、删除等），必须立即重新执行步骤1的完整检查！

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

不能跳过重新检查环节！