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

Implémentation détaillée — docv

Document de référence pour l’implémentation concrète du socle docv (zones 1 à 15). Il complète ARCHITECTURE_DOCV_DETAILLEE.md et les IMPL_xx en précisant l’ordre des zones, le schéma BDD, la surface API et les livrables par phase.

Plan de réalisation : PLAN_REALISATION_DOCV_ENSO.md (Phase 1).
Point d’entrée docv : README.md.

Consommation prioritaire des API docv (docv-back) par les fronts produits pour le périmètre métier commun — alignement architectural : ARCHITECTURE_DOCV_ENSO.md §1 (même énoncé).

---

1. Ordre d’implémentation par zone

Les zones doivent être implémentées dans un ordre respectant les dépendances (auth et offices d’abord, puis rôles et types, puis dossiers et documents, puis partage et abonnement). Ordre recommandé :

Ordre	Zone	IMPL	Dépendances	Objectif
1	1 — Auth et compte	IMPL_01	Aucune	Login, logout, mon compte ; base pour tout le reste.
2	5 — Offices et membres	IMPL_05	Zone 1	Offices, collaborateurs, utilisateurs, RIB ; contexte office actif.
3	6 — Rôles et permissions	IMPL_06	1, 5	Matrice rôle × ressource × action ; utilisé par toutes les zones protégées.
4	4 — Types de dossiers	IMPL_04	5	Référentiel des types de dossiers (par office).
5	3 — Documents et types	IMPL_03	5	Types de documents, upload/download ; prérequis pour les dossiers (documents liés).
6	2 — Dossiers	IMPL_02	4, 5, 6, 3	CRUD dossiers, liste, archivés, supprimés ; cœur métier.
7	7 — Parties et partage	IMPL_07	2, 5, 6	Parties au dossier, partage dossiers, invitations.
8	8 — Notes et rappels	IMPL_08	2, 3	Notes et rappels liés aux dossiers/documents.
9	14 — Contenus et paramètres	IMPL_14	—	Textes légaux, config publique ; utilisé par 13 et par le front.
10	13 — Admin plateforme	IMPL_13	5, 6, 14	Super-admin : rôles plateforme, plans, textes, configuration système.
11	9 — Abonnement et facturation	IMPL_09	5, 13	Abonnement par office, plans, prestataire paiement (back).
12	10, 11 — Espace client / invité	IMPL_10	2, 7	Portail client, accès invité par lien/code.
13	12 — Admin d’office	IMPL_12	5, 6, 2, 3	Portail admin office, métriques, liens vers rôles, users, types.
14	15 — Technique et design	IMPL_15	2, 3	Vérification ancrage, design system, paramétrage écrans/actions.

Les tables screen_config et action_config (paramétrage écrans/actions) peuvent être introduites avec la zone 6 ou 15 ; les seeds de paramétrage par défaut sont à prévoir en phase 1.3.

---

2. Stack technique et conventions

2.1 Backend (docv-back)

Élément	Choix recommandé	Convention
Langage	Rust	Pas de unwrap en production ; erreurs typées, propagation ?.
Framework HTTP	Axum ou Actix-web	Handlers async ; extraction (State, Json, Path).
BDD	PostgreSQL	Pool (ex. deadpool, SQLx) ; migrations versionnées (SQLx migrate ou Diesel).
ORM / requêtes	SQLx (compil-time) ou Diesel	Repositories par entité ; pas de SQL dans les handlers.
Logging	tracing / tracing-subscriber	Structuré (request_id, user_uid, office_uid) ; pas de println!.
Erreurs	Types dédiés (error/)	AppError, AuthError, NotFoundError ; impl From + IntoResponse ; messages non sensibles.
Config	Variables d’environnement	.env.example documenté ; config::Config (DATABASE_URL, JWT_SECRET, ANCHORING_URL, IA_API_URL).
Clients externes	reqwest ou équivalent	clients/anchoring_client.rs, clients/ia_client.rs ; timeouts, erreurs typées.

