Nicolas
4f509865c1
Le code avait beaucoup évolué depuis la dernière mise à jour de la documentation (sources externes, import de recettes, planning en grille, pages de paramètres, thème, tests Cucumber...) sans que README.md/specs/*.md ne suivent. Tour complet du code (backend + frontend) et réécriture : - specs/batch-cooking-modele.md : schéma de données réécrit depuis schema.prisma (foyer/admin/invitation, sources, catalogue ingrédients/unités, techniques détectées, visibilité des recettes). - specs/backend-architecture.md : foyer, préférences/goûts, planning, référence, sources externes (adaptateurs/registre/sync), matching ingrédients/techniques, isolation base de test, suppression de compte. - specs/frontend-architecture.md : routing complet, sidebar/paramètres, thème, planning + picker, catalogue + import, composants UI partagés, tests Cypress+Cucumber. - specs/batch-cooking-architecture.md : module Import passe de TODO à implémenté. - specs/error-handling.md : liste complète des ~19 codes d'erreur. - README.md : réécriture pour refléter tout ce qui précède, plus la note (dangereusement obsolète) sur le partage base de test/dev — le fix existe déjà (apps/api/.env.test), la doc décrivait encore le bug.
107 lines
4.8 KiB
Markdown
107 lines
4.8 KiB
Markdown
# Architecture technique — Projet Batch-cooking
|
|
|
|
> Documentation de l'architecture serveur/client de l'application.
|
|
|
|
---
|
|
|
|
## Vue d'ensemble
|
|
|
|
L'application repose sur une architecture **client-serveur** classique :
|
|
|
|
- Un **serveur** exposant une **API** (échanges standards) et un canal **websocket** (communication temps réel)
|
|
- Plusieurs **clients** (Client 1, Client 2, Client 3...) connectés simultanément au serveur
|
|
- Une base de données **PostgreSQL**
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph SERVER["Server"]
|
|
API["API (REST)"]
|
|
CALC["Calcul batch-cooking<br/><i>(TODO)</i>"]
|
|
IMPORT["Import d'une recette<br/><i>implémenté</i>"]
|
|
IMP1["Import depuis source<br/>(RecipeSourceAdapter)"]
|
|
IMP2["Traduction en étapes<br/>(ingrédients + techniques)"]
|
|
IMP3["Sauvegarde<br/>(sur ajout au planning, ou revue manuelle)"]
|
|
DB[("Database<br/>PostgreSQL")]
|
|
|
|
IMPORT --> IMP1 --> IMP2 --> IMP3 --> DB
|
|
end
|
|
|
|
C1["Client 1"]
|
|
C2["Client 2"]
|
|
C3["Client 3"]
|
|
|
|
API <--> C1
|
|
API <--> C2
|
|
API <--> C3
|
|
|
|
style SERVER fill:none,stroke:#888,stroke-width:1px
|
|
```
|
|
|
|
*(Le canal websocket envisagé dans la conception d'origine pour le calcul
|
|
batch-cooking temps réel n'existe pas encore — rien à documenter tant que ce
|
|
module reste TODO ; voir la note plus bas.)*
|
|
|
|
---
|
|
|
|
## Composants
|
|
|
|
### API
|
|
Point d'entrée principal pour les échanges entre les clients et le serveur — REST classique, `requireAuth` (cookie JWT httpOnly) sur toute route qui n'est pas une donnée de référence publique. Détail complet des modules : [backend-architecture.md](./backend-architecture.md).
|
|
|
|
### Module « Calcul batch-cooking »
|
|
Logique de calcul du batch-cooking (optimisation du planning/des recettes selon le planning). **Statut : TODO — reste à développer**, avec `packages/shared`'s `assertIsNever` déjà en place comme outil prêt à l'emploi pour ce futur module (voir [backend-architecture.md](./backend-architecture.md#packagesshared--assertisnever)).
|
|
|
|
### Module « Import d'une recette »
|
|
**Statut : implémenté.** Pipeline en trois étapes, comme prévu à la conception :
|
|
|
|
1. **Import depuis source** — chaque source concrète (aujourd'hui : TheMealDB,
|
|
API officielle) implémente le contrat `RecipeSourceAdapter`
|
|
(`apps/api/src/lib/recipe-source-adapter.ts` — `list`/`fetchDetail`/`parse`),
|
|
enregistré dans un registre en mémoire et synchronisé vers la table
|
|
`sources`. Un scraper générique JSON-LD/schema.org (`json-ld-recipe.ts`)
|
|
existe aussi, en briques réutilisables par un futur adaptateur dédié à un
|
|
site précis — volontairement pas lui-même une source sélectionnable.
|
|
2. **Traduction en étapes** — `recipe-translation.ts` orchestre la résolution
|
|
des ingrédients/unités en texte libre contre les catalogues de référence
|
|
(`ingredient-matcher.ts`, anglais uniquement pour l'instant) et la
|
|
détection des techniques (`tech-step-matcher.ts`, matching par expressions
|
|
régulières pondérées, avec résolution des chevauchements).
|
|
3. **Sauvegarde** — persistance en base (`recipe.service.ts`'s
|
|
`createImportedRecipe`), déclenchée soit automatiquement quand un import
|
|
"complet" (aucune ligne à arbitrer) est ajouté au planning, soit après une
|
|
revue manuelle (ingrédients non résolus complétés à la main).
|
|
|
|
Détail complet du flux (endpoints, algorithmes, décisions produit) :
|
|
[backend-architecture.md](./backend-architecture.md#sources-externes--adaptateur-registre-synchronisation)
|
|
côté API, [frontend-architecture.md](./frontend-architecture.md#recettes--catalogue-favoris-import-depuis-une-source-externe)
|
|
côté web.
|
|
|
|
### Database (PostgreSQL)
|
|
Stockage de l'ensemble des données de l'application (voir
|
|
[batch-cooking-modele.md](./batch-cooking-modele.md) pour le détail des
|
|
tables — le modèle a beaucoup grandi par rapport à la conception d'origine :
|
|
sources externes, catalogue d'ingrédients/unités normalisé, techniques
|
|
détectées, favoris, visibilité des recettes).
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Le module de calcul batch-cooking (et la « Liste de courses », son
|
|
débouché naturel — `ShoppingListPage` reste un stub côté web) est le
|
|
principal chantier restant côté serveur.
|
|
- Le canal websocket envisagé pour la communication temps réel n'a pas encore
|
|
été construit — rien ne le remplace aujourd'hui (pas de polling), à
|
|
reconsidérer au moment d'attaquer le calcul batch-cooking.
|
|
|
|
---
|
|
|
|
## Documents liés
|
|
|
|
Documentation d'implémentation (ajoutée au fil des features, complète ce document
|
|
conceptuel sans le remplacer) :
|
|
|
|
- [batch-cooking-modele.md](./batch-cooking-modele.md) — schéma de données complet
|
|
- [backend-architecture.md](./backend-architecture.md) — organisation d'`apps/api` (modules, sources, matching)
|
|
- [frontend-architecture.md](./frontend-architecture.md) — organisation d'`apps/web`
|
|
- [error-handling.md](./error-handling.md) — contrat d'erreurs partagé entre l'API et le client
|