b90817b8e1
* Add project specs, gitignore the source PDF specs/batch-cooking-architecture.md and specs/batch-cooking-modele.md are the clean markdown transcription of "Projet batch cooking.pdf" (a scanned/image-only PDF, no extractable text). The PDF itself is gitignored — source working document, not meant to be committed. * Add Prisma schema for the documented data model Models every table from specs/batch-cooking-modele.md: users/household (user_profiles, house, diet, allergy, category), planning (planning, planning_item), and recipes (recipe, ingredients, step, tech_step, tech_step_mapping, sources). Two deliberate deviations from the literal spec doc, per project discussion: - recipe_ingredient (recipe <-> ingredients) carries quantity + unit. The spec describes a plain many-to-many with no extra fields, but a shopping list / batch-cooking calculation needs quantities. - step is modeled one-to-many from recipe (not many-to-many as labeled in the doc): the documented `order` column only makes sense scoped to a single recipe, which isn't reconcilable with steps being shared across recipes. Everything else follows the doc as-is, including field nullability choices made where the doc doesn't specify (e.g. user_profiles.house_id optional, recipe.source_id optional) and onDelete behavior (Cascade for owned child records, SetNull for optional references) — first draft, not meant as final production hardening. Verified: `prisma validate`, `prisma generate`, and a real `prisma migrate dev` against a local Postgres (via docker-compose) — the migration applies cleanly and produces the expected schema. README: documents the migrate command and a Postgres port-conflict gotcha hit during validation (a native Postgres service on this machine was already bound to 5432, intercepting the Docker container's connections). * Add COMMENT ON for every table and column in the init migration Descriptions pulled from specs/batch-cooking-modele.md's per-table field tables. The two tables not in the original spec (join tables recipe_ingredient, user_profile_allergy) get a comment explaining why they exist. Amends the still-unmerged init migration directly rather than adding a follow-up migration, since it hasn't been applied anywhere but this local dev database. Verified: `prisma migrate reset --force` reapplies cleanly, and a query against pg_description confirms every column of every project table has a comment (only Prisma's own internal _prisma_migrations table is uncommented, out of scope).
114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# batchCooking
|
|
|
|
## Structure
|
|
|
|
Monorepo pnpm workspaces :
|
|
|
|
- `apps/api` — backend Express/TypeScript (squelette générique : healthcheck, config env, Prisma non modélisé, tests Mocha + Cucumber/BDD)
|
|
- `apps/web` — frontend React/Vite/TypeScript (squelette générique, prêt à être embarqué par Capacitor plus tard)
|
|
- `packages/shared` — code partagé entre `api` et `web` (types, schémas de validation, constantes) — vide pour l'instant
|
|
|
|
Aucun module métier n'est encore implémenté : cette base ne contient que l'outillage générique (lint/format, tests, CI, DB locale).
|
|
|
|
## Prérequis
|
|
|
|
- Node.js 22 (voir `.nvmrc`)
|
|
- pnpm 10 (`corepack enable` puis `corepack use pnpm@10.12.4`, ou installation manuelle)
|
|
- Docker (pour Postgres en local)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pnpm install
|
|
cp .env.example .env
|
|
cp apps/api/.env.example apps/api/.env
|
|
```
|
|
|
|
Puis **édite ces deux `.env`** pour renseigner de vrais `POSTGRES_USER`/`POSTGRES_PASSWORD`
|
|
(et la `DATABASE_URL` correspondante dans `apps/api/.env`) : les fichiers `.env.example`
|
|
ne contiennent volontairement aucun identifiant réel (juste `changeme`), et
|
|
`docker-compose.yml` refuse de démarrer tant que `POSTGRES_USER`/`PASSWORD`/`DB` ne
|
|
sont pas définis dans `.env` — pas de valeur par défaut en dur dans les fichiers commités.
|
|
|
|
### Cypress : téléchargement du binaire
|
|
|
|
`pnpm install` installe le package `cypress` mais **pas forcément son binaire** (le
|
|
téléchargement du `.exe`/binaire natif peut être ignoré selon l'environnement où
|
|
`pnpm install` a été lancé — ex. un environnement sandboxé/CI dont le cache ne
|
|
correspond pas à celui de ta machine). Si `pnpm --filter web e2e` échoue avec une
|
|
erreur du type :
|
|
|
|
```
|
|
No version of Cypress is installed in: ...\AppData\Local\Cypress\Cache\...
|
|
Please reinstall Cypress by running: cypress install
|
|
```
|
|
|
|
lance simplement, depuis ta machine :
|
|
|
|
```bash
|
|
pnpm --filter web exec cypress install
|
|
```
|
|
|
|
(à faire une seule fois par machine ; le binaire est mis en cache localement,
|
|
hors du repo).
|
|
|
|
## Développement
|
|
|
|
```bash
|
|
# Base de données Postgres locale
|
|
docker compose up -d
|
|
|
|
# Applique le schéma (première fois / après un changement de prisma/schema.prisma)
|
|
pnpm --filter api exec prisma migrate dev
|
|
|
|
# Backend (http://localhost:3000)
|
|
pnpm dev:api
|
|
|
|
# Frontend (http://localhost:5173)
|
|
pnpm dev:web
|
|
```
|
|
|
|
> **Conflit de port possible sur `5432`** : si tu as déjà un Postgres natif installé
|
|
> sur ta machine (service Windows, Homebrew, etc.), il peut occuper le port 5432 et
|
|
> intercepter les connexions à la place du conteneur Docker (symptôme : Prisma
|
|
> renvoie `P1000: Authentication failed` alors que les identifiants sont corrects).
|
|
> Dans ce cas, mets `POSTGRES_PORT=5433` (ou autre) dans ton `.env` **et** adapte le
|
|
> port dans la `DATABASE_URL` de `apps/api/.env`.
|
|
|
|
## Qualité / Tests
|
|
|
|
```bash
|
|
pnpm lint # Biome (lint + format check)
|
|
pnpm lint:fix # Biome --write
|
|
pnpm test # tests unitaires/intégration (Mocha, apps/api)
|
|
pnpm --filter api test:bdd # tests d'intégration BDD (Cucumber/Gherkin, apps/api)
|
|
pnpm --filter web e2e # tests e2e (Cypress, démarre le serveur dev automatiquement)
|
|
pnpm build # build de tous les workspaces
|
|
```
|
|
|
|
La CI GitHub Actions (`.github/workflows/ci.yml`) exécute lint + tests + build sur chaque push/PR vers `main`, puis les tests e2e Cypress.
|
|
|
|
### Cucumber (apps/api)
|
|
|
|
Tests d'intégration lisibles en Gherkin, en complément de Mocha (qui reste pour les
|
|
tests unitaires purs) :
|
|
|
|
- `apps/api/features/*.feature` — scénarios en Given/When/Then (`health.feature` sert
|
|
d'exemple)
|
|
- `apps/api/features/step-definitions/*.steps.ts` — implémentation des steps
|
|
- `apps/api/features/support/world.ts` — contexte partagé entre les steps d'un
|
|
scénario (instancie l'app Express in-process via `createApp()`, comme le fait déjà
|
|
supertest côté Mocha — pas besoin de lancer un vrai serveur)
|
|
- `apps/api/cucumber.cjs` — config (extension `.cjs` volontaire, voir la remarque
|
|
TypeScript/ESM ci-dessous)
|
|
|
|
Pour ajouter un scénario : écrire le `.feature`, lancer `pnpm --filter api test:bdd`,
|
|
implémenter les steps manquants (Cucumber affiche des snippets tout prêts pour ceux
|
|
qui n'existent pas encore).
|
|
|
|
> **Piège TypeScript/ESM à connaître** (déjà rencontré avec `cypress.config.ts`) :
|
|
> les fichiers de config d'outils tiers qui font du chargement dynamique de TS
|
|
> (`cucumber.cjs`, `cypress.config.ts`…) sont sensibles au `"type": "module"` du
|
|
> `package.json`. `cucumber.cjs` évite le problème *pour sa propre config* en étant
|
|
> explicitement CommonJS ; les steps/world restent en `.ts` ESM classique et sont
|
|
> chargés via `tsx` (`NODE_OPTIONS=--import=tsx`, voir le script `test:bdd`).
|