第 04 集：Cursor Rules 与 Context

你的 Prompt
    +
.cursorrules 的内容（自动附加）
    ↓
AI 的回答（基于两者的综合理解）

## 技术栈
- 框架：NestJS 10+
- ORM：Prisma（不使用 TypeORM）
- 语言：TypeScript，strict 模式
- 数据库：PostgreSQL

## 命名规范
- 文件名：kebab-case（user-service.ts）
- 类名：PascalCase（UserService）
- 方法名和变量：camelCase（findAll、userId）
- 常量：SCREAMING_SNAKE_CASE（MAX_RETRY_COUNT）
- 数据库字段：snake_case（created_at）

## 接口返回格式
所有接口必须返回以下格式，不允许直接返回原始数据：
{
  "code": 0,
  "data": any,
  "message": "ok"
}

## Controller 规范
- 每个 Controller 必须有 @ApiTags('模块名')
- 每个接口必须有 @ApiOperation({ summary: '接口描述' })

## 不要做的事情
- 不要生成 .spec.ts 测试文件
- 不要使用 any 类型
- 不要硬编码配置值，使用 ConfigService
- 不要在 Service 层引用 Request、Response 对象
- 不要用 console.log，用 NestJS 内置的 Logger

@user.entity.ts 根据这个 Entity，生成对应的 CreateUserDto 和 UpdateUserDto

@src/modules/user 分析这个模块的代码，有哪些可以改进的地方？

@docs https://docs.nestjs.com/interceptors
帮我实现一个全局的响应格式拦截器，把所有返回值包装成 ResponseDto 格式

node_modules/
dist/
.env
.env.local
*.log
coverage/
prisma/migrations/

npx @nestjs/cli new rules-demo
cd rules-demo
npm install

cursor rules-demo

帮我创建一个用户注册接口

touch .cursorrules

# 技术栈
- 框架：NestJS 10+
- ORM：Prisma（不使用 TypeORM，不使用 Mongoose）
- 语言：TypeScript，strict 模式
- 数据库：PostgreSQL

# 命名规范
- 文件名：kebab-case（user-service.ts）
- 类名：PascalCase（UserService）
- 方法名和变量：camelCase（findAll、userId）
- 数据库字段：snake_case（created_at）

# 接口规范
- 所有 Controller 必须有 @ApiTags 和 @ApiOperation
- 所有接口返回格式：{ code: number, data: any, message: string }
- 路径用 kebab-case（/api/user-profile）

# 错误处理
- 使用 NestJS 内置异常类（NotFoundException、BadRequestException 等）
- 不允许空的 catch 块

# 不要做的事情
- 不要生成 .spec.ts 测试文件
- 不要使用 any 类型
- 不要硬编码配置值，使用 ConfigService
- 不要用 console.log

帮我创建一个用户注册接口

import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn } from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  username: string;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;

  @CreateDateColumn()
  createdAt: Date;
}

@user.entity.ts 根据这个 Entity 的字段，生成 CreateUserDto 和 UpdateUserDto，
用 class-validator 做参数校验

@src/user 分析这个模块的代码，告诉我：
1. 有哪些不符合 NestJS 最佳实践的地方
2. 有哪些不符合当前项目 Rules 规范的地方

touch .cursorignore

node_modules/
dist/
.env
.env.local
*.log
coverage/
prisma/migrations/

@node_modules 这个目录里有什么？

[你的 .cursorrules 内容]
+ [你在 Chat 里说的话]
→ AI 收到的完整输入

my-project/
├── .cursorrules
├── src/
└── ...

my-project/
├── .cursor/
│   └── rules/
│       ├── global.mdc        # 全局规则
│       ├── backend.mdc       # 后端规则（NestJS/Prisma）
│       ├── frontend.mdc      # 前端规则（Vue/React）
│       └── testing.mdc       # 测试规则
├── src/
└── ...

# 项目技术栈
- Runtime: Node.js 20+
- Framework: NestJS 10
- Language: TypeScript 5.x（严格模式）
- ORM: Prisma 5（禁止使用 TypeORM）
- Database: PostgreSQL 16
- 日志: Pino（禁止使用 console.log）

# 代码风格
- 格式化工具: Prettier
- 无分号（semi: false）
- 单引号（singleQuote: true）
- 2 空格缩进
- 行尾 LF（不用 CRLF）
- 每行最大 100 字符

# 接口规范
所有接口返回统一的 Result 格式：

```typescript
interface Result<T = any> {
  code: number    // 0 表示成功，非 0 表示失败
  message: string
  data: T | null
}
```text

使用 ResultHelper 辅助类：

```typescript
// 成功
return ResultHelper.ok(data)

// 失败
throw new BusinessException(ErrorCode.USER_NOT_FOUND)
```text