Impl. enso (tests) : depuis docv/docv-back, cargo test inclut les tests du module dp_layout_fs (routes dp-layout-entries / dp-layout-file : base canonique partagée dp_layout_base_canonical, tri dossiers/fichiers, lecture texte, rejet d’extension et d’échappement de chemin). Les routes instance-layout-entries / instance-layout-file sur /api/v1/offices/:officeUid/... réutilisent la même lecture disque ; la racine est résolue pour tout membre de l’office (dp_layout_root sous instances, sinon instances/<dp_archetype>, sinon instances). Routage api_v1 : chemin relatif en suffixe d’URL après dp-layout-entries/, dp-layout-file/, instance-layout-entries/ ou instance-layout-file/ (segments encodés séparément), avec repli ?path= — voir docs/features/DOCV_API_ENSO_FRONT_MAP.md.

2.2 Frontend (docv-front)

Élément	Choix recommandé	Convention
Framework	Next.js (App Router) ou équivalent	Routes sous app/(auth)/, app/(dashboard)/ ; layout commun dashboard.
Langage	TypeScript	Types stricts ; types API alignés sur le back (ou docv-core / OpenAPI).
Client API	fetch ou axios	Un seul client (api/client.ts) ; base URL depuis env ; intercepteur auth (Bearer) ; gestion 401 → redirect login.
État global	Context ou Zustand	Auth (user, office actif, token) ; chargement screen_config/action_config au login.
i18n	Clés structurées (fr.json, en.json)	Pas de texte en dur ; clés par zone (auth., folders., …).
Design system	Tokens + composants	design-system/tokens, theme ; composants ui/ (Button, Input, Table, Modal).

2.3 Code partagé

• docv-shared (Rust, optionnel) : validation (email, mot de passe, longueurs), formatage (dates, montants), constantes ; compilable en natif (back) et en WASM (front). Référence : ARCHITECTURE_DOCV_DETAILLEE section 5.
• docv-core (TypeScript, optionnel) : types et DTOs API, constantes ; peut être généré depuis OpenAPI (back) pour garder les contrats alignés.

---

3. Schéma BDD synthétique (zones 1–15)

Tables principales et lien avec les zones. Les migrations sont à ordonner selon l’ordre des zones ci-dessus (ex. users/sessions avant offices, offices avant office_members, etc.).

Table	Colonnes clés	Zones utilisatrices
users	uid, email, password_hash, name, phone, preferences, created_at	1, 5, 6, 12, 13
sessions	id, user_uid, token_hash ou jti, expires_at	1 (ou JWT stateless)
offices	uid, name, address, created_at	5, 12, 13
office_members	user_uid, office_uid, role_uid (ou lien rôle)	5, 6, 12
office_rib	office_uid, iban_encrypted, bic, …	5
roles	uid, name, scope (office | platform), …	6, 13
role_permissions	role_uid, resource, action (ou matrice)	6, 13
folder_types	uid, office_uid, name, …	2, 4
document_types	uid, office_uid, name, …	3, 12
folders	uid, office_uid, name, folder_type_uid, status, description, archived_at, deleted_at	2, 7, 8, 10, 12
folder_parties	folder_uid, party_uid ou customer_uid, role	2, 7
folder_shares	folder_uid, sharee_uid ou email, role, token, expires_at	7, 10, 11
documents	uid, folder_uid, document_type_uid, name, file_path ou storage_key, created_at	2, 3, 7, 8, 10, 15
notes	uid, folder_uid ou document_uid, content, author_uid, created_at	8
reminders	uid, folder_uid ou document_uid, due_at, notified, …	8
site_texts	key, locale, version, content, published_at	13, 14
system_configuration	key, value, sensitive, category	13, 14
screen_config	identifiant, office_uid, scope, config (JSON)	15, paramétrage
action_config	identifiant, office_uid, scope, config (JSON)	15, paramétrage
plans	uid, name, features, price, seats, active	9, 13
subscriptions	office_uid, plan_uid, status, current_period_end, …	9
subscription_invites	office_uid, email, role_uid, token, status	9
invitations	token, folder_uid, email, role, expires_at, status	7, 11

Entités optionnelles : contacts, addresses (liés à offices ou users selon modèle). Pas de champs IdNot ou notaire dans le noyau docv.

3.1 Socle actuel (implémenté dans docv-back + enso-front)

