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

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

Référence pour l’arborescence versionnée sous 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 et 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) :

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 §5.
• Principes IA / workspace : IA_GRANDS_PRINCIPES.md.
• Procédure clone AnythingLLM : ANYTHINGLLM_DATAROOM_SYNC.md.