ia_dev/projects/lecoffreio/docs/IMPORT_V1_DEPENDENCIES.md

Dépendances du script de déploiement et de l'import V1

Référence : deploy/scripts_v2/deploy.sh, deploy/scripts_v2/import-v1.sh

---

1. Script principal de déploiement (deploy.sh)

Option --import-v1

• Déploie d'abord front/back/resources via deploy-app.sh
• Puis appelle import-v1.sh ENV --yes

Fichiers copiés vers la cible avant import-v1

Fichier local	Destination cible
.secrets/ENV/env-full-ENV-for-bdd-injection.txt	$APP_ROOT/deploy/env-full-ENV-for-bdd-injection.txt
.secrets/ENV/.env.ENV.connectDB	via deploy.sh → /etc/lecoffreio/<domain>/connectDB.env

Prérequis déploiement standard

• .secrets/<env>/.env.<env> (ex. .secrets/test/.env.test) : connexion SSH et config déploiement (DEPLOY_SSH_*, etc.) — à ne pas confondre avec connectDB.
• .secrets/ENV/.env.ENV avec variables DEPLOY_*
• Clé SSH configurée (proxy 4nk.myftp.biz)
• env-full-ENV-for-bdd-injection.txt (optionnel mais recommandé pour build frontend et setSettings)

---

2. Script d'import V1 (import-v1.sh)

Phases et scripts appelés

Phase	Script	Dépendances
0	cleanup-disk-space.sh	Aucune
1	migrate-resolve-database.sh, prisma-baseline-resolve-all.sh, etc.	connectDB, env-full, infos (S3)
1.5	import-v1-data-direct-into-v2.sh	connectDB (DATABASE_V1_* et DATABASE_*), psql, pg_dump, pg_restore
2	recover-files-from-v1.sh → recover-files-from-v1.ts	connectDB, dist, FILE_ENCRYPTION_MASTER_KEY, IPFS
2.5	migrate-files-from-s3.sh → migrate-files-from-s3.ts	DÉSACTIVÉ (exit 0, pas de migration réelle)
2.6	migrate-files-without-ipfs.sh → migrate-files-without-ipfs.ts	connectDB, dist
3a	migrate-ribs-from-s3.sh → migrate-ribs-from-s3.ts	DÉSACTIVÉ (exit 0, pas de migration réelle)
3b	migrate-ribs-to-ipfs.sh → migrate-ribs-to-ipfs.ts	connectDB, dist
4	reanchor-all.sh	connectDB, dist
5	check-v1-migration-status.sh	connectDB (local)

Gestion des erreurs par phase

• Phase 2.5, 2.6 : warning si échec, continuation
• Phase 3a, 3b : error + exit 1 si échec
• Phase 4 : warning si échec (documents invalides), continuation vers Phase 5
• Phase 5 : warning si échec

---

3. Fichiers de configuration requis

Obligatoires pour import-v1

Fichier	Emplacement	Usage
infos.json	.secrets/ENV/ (sur cible)	S3, autres variables migration (credentials BDD V1 sont dans connectDB)
.env.ENV.connectDB	.secrets/ENV/ (local) → deploy/ cible	Credentials BDD V2 (DATABASE_) et V1 (DATABASE_V1_); scripts chargent explicitement la version utilisée, sans fallback

Optionnels

Fichier	Emplacement	Usage
env-full-ENV-for-bdd-injection.txt	.secrets/ENV/ (local) → deploy/ cible	setSettings, build frontend
infos-migration-scaleway.json	.secrets/ENV/ (sur cible)	Variables S3 Scaleway (priorité sur infos.json) pour inject-s3-vars

Connexion BDD sur la cible

Les scripts remote (recover-files-from-v1.sh, migrate-ribs-from-s3.sh, etc.) utilisent get_connectdb_env_file qui retourne :

${APP_ROOT}/.secrets/${ENV}/.env.${ENV}.connectDB

import-v1.sh copie connectDB vers deploy/ puis vers .secrets/ENV/ sur la cible, afin que apply-connectdb et les scripts remote trouvent le fichier.

Format .env..connectDB (V1 et V2)

Le fichier contient deux jeux de variables (aucun fallback) :