Toolchain Rust : le dépôt enso fixe 1.88.0 via rust-toolchain.toml à la racine du monorepo ( docv-back et enso-back ) ; utiliser rustup et un PATH où ~/.cargo/bin précède le cargo système.

Migrations 20260330140000_offices_folders.sql : tables offices, office_members, folders. Au démarrage, ensure_offices_folders_schema applique la migration ; ensure_folders_purpose_operation_type ajoute folder_purpose / operation_type et renomme l’office démo legacy « Cabinet démo » en « Entreprise démo (fictive) ». 20260403140000_roles_minimal.sql : table roles minimale si absente (support office_members.role_uid). ensure_impl_role_rows_for_all_offices (avant et après le seed des offices démo) et la partie roles de ensure_auxiliary_rows_for_new_office_if_impl après chaque création d’office en seed/migration assurent une ligne roles d’office (« Membre ») lorsque le schéma IMPL impose office_members.role_uid. ensure_impl_folder_type_rows_for_all_offices (même rythme) et la partie folder_types du même helper assurent « Dossier standard » par office lorsque folders.folder_type_uid et la table folder_types existent. Les insertions office_members utilisent require_office_scoped_role_uid (roles.office_uid uniquement — pas de rôle « global », pas d’échec ignoré) ; les insertions de dossiers IMPL utilisent require_office_scoped_folder_type_uid sans création implicite ; repair_seed_demo_user_office_memberships_if_needed rattrape client@example.com sans membre. migrate_legacy_demo_single_office_to_demo_and_type_offices_if_needed (dans db/mod.rs) convertit une base un office démo + 8 dossiers structures en 9 offices (8 types + démo). seed_demo_office_if_needed : si offices est vide, crée les 9 offices (libellés types + DEMO_OFFICE_DISPLAY_NAME) et rattache client@example.com à chacun. seed_demo_dp_folders_for_cabinet_demo_if_needed : pour chaque office type, un dossier dp_structure_demo (instances/<archetype>/) ; pour l’office démo, un dossier avec instances/entreprise_demo/ (schéma IMPL : la ligne folder_types doit déjà exister pour l’office via le bootstrap ci-dessus).

Migration 20260401160000_user_stub_lists.sql : tables user_notifications, user_pending_documents, user_conversations, conversation_messages. ensure_user_stub_lists_schema au démarrage ; seed_stub_lists_demo_if_needed insère un exemple de notification, document en attente et conversation (utilisateur client@example.com) lorsque les tables sont vides et qu’au moins un dossier existe. PATCH /api/v1/notifications/:id met à jour is_read pour la ligne appartenant au porteur du jeton.

Placeholder migration démo : pendant migrate_legacy_demo_single_office_to_demo_and_type_offices_if_needed, un office peut être renommé temporairement en __docv_migrating_legacy_demo__. Ce nom est exclu des listes GET /api/v1/offices et du détail office ; les requêtes « premier office » (liaison e-mails démo / utilisateurs orphelins) l’ignorent également. Au démarrage, remove_stale_legacy_demo_migration_placeholder_office_if_needed supprime cet office s’il n’a aucune ligne dans folders ; sinon un warn est journalisé (migration interrompue — intervention manuelle possible).

Migration 20260401170000_folder_documents.sql : table folder_documents (pièces rattachées à un dossier). Les événements de création / mise à jour de dossier et d’ajout de document alimentent user_notifications pour les autres membres de l’office (voir handlers dans api_v1.rs).

Migration 20260402100000_folder_documents_storage_pending_idx.sql : colonnes storage_url et mime_type sur folder_documents ; index sur user_pending_documents selon le fichier de migration. ensure_folder_documents_storage_columns au démarrage (voir db/mod.rs).

Migration 20260402110000_folders_title_legacy_compat.sql : si la table folders existe sans colonne title mais avec name, renomme en title ; sinon ajoute title avec défaut vide. Évite l’échec du seed stub et des requêtes API sur des BDD de test héritées. ensure_folders_title_legacy_compat au démarrage (db/mod.rs, enchaînée dans main.rs après ensure_offices_folders_schema).

Préfixe public (navigateur) : {origin}/docv-api — nginx retire /docv-api/ et propage /api/v1/... au backend docv-back.
Authentification API métier : en-tête Authorization: Bearer <access_token> (même JWT que celui émis par POST /oauth/token, claims avec iss: "docv-back").

