prakashjune8/test-agent-skills

Compétence Développement Full-Stack (UI & Backend)

Cette compétence fournit un guide architectural de bout en bout, un livre de recettes de workflow et des normes de codage pour développer des applications web de qualité production avec TypeScript/JavaScript moderne, à la fois côté frontend (UI) et backend.

---

1. Principes Architecturaux Fondamentaux

1. Sécurité de Type de Bout en Bout :
   • Source unique de vérité pour les modèles de domaine et les objets de transfert de données (DTO).
   • Utilisez des bibliothèques de validation de schéma (comme Zod) pour analyser et valider les requêtes à l'exécution et inférer les types TypeScript à la compilation.
2. Séparation des Préoccupations en Couches :
   • Frontend : Séparation stricte des primitives de présentation, des composants métier/conteneurs et des hooks de récupération de données.
   • Backend : Séparation stricte entre le Routage/Contrôleurs (transport HTTP), la Couche de Service (logique métier) et la Couche d'Accès aux Données / Référentiel (base de données / ORM).
3. Contrat d'API en Premier :
   • Établissez les contrats de requête et de réponse avant d'implémenter les détails de l'UI ou du backend.
   • Enveloppe de réponse uniforme : { success: true, data: T } ou { success: false, error: { message, code, details } }.
4. Résilience et Gestion des Erreurs :
   • Frontend : Limites d'erreur, états de chargement squelette, replis gracieux et notifications conviviales.
   • Backend : Middleware d'erreur centralisé, catégorisation des erreurs opérationnelles vs programmeur, journalisation structurée et valeurs par défaut sécurisées.
5. Sécurité par Défaut :
   • En-têtes de sécurité (Helmet), politiques CORS explicites, validation/assainissement des entrées, limitation de débit et authentification sécurisée (cookies HTTP-only ou jetons porteurs).

---

2. Structure de Répertoire Recommandée

Pour les dépôts full-stack (monorepo ou structure divisée) :

├── packages/ ou apps/
│   ├── client/                  # UI Frontend (React / Next.js / Vite)
│   │   ├── src/
│   │   │   ├── assets/          # Actifs statiques (images, icônes, polices)
│   │   │   ├── components/      # Composants UI (atomes, molécules, organismes)
│   │   │   │   ├── ui/          # Primitives du système de design de base (Button, Input, Modal)
│   │   │   │   └── features/    # Composants composites spécifiques au domaine
│   │   │   ├── hooks/           # Hooks React personnalisés (useAuth, useDebounce, etc.)
│   │   │   ├── services/        # Client API et intégrations de services
│   │   │   ├── store/           # Gestion d'état global (Zustand, Context, etc.)
│   │   │   ├── types/           # Types spécifiques au client
│   │   │   ├── utils/           # Fonctions d'aide et utilitaires de formatage
│   │   │   ├── App.tsx          # Composant d'application principal et routes
│   │   │   ├── main.tsx         # Point d'entrée
│   │   │   └── index.css        # CSS global et jetons de design
│   │   └── package.json
│   │
│   ├── server/                  # API Backend (Node.js / Express / Fastify)
│   │   ├── src/
│   │   │   ├── config/          # Variables d'environnement et configurations d'exécution
│   │   │   ├── controllers/     # Gestionnaires de routes HTTP (extraire les paramètres, appeler les services)
│   │   │   ├── middleware/      # Auth, validation, gestionnaire d'erreurs, limiteur de débit
│   │   │   ├── models/          # Modèles/schémas de base de données (Prisma, Drizzle, etc.)
│   │   │   ├── routes/          # Définitions de routes Express/Fastify
│   │   │   ├── services/        # Logique métier et interactions API externes
│   │   │   ├── utils/           # Aides backend (jwt, logger, crypto)
│   │   │   ├── app.ts           # Configuration de l'application Express/Fastify
│   │   │   └── server.ts        # Point d'entrée du serveur et arrêt gracieux
│   │   └── package.json
│   │
│   └── shared/                  # Schémas partagés, DTOs et contrats TypeScript
│       ├── src/
│       │   ├── schemas/         # Schémas Zod (user.schema.ts, auth.schema.ts)
│       │   └── types/           # Types inférés (export type User = z.infer<...>)
│       └── package.json

---

3. Workflow de Développement Étape par Étape

Lors de l'implémentation d'une fonctionnalité full-stack, exécutez les phases suivantes dans l'ordre :

Phase 1 : Définir les Contrats Partagés et les Schémas

1. Définissez le schéma Zod représentant les charges utiles des requêtes et les entités de réponse dans shared/ ou common/.
2. Exportez les types TypeScript inférés.

import { z } from 'zod';

export const CreateUserSchema = z.object({
  email: z.string().email('Adresse email invalide'),
  name: z.string().min(2, 'Le nom doit comporter au moins 2 caractères'),
  role: z.enum(['admin', 'user']).default('user'),
});

export type CreateUserInput = z.infer<typeof CreateUserSchema>;
export type UserResponse = CreateUserInput & { id: string; createdAt: string };

