ia_dev/projects/kogus/docs/Deployment.md

# Deployment – Env, seeds, site_texts, vérifications

**Auteur** : Équipe 4NK

## Vérification site_texts (seeds, env, boot)

Objectif : aligner les clés site_texts entre seeds, env et boot (test, pprod, prod).

### 1. Seeds ↔ env (SITE_TEXTS_KEYS_INDEX)

Les clés de `.secrets/<env>/seed-site-texts-<env>.ts` (champ `textKey`) doivent être exactement celles listées dans `SITE_TEXTS_KEYS_INDEX` du fichier `.secrets/<env>/env-full-<env>-for-bdd-injection.txt`.

**Commandes** :

```bash
grep -oP 'textKey: "\K[^"]+' .secrets/test/seed-site-texts-test.ts | sort -u > /tmp/seed-keys.txt
grep '^SITE_TEXTS_KEYS_INDEX=' .secrets/test/env-full-test-for-bdd-injection.txt | sed 's/SITE_TEXTS_KEYS_INDEX=//' | tr ',' '\n' | sort -u > /tmp/env-keys.txt
diff /tmp/seed-keys.txt /tmp/env-keys.txt   # doit être vide
```

### 2. Alignement test / pprod / prod

Mêmes clés site_texts sur les trois environnements ; seuls les contenus peuvent différer (ex. mention [ENVIRONNEMENT DE TEST]). Comparer les listes de clés extraites des seeds test, pprod et prod.

### 3. Boot : SITE_TEXTS_BOOT_SCOPES

`SITE_TEXTS_BOOT_SCOPES` (dans `lecoffre-front-main/src/front/Stores/siteTextsBootConfig.ts`) doit couvrir tous les scopes chargés au boot. Valeur type : `["login", "my-account", "components", "folder", "forms", "documentTypes", "office", "thirdParty"]`. Aucun scope des seeds ne doit être absent du boot.

### 3.1 Scope des textes « tiers » (`thirdParty.roleLabel.*`)

- **Cible** : pour les clés dont le `textKey` commence par `thirdParty.` (ex. `thirdParty.roleLabel.courtier`), le champ **`scope`** en base et dans `seed-site-texts-<env>.ts` doit être exactement **`thirdParty`** (camelCase), comme dans `defaultSiteTextFallbacks.ts`. Le préfixe API publique utilise ce même identifiant : `GET .../site-texts?scope=thirdParty,...`.
- **À ne pas confondre** : les clés **`forms.thirdParty.*`** (formulaire édition tiers) restent en scope **`forms`**. La variante UI `THIRD_PARTY_UI_VARIANT = "third-party"` (tiret) concerne le parcours / l’affichage membre, **pas** le scope `site_texts`.
- **Vérification en lecture seule** (sur la base V2 de l’environnement) : le script **ne se connecte pas à une base locale** ; il copie le SQL et un runner sur le **serveur de déploiement** (SSH, même mécanisme que `scripts/e2e-verify-db-env.sh`), puis exécute `psql` **sur la cible** en utilisant `.secrets/<env>/.env.<env>.connectDB` **présent sur ce serveur** (`DATABASE_HOST=db` → `127.0.0.1` côté cible).

```bash
./scripts/verify-site-texts-thirdparty-scope-readonly.sh <test|pprod|prod>
```

Fichiers : `deploy/scripts_v2/remote/run-verify-site-texts-thirdparty-on-target.sh` (cible), `deploy/scripts_v2/remote/sql/verify-site-texts-thirdparty-scope-readonly.sql`. Équivalent SQL :

```sql
SELECT DISTINCT scope, text_key
FROM site_texts
WHERE text_key LIKE 'thirdParty.%'
ORDER BY scope, text_key;
```

**Convention cible** : une seule valeur de `scope` pour ces lignes : **`thirdParty`** (cohérent avec le préfixe `thirdParty.` du `text_key`).

**Données historiques** : d’anciennes lignes peuvent rester publiées avec **`scope: folder`** pour ces clés. Le backend **`getPublishedTextMap`** retient la version **publiée la plus récente** par `text_key` + locale (indépendamment du scope), afin qu’une migration seed vers **`thirdParty`** soit effective côté API. **Recommandation** : seeds sous **`thirdParty`** (voir `docs/fixKnowledge/site-texts-thirdparty-scope-seed-and-public-merge.md`) ; archiver les vieilles versions `folder` en super-admin si besoin de nettoyage.

Si une valeur inattendue apparaît (`third-party`, etc.), **corriger le seed** et republier. N’ajouter un scope supplémentaire à `SITE_TEXTS_BOOT_SCOPES` qu’en dernier recours si des données historiques ne peuvent pas être migrées tout de suite.

### 4. Évolution

- Nouvelle clé dans un seed : l’ajouter à `SITE_TEXTS_KEYS_INDEX` du même env et aligner test/pprod/prod.
- Nouveau scope en base : l’ajouter à `SITE_TEXTS_BOOT_SCOPES` si nécessaire au chargement initial.

