161 lines
7.7 KiB
Markdown
161 lines
7.7 KiB
Markdown
# Post-Generation Validation
|
|
|
|
After generating the backend or fullstack application, run these checks to ensure the project will run without runtime errors.
|
|
|
|
---
|
|
|
|
# Validation Checklist
|
|
|
|
## 1. Environment file
|
|
|
|
- [ ] **`.env` exists** in the backend root (e.g. `server/.env`).
|
|
- [ ] **`.env.example` exists** with at least `DATABASE_URL` and a placeholder value.
|
|
- [ ] **`DATABASE_URL`** is present in `.env` (or documented in `.env.example` so the user can copy and set it).
|
|
|
|
**Failure symptom:** `Environment variable not found: DATABASE_URL` at startup.
|
|
|
|
---
|
|
|
|
## 2. PrismaService implementation
|
|
|
|
- [ ] A **PrismaService** (or equivalent) class exists and extends `PrismaClient`.
|
|
- [ ] It implements **`OnModuleInit`** and calls **`await this.$connect()`** in `onModuleInit()`.
|
|
- [ ] It does **not** use **`this.$on('beforeExit', ...)`** or any `beforeExit` hook.
|
|
|
|
**Failure symptom:** Deprecation/runtime errors in Prisma 5 when using `beforeExit`.
|
|
|
|
**Reference:** `backend/prisma-service.md`
|
|
|
|
---
|
|
|
|
## 3. Prisma client lifecycle
|
|
|
|
- [ ] **`package.json`** includes a script that runs Prisma client generation:
|
|
- Either **`"postinstall": "prisma generate"`** (or `npx prisma generate`),
|
|
- Or clear documentation to run **`npx prisma generate`** after install.
|
|
- [ ] After schema generation or change, **`npx prisma generate`** has been run (or will run via postinstall).
|
|
|
|
**Failure symptom:** `Cannot find module '@prisma/client'` or missing types at build/run.
|
|
|
|
---
|
|
|
|
## 4. Database migration
|
|
|
|
- [ ] **Migration workflow** is documented (e.g. in README or generation docs).
|
|
- [ ] Instruction to run **`npx prisma migrate dev`** (or `prisma migrate deploy` for production) after first generation or schema change.
|
|
- [ ] Generation pipeline (see `generation/backend-generation.md`) includes or documents the migration step.
|
|
|
|
**Failure symptom:** Tables do not exist; Prisma errors on first query.
|
|
|
|
---
|
|
|
|
## 5. REST route parameters
|
|
|
|
- [ ] For each entity, path parameters use the **correct primary key name** from the DSL.
|
|
- [ ] **Entity with PK `id` (uuid):** routes use **`/:id`** (e.g. `GET /equipment/:id`, `PATCH /equipment/:id`).
|
|
- [ ] **Entity with non-`id` primary key (e.g. `code`):** routes use **`/:code`** (or the actual PK attribute name), e.g. `GET /equipment-types/:code`, **not** `GET /equipment-types/:id`.
|
|
|
|
**Example:**
|
|
|
|
| Entity | Primary key | Correct path | Incorrect path |
|
|
| ------------- | ----------- | ---------------------- | -------------------- |
|
|
| Equipment | id | /equipment/:id | — |
|
|
| EquipmentType | code | /equipment-types/:code | /equipment-types/:id |
|
|
| RepairOrder | id | /repair-orders/:id | — |
|
|
|
|
**Failure symptom:** Controller expects `params.id` but route is defined with `:code`; or vice versa; 404 or wrong resource updated.
|
|
|
|
**Reference:** `backend/architecture.md` — API path rules for non-id primary keys.
|
|
|
|
---
|
|
|
|
## 6. DTO type mapping (serialization)
|
|
|
|
- [ ] **DSL `decimal`** → In DTO/API response, use **`string`** (or a type that serializes to string), not Prisma `Decimal`, to avoid JSON serialization issues.
|
|
- [ ] **DSL `date`** → In DTO/API response, use **`string`** (ISO 8601) or ensure DateTime is serialized to string, so React Admin and JSON consumers receive a string.
|
|
|
|
**Reference:** `backend/prisma-rules.md` — DTO type mapping table.
|
|
|
|
---
|
|
|
|
## 7. React Admin ID field in API responses
|
|
|
|
- [ ] **Every API response object** (list items and single-resource GET) contains a field named **`id`**.
|
|
- [ ] If the entity primary key is **not** named `id`, the response must **map** the primary key to `id`: e.g. `id: record.code` for EquipmentType, so the payload includes both `id` and `code` (or at least `id` with the PK value).
|
|
- [ ] The `id` field value must be the **primary key value** (string or uuid as appropriate).
|
|
|
|
**Failure symptom:** React Admin fails to identify records, breaks cache/references, or throws when expecting `record.id`.
|
|
|
|
**Reference:** `frontend/react-admin-rules.md` — React Admin ID Field Requirement.
|
|
|
|
---
|
|
|
|
## 8. Update payload sanitization (service layer)
|
|
|
|
- [ ] **Update endpoint must not pass `id` (or primary key) in Prisma `data`.** The service must sanitize the incoming DTO before calling `prisma.*.update({ where, data })`: remove `id`, remove the entity primary key field (e.g. `code`), and remove any readonly attributes. Only updatable fields should be passed as `data`.
|
|
- [ ] Generated update methods follow the pattern from **backend/service-rules.md** (e.g. `const { id, code, ...data } = dto` then pass `data` to Prisma).
|
|
|
|
**Failure symptom:** Prisma throws when `data` contains `id` or another field that is not on the model or not writable (e.g. entity with PK `code` receives body with `id` from React Admin).
|
|
|
|
**Reference:** `backend/service-rules.md`
|
|
|
|
---
|
|
|
|
## 9. Database runtime (docker-compose)
|
|
|
|
- [ ] **`docker-compose.yml` exists** at the project root (or documented location).
|
|
- [ ] It defines a **PostgreSQL** service with image (e.g. `postgres:16`), port `5432`, and credentials/DB name matching `DATABASE_URL` in `server/.env`.
|
|
- [ ] **Database container starts:** `docker compose up -d` runs without error and the container is reachable on the configured port.
|
|
|
|
**Failure symptom:** `PrismaClientInitializationError P1001: Can't reach database server at localhost:5432`.
|
|
|
|
**Reference:** `backend/database-runtime.md`
|
|
|
|
---
|
|
|
|
## 10. Migrations and seed
|
|
|
|
- [ ] **`npx prisma migrate dev`** runs successfully from `server/` when the database is up (schema is applied or created).
|
|
- [ ] **Seed script** exists at `server/prisma/seed.ts` (or equivalent) and creates minimal sample data (e.g. one EquipmentType, one Equipment, one RepairOrder).
|
|
- [ ] **`npx prisma db seed`** runs without error (package.json has `prisma.seed` configured and seed runner installed).
|
|
|
|
**Reference:** `backend/seed-rules.md`, `generation/runtime-bootstrap.md`
|
|
|
|
---
|
|
|
|
## 11. Health endpoint
|
|
|
|
- [ ] Backend exposes **GET /health** (or equivalent health route).
|
|
- [ ] **API responds to /health:** With backend running, `GET http://localhost:<port>/health` returns HTTP 200 and a body such as `{ "status": "ok" }`.
|
|
|
|
**Reference:** `backend/architecture.md` — Health Endpoint
|
|
|
|
---
|
|
|
|
# Summary Table
|
|
|
|
| Check | Required artifact / rule |
|
|
| ------------------- | ---------------------------------------------- |
|
|
| .env | File exists with DATABASE_URL |
|
|
| DATABASE_URL | Present in .env or .env.example |
|
|
| PrismaService | OnModuleInit + $connect(); no beforeExit |
|
|
| prisma generate | postinstall script or documented step |
|
|
| Migration | Documented step: prisma migrate dev |
|
|
| REST path params | Use entity PK name (:id or :code, etc.) |
|
|
| Decimal/Date in DTO | Map to string for serialization |
|
|
| API response `id` | Every record has `id`; if PK ≠ id, map PK → id |
|
|
| Update payload | Service strips `id`, PK, readonly from data before Prisma |
|
|
| docker-compose.yml | Exists at project root; PostgreSQL service |
|
|
| Database container | Starts with `docker compose up -d` |
|
|
| prisma migrate dev | Runs successfully from server/ |
|
|
| Seed script | Exists; prisma db seed runs |
|
|
| GET /health | Backend responds with 200 and status payload |
|
|
|
|
---
|
|
|
|
# Integration with generation pipeline
|
|
|
|
1. **Backend generation** (see `generation/backend-generation.md`) should produce artifacts that satisfy the above by default.
|
|
2. After generation, run this checklist manually or via a script that parses generated code and config.
|
|
3. If any check fails, the AI context or generator should be updated so that future runs pass.
|