From 41c33d6159d282221bdb7d4bd011052cbfd40027 Mon Sep 17 00:00:00 2001
From: moyin <244344649@qq.com>
Date: Wed, 14 Jan 2026 13:17:23 +0800
Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E5=AE=8C=E5=96=84=20NestJS=20?=
 =?UTF-8?q?=E6=A1=86=E6=9E=B6=E6=96=87=E4=BB=B6=E5=91=BD=E5=90=8D=E8=A7=84?=
 =?UTF-8?q?=E8=8C=83=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 详细说明 NestJS 文件命名规则（snake_case + 点分隔类型标识符）
- 添加正确和错误的命名示例对比
- 补充所有 NestJS 文件类型标识符列表
- 增加常见错误判断方法说明
---
 docs/ai-reading/step1-naming-convention.md | 64 +++++++++++++++++++++-
 1 file changed, 62 insertions(+), 2 deletions(-)

diff --git a/docs/ai-reading/step1-naming-convention.md b/docs/ai-reading/step1-naming-convention.md
index 2555f98..ef99137 100644
--- a/docs/ai-reading/step1-naming-convention.md
+++ b/docs/ai-reading/step1-naming-convention.md
@@ -22,11 +22,63 @@
 ## 📋 命名规范标准
 
 ### 文件和文件夹命名
+
+#### 🚨 NestJS 框架文件命名规范（重要）
+**本项目使用 NestJS 框架，框架相关文件命名规则：**
+
+**命名组成 = 文件名（snake_case） + 类型标识符（点分隔） + 扩展名**
+
+```
+✅ 正确的 NestJS 文件命名：
+- login.controller.ts          # 单词文件名 + .controller
+- user_profile.service.ts      # snake_case文件名 + .service
+- auth_core.module.ts          # snake_case文件名 + .module
+- login_request.dto.ts         # snake_case文件名 + .dto
+- jwt_auth.guard.ts            # snake_case文件名 + .guard
+- current_user.decorator.ts    # snake_case文件名 + .decorator
+- user_profile.controller.spec.ts  # snake_case文件名 + .controller.spec
+
+❌ 错误的命名示例：
+- loginController.ts           # 错误！应该是 login.controller.ts
+- user-profile.service.ts      # 错误！应该是 user_profile.service.ts
+- authCore.module.ts           # 错误！应该是 auth_core.module.ts
+- login_controller.ts          # 错误！类型标识符应该用点分隔，不是下划线
+```
+
+**关键规则：**
+1. **文件名部分**：使用 snake_case（如 `user_profile`、`auth_core`）
+2. **类型标识符**：使用点分隔（如 `.controller`、`.service`）
+3. **完整格式**：`文件名.类型标识符.ts`（如 `user_profile.service.ts`）
+
+**NestJS 文件类型标识符（必须使用点分隔）：**
+- `.controller.ts` - 控制器（如 `user_auth.controller.ts`）
+- `.service.ts` - 服务（如 `user_profile.service.ts`）
+- `.module.ts` - 模块（如 `auth_core.module.ts`）
+- `.dto.ts` - 数据传输对象（如 `login_request.dto.ts`）
+- `.entity.ts` - 实体（如 `user_account.entity.ts`）
+- `.interface.ts` - 接口（如 `game_config.interface.ts`）
+- `.guard.ts` - 守卫（如 `jwt_auth.guard.ts`）
+- `.interceptor.ts` - 拦截器（如 `response_transform.interceptor.ts`）
+- `.pipe.ts` - 管道（如 `validation_pipe.pipe.ts`）
+- `.filter.ts` - 过滤器（如 `http_exception.filter.ts`）
+- `.decorator.ts` - 装饰器（如 `current_user.decorator.ts`）
+- `.middleware.ts` - 中间件（如 `logger_middleware.middleware.ts`）
+- `.spec.ts` - 单元测试（如 `user_profile.service.spec.ts`）
+- `.e2e.spec.ts` - E2E 测试（如 `auth_flow.e2e.spec.ts`）
+
+**命名规则说明：**
+1. **文件名使用 snake_case**：多个单词用下划线连接（如 `user_profile`、`auth_core`）
+2. **类型标识符使用点分隔**：遵循 NestJS/Angular 风格（如 `.controller`、`.service`）
+3. **组合格式**：`snake_case文件名.类型标识符.ts`
+4. **社区标准**：这是本项目结合 NestJS 规范和 snake_case 约定的标准做法
+
+#### 普通文件和文件夹命名
 - **规则**：snake_case（下划线分隔），保持项目一致性
+- **适用范围**：非 NestJS 框架文件、工具类、配置文件、普通文件夹等
 - **示例**：
   ```
-  ✅ 正确：user_controller.ts, admin_operation_log_service.ts
-  ❌ 错误：UserController.ts, user-service.ts, adminOperationLog.service.ts
+  ✅ 正确：user_utils.ts, admin_operation_log.ts, config_loader.ts
+  ❌ 错误：UserUtils.ts, user-utils.ts, adminOperationLog.ts
   ```
 
 ### 变量和函数命名
@@ -161,6 +213,14 @@ src/business/auth/
 2. **凭印象判断，不使用工具获取准确数据**
 3. **遗漏≤3个文件文件夹的识别**
 4. **忽略测试文件夹扁平化**：认为tests文件夹是"标准结构"
+5. **🚨 错误地要求修改 NestJS 框架文件命名**：
+   - ❌ 错误：要求将 `login.controller.ts` 改为 `login_controller.ts`（类型标识符不能用下划线）
+   - ❌ 错误：要求将 `userProfile.service.ts` 改为 `userProfile.service.ts`（文件名应该用 snake_case）
+   - ✅ 正确：`user_profile.service.ts`（文件名用 snake_case + 类型标识符用点分隔）
+   - **判断方法**：
+     - 检查类型标识符是否用点分隔（`.controller`、`.service` 等）
+     - 检查文件名本身是否用 snake_case
+     - 完整格式：`snake_case文件名.类型标识符.ts`
 
 ## 🔍 检查执行步骤