smart_ide/services/docv/enso-docs/REGLES_CODING_PROJET.md

Règles de coding spécifiques au projet — docv / enso

Ce document consolide les règles de développement spécifiques au monorepo enso (docv, enso). Les règles Cursor et lint générales (max-lines, complexity, etc.) sont détaillées en section 9 ; la config détaillée reste dans .cursor/rules/ et les fichiers ESLint/Clippy.

Références : ARCHITECTURE_DOCV_ENSO.md, ARCHITECTURE_DOCV_DETAILLEE.md, PLAN_REALISATION_DOCV_ENSO.md (section 5).

---

1. Placement du code et héritage

Règle	Description
Code dans docv	Tout le code applicatif commun (back et front) est dans docv. enso ne duplique pas ce code ; il hérite (structure, design system, types) et configure (BDD, seeds, paramétrage, thème, i18n).
Spécifiques listés et confirmés	Tout spécifique enso (E1–E31) doit être listé dans SPECIFIQUES_PROJETS.md et passé en statut Confirmé avant toute implémentation. Aucun code spécifique (écran, action, service, intégration API) sans confirmation.
Pas de dépendance croisée	docv ne dépend pas d’enso. enso dépend de docv pour le socle commun ; aucune autre déclinaison produit n’est suivie dans ce dépôt.

1.1 Où va le code par projet

