Rédacteur technique pour documentation de projet en langage clair

# FORME.md - Le Guide Complet ## 1. La Vue d'Ensemble FORME est une plateforme qui transforme la façon dont les gens créent et partagent des formulaires en ligne. Pensez-y comme à un atelier de menuiserie numérique - au lieu de construire des étagères, vous construisez des formulaires, et au lieu de les livrer en camion, vous les partagez par un lien. **Le problème :** Créer des formulaires en ligne est soit trop compliqué (il faut coder), soit trop limité (les outils existants sont rigides et chers). **Pour qui :** Pour toute personne qui a besoin de collecter des informations - un organisateur d'événements qui veut des inscriptions, un propriétaire de petite entreprise qui veut des commandes, un enseignant qui veut des questionnaires. **Le parcours utilisateur :** Vous arrivez sur le site, vous créez un formulaire en glissant-déposant des champs (comme assembler des blocs LEGO), vous obtenez un lien unique, vous l'envoyez à qui vous voulez, et les réponses arrivent dans votre tableau de bord en temps réel. **L'analogie du restaurant :** Si FORME était un restaurant, la page d'accueil serait la salle à manger (là où les clients arrivent), l'éditeur de formulaire serait la cuisine (là où on prépare les plats), la base de données serait le garde-manger (là où on stocke les ingrédients), et le tableau de bord des réponses serait le service en salle (là où on sert les résultats). --- ## 2. Architecture Technique - Le Plan ### Le Diagramme ``` ┌─────────────────────────────────────────────────────────────┐ │ NAVIGATEUR (Frontend) │ │ React + Vite - Ce que l'utilisateur voit et touche │ └────────────────────────┬────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ API (Backend) │ │ Node.js + Express - Le cerveau qui traite les demandes │ └────────────┬──────────────────────────────┬─────────────────┘ │ │ ▼ ▼ ┌──────────────────────┐ ┌──────────────────────────────┐ │ BASE DE DONNÉES │ │ SERVICES EXTERNES │ │ PostgreSQL │ │ - Auth (identification) │ │ - Utilisateurs │ │ - Stockage de fichiers │ │ - Formulaires │ │ - Envoi d'emails │ │ - Réponses │ │ │ └──────────────────────┘ └──────────────────────────────┘ ``` ### La Visite Guidée **Le Frontend (la salle d'exposition)** - C'est tout ce que l'utilisateur voit et avec quoi il interagit. Nous utilisons React avec Vite, ce qui est comme avoir un showroom ultra-rapide où chaque pièce se met à jour instantanément sans recharger la page. **L'API (la cuisine)** - C'est le cœur du système. Quand quelqu'un clique sur "Enregistrer", la demande voyage jusqu'ici, est validée, traitée, puis stockée. Nous avons choisi Node.js avec Express parce que c'est comme avoir une cuisine avec un chef qui parle la même langue que les serveurs (JavaScript partout) - pas besoin de traducteur entre le frontend et le backend. **La Base de Données (le garde-manger)** - PostgreSQL est notre système de stockage. Nous avons choisi PostgreSQL plutôt que MongoDB (une alternative populaire) parce que nos données sont très structurées - chaque formulaire a des champs, chaque réponse correspond à un formulaire. C'est comme préférer des boîtes étiquetées et organisées plutôt qu'un grand tiroir où on jette tout. **Pourquoi cette architecture ?** Nous avons séparé le frontend du backend pour que chaque partie puisse évoluer indépendamment. Si un jour nous voulons créer une application mobile, elle pourra utiliser la même API sans rien réinventer. --- ## 3. Structure du Code - Le Système de Classement ``` forme/ ├── client/ # Le Frontend (ce que l'utilisateur voit) │ ├── src/ │ │ ├── components/ # Les briques visuelles (boutons, champs, etc.) │ │ ├── pages/ # Les écrans principaux (accueil, éditeur, etc.) │ │ ├── hooks/ # Les fonctions réutilisables │ │ └── utils/ # Les outils d'aide │ └── public/ # Les images et fichiers statiques │ ├── server/ # Le Backend (le cerveau) │ ├── routes/ # Les chemins de l'API (les "portes" d'entrée) │ ├── controllers/ # La logique métier (ce qui se passe derrière chaque porte) │ ├── models/ # La définition des données (les "fiches" de stockage) │ └── middleware/ # Les contrôles de sécurité (le videur) │ ├── shared/ # Le code partagé entre frontend et backend │ └── types/ # Les définitions de types (les "contrats" de données) │ └── docs/ # La documentation ``` **Les points d'entrée :** - `client/src/main.jsx` - C'est là que l'application frontend démarre (comme l'ouverture des portes du restaurant) - `server/index.js` - C'est là que le serveur démarre (comme l'allumage des fourneaux) **Conventions de nommage :** Les fichiers sont nommés en `camelCase` (pas d'espaces, chaque mot commence par une majuscule après le premier). Les composants React sont en `PascalCase` (première lettre en majuscule) pour les distinguer des fonctions ordinaires. --- ## 4. Connexions & Flux de Données - Comment les Choses se Parlent ### Action 1 : Un utilisateur crée un compte 1. L'utilisateur remplit le formulaire d'inscription et clique "S'inscrire" - c'est comme sonner à la porte du restaurant 2. Le frontend envoie les informations à `/api/auth/register` - le serveur reçoit la demande 3. Le serveur vérifie que l'email n'existe pas déjà (comme vérifier qu'il n'y a pas de réservation en double) 4. Le mot de passe est haché (transformé en code illisible) avant d'être stocké - c'est comme écrire le mot de passe dans une langue secrète que seul le serveur comprend 5. Un jeton d'authentification est créé et renvoyé au navigateur - c'est comme donner un badge d'accès au client 6. Le navigateur stocke ce jeton et l'utilisateur est connecté ### Action 2 : Un utilisateur crée un formulaire 1. L'utilisateur glisse des champs dans l'éditeur - chaque action met à jour l'état local (comme disposer les couverts sur la table) 2. Quand il clique "Publier", le frontend envoie la structure du formulaire à `/api/forms` 3. Le serveur valide que la structure est correcte (pas de champs vides, pas de noms dupliqués) 4. Le formulaire est stocké dans PostgreSQL avec un identifiant unique 5. Un lien public est généré - c'est comme donner l'adresse du restaurant à partager ### Action 3 : Un visiteur soumet une réponse 1. Le visiteur ouvre le lien public et remplit le formulaire 2. En cliquant "Envoyer", les données vont à `/api/forms/:id/responses` 3. Le serveur vérifie que le formulaire existe et accepte encore des réponses 4. La réponse est stockée avec un horodatage 5. Le créateur du formulaire voit la réponse apparaître en temps réel dans son tableau de bord ### Services Externes et Gestion des Pannes - **Authentification :** Si le service d'auth tombe en panne, les utilisateurs ne peuvent pas se connecter mais les formulaires déjà publiés restent accessibles - **Stockage de fichiers :** Si un utilisateur téléverse une image et que le service est down, l'utilisateur voit un message d'erreur clair et peut réessayer - **Emails :** Si l'envoi d'emails échoue, l'utilisateur voit une notification dans l'application au lieu de dépendre de l'email --- ## 5. Choix Technologiques - La Boîte à Outils | Technologie | Ce Qu'Elle Fait Ici | Pourquoi Celle-ci | Attention | |------------|---------------------|-------------------|-----------| | **React** | Construit l'interface utilisateur | La plus grande communauté, énorme écosystème, facile à recruter des développeurs | Les mises à jour fréquentes peuvent casser du code existant | | **Vite** | Outil de développement frontend | Beaucoup plus rapide que Webpack (l'alternative), démarrage en millisecondes | Moins de plugins disponibles que Webpack | | **Node.js + Express** | Le serveur backend | JavaScript partout (même langage que le frontend), léger et flexible | La gestion de la mémoire peut être délicate à grande échelle | | **PostgreSQL** | Base de données relationnelle | Fiable, mature, excellent pour les données structurées, gratuit en open source | Nécessite une configuration plus complexe que MongoDB | | **JWT (Jetons)** | Authentification | Sans état (le serveur n'a pas besoin de stocker les sessions), standard de l'industrie | Les jetons ne peuvent pas être révoqués facilement avant expiration | | **Tailwind CSS** | Styles et design | Développement rapide, pas de fichiers CSS séparés, cohérence visuelle | Le HTML devient plus verbeux avec toutes les classes | **Coûts :** Toutes ces technologies sont open source et gratuites. Les coûts viennent de l'hébergement (serveurs, base de données) et des services externes (envoi d'emails, stockage de fichiers) qui facturent généralement selon l'usage. --- ## 6. Environnement & Configuration ### Variables d'Environnement | Variable | Ce Qu'Elle Contrôle | Où La Trouver | |----------|---------------------|---------------| | `DATABASE_URL` | L'adresse de la base de données (comme l'adresse du garde-manger) | Fichier `.env` à la racine | | `JWT_SECRET` | La clé secrète pour signer les jetons d'authentification (comme le sceau du roi) | Fichier `.env` à la racine | | `PORT` | Le port sur lequel le serveur écoute (comme la fréquence radio) | Fichier `.env` à la racine | | `CLIENT_URL` | L'adresse du frontend (pour les autorisations CORS) | Fichier `.env` à la racine | ### Les Environnements - **Développement :** Votre machine locale. Tout est en mode debug, les erreurs sont verbeuses, la base de données est locale - **Staging :** Un environnement de test qui ressemble à la production. C'est là qu'on teste avant de déployer - **Production :** Le vrai site que les utilisateurs voient. Les erreurs sont masquées, les performances sont optimisées ### Changements Importants Si vous devez changer la clé secrète JWT (`JWT_SECRET`), tous les utilisateurs seront déconnectés car leurs jetons deviendront invalides. C'est comme changer la serrure de la porte - tout le monde doit recevoir une nouvelle clé. **Ne jamais committer le fichier `.env` dans le dépôt Git.** C'est comme laisser la combinaison du coffre-fort sur un post-it collé à la porte. --- ## 7. Leçons Apprises - Les Histoires de Guerre ### Bugs & Corrections **Le Bug des Réponses Perdues :** Un jour, des réponses disparaissaient mystérieusement. Le problème : quand un utilisateur soumettait un formulaire, la requête échouait silencieusement si le formulaire avait été supprimé entre-temps. La correction : ajouter une vérification explicite et un message d'erreur clair. La leçon : ne jamais supprimer silencieusement les erreurs - toujours les logger et les afficher. **Le Bug de l'Éditeur qui Plantait :** L'éditeur de formulaire plantait quand on ajoutait plus de 50 champs. Le problème : chaque champ déclenchait un re-rendu complet de toute la page. La correction : optimiser avec la mémoïsation (ne re-rendre que ce qui a changé). La leçon : les performances doivent être pensées dès le début, pas ajoutées après. ### Pièges & Mines Terrestres - **Changer le type d'un champ existant** (par exemple, passer de "texte" à "nombre") peut casser les réponses déjà collectées. Les anciennes réponses peuvent ne plus correspondre au nouveau format. - **Modifier la structure d'un formulaire publié** affecte les réponses futures mais pas les passées. C'est voulu, mais ça peut créer des incohérences dans l'analyse des données. - **La suppression d'un utilisateur** ne supprime pas automatiquement ses formulaires. C'est un choix délibéré pour éviter les pertes accidentelles, mais ça signifie que des données orphelines peuvent s'accumuler. ### Découvertes - **Tailwind CSS** a révolutionné notre vitesse de développement. Au début, nous étions sceptiques (les classes dans le HTML semblaient désordonnées), mais la rapidité de prototypage a convaincu tout le monde. - **Vite** a été une révélation après des années de Webpack. Le rechargement à chaud en quelques millisecondes change vraiment l'expérience de développement. - **Si nous recommencions,** nous utiliserions probablement TypeScript dès le premier jour plutôt que de le migrer plus tard. La migration a été douloureuse. ### Sagesse d'Ingénierie - **Toujours valider les entrées côté serveur.** Le frontend peut être contourné. C'est comme vérifier les pièces d'identité à la porte, pas seulement à l'accueil. - **Les tests ne sont pas optionnels.** Les tests automatisés sont comme des exercices d'incendie - personne ne les aime, mais quand le feu arrive, ils sauvent des vies. - **Documenter au fur et à mesure.** La documentation écrite six mois après est toujours incomplète et inexacte. --- ## 8. Carte de Référence Rapide ### Lancer le Projet Localement 1. **Installer Node.js** (version 18 ou supérieure) depuis nodejs.org 2. **Cloner le dépôt :** `git clone [URL_DU_DEPOT]` 3. **Installer les dépendances :** ```bash cd forme npm install cd client && npm install cd ../server && npm install ``` 4. **Configurer l'environnement :** Copier `.env.example` vers `.env` et remplir les valeurs 5. **Démarrer la base de données :** `docker-compose up -d` (ou utiliser une base PostgreSQL locale) 6. **Lancer le serveur :** `cd server && npm run dev` 7. **Lancer le frontend :** `cd client && npm run dev` 8. **Ouvrir le navigateur :** Aller sur `http://localhost:5173` ### URLs Clés - **Production :** `https://forme.app` - **Staging :** `https://staging.forme.app` - **API en production :** `https://api.forme.app` - **Tableau de bord admin :** `https://forme.app/admin` ### En Cas de Problème - **Le site est down :** Vérifier le statut des serveurs sur [status.forme.app] - **Une erreur apparaît :** Regarder les logs sur la plateforme d'hébergement (Vercel/Railway/etc.) - **Les données semblent corrompues :** Contacter le responsable technique avec l'heure exacte et l'action effectuée ### Commandes Fréquentes ```bash # Lancer les tests npm test # Déployer en staging npm run deploy:staging # Déployer en production npm run deploy:prod # Vérifier les erreurs de lint npm run lint # Sauvegarder la base de données npm run db:backup ``` --- **Ce document est vivant.** Mettez-le à jour à chaque décision importante, chaque bug corrigé, chaque leçon apprise. Dans six mois, vous serez reconnaissant d'avoir pris le temps.