KIS-TOiR/generation/post-generation-validation.md

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.