Liste des routes HTTP et câblage handlers ↔ enso-front : features/DOCV_API_ENSO_FRONT_MAP.md §1 — référence unique (ne pas dupliquer ce tableau ici).

POST /api/v1/folders : si la colonne folders.folder_type_uid est présente (IMPL), handle_create_folder appelle db::ensure_folder_type_uid_for_api_create puis insère avec folder_type_uid, folder_purpose = client_operation, champs DP nuls et description vide ; sinon insert minimal inchangé.

Fichiers pièces (optionnel) : variable DOCV_FILE_STORAGE_DIR sur docv-back : POST /api/v1/folders/:uid/documents/binary enregistre les octets et expose GET /api/v1/files/:docUid (Bearer) ; storage_url relative au site (/docv-api/api/v1/files/...). Sans répertoire, le front conserve le flux JSON métadonnées uniquement.

Dossiers permanents types (données versionnées) : arborescence data/dossiers-permanents/ dans le monorepo ; colonnes BDD folders.dp_archetype, folders.dp_layout_root, folder_documents.dp_mirror_path ; sync Git optionnelle après upload (DOCV_DP_GIT_*). Voir features/DOSSIERS_PERMANENTS_DATA_GIT.md. Côté enso-front, la fiche société affiche un explorateur du gabarit instances/… via les routes office instance-layout-* (toujours visible pour les membres de l’office) ; la fiche dossier continue d’utiliser dp-layout-* par UID de dossier — distinction produit : MODELE_SOCIETES_ET_DOSSIERS_DOPERATION.md § « Arborescence disque dans l’UI ».

enso-front : client docvFetch (src/lib/docv/client.ts) avec NEXT_PUBLIC_DOCV_API_BASE optionnelle (sinon {origin}/docv-api). Toute réponse 401 sur ce client (et sur l’upload binaire qui partage assertDocvResponseOk) enchaîne comme logout : effacement jeton + état OAuth, puis GET /oauth/sign-out avec return_url = /?signed_out=1 (invalidateLocalSessionAndGoHome, ensoSignedOutHomeReturnUrl). Types domaine dans src/lib/domain/types.ts. Après lecture du JWT session, enrichUserFromDocv appelle GET /api/v1/me pour aligner nom, id et email sur la BDD. Les offices et dossiers affichés viennent de GET /api/v1/offices et GET /api/v1/folders via fetchUserCompanies / écrans (un seul enchaînement GET /offices côté catalogue). La fiche dossier (/company/[id]/case/[caseId]) enchaîne en parallèle GET /api/v1/offices/:uid et GET /api/v1/folders/:uid (loadCasePage) ; la demande de pièce côté cabinet utilise GET /api/v1/offices/:uid/members pour lister les clients (role métier). La liste complète des dossiers d’un office reste sur GET /api/v1/folders?office_uid= pour la page société et le catalogue ; la page société expose aussi POST /api/v1/folders (nouveau dossier). Sur la fiche dossier : PATCH /api/v1/folders/:uid, DELETE pièce, POST /api/v1/pending-documents / DELETE /api/v1/pending-documents/:id ; la messagerie appelle POST /api/v1/conversations/:id/messages puis refetch des listes. Le DocvStubListsProvider regroupe en un lot parallèle GET /api/v1/notifications, GET /api/v1/pending-documents et GET /api/v1/conversations pour dashboard, sidebar et messagerie (données persistées ; jeux démo optionnels via seed au démarrage).

Checklists « documents attendus » (par operation_type slug) : JSON statique dans enso/enso-front/src/lib/operationChecklists/, sans endpoint docv ; i18n sous case.operationChecklist.<slug>. Détail : OPERATION_CHECKLISTS.md.

Alignement doc installation : contenu à reporter dans INSTALLATION_ENVIRONNEMENT.md §4.2 (tableau + paragraphe Bearer / nginx) — voir le supplément consolidé installation-docv-enso-front-supplement.md et l’échantillon patches/INSTALLATION_4.2_DOCV_FRAGMENT.md. enso/enso-front/.env.example documente NEXT_PUBLIC_DOCV_API_BASE.

