# 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](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](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](../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](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](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](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](../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.