Cursor rule

1---
2globs: buero-backend-api/src/**/*.ts
3description: "API та NestJS-патерни для backend buero.de"
4---
5 
6# API Patterns — NestJS backend buero.de
7 
8## Структура модуля
9 
10- Модуль: `*.module.ts` (imports, exports, providers).
11- Контролер: `*.controller.ts` — тільки HTTP (параметри, виклик сервісу, повернення).
12- Сервіс: `*.service.ts` — бізнес-логіка, робота з Prisma (інжекція PrismaService).
13- DTO: окремі файли або папка dto; class-validator + class-transformer; Swagger @ApiProperty / @ApiPropertyOptional.
14 
15## Аутентифікація та авторизація
16 
17- Захист ендпоінтів: **JwtAuthGuard** (Passport JWT). Токен з cookie або заголовка `Authorization: Bearer`.
18- Ролі: **RolesGuard** + декоратор **@Roles('student' | 'teacher')**. Адмін-ролі немає.
19- Поточний користувач: декоратор типу **@CurrentUser()** або **req.user** (payload JWT: id, role, email тощо).
20- Деталі: docs/auth-spec.md (токени в cookie, refresh у Postgres, revoke при logout).
21 
22## Контролери
23 
24- Swagger: **@ApiTags**, **@ApiOperation**, **@ApiResponse**; для захищених — **@ApiBearerAuth()** або опис cookie.
25- Валідація: **ValidationPipe** глобально; DTO з декораторами class-validator.
26- Помилки: **HttpException** з відповідним статусом (400, 401, 403, 404); не витікати внутрішні деталі.
27- Доступ до контенту (курси, матеріали): перевіряти активну підписку або trial для студента (модуль Subscriptions / student_profiles.trial_ends_at).
28 
29## DTO та валідація
30 
31- **@IsString()**, **@IsEmail()**, **@IsUUID()**, **@IsEnum()**, **@IsOptional()**, **@Min()**, **@Max()**, **@ValidateNested()**, **@Type()** (class-transformer).
32- Swagger: **@ApiProperty({ description, example })** для обов'язкових; **@ApiPropertyOptional()** для опціональних.
33- Не повертати в response поля типу password_hash; при потребі **@Exclude()** та class-transformer.
34 
35## Робота з БД
36 
37- Єдиний доступ до БД через **PrismaService** (інжекція в сервіси).
38- Складні операції (кілька записів, консистентність) — **транзакції** Prisma.
39- Перевіряти існування сутностей перед оновленням/видаленням (наприклад курс, матеріал, user); 404 якщо не знайдено.
40- Не використовувати Redis у MVP; сесія = JWT + refresh у Postgres.
41