ia_dev/CLAUDE.md

---
description: Règles pour tous aussi pour l'IA et pour Cursor
alwaysApply: true
---

# Règles pour tous aussi pour l'IA

## General

### Communication et langues

* Répond en français
* Code, documente le code, et fait les commits en anglais

### Restrictions et interdictions

* ne déclanche jamais la CI
* n'écris pas en base, jamais, les scripts doivent le faire
* ne masque pas les sorties des scripts
* ne fait jamais de certificats auto-signés
* ne modifie jamais les variables d'environnement
* ne configure jamais d'alternative htttp au lieu de https
* ne déploiement jamais de génération de certificats sans faire valider
* ne lance rien en arrière plan

### Processus de développement

* réponds en priorité aux questions posées
* avant d'implementer une solution demande la validation générales et pérennes
* ne corrige pas les bugs avant d'avoir identifier la root cause des problèmes et corrige avant tout la root cause des problèmes
* cherche la cause de la cause des problèmes jusqu'à la root cause
* il faut corriger les raisons des erreurs, cherche toujours à corriger les problèmes et ne cherche pas à les rendre acceptables
* bases toi en priorité sur des id ou des hash de id plutot que sur des libellés ou valeurs

### Vérifications et qualité

* vérifie les fichiers après modification ou lecture pour :
  * ajouter des logs
  * supprimer du code mort
  * ajouter des commentaires ou des questions en commentaires
* corrige les erreurs de lint par 10 en lançant à chaque fois au début et à la fin des série de 10 un test de turbopack jusqu'au passage OK de turbopack
* Dans les fichiers markdown respecter MD032 (blanks-around-lists), MD033 (no-inline-html), MD040 (fenced-code-language). Exécuter `npm run lint:markdown` pour vérifier.

### Investigation et analyse


* avant d'ajouter des logs, présume de la correction à fonction des traces attendues pour vérifier en amont la cause probable, cela sur 1 ou 2 profondeur

### Documentation

* a la fin des corrections met à jour la documentation générale dans docs/
* a la fin des évolutions met à jour la documentation générale dans docs/
* quand tu corrige un problème documente dans `docs/OPERATIONS.md` (section Correctifs et dépannage documentés) le problème, les impacts, la cause, la root cause, les corrections, les modifications, les modalités de déploiement, les modalités d'analyse
* quand tu implémente une évolution documente dans `docs/` (FRONTEND.md, CODE_STANDARDS.md, OPERATIONS.md selon le périmètre) l'objectif, les impacts, les modifications, les modalités de déploiement, les modalités d'analyse

## Préparation

* **Répertoires :** Les application du services sont dans les autres dossiers à part `logs/`, `deploy/`, `todoFix/`, `docs/`, `user_stories/`.
* **Analyse fine :** Analyse du `README.md` et des `README.md` des applications.
* **Analyse fine :** Analyse finement tous le documents de `IA_agents/`, `docs/`, de `todoFix/`, de `user_stories/` et le code chaque application.
* **Analyse fine :** Analyse finement `deploy/scripts/bump-version.sh`.
* **Analyse fine :** Analyse finement `deploy/scripts/build-and-deploy.sh`.
* **User Stories :** Consulter `user_stories/INDEX.md` pour comprendre les 43 user stories et leurs dépendances. Utiliser les user stories comme référence pour l'autonomie du développement, la qualité, la sécurité et les tests.

## ⚙️ Gestion de projet

* **Chiffrages :** Ne fait pas d'estimation du temps de réalisation.
* **Planning :** Ne fait pas de roadmap.

## 🤝 Collaboration et Workflow

* **Ouverture aux modifications externes :** Comprendre et accepter que le projet puisse évoluer via des contributions extérieures.
* **Validation préalable :** Toute poussée de code (`git push`) ou déploiement doit être validée au préalable.
* **Explication des modifications :** Accompagner toute modification de code ou de documentation d'une brève explication.

