89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
# Backend Rules
|
|
|
|
The backend remains derived from `domain/*.dsl` inside the existing LLM-first pipeline. No compiler platform or generator engine is introduced.
|
|
|
|
## Backend scaffold baseline
|
|
|
|
- Start backend initialization from the official NestJS CLI workspace, not from manually created files.
|
|
- The backend must remain compatible with standard Nest workspace tooling such as `nest build` and `nest start`.
|
|
- Preserve the core Nest workspace files generated by the CLI, especially:
|
|
- `server/tsconfig.json`
|
|
- `server/tsconfig.build.json`
|
|
- `server/nest-cli.json`
|
|
- `server/src/main.ts`
|
|
- `server/src/app.module.ts`
|
|
- For domain resources, prefer official Nest CLI generation patterns for modules/controllers/services/resources and then adapt the generated code to Prisma and auth requirements.
|
|
- Do not delete required Nest workspace files just because the LLM can inline a smaller custom structure.
|
|
|
|
## Forbidden backend generation patterns
|
|
|
|
- Do not bootstrap `server/` by hand-writing a pseudo-Nest project from memory.
|
|
- Do not remove `tsconfig.json`, `tsconfig.build.json`, or `nest-cli.json` after generation.
|
|
- Do not replace standard Nest package scripts with ad hoc commands that break `nest build` or `nest start`.
|
|
- Do not continue CRUD generation on top of a degraded backend workspace without repairing the workspace first.
|
|
|
|
## Domain-derived output
|
|
|
|
- `domain/*.dsl` is the source of truth for entities, fields, primary keys, foreign keys, and enums.
|
|
- `domain-summary.json` is a derived artifact used to stabilize LLM generation and validation. It must never replace the DSL as the source of truth.
|
|
- Each entity becomes:
|
|
- a Prisma model
|
|
- a NestJS module
|
|
- a controller
|
|
- a service
|
|
- create/update DTOs
|
|
|
|
## DTO and Prisma mapping
|
|
|
|
- `decimal` -> Prisma `Decimal`, DTO/API `string`
|
|
- `date` -> Prisma `DateTime`, DTO/API `string`
|
|
- Enums remain string-valued in DTO/API contracts
|
|
|
|
## CRUD and natural-key invariants
|
|
|
|
- CRUD routes use the real primary key name in the path.
|
|
- Every API record returned to React Admin must include `id`.
|
|
- For entities whose primary key is not `id`, the backend must map the real key to `id`.
|
|
- Natural-key list/sort logic must never build ORM `orderBy` against a fake physical `id`.
|
|
|
|
## Service invariants
|
|
|
|
- Never pass raw update DTOs into Prisma update `data`.
|
|
- Remove `id`, the real primary key, and readonly fields from update payloads before calling Prisma.
|
|
- Keep PrismaService lightweight:
|
|
- extend `PrismaClient`
|
|
- implement `OnModuleInit`
|
|
- call `$connect()`
|
|
- do not use `beforeExit`
|
|
|
|
## Filtering contract
|
|
|
|
- List endpoints must support React Admin query parameters:
|
|
- `_start`, `_end`, `_sort`, `_order`
|
|
- arbitrary field filters from query string
|
|
- `q` for reference autocomplete search
|
|
- String/text search filters may use `contains` with case-insensitive mode.
|
|
- Foreign key filters must use exact-match semantics (no `contains` for FK scalar keys).
|
|
- Enum filters must support both single and repeated query params:
|
|
- `status=Draft`
|
|
- `status=Draft&status=Approved`
|
|
- Repeated enum params must map to Prisma `{ in: [...] }`.
|
|
- Sorting must use real model scalar fields only; natural-key entities must not fallback to fake physical `id`.
|
|
|
|
## Reproducibility invariants
|
|
|
|
- A freshly generated backend must be bootstrappable with ordinary Nest + Prisma commands from `prompts/runtime-rules.md`.
|
|
- Missing TypeScript or Nest workspace config is a generation failure, not an acceptable simplification.
|
|
- The baseline backend should fail only on missing runtime dependencies or env values, not because the Nest workspace itself is incomplete.
|
|
|
|
## Recovery rule if backend workspace degraded
|
|
|
|
- If required Nest scaffold files are missing or broken, restore the official workspace baseline before editing Prisma models, modules, controllers, services, or DTOs.
|
|
- Treat workspace repair as higher priority than feature generation, because generated domain code on top of a broken workspace is invalid baseline output.
|
|
|
|
## Backend auth defaults
|
|
|
|
- `GET` -> `viewer | editor | admin`
|
|
- `POST`, `PATCH`, `PUT` -> `editor | admin`
|
|
- `DELETE` -> `admin`
|