tomozard/agent-skills

Guide des Patrons de Conception Fullstack

Utilisez cette compétence pour conseiller, architecturer et refactoriser des systèmes fullstack de bout en bout. Appliquez les patrons strictement pour résoudre une friction architecturale identifiable, et non pour une abstraction spéculative.

Principes Fondamentaux

1. Sélection axée sur le problème : N'introduisez jamais un patron de conception sans une friction architecturale explicite ou un code smell (ex. : prop drilling, composants god gonflés, couplage API serré, logique non testable, pannes réseau en cascade).
2. Limites architecturales claires : Maintenez des frontières nettes entre :
   • Vue / Présentation : Composants déclaratifs et passifs pilotés par les props.
   • État client & Interaction : Hooks headless, stores centralisés et mise en cache de l'état serveur.
   • Couche API / Contrat : Schémas typés, adaptateurs DTO et couches anti-corruption.
   • Domaine & Accès aux données : Règles métier découplées et accès aux données via Repository.
3. Évitez la sur-ingénierie : N'appliquez pas d'abstractions d'entreprise complexes (comme les micro-frontends, CQRS ou pub/sub distribué) à de simples pages CRUD ou applications web standard.

---

Matrice de Décision des Patrons & Heuristiques de Déclenchement

Couche	Symptôme / Friction dans la base de code	Patron Recommandé	Limite Architecturale
Frontend UI	Composant god mélangeant récupération API, mise en forme et mise en page JSX	Conteneur / Présentation	Séparer le rendu UI de la récupération de données
Frontend UI	Style étroitement couplé à l'intérieur de composants interactifs (modales, menus déroulants)	Composant Headless / Hooks personnalisés	Isoler l'état et la logique de clavier/interaction
Frontend UI	API de composants rigides nécessitant des sous-éléments flexibles	Composants Composés	Partage d'état déclaratif parent-enfant (ex. : Onglets, Select)
Frontend UI	Prop drilling profond ou états UI multi-composants désynchronisés	Observateur / Store (Zustand/Redux/Context)	Centraliser l'état client partagé
Fullstack API	Les changements de schéma de l'API backend cassent les composants UI frontend	Pattern Adaptateur (Data Mapper)	Couche Anti-Corruption traduisant le DTO en ViewModel
Fullstack API	L'interface utilisateur attend sur des réseaux lents avant de confirmer l'action utilisateur	UI Optimiste avec Rollback	Réponse UI immédiate soutenue par un rollback transactionnel
Backend	Appels SQL/ORM dispersés dans les gestionnaires de routes ou les services	Pattern Repository	Découpler les requêtes de persistance des règles métier
Backend	Instanciation de différents SDK tiers utilisant un if-else en ligne	Pattern Factory	Centraliser la création d'objets et de clients
Backend	if-else / switch en cascade pour le calcul de prix, l'authentification ou les algorithmes	Pattern Stratégie	Encapsuler des algorithmes interchangeables derrière une interface
Backend / Distribué	Action métier principale déclenchant 5+ effets secondaires non liés	Observateur / Piloté par événements (Pub/Sub)	Découpler les effets secondaires via des événements de domaine ou des files d'attente de messages
Backend / Distribué	Latence de l'API externe provoquant une famine de threads et des temps d'arrêt en cascade	Circuit Breaker	Échec rapide, réponse de repli et sondage de santé en aval

---

Plongée en profondeur : Patrons Fullstack & Règles d'Implémentation

1. Frontend : Patron Conteneur / Présentation

• Contexte : Composants dépassant 200 lignes en combinant useEffect, requêtes, transformations de données et JSX de mise en page.
• Règles :
  • Composant de Présentation : Reçoit les données et les callbacks uniquement via les props ; pur, facilement testable dans Storybook sans mocks API.
  • Conteneur (ou Hook de Page) : Récupère les données serveur, gère les états de chargement/erreur et transmet les données transformées vers le bas.

2. Frontend : Patron Composant Headless & Hook Personnalisé

• Contexte : Comportements interactifs complexes (autocomplétion, assistants multi-étapes, accordéon) nécessitant une réutilisation à travers différents designs visuels.
• Règles :
  • Extrayez l'état, les gestionnaires de clavier et les attributs ARIA dans un hook personnalisé headless (ex. : useAutocomplete, useDisclosure).
  • Gardez le style et le balisage DOM entièrement entre les mains du consommateur.

3. Frontend : Composants Composés

• Contexte : Composants avec des sous-parties profondément liées nécessitant un état interne cohérent sans passer des dizaines de props de configuration.
• Règles :
  • Exploitez le Contexte React pour communiquer implicitement entre parent et enfant (<Accordion><Accordion.Item /><Accordion.Panel /></Accordion>).

4. Intégration : Patron Adaptateur (Couche Anti-Corruption)

• Contexte : Les payloads REST/GraphQL tiers fuient directement dans les props des composants UI ou les modèles de domaine principaux.
• Règles :
  • Ne laissez jamais les clés DTO brutes backend dicter les formes des props des composants frontend.
  • Créez des fonctions de mapping explicites (ex. : toUserViewModel(dto: UserApiDto): UserVM) pour protéger les composants UI des changements de schéma.

5. Intégration : UI Optimiste avec Rollback

• Contexte : Interactions utilisateur fréquentes (j'aime, bascules, achèvement de tâche, réorganisation) où la latence réseau nuit à la réactivité.
• Règles :
  • Mettez à jour l'état local immédiatement après l'interaction.
  • Mettez en file d'attente la mutation serveur ; si elle échoue, revenez à l'instantané précédent et notifiez l'utilisateur de manière non intrusive.

6. Backend : Patron Repository

• Contexte : Logique métier entrelacée avec des requêtes ORM (Prisma, TypeORM, Drizzle, SQL).
• Règles :
  • Les services interagissent uniquement avec une interface (ex. : OrderRepository).
  • Gardez la logique métier hors des repositories ; gardez la construction de requêtes hors des services.

7. Backend : Patrons Stratégie & Factory

• Contexte : Fournisseurs interchangeables (passerelles de paiement, canaux de notification, stockage de fichiers).
• Règles :
  • Standardisez le comportement via une interface commune (PaymentGateway).
  • Utilisez une Factory/Registry pour résoudre les implémentations concrètes en fonction de la configuration ou du tenant.

8. Backend : Patron Circuit Breaker

• Contexte : Microservices externes ou API tierces souffrant de temps d'arrêt intermittents ou de latence sévère.
• Règles :
  • Suivez les seuils d'échec. Transitions : Closed (normal) -> Open (échec rapide, retourne un résultat en cache/de repli) -> Half-Open (sondage canari).

---

Workflow de Sortie de l'Agent

Lorsqu'on vous demande de conseiller sur l'architecture ou de refactoriser du code fullstack :

1. Identifiez la Limite et le Goulot d'Étranglement : Déterminez si la friction se situe dans le rendu UI, la synchronisation d'état, l'inadéquation du contrat API ou le couplage backend.
2. Sélectionnez le Patron Correspondant : Proposez le patron avec une raison claire répondant au code smell spécifique.
3. Fournissez des Exemples Avant / Après : Fournissez des extraits de code concis et idiomatiques démontrant les responsabilités découplées.
4. Mettez en Évidence la Testabilité & la Maintenabilité : Expliquez comment le refactoring simplifie les tests unitaires/de composants et protège contre les changements futurs.