wwjcloud-nest-v1/.cursor/rules/naming.mdc

---
description:
globs:
alwaysApply: true
---
# 🏷️ 命名规范指南

## 📋 概述

本文档为AI开发者提供完整的命名规范指南，确保NestJS项目与PHP项目在业务层面保持100%一致，同时遵循NestJS框架特性。

## 🎯 核心原则

1. **业务对齐优先**: 业务逻辑命名与PHP项目保持一致
2. **框架规范遵循**: NestJS特有文件类型按NestJS规范
3. **可读性保证**: 确保命名清晰、语义明确
4. **数据库一致性**: 与PHP项目共用数据库，命名必须完全一致

## 🏗️ 三大框架命名规范对比

### 1. PHP (ThinkPHP) 实际命名规范

基于 `niucloud-php` 项目的实际分析：

| 文件类型 | 命名规范 | 实际示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `PascalCase.php` | `User.php`, `Order.php` | 无Controller后缀 |
| **模型** | `PascalCase.php` | `SysUser.php`, `MemberLevel.php` | 直接使用业务名称 |
| **验证器** | `PascalCase.php` | `User.php`, `Member.php` | 无Validate后缀 |
| **服务** | `PascalCase.php` | `UserService.php`, `OrderService.php` | 有Service后缀 |
| **目录** | `snake_case` | `adminapi/`, `validate/`, `model/` | 小写下划线 |

### 2. Java (Spring Boot) 标准命名规范

| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `PascalCase + Controller.java` | `UserController.java` | 有Controller后缀 |
| **实体** | `PascalCase.java` | `User.java`, `Order.java` | 直接使用业务名称 |
| **服务** | `PascalCase + Service.java` | `UserService.java` | 有Service后缀 |
| **DTO** | `PascalCase + Dto.java` | `CreateUserDto.java` | 有Dto后缀 |
| **仓储** | `PascalCase + Repository.java` | `UserRepository.java` | 有Repository后缀 |

### 3. NestJS 框架标准命名规范

| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `camelCase.controller.ts` | `userController.ts`, `userProfileController.ts` | camelCase + 后缀 |
| **实体** | `camelCase.entity.ts` | `userEntity.ts`, `sysUser.entity.ts` | camelCase + 后缀 |
| **服务** | `camelCase.service.ts` | `userService.ts`, `userProfileService.ts` | camelCase + 后缀 |
| **DTO** | `camelCase.dto.ts` | `createUser.dto.ts`, `updateUser.dto.ts` | camelCase + 后缀 |
| **模块** | `camelCase.module.ts` | `userModule.ts`, `adminModule.ts` | camelCase + 后缀 |

**重要说明**：
- **文件名**：使用 `camelCase.suffix.ts` 格式（项目统一规范）
- **类名**：使用 `PascalCase` 格式（TypeScript 标准）
- **示例**：文件 `userController.ts` 导出类 `UserController`

## 🎯 统一命名标准（最终规范）

### 文件命名规范（camelCase + 后缀）

#### 实体文件命名
- **规范**: `{PHP模型名转camelCase}.entity.ts`
- **对应关系**: 与 PHP 模型文件一一对应，但使用 camelCase 命名
- **示例**:
  - PHP `SysUser.php` → NestJS `sysUser.entity.ts`
  - PHP `SysConfig.php` → NestJS `sysConfig.entity.ts`
  - PHP `MemberLevel.php` → NestJS `memberLevel.entity.ts`

#### 控制器文件命名
- **规范**: `{模块名}.controller.ts`（使用 camelCase）
- **示例**: `userController.ts`, `orderController.ts`, `adminController.ts`

#### 服务文件命名
- **规范**: `{模块名}.service.ts`（使用 camelCase）
- **示例**: `userService.ts`, `orderService.ts`, `adminService.ts`

#### DTO文件命名
- **规范**: `{操作动词}{模块名}.dto.ts`（使用 camelCase）
- **示例**: `createUser.dto.ts`, `updateUser.dto.ts`, `queryAdmin.dto.ts`

#### 验证器文件命名
- **规范**: `{模块名}.validator.ts` (区别于PHP无后缀)
- **示例**: `user.validator.ts`, `member.validator.ts`

#### 模块文件命名
- **规范**: `{模块名}.module.ts` (NestJS 标准)
- **示例**: `user.module.ts`, `admin.module.ts`, `auth.module.ts`

### 类命名规范

#### 实体类命名
- **规范**: `PascalCase` (与PHP模型名保持一致)
- **示例**: `SysUser`, `SysConfig`, `MemberLevel`

#### 控制器类命名
- **规范**: `PascalCase + Controller`
- **示例**: `UserController`, `AdminController`, `AuthController`

#### 服务类命名
- **规范**: `PascalCase + Service`
- **示例**: `UserService`, `OrderService`, `AdminService`

#### DTO类命名
- **规范**: `{操作动词}{模块名}Dto`
- **示例**: `CreateUserDto`, `UpdateOrderDto`, `QueryMemberDto`

### 方法命名规范

#### 业务逻辑方法
**优先与PHP项目保持一致，NestJS特有方法按NestJS规范**

- **CRUD方法**: 与PHP项目方法名保持一致
- **查询方法**: 与PHP项目方法名保持一致  
- **业务方法**: 与PHP项目方法名保持一致
- **NestJS生命周期方法**: 按NestJS规范，如 `onModuleInit()`, `onApplicationBootstrap()`

#### 变量命名规范
**业务变量优先与PHP项目保持一致，NestJS特有变量按NestJS规范**

