J5 — Les contrats

L’objectif du jour : ajouter un champ et le voir arriver jusqu’à l’écran, en sachant à chaque étape ce qui est écrit à la main et ce qui est engendré.

Durée réaliste	une demi-journée, exercice compris
Prérequis	J3 — la carte, et le réflexe du ^build

Deux contrats, pas un

Le dépôt en porte deux, et on les confond volontiers :

• packages/schemas — des schémas Zod écrits à la main, partagés par l’API, le web et le solveur. C’est le contrat de validation : mêmes règles des deux côtés du réseau, et des fonctions pures partagées plutôt que dupliquées.
• packages/api-client — un client TypeScript entièrement engendré depuis l’OpenAPI que l’API émet. C’est le contrat de transport : les chemins, les paramètres, les formes de réponse.

Le premier se modifie. Le second se régénère. Rien ne s’écrit à la main sous packages/api-client/src/generated/.

La chaîne que personne ne devine

Elle est déclarée dans turbo.json, et c’est la seule partie du dépôt qui a besoin d’être lue avant d’être comprise :

api#openapi:emit  →  @beemyschool/api-client#generate  →  @beemyschool/api-client#build

En clair :

1. api#openapi:emit démarre l’application NestJS sans écouter de port, construit le document OpenAPI et l’écrit dans apps/api/openapi.json. Il tourne en NODE_ENV=test, ce qui saute les migrations au démarrage : aucune base n’est nécessaire pour engendrer la spécification.
2. generate passe ce fichier à openapi-typescript, qui écrit packages/api-client/src/generated/schema.ts.
3. build compile le paquet, que apps/web consomme.

Le typecheck du client dépend lui aussi de generate — sinon il vérifierait un fichier absent ou périmé.

Ce qu’il faut relancer après un changement de contrat : la chaîne entière, ce que fait bun run build à la racine. Turbo en respecte l’ordre et ne rejoue que ce qui a bougé.

Le raccourci du pro

apps/api/openapi.json et packages/api-client/src/generated/ sont des artefacts. Les modifier à la main fonctionne — jusqu’au prochain build, qui les écrase sans prévenir. Une correction s’y fait toujours en amont : dans le décorateur, le DTO ou le schéma qui les produit.

L’exercice : un champ, de la base à l’écran

Prenez un champ optionnel sur une ressource existante — c’est le meilleur exercice du dépôt, parce qu’il traverse tout sans rien risquer.

1. packages/db/src/schema.ts — ajoutez la colonne, puis bun run --filter @beemyschool/db db:generate et relisez le SQL produit.
2. packages/schemas — ajoutez le champ au schéma Zod de la ressource. Optionnel, pour ne rien casser chez les appelants existants.
3. apps/api — le module concerné : le champ traverse le contrôleur, le service et la réponse.
4. La chaîne — bun run build à la racine. Vérifiez que le champ apparaît bien dans apps/api/openapi.json, puis dans packages/api-client/src/generated/schema.ts.
5. apps/web — affichez-le. Le client typé vous guide : si le champ n’existe pas dans les types, c’est que l’étape 4 n’a pas été rejouée.
6. Les tests — un cas côté API, et bun run typecheck à la racine pour la traversée complète.

Si les six étapes passent, vous savez livrer une fonctionnalité de bout en bout. C’est aussi la première contribution que propose J7.

Le piège du jour

Le web parle à un client engendré, pas à votre API

apps/web ne dépend pas de apps/api — il dépend de @beemyschool/api-client, qui est le reflet de l’OpenAPI au moment de la dernière génération.

Ce que vous observez : votre champ existe dans le DTO, l’API le renvoie — vous l’avez vu dans /docs — et le web refuse de compiler en affirmant que la propriété n’existe pas. L’erreur désigne votre composant, c’est-à-dire le seul fichier innocent de l’histoire.

Comment vous en sortez : relancez la chaîne — bun run build à la racine — et vérifiez la présence du champ dans packages/api-client/src/generated/schema.ts. S’il n’y est pas, remontez : est-il dans apps/api/openapi.json ? Non ? Alors le problème est dans le décorateur ou le DTO, pas dans le web.

Le même piège existe à l’envers, plus sournois : un artefact committé alors qu’il aurait dû être régénéré fait passer la CI sur un contrat qui n’est plus celui de l’API.

Ce qui doit exister à la fin de la journée

• Vous savez distinguer le contrat de validation (schemas) du contrat de transport (api-client)
• Vous savez réciter la chaîne openapi:emit → generate → build et dire ce que produit chaque étape
• Vous savez que la génération de l’OpenAPI ne demande aucune base
• Votre champ d’exercice remonte jusqu’à l’écran
• Vous savez où regarder — openapi.json, puis generated/schema.ts — quand un type manque

Demain

J6 — Le solveur : le seul module du dépôt qui ne soit pas en TypeScript, et le seul dont le contrat est tenu par deux implémentations à la fois.