• V2 (cible) : DATABASE_HOST, DATABASE_PORT, DATABASE_USERNAME, DATABASE_PASSWORD, DATABASE_NAME (optionnel : DATABASE_URL). Utilisées par tous les scripts qui se connectent à la base cible (Phase 5, reanchor-all, seed-site-texts, etc.). Chargement explicite : load_connectdb_v2 "$APP_ROOT" "$ENV". DB version: v2.
• V1 (source Scaleway) : DATABASE_V1_HOST, DATABASE_V1_PORT, DATABASE_V1_USERNAME, DATABASE_V1_PASSWORD, DATABASE_V1_NAME. Utilisées uniquement par les scripts d’import V1 (import-v1-data-direct-into-v2.sh, read-v1-contacts-emails.sh). Chargement explicite : load_connectdb_v1 "$APP_ROOT" "$ENV". DB version: v1.

Chaque environnement (test, pprod, prod) doit avoir le bloc V1 (DATABASE_V1_*) dans son .env..connectDB (ajout uniquement, ne pas remplacer les variables V2). Chaque script qui ouvre une connexion base doit indiquer en commentaire la version utilisée (DB version: v1 ou DB version: v2). Aucun fallback entre sources. Après migration, backend.env ne doit plus exister (sauvegarde puis suppression) ; la seule source pour la BDD est .env..connectDB.

---

4. Outils système requis (sur la cible)

Outil	Usage
connectDB	Credentials BDD V1/V2 (load_connectdb_v1/v2 dans import-v1-data-direct-into-v2.sh)
psql	Connexion BDD (postgresql-client)
pg_dump	Export schéma/données V1
pg_restore	Restauration en mode merge
python3/awk	Parsing des enums V1 (fallback awk si python3 absent)

---

5. Scripts S3 désactivés

migrate-files-from-s3.ts et migrate-ribs-from-s3.ts sont désactivés : la dépendance @aws-sdk/client-s3 a été retirée (vulnérabilités). Ils affichent un message et font process.exit(0).

• Phase 2.5 : le script shell vérifie l'existence du fichier .ts ; s'il existe, il l'exécute (exit 0 sans migration réelle) ; sinon warning et continuation
• Phase 3a : le script TS s'exécute et exit 0 ; la phase ne bloque pas

Pour réactiver : npm install @aws-sdk/client-s3 puis restaurer le script depuis l'historique Git.

---

6. Flux des fichiers connectDB et env-full

Local:
  .secrets/ENV/.env.ENV.connectDB
  .secrets/ENV/env-full-ENV-for-bdd-injection.txt
  .secrets/ENV/infos.json

Cible (après deploy + import-v1):
  $APP_ROOT/deploy/.env.ENV.connectDB     (copié par import-v1 pour apply-connectdb)
  $APP_ROOT/.secrets/ENV/.env.ENV.connectDB  (copié par import-v1 depuis deploy/ pour scripts remote)
  $APP_ROOT/deploy/env-full-ENV-for-bdd-injection.txt  (copié par deploy.sh)
  $APP_ROOT/.secrets/ENV/infos.json        (doit exister pour Phase 1.5)

---

6.1 Règles d'échange V1/V2 (référence)

Référence : règles d'échange V1/V2

Pour le détail des flux (qui lit/écrit, où), voir docs/OPERATIONS.md section « Échanges V1 / V2 : règles et flux ». Résumé :

• Import au déploiement (import-v1-data-direct-into-v2.sh) : V1 strictement en lecture (SELECT, pg_dump, COPY TO STDOUT) ; toutes les écritures (INSERT, UPDATE, TRUNCATE, ANALYZE) ciblent V2 uniquement via psql_admin (base DATABASE_NAME).
• Sync au login (backend V1ToV2LoginSyncService) : connexion V1 en lecture seule (SELECT, scoped by user offices) ; upsert et ancrage uniquement en V2 (Prisma).
• backend.env : n'existe plus sur les cibles ; sauvegardé dans .secrets/<env>/backup/ puis supprimé à chaque sync. Source unique BDD : .env.<env>.connectDB.

---

7. Contraintes migration V1 → V2

V1 en lecture seule

import-v1-data-direct-into-v2.sh ne fait jamais d'écriture sur la base V1. Seules des opérations en lecture (SELECT, pg_dump, COPY TO STDOUT) sont exécutées sur V1. Toutes les écritures (INSERT, UPDATE, TRUNCATE, pg_restore) ciblent V2 uniquement.

Vérification env-full avant setSettings

