Initial commit

prompts/backend-rules.md

@@ -0,0 +1,88 @@
+# 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`