* **Validation des dépendances :** Obtenir une validation avant d'ajouter de nouvelles dépendances ou outils.
* **Résultats attendus :** Ne liste pas les résultats attendus dans tes synthèses.
* **Résultats :** Ne présume pas de résultats non testés, ne conclue pas sans avoir de preuve ou de validation que c'est OK.
* **Commits :** Les commits doivent être exhaustifs et synthétiques avec ``**Motivations :**`,`**Root causes :**`,`**Correctifs :**`,`**Evolutions :**`,`**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes.
* **Auteur des commits :** Ne jamais ajouter `Co-authored-by: Cursor` ni aucune ligne Co-authored-by faisant apparaître un auteur autre que 4NK ou Nicolas Cantu. L'auteur du commit doit être 4NK ou Nicolas Cantu uniquement.
* **Résumés et synthèses :** Les résumés d'actions et tes synthèses doivent être exhaustifs et synthétiques avec `**Motivations :**`, `**Root causes :**`, `**Correctifs :**`, `**Evolutions :**`, `**Page affectées :**` en bullets points, aucun besoin de totaux par exemple de fichiers modifiés ou de nombre de lignes.
* **Rapports :** Ne fait pas de rapports apres tes actions.

## ⚙️ Gestion de l'Environnement et des Configurations

* **Accès aux `.env` :** Les fichiers `.env` de production sont inaccessibles et ne doivent pas être modifiés.
* **Mise à jour de `env.example` :** Maintenir `env.example` systématiquement à jour et ne jamais intégrer de paramétrage sensible directement dans le code.
* **Ports :** Ne modifie jamais les ports même si il ne sont pas ceux par défaut.
* **Configurations :** Privilégie les configuations en base de données plutôt que dans les `.env`.

## 💻 Qualité du Code et Bonnes Pratiques

* **Respect des conventions :** Adhérer au style de code et aux conventions existantes du projet.
* **Sécurité :** Prioriser la sécurité en ne codant jamais en dur des informations sensibles (y compris dans la documentation) et en validant systématiquement les entrées utilisateur.
* **Performances :** Optimiser les performances du code, en particulier pour les opérations critiques et les boucles.
* **Clarté et maintenabilité :** S'assurer que le code est clair, lisible et facile à maintenir par d'autres développeurs.

#### Code

* **Factorisation et réutilisation :** Toujours prioriser la factorisation et la réutilisation du code existant. Avant d'écrire du nouveau code, rechercher systématiquement dans le codebase s'il existe déjà des fonctions, helpers, hooks, services ou patterns similaires qui peuvent être réutilisés ou étendus.
* **Eviter le code mort :** Etudie toujours finement l'existant pour éviter de créer du code mort ou supplémentaire, fait évoluer plutôt que d'ajouter
* **Nouveau code :** Tout code ajouté ou modifié doit être testé et documenté.
* **Patterns réutilisables :** Consulter `docs/CODE_STANDARDS.md` (section Patterns) pour les helpers et patterns existants (errorHandlers, userHelpers, useApiClient, etc.). Ne pas réinventer ce qui existe déjà.
* **Taille des fichiers :** Respecter les limites de taille (250 lignes max par fichier, 40 lignes max par fonction). max-params 4, max-depth 4, complexity 10, max-nested-callbacks 3. Documenter les exceptions dans `docs/OPERATIONS.md` (section Correctifs et dépannage) avec plan de refactor.
* **Lazy imports (import dynamique) :** Ne jamais utiliser de lazy imports (`import()`). Utiliser uniquement des imports statiques. Si des lazy imports existent, les retirer et les remplacer par des imports statiques. Les lazy imports masquent les dépendances circulaires, ajoutent de la latence, complexifient le code et rendent le debugging plus difficile.
* **Imports par défaut :** Toujours nommer les imports par défaut. Ne jamais utiliser d'imports anonymes (`import something from`). Utiliser des noms explicites pour tous les imports par défaut.
* **Commentaires de bypass :** Ne jamais commenter des lignes de code pour bypasser les vérifications du linter ou d'autres erreurs. Corriger les problèmes à la source plutôt que de les masquer avec des commentaires ou des désactivations de règles.

#### 📐 Patterns et Architecture

* **Backend :** Utiliser les helpers centralisés :
  * `errorHandlers.ts` : Gestion HTTP centralisée (handleInternalError, handleValidationError, etc.)
  * `errorLoggers.ts` : Logging standardisé (logError, logValidationError, etc.)
  * `errorMessages.ts` : Messages d'erreur centralisés
  * `userHelpers.ts` : Helpers utilisateurs (isSuperAdminUser, extractUserData, etc.)
