# Dossiers permanents : données sur disque, Git et synchronisation

Référence pour l’arborescence versionnée sous [`data/dossiers-permanents/`](/data/dossiers-permanents/), le lien avec la base PostgreSQL (docv-back) et le flux Git vers les clones (AnythingLLM, CI locale, etc.).

## 1. Stratégie validée (monorepo)

- **Arborescence type** : dans ce dépôt, répertoire `data/dossiers-permanents/` (versionné).
- **Manifeste** : `data/dossiers-permanents/manifest.json` décrit l’arbre canonique (dérivé du dossier type métier ; archive zip locale non versionnée dans `docs/`).
- **Instances de démonstration** : `data/dossiers-permanents/instances/<id>/` — gabarits nommés `groupe_*`, `sous-groupe_*`, `filiale_*`, `entreprise_*` (segments `sci|commercial` × `is|ir`).
- **Dépôt Git dédié (option B)** : si le volume des binaires dépasse ce que le monorepo peut supporter, dupliquer uniquement `data/dossiers-permanents/` dans un dépôt séparé ; conserver le même schéma de chemins pour que les outils et la doc restent valides. **Git LFS** recommandé pour les pièces lourdes si tout reste dans le monorepo.
- **Branche et identifiants push** : sur serveur (ex. test), utiliser une **clé de déploiement** ou token en configuration **hôte / secrets déploiement** — ne pas committer de secrets ; ne pas modifier arbitrairement les `.env` des postes de dev (documenter les variables attendues uniquement).

## 2. Convention de nommage

Format logique : `{groupe|sous-groupe|filiale|entreprise}_{sci|commercial}_{is|ir}` (ex. `groupe_sci_is`, `filiale_commercial_ir`).

- **Filiales hétérogènes** : un même groupe type peut contenir des filiales aux juridiques / fiscaux différents ; la **forme** des dossiers reste celle du manifeste (sous-arborescence `sci` ou `commercial` selon le segment).
- **Sous-groupe** : même forme qu’un groupe, imbriqué sous `sous-groupes/<nom>/`.

## 3. Variables d’environnement (docv-back)

| Variable | Rôle |
|----------|------|
| `DOCV_DP_GIT_SYNC` | Si `1` ou `true`, tente un `git add` / `commit` / `push` après upload réussi (voir ci-dessous). |
| `DOCV_DP_GIT_REPO_ROOT` | Chemin absolu vers la racine du dépôt Git (souvent le clone du monorepo sur le serveur). |
| `DOCV_DP_GIT_DATA_SUBPATH` | Sous-chemin relatif depuis la racine (défaut : `data/dossiers-permanents`). |
| `DOCV_DP_GIT_REMOTE` | Nom du remote (défaut : `origin`). |
| `DOCV_DP_GIT_BRANCH` | Branche à pousser (optionnel ; si vide, pas de `push` ciblé — utilise branche courante du clone). |

**Déploiement (`deploy/scripts_v2`)** : `remote/sync-docv-deploy-opts-to-docv-env.sh` met à jour `docv/docv-back/.env` avec `DOCV_DP_GIT_REPO_ROOT` = racine du clone sur la cible (`ENSO_REMOTE_ROOT`) lorsque la variable n’est pas fournie côté déploiement, et `DOCV_DP_GIT_DATA_SUBPATH` (défaut `data/dossiers-permanents`). `DOCV_DP_GIT_SYNC`, `DOCV_DP_GIT_REMOTE`, `DOCV_DP_GIT_BRANCH` ne sont écrites que si non vides. Voir `deploy/enso-deploy.env.example` et `deploy/scripts_v2/deploy.sh` (exports SSH).

Upload binaire existant : `DOCV_FILE_STORAGE_DIR` (fichiers servis par UUID). En complément :

| En-tête HTTP | Rôle |
|--------------|------|
| `X-Enso-Dp-Mirror-Relative-Path` | Chemin **relatif** sous `DOCV_DP_GIT_DATA_SUBPATH` (sans `..`) où une copie du fichier est écrite pour Git / AnythingLLM (défaut si sync actif : `_uploads/<folder_uid>/<sanitized_name>`). |

## 4. Cohérence BDD ↔ disque

- Table `folders` : `dp_archetype`, `dp_layout_root` (ex. `instances/groupe_sci_is`).
- Table `folder_documents` : `dp_mirror_path` (chemin relatif sous `data/dossiers-permanents/` vers la copie « lisible »).

**Lecture navigateur (enso-front + docv-back)** : au niveau **société**, **`GET /api/v1/offices/:officeUid/instance-layout-entries`** (et **`instance-layout-file`**) sert à parcourir le référentiel **`instances/`** pour tout membre de l’office ; la racine disque est résolue sans exiger un dossier **`dp_structure_demo`** seul (voir [MODELE_SOCIETES_ET_DOSSIERS_DOPERATION.md](MODELE_SOCIETES_ET_DOSSIERS_DOPERATION.md) et [DOCV_API_ENSO_FRONT_MAP.md](DOCV_API_ENSO_FRONT_MAP.md)). Au niveau **d’un dossier**, le parcours reste **`GET /api/v1/folders/:folderUid/dp-layout-*`**.

Les migrations appliquent les colonnes au démarrage de docv-back (même mécanisme que les migrations folder_documents existantes).

## 5. Concurrence et limites

- **docv-back** sérialise les opérations **miroir disque + `git add` / `commit` / `push`** pour un même processus via un mutex async (`AppState.dp_git_serial`), ce qui limite les courses entre requêtes concurrentes.
- Des conflits restent possibles si plusieurs instances de docv-back ou d’autres acteurs modifient le même dépôt ; une file dédiée ou une branche par office peut compléter ce dispositif.
- Le push échoue si le clone n’a pas de remote configuré ou sans droits ; l’upload API reste réussi si l’écriture disque + BDD ont réussi — l’échec Git est **journalisé** (`warn`).

## 6. Régénérer les instances et le manifeste

Depuis la racine du dépôt (Node ≥ 18) :

```bash
node tools/dp-seed/generate-dp-data.mjs
```

Prérequis : liste d’entrées zip `tools/dp-seed/_zip_all_paths.txt` (générée par `unzip -Z1 docs/5-DOSSIER\ TYPE\ INFORMATIQUE.zip > tools/dp-seed/_zip_all_paths.txt` lorsque l’archive est présente localement).

## 7. Références

- Plan produit : dataroom / DP dans [`FONCTIONNALITES_IA_LOCAL_A_INTEGRER.md`](FONCTIONNALITES_IA_LOCAL_A_INTEGRER.md) §5.
- Principes IA / workspace : [`IA_GRANDS_PRINCIPES.md`](IA_GRANDS_PRINCIPES.md).
- Procédure clone AnythingLLM : [`ANYTHINGLLM_DATAROOM_SYNC.md`](ANYTHINGLLM_DATAROOM_SYNC.md).