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 :

```text
${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.<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.<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.<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

```text
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)