smart_ide/services/docv/enso-docs/features/ENSO_FRONT_BACKEND_CONTRACT.md

Contrat front enso-front → backends (audit)

Document vivant : priorité front ; les évolutions d’API sont pilotées par les écrans, la doc suit.

Carte détaillée docv HTTP : DOCV_API_ENSO_FRONT_MAP.md

1. Appels docvFetch → docv-back (/docv-api)

Liste exhaustive des routes /api/v1/*, handlers, modules TS et écrans : DOCV_API_ENSO_FRONT_MAP.md §1 (référence unique, non dupliquée ici).

OAuth (hors docvFetch navigateur direct) : authorize + POST token via Next docv-token.

Déconnexion : logout efface jeton + état OAuth (sessionStorage), puis redirige vers GET {docv}/oauth/sign-out?return_url=<origin>/?signed_out=1 afin d’effacer le cookie HttpOnly docv_oauth_session (sans quoi /oauth/authorize pouvait encore délivrer un code sans mot de passe). / redirige vers /dashboard?signed_out=1 ; ProtectedRoute propage signed_out=1 jusqu’à /login?signed_out=1. LoginPageInner n’enchaîne pas le SSO tout de suite ; relance automatique après un court délai ou bouton manuel. Même return_url pour une 401 docv (invalidateLocalSessionAndGoHome). Les durées et sign-out sont détaillés dans docv/AUTH_SESSION.md.

Ressource	Rappel
docv métier (/docv-api + /api/v1/…)	Voir tableau §1 de la carte API ; persistance : tables users, offices, office_members, folders, folder_documents, listes utilisateur (user_notifications, user_pending_documents, user_conversations, conversation_messages).

Données hors backends : les checklists « documents attendus » par type d’opération (lib/operationChecklists/data/*.json) ne passent ni par docv ni par enso-back ; le front les affiche selon folders.operation_type (slug). Voir OPERATION_CHECKLISTS.md.

2. Types JSON attendus par le front (camelCase)

• Company (modèle UI après officeAndFoldersToCompany) : champs office + dossiers ; organizationArchetypes = liste triée des dp_archetype distincts des dossiers (types d’organisation DP : groupe / filiale / SCI · commercial · IS / IR), pour affichage « Types d’organisation » sur le tableau de bord, la fiche société et la sidebar.

• Chargement dashboard : le catalogue GET /api/v1/offices et les stubs (notifications, pending, conversations) ne doivent pas être bloqués sur l’objet user React encore null alors que le jeton est déjà en session — le filtre d’appel est la présence du Bearer (useOfficesCatalog, useDocvStubListsState).

• Notification : id, type (new_document | request_document | case_update), message, companyId, companyName, caseId?, createdAt, isRead.

• PendingDocument : id, name, description, companyId, companyName, caseId, caseName, requestedAt, dueDate?.

• Conversation : id, contactName, contactRole, lastMessage, lastMessageAt, unreadCount, messages[]
  Message : id, senderId, senderName, senderRole (client | cabinet), content, createdAt, isRead.

Les handlers docv-back sérialisent en camelCase pour ces trois ressources en réponse.

Corps POST /api/v1/pending-documents (aligné docv-back, snake_case dans le JSON) : target_user_uid, office_uid, case_uid, name, description, optionnellement case_name, due_date.

Corps POST /api/v1/folders/:uid/documents : name, type, category, uploaded_by, size (conventions actuelles du client) ; optionnel storage_url, mime_type.

POST /api/v1/folders/:uid/documents/binary : corps brut = fichier ; métadonnées en en-têtes X-Enso-* (voir DOCV_API_ENSO_FRONT_MAP.md §1), optionnel X-Enso-Dp-Mirror-Relative-Path ; activé si DOCV_FILE_STORAGE_DIR est défini ; réponse pièce peut inclure dpMirrorPath (camelCase). Sync Git : DOCV_DP_GIT_* — DOSSIERS_PERMANENTS_DATA_GIT.md.

GET /api/v1/folders/:uid : champs dossier optionnels snake_case dp_archetype, dp_layout_root (alignés sur docv-back FolderJson).

Arborescence DP sur disque : listing et fichier texte — GET /api/v1/folders/:folderUid/dp-layout-entries / dp-layout-file (périmètre dossier) ; GET /api/v1/offices/:officeUid/instance-layout-entries / instance-layout-file (périmètre société, racine sous instances/ résolue côté serveur pour tout membre d’office, sans filtre dp_structure_demo seul — voir carte API §1).

Corps POST /api/v1/conversations/:id/messages : content (chaîne).

PATCH /api/v1/notifications/:id : { "isRead": true } pour enregistrer la lecture côté BDD (notification appartenant à l’utilisateur Bearer). Corps vide accepté (comportement identique à isRead: true).

3. enso-back (zone 17 / spécifique)

Le front ne consomme pas encore d’JSON métier enso-back dans le socle actuel ; les appels Next /api/* concernent surtout OAuth.
Point d’entrée de présence : GET /api/v1/enso/status sur le port enso-back (voir PORTS_ENSO.md) — JSON : service, ready, database, champs réservés anchoring / ia (null tant que non intégrés). ready est vrai lorsque le pool PostgreSQL répond à SELECT 1.

4. Prochaines évolutions (hors ce lot)

• Stockage objet (S3 / pré-signé) ou réplication hors disque local du répertoire DOCV_FILE_STORAGE_DIR.
• Appels enso-front → enso-back pour zone 17 quand les routes existent.