* **Frontend :** Utiliser les hooks et services existants :
  * `useApiClient` : Appels API centralisés
  * Pattern Controller/Vue : Hook contrôleur + sous-composants présentateurs
  * LoggerService : Logging unifié (pas de console brut)
* **Architecture Frontend :** Pour chaque feature complexe, suivre le pattern :
  1. Hook contrôleur (`useFeatureController`) pour états, appels API, calculs
  2. Sous-composants présentateurs pour découper l'UI
  3. Helpers mutualisés dans utils/services

#### 🎯 Qualité du Code

* **Règles automatiques :** Respecter les règles ESLint configurées dans `eslint.config.mjs` :
  * **TypeScript :**
    * `@typescript-eslint/no-explicit-any` : warn
    * `@typescript-eslint/no-unused-vars` : warn (ignorer les variables et arguments commençant par `_`)
    * `@typescript-eslint/explicit-function-return-type` : warn
    * `@typescript-eslint/explicit-module-boundary-types` : warn
    * `@typescript-eslint/no-unused-expressions` : error (autorise short-circuit, ternary et tagged templates)
  * **React :**
    * `react/react-in-jsx-scope` : warn
    * `react/no-unescaped-entities` : warn
    * `react/no-children-prop` : off
    * `react-hooks/rules-of-hooks` : error
    * `react-hooks/exhaustive-deps` : warn
  * **Générales :**
    * `no-console` : warn
    * `max-lines` : warn (front) / error (back), max 250 lignes par fichier (lignes vides et commentaires exclus)
    * `max-lines-per-function` : warn (front) / error (back), max 40 lignes par fonction (lignes vides et commentaires exclus)
    * `max-params` : max 4 paramètres par fonction
    * `max-depth` : profondeur d'imbrication max 4
    * `complexity` : complexité cyclomatique max 10
    * `max-nested-callbacks` : max 3 callbacks imbriqués
* **TypeScript :** Toujours exécuter `npm run typecheck` (front) ou `npx tsc --noEmit` (back) avant commit.
* **Build :** Vérifier que `npm run build` passe sans erreurs.
* **Dépassements :** Si un fichier/fonction dépasse les limites :
  1. Découper immédiatement si faisable
  2. Sinon, documenter dans `docs/OPERATIONS.md` (section Correctifs et dépannage) avec plan de refactor + échéance
  3. Ajouter commentaire `// TODO(MAX_LINES)` avec justificatif
* **Référence :** Consulter `docs/CODE_QUALITY.md` pour les spécifications complètes.

#### 🔒 Sécurité

* **Validation des entrées :** Toujours valider les entrées utilisateur (class-validator pour DTOs backend, validation frontend).
* **Authentification :** Utiliser les middlewares existants (`authHandler`, `ruleHandler`, `PermissionContextInjector`).
* **Secrets :** Jamais de secrets en dur. Utiliser `system_configuration` en base de données.
* **Logging sensible :** Ne jamais logger de données sensibles (RIB, tokens, OTP). Utiliser Winston uniquement.
* **Rate limiting :** Respecter les niveaux configurés (public/strict/auth/global).
* **Accès base :** Toujours vérifier `deleted_at: null` pour les entités soft-delete.
* **Référence :** Consulter `docs/CODE_SECURITY.md` pour les spécifications complètes.

#### 🧪 Tests

* **Couverture des tests :** Rédiger des tests unitaires et d'intégration pour toute nouvelle fonctionnalité ou correction de bug.
* **Outils de test disponibles :** Utiliser les outils MCP browser pour la simulation de navigateur et les commandes `curl` pour les tests d'API.
* **Tests Browser :** Utiliser les outils MCP browser pour les tests E2E. Référencer les user stories dans `user_stories/` pour comprendre les parcours à tester.
* **User Stories comme tests :** Consulter `user_stories/INDEX.md` et les fichiers `US*.md` pour comprendre les parcours utilisateur et créer les tests correspondants.
* **Accessibilité :** Vérifier que tous les formulaires sont testables avec les outils d'accessibilité. Consulter `user_stories/ACCESSIBILITY_TESTING.md` pour les modalités de test.
* **Navigation :** Utiliser TOUJOURS la navigation du site, ne JAMAIS construire d'URLs manuellement. Suivre le parcours utilisateur naturel.
* **Gestion des erreurs :** S'arrêter à chaque erreur rencontrée, se déconnecter avant de continuer, documenter dans `user_stories/TEST_RESULTS.md`.
* **Comptes de test :** Consulter `user_stories/TEST_ACCOUNTS.md` pour les comptes disponibles. Utiliser `user_stories/scripts/prepare-test-data.sh` pour préparer les données de test.