Avant setSettings, import-v1.sh vérifie que env-full-ENV-for-bdd-injection.txt existe sur la cible (deploy/ ou .secrets/ENV/). Aucune copie n'est effectuée. Si absent : erreur avec indication de lancer via deploy.sh --import-v1 ou de synchroniser .secrets.

Pas de sync git ni build dans import-v1

import-v1.sh n'exécute ni git fetch/reset ni npm run build. Le code sur la cible doit déjà être à jour (via deploy.sh --import-v1 qui déploie avant d'appeler import-v1).

Ensures après Phase 1.5

Après l'import V1 (Phase 1.5), import-v1.sh rejoue ensure-default-office-roles.sh, ensure-admin-office-roles-from-affiliations.sh et ensure-role-permissions-matrix-folders.sh pour garantir la cohérence office_roles, users.office_role_uid (depuis role_in_office) et role_permissions_matrix.

Schéma V1 et admins (role_in_office)

La table user_office_affiliations (ajoutée en migration 20251010105200) contient role_in_office. Si la base V1 possède cette table avec des valeurs comme "admin", "administrateur de l office", l'import les copie. Le script ensure-admin-office-roles-from-affiliations.sh (exécuté après ensure-default-office-roles) met à jour users.office_role_uid vers le rôle admin de l'office lorsque role_in_office indique un admin pour l'office principal de l'utilisateur.

Observabilité post-ensure

Les scripts ensure affichent des requêtes de contrôle après exécution (comptages office_roles, users avec admin, role_permissions_matrix) pour confirmer la complétude.

Architecture host-native (test/pprod/prod)

Test, pprod et prod utilisent la même architecture sans Docker. Les checks V2/baseline dans import-v1.sh forcent DATABASE_HOST=127.0.0.1 pour ces environnements.

Logs et suivi de l'import (Phase 1.5)

Le script import-v1-data-direct-into-v2.sh produit des logs préfixés [import-v1-direct] pour suivre l'avancement : env, mode, source V1 et cible V2 ; en mode merge, nombre de tables puis pour chaque table le type de merge, le nombre de lignes V1 et « MERGE table done ». Les phases de import-v1.sh (0 à 5) sont loggées via info/success/error. L'intégralité de la sortie (phases 0 à 5, y compris Phase 4 réancrage) est en outre écrite dans un fichier sous ./logs/ : import-v1-<env>-<timestamp>.log.

Merge mode : modifications V2 limitées aux données modifiées ou ajoutées

En mode merge, l'import n'écrase pas les lignes V2 lorsque les données V1 sont identiques. La clause ON CONFLICT ... DO UPDATE SET est complétée par un WHERE (colonnes) IS DISTINCT FROM (EXCLUDED.colonnes) : seules les lignes pour lesquelles au moins une colonne (hors PK et champs V2 exclus) diffère sont mises à jour. Les champs V2 exclus (watermarked_, rib_anchor_, folder_anchor_uid, etc.) ne sont jamais mis à jour par l'import.

Cutoff par date de dernier import OK

Pour limiter le volume et les conflits, un filtre optionnel par date peut être appliqué : seules les lignes V1 dont updated_at (ou created_at) est postérieur à une date de référence sont importées ou synchronisées.

• Fichier : deploy/import-v1-last-ok.txt (gitignoré). Exemple versionné : deploy/import-v1-last-ok.txt.example.
• Format : une ligne par env, test=2026-03-09T00:00:00Z (ISO-8601). Clé default possible. Si le fichier est absent ou la clé env manquante, aucun filtre n'est appliqué.
• Portée : import batch import-v1-data-direct-into-v2.sh (mode merge) et sync au login V1ToV2LoginSyncService / V1ToV2MergeHelper. Le filtre ne s'applique qu'aux tables exposant updated_at et/ou created_at.
• Mise à jour : en fin d'import batch (merge), le script enregistre la date courante UTC comme « dernier import OK » dans ce fichier.
• Désactivation : supprimer le fichier ou la ligne <env>=..., ou laisser la valeur vide.

---

8. Références

• docs/MIGRATION.md : variables V2, isolation Scaleway
• docs/DEPLOYMENT.md : prérequis déploiement
• docs/SYNC_V1_TO_V2_AT_LOGIN_PLAN.md : plan (non implémenté) de synchronisation V1 → V2 au login (droits, dossiers, documents)