---

## Fichiers de textes (validation métier)

Liste des fichiers contenant les textes affichés à l’utilisateur (libellés, messages d’erreur, placeholders) à transmettre au métier pour validation :

- **COMMON_UI_I18N** : commonUiI18nPart1.ts, commonUiI18nPart2.ts (modales, formulaires, dossiers, documents, rôles, types d’actes, souscription, Corbeille, erreurs métier, confrères, admin site texts, collaborateurs, etc.).
- **Upload / validation** : fileUploadUiI18n.ts, fileValidationI18n.ts.
- **Erreurs / login** : Utils/errorMessages/* (getUserFriendlyError, httpStatusMessages, humanizeError), loginErrorCodes.ts.
- **Site texts** : `.secrets/<env>/seed-site-texts-<env>.ts` ; clés dans env-full-*-for-bdd-injection.txt (SITE_TEXTS_KEYS_INDEX).

---

## Déploiement applicatif

- **Multi-site (`SITE_CODE`, secrets imbriqués)** : les scripts applicatifs (`deploy/scripts_v2`, `connect-db-paths.sh`) attendent **`.secrets/<site>/<env>/`** avec **`site ∈ { notary, enso, genealogie }`**. **`SITE_CODE`** (ou **`LECOFFRE_SITE_CODE`** / **`DEPLOY_SITE_CODE`**) doit être **exporté explicitement** avant ces scripts ; l’orchestrateur **ia_dev** ne le déduit pas depuis le `conf.json`. Sous **`projects/kogus/conf.json`**, **`deploy.secrets_path`** pointe souvent vers un arbre **plat** **`<secrets_path>/<env>/`** uniquement : **`orchestrator.sh`** et **`deploy/deploy-by-script-to.sh`** peuvent alors créer pour chaque site **notary**, **enso**, **genealogie** un lien **`<secrets_path>/<site>/<env>` → `../<env>`** si l’emplacement imbriqué n’existe pas encore et que **`<secrets_path>/<env>/`** est un répertoire. Un répertoire **réel** (non lien) existant n’est pas écrasé ; pour des secrets **distincts** par site, remplacer le lien par un vrai répertoire.
- **Orchestration ia_dev** : depuis la racine du dépôt ia_dev, `./deploy/deploy.sh <project_id> <env> [options]` exporte `IA_PROJECT_ID` puis exécute `orchestrator.sh`. Celui-ci enchaîne les scripts listés dans `deploy.hooks.phases` du `conf.json` du projet (chemins relatifs à `repository_root`), ou exécute `deploy.deploy_script_path` si `phases` est vide. `run-project-hooks.sh` délègue à `orchestrator.sh` (compatibilité). Cadrage : `deploy/DEPLOY_ORCHESTRATION_IA_DEV.md`.
- **Scripts** : `deploy/scripts_v2/` ; chemin projet dans ia_dev `projects/kogus/conf.json` (project_path, build_dirs, deploy.deploy_script_path, deploy.secrets_path).
- **Clé SSH déploiement (`DEPLOY_SSH_KEY`)** : définie dans `.secrets/<env>/.env.<env>`. Utiliser un chemin **portable** : par ex. `DEPLOY_SSH_KEY='$HOME/.ssh/id_ed25519_4nk'` (l’expansion de `$HOME`, `${HOME}` et un préfixe `~/` est appliquée par `lecoffre_deploy_resolve_deploy_ssh_key` après `load_dotenv_file_strict`, qui ne fait pas d’`eval`). Ne pas figer un autre compte système (`/home/desk/...`). Ordre de repli si la clé indiquée est absente : `$HOME/.ssh/id_ed25519_4nk`, puis `$HOME/.ssh/id_ed25519`. Avant toute connexion SSH, la clé retenue est validée avec `ssh-keygen -y`. Vérification réseau : `bash deploy/scripts_v2/run-verify-ssh.sh <env>` ou les trois d’un coup : `bash deploy/scripts_v2/run-verify-ssh-all-envs.sh`.
- **Modifications locales** : en **test**, le script `deploy.sh` met en stash les changements non commités avant pull/require_clean et les remet en place (stash pop) en fin de déploiement réussi. En **pprod** et **prod**, les changements locaux sont mis en stash sans remise en place (pas de développement local à conserver).
- **Versions** : version.package_json_paths (backend, frontend) ; splash_app_name pour la notice.
- **Secrets** : `.secrets/<env>/env-full-<env>-for-bdd-injection.txt` pour l’injection en BDD ; NOTARY_AI_AGENT_URL, NOTARY_AI_AGENT_TOKEN pour l’agent IA notaire (voir API.md).
- **Cartographie des checks de déploiement** : référence unique dans la doc projet (ex. projects/kogus/docs ou doc dédiée) ; ne pas dupliquer ici.