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 :

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).

./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 :

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.