Cartographie fichier à fichier (handlers Rust ↔ modules Next) : features/DOCV_API_ENSO_FRONT_MAP.md §1 — à mettre à jour lors de l’évolution de api_v1.rs ou des appels docvFetch (sans recréer de second tableau dans ce fichier).

---

4. Surface API par zone (synthèse)

Cette section est une vision synthétique par zones du socle générique docv ; elle n’est pas équivalente route par route à l’implémentation actuelle de docv-back dans ce dépôt. Pour les chemins réellement exposés et câblés avec enso-front, utiliser DOCV_API_ENSO_FRONT_MAP.md §1.

Endpoints principaux exposés par docv-back, regroupés par zone. Préfixe commun (ex. /api/v1) et authentification (Bearer ou session) à appliquer selon la config.

Zone	Méthodes et chemins (synthèse)
1 — Auth	POST /auth/login, POST /auth/logout, GET /auth/me, PATCH /users/me, POST /auth/change-password
5 — Offices	GET/POST/PUT /offices, GET /offices/:id, GET/PUT /offices/:id/rib, GET /collaborators, GET/PATCH /collaborators/:id, GET /users (scope office)
6 — Rôles	GET/POST/PUT /roles, GET /roles/:id, GET/PUT (matrice permissions)
4 — Types dossiers	GET/POST/PUT /folder-types, GET /folder-types/:id
3 — Documents	GET/POST /folders/:folderId/documents, GET/PUT/DELETE /documents/:id, upload/download
2 — Dossiers	GET/POST/PUT /folders, GET /folders/:id, POST /folders/:id/archive
7 — Partage	GET/POST/PATCH/DELETE /folders/:id/shares, POST /invitations, GET /invitations/:token
8 — Notes / rappels	GET/POST/PATCH/DELETE /folders/:id/notes, GET/POST/PATCH/DELETE /reminders
14 — Contenus	GET /site-texts/public?key=...
13 — Admin plateforme	GET /super-admin/overview, GET/PATCH /super-admin/roles, GET/POST/PATCH /super-admin/plans, GET/POST/PATCH /super-admin/texts, GET/PATCH /super-admin/config
9 — Abonnement	GET /subscription, POST /subscription/subscribe, PATCH /subscription, GET/PATCH /subscription/collaborators, POST /subscription/invites
10, 11 — Client / invité	GET /client-dashboard/folders, GET /client-dashboard/folders/:id, POST /auth/invitee, GET /third-party/folders
12 — Admin office	GET /admin/metrics (ou agrégation de endpoints existants)
15 — Technique	GET/POST /anchor/verify (optionnel), GET /config/public (feature flags, config publique)

Détail complet des paramètres, body et réponses : voir les IMPL_xx correspondants.

---

5. Checklist Phase 1 (livrables)

5.1 Phase 1.1 — Backend docv (Rust)

• Projet Cargo docv-back avec structure (handlers, services, repositories, models, middleware, config, error, clients).
• Config : chargement DATABASE_URL, JWT_SECRET, ANCHORING_URL, IA_API_URL depuis l’env ; .env.example documenté.
• BDD : migrations pour toutes les tables zones 1–15 (ordre cohérent avec la section 3) ; pool de connexions au démarrage.
• Auth : POST /auth/login, POST /auth/logout, GET /auth/me ; génération et validation JWT (ou sessions) ; middleware auth sur routes protégées.
• Zones 1, 5, 6, 4, 3, 2, 7, 8, 14, 13, 9, 10, 12, 15 : handlers et services implémentés selon IMPL_01 à IMPL_15 ; endpoints documentés ou cohérents avec la section 4.
• Clients externes : anchoring_client et ia_client (stubs ou réels) ; appel uniquement depuis les services ; pas d’exposition au front.
• Erreurs : types typés, impl IntoResponse ; logging structuré (tracing) ; pas de fallback silencieux.
• Livrable : le service démarre, répond aux endpoints listés, lit/écrit la BDD, et consomme (ou stub) ancrage et IA côté back.

5.2 Phase 1.2 — Frontend docv