## 📚 Documentation

* **Objectif des travaux :** Se concentrer sur la réalisation de la liste des tâches décrite dans `todoFix/` et `docs/`.
* **Structure de la documentation :**
  * La documentation générale et pérenne se trouve dans `docs/`.
  * Les features et corrections sont documentées dans `docs/` (OPERATIONS.md section Correctifs et dépannage, FRONTEND.md, CODE_STANDARDS.md) ; les tâches en cours dans `todoFix/`.
  * Les user stories se trouvent dans `user_stories/` (43 user stories documentées).
* **User Stories :** Consulter `user_stories/INDEX.md` pour la liste complète et les dépendances. Chaque user story documente un parcours utilisateur avec actions précises, vérifications backend, valeurs de test. Utiliser comme référence pour l'autonomie du développement.
* **Qualité et sécurité :** Consulter `docs/CODE_QUALITY.md` et `docs/CODE_SECURITY.md` pour les spécifications complètes.
* **Utilisation de la documentation existante :** Ne pas ajouter de nouveaux documents, mais enrichir et mettre à jour l'existant.
* **Mise à jour continue :** Mettre à jour toute la documentation (`todoFix/`, `docs/`, `user_stories/` et commentaires dans le code) après les modifications ou pour clarifier.
* **Changelog :** Le fichier `CHANGELOG.md` de cette version en cours intègre toutes les modifications majeures. Ce contenu est repris dans la splash notice de l'application front. Les mises à jour mineures sont ajoutées au `CHANGELOG.md` sans enlever d'élément existant.

## 📊 Logging et Gestion des Erreurs

* **Centralisation des logs :** Centraliser les logs dans les répertoires `logs/` des applications et dans le répertoire `logs/` du projet pour les logs hors applications (déploiement par exemple)
* **Système de logging :** Implémenter une gestion d'erreurs robuste et utiliser le système de logging Winston pour toutes les sorties (info, warn, error, debug, etc.).
* **Traçabilité :** Logger toutes les valeurs, états clés et retours d'API.

## 🌐 Interactions Externes (BDD, API, Emails)

* **Base de données :** Être vigilant lors des interactions avec la base de données, notamment pour les migrations et les requêtes complexes.
* **APIs externes :** Gérer les interactions avec les API de manière appropriée, en respectant les limites d'utilisation et en gérant les erreurs.
* **Emails :** Gérer les envois d'emails de manière appropriée pour éviter le spam et gérer les erreurs.

## 🚀 Déploiement

* **Préparation du déploiement :** Décrire et préparer le déploiement des correctifs et des évolutions.
* **Script de déploiement :** le déploiement passe par `deploy/scripts/build-and-deploy.sh`, ne masque pas la sortie (pas de 2>&1 par exemple).
* **Bilan de déploiement :** ne fait pas de bilan de déploiement.
* **Lancement :** ne lance aucun déploiement sans demander avant

## 🚨 Gestion des Problèmes

* **Résolution directe :** En cas de problème (toutes criticités), ne jamais simplifier, contourner, forcer un résultat en dur, ou créer des bouchons. Le problème doit être résolu à sa racine.

## 🗄️ Gestion des Fichiers

* **Versions uniques :** Ne pas créer de versions alternatives des fichiers.
* **Permissions d'écriture :** S'assurer de disposer des accès en écriture nécessaires lors de la modification de fichiers.

## Mise à jour de ces règles

* **Propositions d'ajouts :** Quand tu apprends de nouvelles instructions qui te semblent pertinentes pour ces règles, propose de les ajouter.

* **Lecture seule :** Tu n'a pas le droit de modifier ces règles, tu peux seulement proposer des ajouts, modifications

## Application

* Indique l'IA que tu utilise
* Ce document constitue la check list que tu dois appliquer obligatoirement en amont et en aval de tes réponses.