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_ENSO.md), [ARCHITECTURE_DOCV_DETAILLEE.md](ARCHITECTURE_DOCV_DETAILLEE.md), [PLAN_REALISATION_DOCV_ENSO.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](features/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](features/specs/SPEC_01_auth_compte.md), [ARCHITECTURE_DOCV_DETAILLEE.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](features/PARAMETRAGE_ECRANS_ACTIONS.md). |

### 4.1 Identifiants stables

Utiliser les **identifiants stables** du [référentiel écrans et actions](features/REFERENTIEL_ECRANS_ACTIONS.md) 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](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](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

```text
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_ENSO.md), [ARCHITECTURE_DOCV_DETAILLEE.md](ARCHITECTURE_DOCV_DETAILLEE.md)
- **Plan et règles globales** : [PLAN_REALISATION_DOCV_ENSO.md](PLAN_REALISATION_DOCV_ENSO.md) (section 5)
- **Implémentation docv** : [docv/IMPLEMENTATION.md](docv/IMPLEMENTATION.md) — ordre des zones, stack, BDD, API
- **Spécifiques** : [SPECIFIQUES_PROJETS.md](features/SPECIFIQUES_PROJETS.md)
- **Paramétrage** : [PARAMETRAGE_ECRANS_ACTIONS.md](features/PARAMETRAGE_ECRANS_ACTIONS.md)
- **Référentiel écrans/actions** : [REFERENTIEL_ECRANS_ACTIONS.md](features/REFERENTIEL_ECRANS_ACTIONS.md)
- **Auth** : [SPEC_01_auth_compte.md](features/specs/SPEC_01_auth_compte.md)
- **IMPL_xx** : [features/implementation/README.md](features/implementation/README.md) — index des fiches d’implémentation par zone