• Projet Next.js (ou équivalent) avec structure app/, components/, api/, i18n/, design-system/, stores/, hooks/, types/.
• Client API unique : base URL depuis env, header Authorization (Bearer), gestion 401 → redirect login ; pas d’appel direct ancrage/IA.
• Auth : pages login, logout-callback, my-account ; formulaire profil et changement mot de passe ; chargement user et office actif (context/store).
• Zones 2 à 15 : pages et composants pour chaque écran du référentiel (zones 1–15) ; appels API vers docv-back uniquement.
• Design system : tokens (couleurs, typo, espacements), thème par défaut, composants de base (Button, Input, Table, Modal, etc.).
• i18n : clés structurées (auth., folders., …) ; fr.json et en.json avec textes par défaut.
• Paramétrage : chargement screen_config / action_config (GET /screen-config, /action-config ou équivalent) au login ; affichage conditionnel des menus et boutons selon la config.
• Livrable : front utilisable en autonomie sur la BDD et le back docv ; toutes les fonctionnalités des écrans zones 1–15 accessibles selon paramétrage.

5.3 Phase 1.3 — Données et paramétrage par défaut

• Seeds : rôles par défaut, matrice de permissions par défaut, types de documents et types de dossiers par défaut, textes site (clés legal., auth., …), configuration système (clés feature flags, options).
• Paramétrage : seeds ou migrations pour screen_config et action_config (identifiants stables des écrans et actions zones 1–15) ; résolution par office et rôle opérationnelle.
• Livrable : une instance docv déployée contient toutes les structures et données par défaut réutilisables pour enso.

---

5.4 OAuth2 — plusieurs clients et branding (docv-back)

Le binaire docv-back expose /oauth/authorize, /oauth/sign-in (formulaire HTML), /oauth/sign-out (effacement cookie session navigateur) et /oauth/token. Comportement actuel :

• OAUTH_CLIENT_ID : une liste d’identifiants clients séparés par des virgules (ex. enso-web,autre-client). Chaque valeur doit correspondre au client_id transmis par les applications (ex. enso-front). Le secret OAUTH_CLIENT_SECRET reste unique pour l’instant (tous ces clients partagent le même secret côté échange de code).
• Branding de la page de connexion HTML : fichier JSON versionné docv/docv-back/tenants.default.json (clé default + objet clients indexé par client_id). Les champs optionnels par client fusionnent avec default. Champs : page_title, heading, subtitle, primary_color, accent_color, surface_color, text_color, submit_label, font_family (couleurs en #RRGGBB, polices sans < > ; pour limiter les injections CSS).
• Surcharge runtime : variable OAUTH_TENANTS_JSON (contenu JSON complet) ou OAUTH_TENANTS_PATH (chemin vers un fichier JSON). Si absent ou invalide, repli sur tenants.default.json embarqué.
• Le client_id est lu depuis le return_url interne (/oauth/authorize?...&client_id=..., y compris avec préfixe /docv-api/...) pour choisir le bloc clients.<id>.
• OAUTH_BROWSER_PATH_PREFIX (défaut /docv-api) : préfixe ajouté aux Location et au action du formulaire HTML pour /oauth/sign-in et au return_url stocké ; sans cela le navigateur résout /oauth/… sur l’hôte du front (404). Laisser vide uniquement si l’API OAuth est publiée à la racine du nom d’hôte.
• DOCV_USERS_PK_COLUMN : id (défaut, migrations docv-back actuelles) ou uid si la table users existante utilise uid comme clé primaire (schémas plus anciens / alignés IMPL).
• Durées JWT / cookie et rattachement offices : voir AUTH_SESSION.md (variable unique DOCV_OAUTH_ACCESS_TOKEN_TTL_SEC, options DOCV_DEMO_MEMBER_EMAILS et DOCV_LINK_ORPHAN_USERS_TO_FIRST_OFFICE).

---

6. Références

• ARCHITECTURE_DOCV_DETAILLEE.md — couches, responsabilités, structure back/front.
• features/implementation/README.md — index des IMPL_01 à IMPL_15.
• features/REFERENTIEL_ECRANS_ACTIONS.md — identifiants stables écrans et actions.
• features/PARAMETRAGE_ECRANS_ACTIONS.md — modèle de paramétrage.