Garder le backend et le frontend d’une app de génération synchronisés via OpenAPI

## Régénérer les types et clients OpenAPI après chaque changement d’API du backend Après chaque modification d’une API du backend, exécutez la commande de mise à jour OpenAPI du dépôt. Traitez le schema généré et les types du frontend comme des éléments de la même modification, et non comme un nettoyage ultérieur. Le code du frontend doit appeler les endpoints du backend au moyen du client OpenAPI généré. N’ajoutez pas d’adaptateurs de service écrits à la main qui dupliquent les contrats générés de requête et de réponse. Séparez strictement les responsabilités du backend : - la couche API analyse les entrées, effectue l’authentification et l’autorisation, puis organise les réponses ; - la couche service prend en charge les règles métier, les transitions d’état et l’orchestration des données. Placez les contrats de génération transversaux, notamment les DTO d’entrée et de sortie et la configuration des fournisseurs, dans un module contracts partagé. Les modules task doivent contenir l’encapsulation, la répartition et l’orchestration de l’exécution des tâches, et non des définitions de DTO partagés. Les modules integration peuvent dépendre des contracts partagés, mais ne doivent pas dépendre des modules de types internes à task. Lorsqu’une API, un type ou un modèle d’état change, mettez à jour ensemble l’implémentation du backend, le document OpenAPI, les types générés du frontend, l’utilisation du client et la documentation directement concernée. ## Commenter chaque fonction et séparer dans la documentation les faits actuels des projets futurs Lorsqu’un style du frontend est répété plus d’une fois, privilégiez un composant réutilisable ou une structure de styles partagée plutôt qu’une nouvelle copie. Chaque fonction, classe ou bloc de code comparable doit comporter un commentaire expliquant ce qu’il fait et pourquoi il existe. Une logique complexe doit aussi documenter les paramètres pertinents, le comportement du retour et les décisions internes essentielles. Maintenez les commentaires synchronisés avec l’implémentation. Classez la documentation avant de l’écrire : - `guide` explique comment accomplir une tâche ou intégrer une capacité ; - `architecture` décrit le système actuellement implémenté ; - `plans` décrit les travaux futurs, les tâches échelonnées et les changements proposés ; - `reference` contient des faits stables destinés à la consultation ; - `blog` contient les notes de version. Placez les limites actuelles, les transitions d’état implémentées et le comportement réel dans la documentation architecture. Placez dans plans les travaux encore en conception ou en cours d’exécution. Placez les procédures d’exploitation et les flux de développement dans guide. Ne mélangez pas les faits actuels et les intentions futures dans un seul document pratique. Séparez-les entre architecture et plans, même lorsqu’ils concernent le même sujet. Ne modifiez pas une note de version historique finalisée, sauf si la tâche l’exige explicitement. ## Garder le centre de tâches léger et donner à chaque écran du flux son propre rôle Répartissez le flux principal de l’utilisateur entre des interfaces aux responsabilités claires : - une page de préparation extrait les données métier, confirme les éléments candidats, corrige les informations de base et fait passer l’élément à `ready` ; - un espace de génération vérifie l’état de préparation de la sortie, gère les ressources et paramètres essentiels, lance la génération et présente les résultats ; - un centre de tâches affiche uniquement des informations légères et génériques, telles que l’état, la progression, la réussite, l’échec, l’annulation et un lien de retour. Ne placez pas de résumés propres au domaine, de contexte de débogage des invites, de correspondances de ressources ni d’autres détails volumineux dans le centre de tâches générique. Conservez-les dans le panneau de préparation, de génération, d’exécution ou de diagnostic approprié. Si les outils d’extraction restent disponibles dans l’espace de génération, présentez-les uniquement comme des raccourcis ou des outils de diagnostic. Ils ne doivent pas remplacer la page de préparation comme interface principale de confirmation. Lorsqu’une limite de responsabilité change, mettez à jour à la fois l’UI concernée et la documentation architecture. La refonte du centre de tâches ne doit pas le transformer en une nouvelle page de détails métier. ## Réserver le statut de l’élément à la confirmation, pas à l’avancement de la génération Utilisez l’état principal de l’élément métier uniquement pour représenter l’état de confirmation des informations : - `pending` signifie qu’un travail d’extraction ou de confirmation reste à accomplir ; - `ready` signifie que les informations requises sont confirmées et que la préparation en aval peut commencer. N’utilisez pas cet état pour représenter la génération pendant l’exécution. Les valeurs comme `generating` appartiennent au système de tâches et au résumé d’exécution. Représentez l’état de préparation de la sortie comme une dimension distincte. Le fait qu’un élément soit `ready` pour la préparation en aval ne garantit pas que toutes les conditions de génération sont remplies. Chaque interface utilisateur doit distinguer : 1. l’état de confirmation des informations ; 2. l’état de la tâche pendant l’exécution ; 3. l’état de préparation à la génération de la sortie. Lorsque la sémantique des états change, synchronisez le comportement du backend, OpenAPI, les types générés du frontend, les libellés d’état, les conditions de navigation et la documentation de développement. ## Mener l’utilisateur de la page de préparation à l’espace de génération après confirmation Le flux standard est le suivant : 1. extraire les éléments de travail du contenu source ; 2. confirmer et corriger, sur la page de préparation, les ressources, les dialogues ou les autres informations requises qui ont été extraits ; 3. passer à l’espace de génération pour vérifier les ressources principales, les documents de référence, les paramètres de sortie et l’état de préparation ; 4. lancer la génération depuis l’espace de génération ; 5. examiner les résultats dans l’espace métier tout en utilisant le centre de tâches uniquement pour la progression générique. La page de préparation prend en charge l’extraction, la confirmation et la correction. L’espace de génération prend en charge la préparation et l’exécution de la génération ainsi que l’examen des résultats. Une fois la préparation réussie, dirigez clairement l’utilisateur vers l’espace de génération. Si cet espace constate qu’un élément n’est pas `ready`, renvoyez l’utilisateur vers la préparation avec une explication claire. Donnez la priorité à ce flux lors de la modification des interactions. Les raccourcis pratiques ne doivent ni masquer l’étape canonique suivante ni fusionner la préparation et la génération dans une interface ambiguë. ## Mettre à jour les documents architecture à chaque changement et donner des étapes de migration utilisables dans les notes de version La documentation architecture ne contient que le comportement actuellement réel. Plans contient les travaux en cours, les tâches échelonnées, les priorités et les futurs chemins d’exécution. Lorsque le comportement du code, la sémantique des états ou les responsabilités d’une page changent, mettez à jour la documentation architecture dans le même travail. Lorsque la portée, la priorité ou l’ordre d’un plan change, mettez à jour plans. Un plan implémenté doit passer dans architecture ou devenir une note de version. Considérez comme incomplet tout travail qui laisse la documentation architecture ou plans obsolète. Les notes de version doivent inclure des métadonnées initiales pour `title`, `date`, `description`, `tags` et `authors`. Utilisez un ordre de sections stable et omettez uniquement les sections sans objet : 1. Points forts ; 2. Ajouts, modifications et corrections ; 3. Changements incompatibles et abandons annoncés ; 4. Sécurité et problèmes connus ; 5. Guide de migration et instructions de retour en arrière ; 6. Matrice de compatibilité, commandes de validation et liste de mise à niveau ; 7. Références, notes pour les contributeurs et remerciements. Rédigez les notes de version avec la voix de l’équipe de maintenance : présentez d’abord les conclusions et les informations exécutables, utilisez des paragraphes courts et des listes, et conservez une terminologie stable. Séparez clairement les nouvelles capacités, les changements de comportement, les risques de compatibilité et les problèmes connus. Les étapes de migration, les étapes de retour en arrière et les commandes de validation doivent être directement utilisables et non vagues. ## Ne terminer que lorsque les types générés et la documentation concordent avec le code Le travail n’est terminé que lorsque toutes les conditions applicables sont remplies : 1. l’implémentation est présente, sans marqueurs provisoires évidents ni résidus de compatibilité obsolètes ; 2. les fonctions et classes nouvelles ou modifiées comportent des commentaires précis et utiles ; 3. les modifications d’API ont mis à jour OpenAPI, les types générés du frontend et l’utilisation du client généré ; 4. le comportement actuel apparaît dans la documentation architecture et les travaux futurs dans plans ; 5. les responsabilités de la préparation, de la génération et du centre de tâches restent distinctes ; 6. les modifications du frontend réussissent la vérification TypeScript sans émission du dépôt ; 7. les modifications du backend réussissent les tests pertinents ou, au minimum, les vérifications documentées de syntaxe et d’importation ; 8. le rapport d’achèvement indique ce qui a changé et quelles vérifications ont réussi ; 9. les travaux restants ou les recommandations ultérieures sont énumérés séparément. Ne déclarez pas le travail terminé tant que le code, les contrats, les types générés, la documentation, la sémantique des états ou les interfaces du flux de travail sont incohérents.