• docv-back : handlers/ (auth, folders, documents, offices, users, roles, site_texts, system_configuration, screen_config, action_config), services/, repositories/, clients/ (anchoring_client, ia_client). Aucune référence à « lawyer » ou « notary ».
• enso-back : mêmes modules que docv pour les zones 1–15 (ou réutilisation via dépendance docv) ; en plus handlers/ia/*, services/lawyer/, services/ia/ (ou équivalent) pour la zone 17. Pas de handlers/idnot ni de clients Mailchimp/OVH/Stripe côté périmètre avocat.
• Fronts : docv-front contient tous les écrans zones 1–15 ; enso-front hérite de la structure (composants, design-system, i18n) et ajoute ou surcharge (routes /ia/*, thème/i18n avocat).

---

2. API externes et couches back

Règle	Description
API externes côté back uniquement	Les API externes pertinentes du périmètre (ancrage, IA) sont consommées par le backend uniquement. Les fronts n’appellent jamais directement ces API ; ils appellent docv-back ou enso-back.
Handlers	Réception HTTP, extraction params/body, appel au service, retour JSON ou erreur. Pas de logique métier ni de SQL dans les handlers.
Services	Logique métier, orchestration, appels aux repositories et aux clients externes (anchoring, ia). Pas d’accès direct à la requête HTTP.
Repositories	Requêtes SQL (ou ORM) et mapping vers les modèles. Pas de règles métier.
Clients externes	Erreurs typées ; pas de fallback silencieux ; erreurs remontées avec contexte et journalisées.

2.1 Handlers — contenu autorisé et interdit

Autorisé : extraction des entrées (Path, Query, Json, State), appel à une fonction de service (ex. folder_service::get_by_id(uid)), mapping du résultat en réponse HTTP (status + JSON), mapping des erreurs en réponse HTTP (ex. AppError::into_response()). Une seule responsabilité par handler (une route = un cas d’usage).

Interdit : requêtes SQL ou accès direct au repository depuis le handler ; conditions métier (ex. « si l’utilisateur est admin alors… ») ; calculs, validations métier complexes ; appels directs aux API externes. En cas de besoin de logique, déplacer dans le service.

Exemple de structure (Rust) :
handler : extract Path(id), State(state) → service::get(state.db(), id) → map Ok to 200 Json, Err to IntoResponse.

2.2 Services — signature et responsabilités

Signature : les services reçoivent des types métier (identifiants, DTOs, options) et des références au pool BDD ou aux repositories ; ils ne reçoivent pas la requête HTTP (Request/Response). Retour : Result<T, E> ou type métier ; les erreurs sont typées (ex. AuthError, NotFoundError).

Responsabilités : appliquer les règles métier, orchestrer les appels aux repositories et aux clients externes (anchoring, ia), vérifier les permissions (ou déléguer au middleware après résolution du contexte). Pas d’écriture SQL : passer par les repositories.

2.3 Repositories — périmètre

Un repository par entité principale (ex. user_repository, folder_repository, document_repository). Méthodes typiques : find_by_id, list (avec filtres/pagination), create, update, delete. Retour : modèles ou Option<T> / Result. Aucune règle métier (pas de « si rôle alors requête différente » ; la condition est gérée par le service qui choisit quelle méthode du repository appeler).

---

3. Authentification

Règle	Description
Login par défaut docv	docv fournit un système de login par défaut (identifiant / mot de passe, session ou JWT, choix d’office) pour tous les types de membres (rôles des offices, membres des dossiers).
enso	Utilise ce login docv par défaut ; pas d’implémentation auth spécifique.

Référence : SPEC_01_auth_compte.md, ARCHITECTURE_DOCV_DETAILLEE.md (section 7).

---

4. Paramétrage (écrans, actions, options)

Règle	Description
Paramétrable sans changement de code	Chaque écran, chaque action et chaque option d’implémentation doit être paramétrable (activation, visibilité, droits, libellés) via BDD / config (screen_config, action_config, system_configuration).
Pas de listes en dur	Pas de listes d’écrans ou d’actions en dur dans le front ; chargement de la config (GET /screen-config, GET /action-config ou équivalent) au login ou au changement d’office ; rendu conditionnel des menus et boutons selon cette config.
Résolution	Service dédié (parametrage_service) qui fusionne plateforme → office → type de dossier → rôle → préférence utilisateur. Référence : PARAMETRAGE_ECRANS_ACTIONS.md.

4.1 Identifiants stables

Utiliser les identifiants stables du référentiel écrans et actions pour screen_config et action_config (ex. auth.login, folders.list, folders.detail, ia.crm, ia.dashboard). Pas d’invention de clés en dehors du référentiel sans l’y ajouter.

---

5. Code partagé (docv-shared, docv-core)

Règle	Description
docv-shared (Rust)	Validation (email, mot de passe, longueurs), formatage (dates, montants), constantes, règles métier pures sans I/O. Compilable en natif (backs) et en WASM (fronts) pour réutiliser la même logique. Place : docv/docv-shared/.
docv-core (TypeScript, optionnel)	Types et contrats API (DTOs), constantes partagées. Pas de logique métier lourde. Peut être généré depuis OpenAPI (docv-back). Place : docv/docv-core/.
Pas de duplication	Éviter de dupliquer la logique back/front ; privilégier docv-shared (WASM) ou docv-core pour garder les contrats alignés.

5.1 Quand utiliser docv-shared

Règles de validation (longueur mot de passe, format email, plages de dates), formatage affichage (montants, dates), constantes métier (codes statut, libellés techniques). Tout ce qui doit être identique côté back (vérification) et front (feedback immédiat) sans appel réseau. Ne pas y mettre de requêtes BDD ni d’appels HTTP.

---

6. Erreurs et logging

Règle	Description
Erreurs typées	Back : types dédiés (AppError, AuthError, NotFound, ValidationError) ; impl From et IntoResponse ; format JSON cohérent. Front : client API transforme les réponses en erreurs typées ; affichage via i18n.
Pas de fallback implicite	Aucun fallback silencieux ; aucune continuation après erreur sans comportement explicite et documenté. En cas d’erreur, remonter et journaliser.
Logging structuré	Niveau, contexte (request_id, user_uid, office_uid), pas de données sensibles. Pas de console.log / println! pour le métier ; utiliser le logger centralisé.
Clients externes	Erreurs ancrage/IA remontées avec contexte ; journalisées ; pas de continuation silencieuse.

6.1 Format des erreurs API (back)

Réponse JSON d’erreur recommandée : un corps structuré (ex. { "error": { "code": "VALIDATION_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "INTERNAL", "message": "..." } }). Le message est destiné au client ; ne pas y mettre de stack ni de chemins internes en production. Mapping HTTP cohérent : 400 (validation), 401 (non authentifié), 403 (non autorisé), 404 (ressource absente), 409 (conflit si pertinent), 500 (erreur interne ; message générique).

6.2 Logging — champs et exclusions

Inclure : niveau (info, warn, error), message, request_id (ou trace_id), user_uid et office_uid quand disponibles, duration_ms pour les requêtes, code erreur métier. Exclure : mots de passe, tokens, secrets, données personnelles non nécessaires au diagnostic (email peut être masqué partiellement si requis par la politique). Utiliser le logger structuré (ex. tracing avec champs) ; pas de concaténation de chaînes pour des données non contrôlées (risque d’injection dans les agrégateurs de logs).

---

7. Frontend

Règle	Description
Un seul client API	Tous les appels passent par un client unique vers docv-back ou enso-back. Pas d’URL ancrage ni IA côté front.
i18n	Clés structurées (auth., folders., …) ; textes par défaut dans docv ; pas de texte en dur dans l’UI.
Design system	Tokens (couleurs, typo, espacements), thème par défaut ; composants réutilisables ; enso surcharge (thème, couleurs) sans dupliquer la structure.
Accessibilité	ARIA, contraste, clavier (référence SCREENS_AND_FUNCTIONS_MAP.md et règles projet).

7.1 Client API — contrat

Un seul module client (ex. api/client.ts) : création d’instance avec base URL lue depuis une variable d’environnement (ex. NEXT_PUBLIC_API_URL), intercepteur qui ajoute le header Authorization: Bearer <token> (token lu depuis le store auth ou cookie), gestion des réponses (200 → body, 401 → invalidation session + redirection vers login, 4xx/5xx → conversion en erreur typée). Toutes les routes métier passent par ce client ; pas de fetch ou axios direct ailleurs dans le code métier.

7.2 i18n — structure des clés

Préfixe par zone puis par écran/action : auth.login.title, auth.login.error, auth.logout, auth.my-account.title, folders.list.title, folders.detail.actions.archive, etc. Fichiers par locale : fr.json, en.json (et autres si besoin). Clés de validation : validation.required, validation.email_invalid, etc. Pas de chaîne en dur dans les composants (boutons, labels, messages d’erreur, titres de page).

---

8. Sécurité et données

Règle	Description
Secrets	Aucun secret en front. URLs et clés API (ancrage, IA, IdNot, etc.) uniquement en back (variables d’environnement ou config serveur).
Validation des entrées	Validation côté back obligatoire ; optionnellement côté front via docv-shared (WASM) ; pas de confiance aveugle au client.
Autorisation	Matrice rôle × ressource × action ; vérification dans les services ou middleware avant toute opération sensible.
BDD docv	Pas de champs IdNot ou notaire dans le noyau docv (structure agnostique).

8.1 Variables d’environnement — back

Documenter dans .env.example ; ne jamais commiter de valeurs réelles. Noms attendus (ex.) : DATABASE_URL, JWT_SECRET, ANCHORING_URL, IA_API_URL, HOST, PORT. Lecture dans un module config (ex. Config::load_from_env()) ; pas de lecture dispersée de env::var dans les services.

---

9. Conventions de code (résumé)

À appliquer sur tout le code (docv, enso). Détail dans .cursor/rules/ et config lint.

Domaine	Règle
Langues	Répondre en français ; code, documentation du code et commits en anglais.
Taille et complexité	Max 250 lignes/fichier, 40 lignes/fonction ; max 4 paramètres ; profondeur d’imbrication max 4 ; complexité cyclomatique max 10.
Factorisation	Réutilisation systématique ; pas de code mort ; helpers centralisés.
TypeScript	Types de retour explicites ; pas de any ; pas de lazy imports ; imports nommés selon convention du projet.
Rust	Pas de unwrap en production ; erreurs typées, propagation ? ; format (rustfmt), Clippy.
Lint	Pas de contournement (pas de disable de règle sans justification documentée) ; pas de bypass par commentaires.

Référence : PLAN_REALISATION_DOCV_ENSO.md (section 5).

9.1 Seuils numériques (à faire respecter par la config)

• Fichier : 250 lignes maximum (lignes vides et commentaires exclus).
• Fonction : 40 lignes maximum (lignes vides et commentaires exclus).
• Paramètres : 4 maximum par fonction ; au-delà, regrouper dans un objet options typé.
• Imbrication : profondeur max 4 (blocs if/for/match imbriqués).
• Complexité cyclomatique : max 10 par fonction.
• Callbacks imbriqués : max 3 (ex. then/then/catch ; au-delà, décomposer ou async/await).

9.2 Nommage

• Rust : snake_case pour modules, fonctions, variables, champs ; PascalCase pour types, enum variants. Fichiers : snake_case (ex. auth_service.rs, folder_repository.rs).
• TypeScript/React : camelCase pour fonctions et variables ; PascalCase pour composants et types. Fichiers composants : PascalCase ou kebab-case selon convention du projet (ex. LoginForm.tsx, folder-list.tsx).
• Routes front : alignées sur le référentiel (ex. /login, /my-account, /folders, /folders/[id], /ia/dashboard pour enso).

9.3 Variables inutilisées

Supprimer les variables inutilisées plutôt que de les préfixer par _. Les paramètres de fonction non utilisés peuvent être omis ou nommés explicitement si la signature doit rester stable (ex. callback avec signature imposée).

9.4 Fichiers de configuration lint

• ESLint (fronts) : config partagée à la racine eslint.config.base.mjs (règles fix-lint) ; enso-front étend cette base via enso/enso-front/eslint.config.mjs. Lint des fronts : npm run lint (racine) ou npm run lint dans chaque workspace ; lint Rust : npm run lint:rust (docv workspace + enso-back). Référence : .cursor/agents/fix-lint.md.
• Clippy (Rust) : config partagée dans docv/Cargo.toml ([workspace.lints.clippy]) ; les crates docv-back et docv-shared héritent via [lints] workspace = true ; enso-back suit la même logique (voir Cargo.toml).

---

10. Documentation

Règle	Description
Mise à jour	Toute modification de code ou d’architecture entraîne la mise à jour de la documentation concernée dans docs/.
Emplacement	Évolutions : docs/features/ ; corrections : docs/fixKnowledge/ ; architecture et plans : docs/. Rationalisation : pas de doublons ; centralisation dans docs/.
Commentaires	Commentaires pour invariants, hypothèses, contrats, cas limites ; pas de commentaires qui répètent le code.

---

11. Commits

Règle	Description
Format	Message structuré avec : Motivations, Root causes, Correctifs, Evolutions, Pages affectées (en bullets).
Auteur	4NK ou Nicolas Cantu uniquement ; pas de Co-authored-by: Cursor ni d’auteur autre que 4NK ou Nicolas Cantu.
Atomicité	Commits atomiques et logiques ; pas de modifications non commitées durablement.

Référence : CONTRIBUTING.md ou conventions du dépôt.

11.1 Exemple de message de commit

Add folder archive endpoint and front action

**Motivations:**
- Allow users to archive folders from the detail screen.

**Root causes:**
- N/A (evolution).

**Correctifs:**
- N/A.

**Evolutions:**
- POST /folders/:id/archive in docv-back (handler + folder_service).
- Archive button on folder detail page (docv-front), gated by action_config.

**Pages affectées:**
- docv/docv-back/src/handlers/folders.rs
- docv/docv-back/src/services/folder_service.rs
- docv/docv-front/src/app/(dashboard)/folders/[id]/page.tsx
- docs/features/implementation/IMPL_02_dossiers.md (reference)

---

12. Interdictions (rappel)

Interdit	Description
Appels directs aux API externes depuis le front	Ancrage, IA, IdNot, etc. : back uniquement.
Logique métier ou SQL dans les handlers	Handlers : extraction + appel service + retour.
Fallback silencieux	Pas de continuation après erreur sans comportement explicite.
Textes en dur dans l’UI	Utiliser i18n (clés structurées).
Listes d’écrans/actions en dur	Utiliser screen_config / action_config.
Secrets en dur	Variables d’environnement ou config serveur.
Code spécifique non confirmé	Spécifiques enso listés et confirmés dans SPECIFIQUES_PROJETS avant implémentation.

---

13. Références

• Architecture : ARCHITECTURE_DOCV_ENSO.md, ARCHITECTURE_DOCV_DETAILLEE.md
• Plan et règles globales : PLAN_REALISATION_DOCV_ENSO.md (section 5)
• Implémentation docv : docv/IMPLEMENTATION.md — ordre des zones, stack, BDD, API
• Spécifiques : SPECIFIQUES_PROJETS.md
• Paramétrage : PARAMETRAGE_ECRANS_ACTIONS.md
• Référentiel écrans/actions : REFERENTIEL_ECRANS_ACTIONS.md
• Auth : SPEC_01_auth_compte.md
• IMPL_xx : features/implementation/README.md — index des fiches d’implémentation par zone