- **业务变量**: 与PHP项目变量名保持一致
- **业务常量**: 与PHP项目常量名保持一致
- **NestJS注入变量**: 按NestJS规范，如 `private readonly userService: UserService`
- **TypeORM相关变量**: 按TypeORM规范，如 `@InjectRepository(User)`

## 🗄️ 数据库命名规范

### 重要约束
**与PHP项目共用数据库，必须保持命名100%一致**

- **表名**: 与PHP项目完全一致，包括前缀和命名方式
- **字段名**: 与PHP项目完全一致，不能修改任何字段名
- **字段类型**: 与PHP项目完全一致，不能修改字段类型
- **索引结构**: 与PHP项目完全一致，不能添加或删除索引

### 实体映射规范

```typescript
// 正确示例：与PHP模型SysUser.php对应
@Entity('sys_user') // 表名与PHP项目一致
export class SysUser {
  @PrimaryGeneratedColumn()
  id: number; // 字段名与PHP项目一致

  @Column({ name: 'username', length: 50 })
  username: string; // 字段名与PHP项目一致

  @Column({ name: 'created_at', type: 'timestamp' })
  createdAt: Date; // 字段名与PHP项目一致
}
```

## 📁 目录结构命名规范

### 标准模块目录结构
```
src/common/{模块名}/
├── {模块名}.module.ts    # 模块定义文件
├── controllers/          # 控制器目录
│   ├── adminapi/        # 管理端控制器目录（对应PHP adminapi/controller）
│   │   └── {模块名}.controller.ts
│   └── api/             # 前台控制器目录（对应PHP api/controller）
│       └── {模块名}.controller.ts
├── services/            # 服务目录
│   ├── admin/           # 管理端服务目录（对应PHP service/admin）
│   │   └── {模块名}.service.ts
│   ├── api/             # 前台服务目录（对应PHP service/api）
│   │   └── {模块名}.service.ts
│   └── core/            # 核心服务目录（对应PHP service/core）
│       └── {模块名}.service.ts
├── entity/              # 实体目录（对应PHP model）
│   ├── {实体名}.entity.ts      # 实体文件（camelCase.entity.ts 格式）
│   └── {配置实体}.entity.ts    # 配置实体文件
├── dto/                 # DTO 目录（对应PHP validate）
│   ├── admin/           # 管理端DTO目录
│   │   ├── create-{模块名}.dto.ts
│   │   └── update-{模块名}.dto.ts
│   └── api/             # 前台DTO目录
│       ├── {操作}-{模块}.dto.ts
│       └── {操作}-{模块}.dto.ts
├── guards/              # 守卫目录（可选）
├── decorators/          # 装饰器目录（可选）
├── interfaces/          # 接口目录（可选）
└── enums/               # 枚举目录（可选）
```

### 实际示例（基于auth模块）
```
src/common/auth/
├── auth.module.ts
├── controllers/
│   ├── adminapi/
│   │   └── auth.controller.ts        # 管理端控制器
│   └── api/
│       └── auth.controller.ts        # 前台控制器
├── services/
│   ├── admin/
│   │   └── auth.service.ts           # 管理端服务
│   ├── api/
│   │   └── auth.service.ts           # 前台服务
│   └── core/
│       └── auth.service.ts           # 核心服务
├── entity/
│   └── auth-token.entity.ts          # 实体文件
├── dto/
│   ├── admin/
│   │   ├── create-auth.dto.ts        # 管理端DTO
│   │   └── update-auth.dto.ts
│   └── api/
│       ├── login.dto.ts              # 前台DTO
│       └── register.dto.ts
├── guards/
│   ├── global-auth.guard.ts
│   ├── jwt-auth.guard.ts
│   └── roles.guard.ts
├── decorators/
│   ├── roles.decorator.ts
│   ├── public.decorator.ts
│   └── user-context.decorator.ts
└── interfaces/
    └── user.interface.ts
```

## 🚫 命名禁止规则

### 绝对禁止的命名行为

1. **🚫 禁止修改数据库相关命名**
   - 不能修改表名、字段名、索引名
   - 不能修改字段类型和长度
   - 必须与PHP项目数据库结构100%一致

2. **🚫 禁止自创业务方法名**
   - 业务方法名必须与PHP项目对应方法保持一致
   - 不能随意创造新的业务方法名

3. **🚫 禁止使用非标准缩写**
   - 避免使用不明确的缩写，如 `usr` 代替 `user`
   - 避免使用中文拼音命名

4. **🚫 禁止混合命名风格**
   - 同一项目内必须保持命名风格一致
   - 不能在同一文件中混用不同的命名规范

## ✅ 命名检查清单

### 开发前检查
- [ ] 已查看对应的PHP源码文件命名
- [ ] 已确认数据库表结构和字段命名
- [ ] 已理解业务逻辑和方法命名
- [ ] 已确认模块目录结构规范

### 开发中检查
- [ ] 实体类名与PHP模型名保持一致
- [ ] 数据库表名和字段名与PHP项目一致
- [ ] 业务方法名与PHP项目对应方法一致
- [ ] 文件命名符合NestJS规范

### 开发后检查
- [ ] 所有命名符合统一标准
- [ ] 没有使用禁止的命名方式
- [ ] 目录结构清晰规范
- [ ] 文档和注释命名准确

## 📚 相关文档

- [AI智能体工作流程指南](./AI-WORKFLOW-GUIDE.md)
- [AI开发禁止规则](./AI-DEVELOPMENT-RULES.md)
- [三框架原则对比](./FRAMEWORK-PRINCIPLES.md)
- [项目整体结构参考](./PROJECT-STRUCTURE.md)

---

**重要提醒**: 命名规范是代码质量的基础，所有AI开发者必须严格遵循此命名规范，确保项目的一致性和可维护性。