nestjs-backend-conventions

NestJS 后端开发规范 Skill

适用于 Flutter + NestJS + Prisma + MySQL 全栈项目的后端层。所有 <PLACEHOLDER> 替换为项目实际值。

占位符约定：本 skill 用 <TENANT_ID> 表示业务租户字段名（id 列），<tenant> 表示其 Prisma model 小写（如 <tenant> model 实际可能是 hotel / store / org），<Tenant> 表示 Pascal case 类型。新项目按业务命名替换 — 例如酒店 SaaS 用 hotelId / hotel / Hotel，门店 SaaS 用 storeId / store / Store，通用多租户用 tenantId / tenant / Tenant。

1. 分层架构

server/
├── prisma/
│   ├── schema.prisma           # 数据库 schema（唯一真相源）
│   └── migrations/             # 生产用 migration（开发用 db push 即可）
├── src/
│   ├── modules/                # 业务模块（每个模块一个文件夹）
│   │   └── <feature>/
│   │       ├── <feature>.module.ts
│   │       ├── <feature>.controller.ts
│   │       ├── <feature>.service.ts
│   │       ├── dto/
│   │       │   └── <feature>.dto.ts
│   │       └── interfaces/
│   ├── common/                 # 跨模块基础设施
│   │   ├── prisma/             # PrismaModule（全局）
│   │   ├── redis/              # RedisModule（全局，ioredis）
│   │   ├── queue/              # BullMQ QueueModule（全局）
│   │   ├── decorators/         # @CurrentUser、@RequirePermission
│   │   ├── guards/             # JwtAuthGuard、PermissionGuard
│   │   ├── interceptors/       # 日志 / 限流
│   │   ├── filters/            # HTTP 异常过滤器
│   │   ├── services/           # UploadService、CryptoService 等
│   │   ├── constants/          # 全局常量（语言列表、tier 限额、credit 默认值）
│   │   └── utils/              # 工具函数（normalizeBusinessLanguageCode 等）
│   ├── h5/                     # 对客 H5 渲染（Handlebars 模板）
│   ├── websocket/              # WebSocket Gateway
│   └── main.ts                 # bootstrap
└── .env                        # 环境配置（不进 git）

2. 命名规范

• 文件：kebab-case.ts（如 complaint-analytics.service.ts）
• 类：PascalCase（如 ComplaintAnalyticsService）
• DTO 类：<Action><Resource>Dto（如 CreateComplaintDto）
• 注释：中文（如团队偏好）
• Service 方法：动词开头，camelCase（generateAnalyticsReport / consumeReserved）

3. Module / Controller / Service 模板

// <feature>.module.ts
@Module({
  imports: [/* PrismaModule、RedisModule 全局，无需重复 import */],
  controllers: [<Feature>Controller],
  providers: [<Feature>Service],
  exports: [<Feature>Service],   // 仅当其他模块需要才 export
})
export class <Feature>Module {}