Phase 2 : Construire le Service Backend et les Points de Terminaison

1. Middleware de Validation : Appliquez un middleware de validation avec le schéma Zod pour rejeter les entrées malformées tôt avec un code HTTP 400.
2. Couche de Service : Écrivez la logique métier pure dans une classe ou un module de service. Isolez les requêtes de base de données des concepts HTTP (req, res).
3. Contrôleur : Gérez l'extraction des entrées HTTP, appelez le service et renvoyez des réponses standardisées en utilisant sendSuccess().
4. Gestion des Erreurs : Utilisez des erreurs personnalisées (NotFoundError, BadRequestError, UnauthorizedError) et laissez le middleware d'erreur centralisé les attraper et formater la réponse.

Phase 3 : Construire les Composants UI Frontend

1. Jetons du Système de Design : Assurez-vous que les propriétés personnalisées CSS ou les variables du système de design existent pour les couleurs, la typographie, l'espacement et les ombres.
2. Primitives Atomiques / UI : Construisez ou réutilisez des composants de base (boutons, champs de saisie, badges, dialogues) avec navigation au clavier et attributs ARIA.
3. Vue de Fonctionnalité / Page : Assemblez des composants composites avec une hiérarchie visuelle claire, un espacement généreux, une typographie moderne et une grille/flexbox responsive.
4. État et Micro-Interactions :
   • Fournissez un retour visuel pour les états survol, actif, focus-visible et désactivé.
   • Incluez des squelettes de chargement, des indicateurs de spinner et des boutons désactivés pendant les soumissions en attente.

Phase 4 : Intégration et Récupération de Données

1. Client API : Utilisez une enveloppe de récupération centralisée ou une instance Axios configurée avec l'URL de base, le délai d'attente, les informations d'identification et les intercepteurs.
2. État du Serveur : Utilisez TanStack Query (React Query) ou des hooks standard pour interroger et muter les données.
   • Invalidation du cache sur les mutations réussies.
   • Mises à jour optimistes lorsque c'est approprié pour une expérience utilisateur réactive.
3. Gestion des Formulaires : Intégrez les formulaires avec React Hook Form et le résolveur Zod pour partager exactement les mêmes règles de validation entre le client et le serveur.

Phase 5 : Vérification et Renforcement

1. Vérification Backend : Testez les points de terminaison avec des tests unitaires/d'intégration ou curl/fetch pour vérifier les cas limites (entrées invalides, jetons manquants, clés en double).
2. Vérification Frontend : Vérifiez la réactivité sur les largeurs de fenêtre de bureau, tablette et mobile.
3. Vérification de Sécurité : Confirmez que CORS, la limitation de débit et les gardes d'authentification sont actifs.

---

4. Modèles de Code Rapides

Aide de Réponse API Standard (Backend)

// server/src/utils/response.ts
import { Response } from 'express';

export function sendSuccess<T>(res: Response, data: T, statusCode = 200, meta?: unknown) {
  return res.status(statusCode).json({
    success: true,
    data,
    ...(meta ? { meta } : {}),
  });
}

export function sendError(res: Response, message: string, statusCode = 500, details?: unknown) {
  return res.status(statusCode).json({
    success: false,
    error: {
      message,
      statusCode,
      details: details ?? null,
    },
  });
}

Middleware d'Erreur Express Centralisé

// server/src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';
import { ZodError } from 'zod';

export class AppError extends Error {
  constructor(public message: string, public statusCode = 500, public details?: unknown) {
    super(message);
    this.name = 'AppError';
  }
}

export function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction) {
  if (err instanceof ZodError) {
    return res.status(400).json({
      success: false,
      error: {
        message: 'Échec de la validation',
        statusCode: 400,
        details: err.flatten().fieldErrors,
      },
    });
  }

  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      success: false,
      error: {
        message: err.message,
        statusCode: err.statusCode,
        details: err.details ?? null,
      },
    });
  }

  console.error('Erreur serveur non gérée :', err);
  return res.status(500).json({
    success: false,
    error: {
      message: 'Erreur interne du serveur',
      statusCode: 500,
    },
  });
}

Client API Type-Safe (Frontend)

// client/src/services/apiClient.ts
interface ApiResponse<T> {
  success: boolean;
  data: T;
  error?: {
    message: string;
    statusCode: number;
    details?: unknown;
  };
}

export async function apiRequest<T>(url: string, options?: RequestInit): Promise<T> {
  const res = await fetch(url, {
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
    ...options,
  });

  const body: ApiResponse<T> = await res.json();

  if (!res.ok || !body.success) {
    throw new Error(body.error?.message || `HTTP ${res.status}: La requête a échoué`);
  }

  return body.data;
}

---

5. Références et Approfondissements

Pour des modèles architecturaux approfondis, consultez :

• Directives d'Architecture et de Style UI
• Directives d'Architecture et de Sécurité Backend
• Contrats API et Sécurité de Type de Bout en Bout