禁止在 Controller 层直接 throw HttpException，统一通过 BusinessException + 全局 Filter 处理。

# 目录结构
```plain
src/
├── common/                    # 公共基础设施
│   ├── decorators/
│   ├── filters/               # 全局异常过滤器
│   ├── guards/
│   ├── interceptors/
│   └── pipes/
├── config/                    # 配置模块
├── modules/                   # 业务模块
│   └── [module-name]/
│       ├── [module].controller.ts
│       ├── [module].service.ts
│       ├── [module].module.ts
│       └── dto/
│           ├── create-[module].dto.ts
│           ├── update-[module].dto.ts
│           └── query-[module].dto.ts
└── prisma/                    # Prisma 相关
```text

# 命名约定
+ 文件名: kebab-case（user-profile.service.ts）
+ 类名: PascalCase（UserProfileService）
+ 变量/函数: camelCase
+ 常量: UPPER_SNAKE_CASE
+ Prisma 模型字段: camelCase
+ 数据库列名: snake_case（通过 @map 映射）

# DTO 规范
+ 所有 DTO 使用 class-validator 装饰器进行校验
+ 创建 DTO：所有必填字段都要加 @IsNotEmpty() + 具体类型装饰器
+ 更新 DTO：继承 PartialType(CreateDto)，所有字段可选
+ 查询 DTO：继承 PageQueryDto，分页参数已内置

```typescript
// 示例：创建用户 DTO
export class CreateUserDto {
  @IsEmail()
  @IsNotEmpty()
  email: string

  @IsString()
  @MinLength(8)
  @MaxLength(32)
  password: string

  @IsString()
  @MinLength(2)
  @MaxLength(50)
  name: string
}
```text

# Prisma 使用规范
+ 所有查询必须处理 `isDeleted: false` 过滤（软删除）
+ 不允许直接暴露 Prisma 模型作为接口返回类型，必须用 DTO/VO 映射
+ 分页查询统一使用 `findMany + count` 的方式，不用游标分页
+ 敏感字段（password 等）必须在 select 或 omit 中明确排除

# 日志规范
+ 使用 Pino logger，通过 DI 注入
+ 格式：`this.logger.info({ userId, action }, 'User created')`（结构化日志）
+ 禁止在 service 层打 debug 无关的业务信息日志

# 安全规范
+ 所有需要认证的接口加 @UseGuards(JwtAuthGuard)
+ 密码必须 bcrypt 加密（rounds=10），禁止 MD5/SHA1
+ 禁止在日志中打印密码、token 等敏感信息
+ 禁止在代码中硬编码任何密钥、密码、API Key

# 生成代码的要求
+ 生成代码时不需要解释，直接给完整代码
+ 遇到类型不确定的地方，用 TypeScript 严格类型，不允许用 any
+ 生成的代码要可以直接运行，不留 TODO 占位
+ 如果某个功能需要额外配置或环境变量，在代码注释里说明，不要遗漏

```plain
---

### 5. .cursorignore

`.cursorignore` 和 `.gitignore` 的语法一样，告诉 Cursor 哪些文件/目录不要纳入上下文索引。

```gitignore
# 构建产物
dist/
build/

# 依赖
node_modules/

# 测试覆盖率
coverage/

# 环境变量（含敏感信息）
.env
.env.local
.env.production

# 日志文件
*.log
logs/

# 大文件，不需要 AI 读
*.pdf
*.zip
prisma/migrations/  # 迁移文件太多，干扰上下文

@src/common/filters/http-exception.filter.ts
帮我看看这个 filter 的写法，然后按相同风格写一个处理 Prisma 错误的 filter

参考 @src/modules/product/ 的模块结构，
帮我在 src/modules/order/ 创建同样结构的订单模块

@UserService.findAll 这个方法有 N+1 查询问题，帮我优化

@Codebase 项目里所有使用了 bcrypt.hash 的地方在哪？
我要统一改成从配置读取 rounds 数

@NestJS Docs 帮我查一下 NestJS 的 Global Pipes 怎么配置

@Git 最近 3 次提交做了哪些改动？帮我写一份变更说明

这次只做一个快速验证的脚本，可以用 console.log，不需要 Pino

git add .cursorrules
git commit -m "feat: add cursorrules for team AI coding standards"

# ===== 技术栈 =====
[基础技术选型，明确"用什么"和"不用什么"]

# ===== 代码风格 =====
[Prettier 配置摘要，命名约定]

# ===== 架构约定 =====
[目录结构，分层职责]

# ===== 接口规范 =====
[请求/响应格式，错误处理方式]

# ===== 数据层规范 =====
[ORM 使用规范，字段命名]

# ===== 安全规范 =====
[认证、加密、敏感信息处理]

# ===== AI 生成代码要求 =====
[告诉 AI 生成代码时的行为规范]