# Backend Rules

<!-- prompt-version: 2.0 -->
<!-- applies-to: server/src/modules/, server/src/app.module.ts -->
<!-- validated-by: tools/validate-generation.mjs §validateApiDslCoverage §validateNaturalKeyChecks -->

Use this document during the **Backend** stage defined in `prompts/general-prompt.md`.

## Purpose

Generate NestJS CRUD artifacts that match the DSL contract exactly and remain compatible with a standard NestJS workspace.

## Mandatory Inputs

- `prompts/general-prompt.md`
- the active `api API.<Entity>` block from `domain/toir.api.dsl`
- referenced DTOs and enums from `domain/toir.api.dsl`
- an intact or repaired official NestJS scaffold under `server/`

`api-summary.json` may be consulted only as an auxiliary inventory or validator-related artifact. It must never replace the DSL as the backend source of truth.

## Expected Outputs

Per entity:

- `server/src/modules/<kebab>/<kebab>.module.ts`
- `server/src/modules/<kebab>/<kebab>.controller.ts`
- `server/src/modules/<kebab>/<kebab>.service.ts`
- `server/src/modules/<kebab>/dto/create-<kebab>.dto.ts`
- `server/src/modules/<kebab>/dto/update-<kebab>.dto.ts`

Repository-wide:

- `server/src/app.module.ts` registrations

## Scaffold Baseline

- Start backend initialization and repair from the official NestJS CLI workspace, not from hand-written files.
- Preserve Nest workspace essentials:
  - `server/tsconfig.json`
  - `server/tsconfig.build.json`
  - `server/nest-cli.json`
  - `server/src/main.ts`
  - `server/src/app.module.ts`
- If the workspace is degraded, repair it before generating domain code.

Forbidden patterns:

- hand-written pseudo-Nest scaffolds
- deleting required Nest config files after generation
- replacing normal Nest build/start behavior with ad hoc scripts

## Route And Resource Contract

- Use the shared entity-to-resource naming convention from `prompts/general-prompt.md`.
- Each entity becomes a NestJS module, controller, service, and create/update DTO pair.
- CRUD routes use the real primary key name in the path.
- Every API record returned to React Admin must include `id`.
- For natural-key entities, map the real primary key to `id` in responses and sort translation.

## DTO Contract

- `DTO.<Entity>Create` defines `Create<Entity>Dto`.
- `DTO.<Entity>Update` defines `Update<Entity>Dto`.
- Do not invent fields or pull field lists from memory.
- Never include `id` in Create/Update DTOs.

Type and decorator rules:

| DSL type  | TS DTO type | class-validator decorator | Notes |
|-----------|-------------|---------------------------|-------|
| `uuid`    | `string`    | `@IsUUID()`               |       |
| `string`  | `string`    | `@IsString()`             |       |
| `text`    | `string`    | `@IsString()`             |       |
| `integer` | `number`    | `@IsInt()`                |       |
| `number`  | `number`    | `@IsNumber()`             |       |
| `decimal` | `string`    | `@IsString()`             | serialize with Prisma Decimal |
| `date`    | `string`    | `@IsString()`             | serialize as ISO string |
| `boolean` | `boolean`   | `@IsBoolean()`            |       |
| enum name | `string`    | `@IsEnum(EnumName)`       |       |

Nullability rules:

- every field that is not `is required` gets `@IsOptional()` before the type decorator
- every generated DTO imports from `'class-validator'`

## Controller Contract

- Apply `@UseGuards(JwtAuthGuard, RolesGuard)` at controller class level.
- Roles per verb:
  - `GET` -> `viewer | editor | admin`
  - `POST`, `PATCH`, `PUT` -> `editor | admin`
  - `DELETE` -> `admin`
- Reconcile DSL HTTP shapes for repository compatibility:
  - list endpoints declared as `POST .../page` generate as `@Get()` with React Admin query params
  - update endpoints declared as `PUT` generate as `@Patch(':<pk>')`
- Path parameters are taken from the DSL endpoint contract, not invented from generic CRUD memory.

## Service Contract

- Never pass raw update DTOs directly into Prisma update `data`.
- Strip `id`, the real primary key, and readonly fields before writes.
- Keep `PrismaService` lightweight:
  - extend `PrismaClient`
  - implement `OnModuleInit`
  - call `$connect()`
  - do not add `beforeExit`

List endpoint requirements:

- accept React Admin query params: `_start`, `_end`, `_sort`, `_order`, `q`
- set `Content-Range`
- set `Access-Control-Expose-Headers: Content-Range`

Filtering rules:

- string/text filters may use case-insensitive `contains`
- foreign-key scalar filters must use exact-match semantics
- enum filters must support both single and repeated params
- repeated enum params must map to Prisma `{ in: [...] }`
- `_sort=id` must map to the real primary key for natural-key entities

Decimal and date handling:

- `decimal` writes: `new Prisma.Decimal(value)`
- `decimal` reads: `.toString()`
- `date` writes: `new Date(value)`
- `date` reads: `.toISOString()`

## Natural-Key Rules

For entities whose physical primary key is not `id`:

- route params use the real primary key name
- responses expose `id` mapped from that primary key
- sort/update behavior never targets a fake physical `id`
- update payload sanitization removes both `id` and the real primary key

## Completion Expectations

Backend generation is incomplete if any of the following is true:

- required Nest scaffold files are missing
- DTO decorators are incomplete or type-incorrect
- controllers are missing guards or role decorators
- natural-key handling regresses to a fake physical `id`
- list/filter behavior is incompatible with React Admin expectations