ia_dev/projects/kogus/docs/Deployment.md

Deployment – Env, seeds, site_texts, vérifications

Auteur : Équipe 4NK

Source de vérité multisite (dépôt LeCoffre)

La documentation canonique multisite (architecture, secrets imbriqués .secrets/<site>/<env>/, .secrets/kogus/<env>/, manifeste, runbooks, politique données LeCoffre ↔ ia_dev) est versionnée dans le dépôt applicatif dont conf.json expose deploy.repository_root (clone LeCoffre / kogus sur Gitea).

• Politique données : docs/features/multisite-data-policy-lecoffre-vs-ia-dev.md sur la branche suivie (ex. test).
• Checklist opérateur : docs/features/multisite-operator-master-checklist.md.
• Snippet wiki à publier : docs/features/wiki-deployment-multisite-snippet.md.
• Fichier aligné sur ce miroir : docs/Deployment.md (racine du clone LeCoffre).

URL type (adapter branche) : https://git.4nkweb.com/4nk/kogus/src/branch/test/docs/features/multisite-data-policy-lecoffre-vs-ia-dev.md.

Les sections suivantes reprennent le contenu de docs/Deployment.md du clone LeCoffre. Les chemins .md et répertoires .secrets/... ci-dessous sont relatifs à la racine Git du dépôt LeCoffre (repository_root), pas à la racine du dépôt ia_dev.

En cas de divergence entre ce fichier et le dépôt LeCoffre, priorité au dépôt LeCoffre.

---

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 du seed seed-site-texts-<env>.ts (champ textKey) doivent être exactement celles listées dans SITE_TEXTS_KEYS_INDEX du fichier env-full-<env>-for-bdd-injection.txt du même environnement.

Chemins :

• Multi-site (préféré) : .secrets/<site_dir>/<env>/… (ligne notaire : .secrets/lecoffreio/test/ avec SITE_CODE=lecoffreio côté processus / BDD ; voir docs/features/secrets-multisite-kogus-and-sites.md).
• Legacy (checkout non migré) : .secrets/<env>/… (ex. .secrets/test/).

Commandes :

SITE_CODE=lecoffreio
ENV=test
# Ligne notaire : répertoire disque lecoffreio/ (SITE_CODE processus = lecoffreio)
SECRETS_DIR=".secrets/lecoffreio/${ENV}"  # ou ".secrets/${ENV}" (legacy plat)

grep -oP 'textKey: "\K[^"]+' "${SECRETS_DIR}/seed-site-texts-${ENV}.ts" | sort -u > /tmp/seed-keys.txt
grep '^SITE_TEXTS_KEYS_INDEX=' "${SECRETS_DIR}/env-full-${ENV}-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 front-common/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 le fichier connectDB résolu sur la cible (canonique imbriqué .secrets/<site_code>/<env>/.env.<env>.connectDB, orchestrateur .secrets/kogus/<env>/.env.<env>.connectDB, ou legacy deploy/.env.<env>.connectDB, comme resolve_connect_db_path_on_target / import-v1.sh) 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/<site_code>/<env>/seed-site-texts-<env>.ts (ou legacy .secrets/<env>/…) ; clés dans env-full-*-for-bdd-injection.txt (SITE_TEXTS_KEYS_INDEX).

---

Déploiement applicatif

• Multi-site (runbook) : ordre test → préparation pprod/prod, migrations Prisma, smoke site-config — docs/features/multi-site-deploy-runbook.md ; snippet wiki docs/features/wiki-deployment-multisite-snippet.md.
• Admin local (exports / imports secrets par site, sans déploiement) : docs/features/secrets-devai-kogus-sites-and-imports.md — couches dev_ai / kogus / site, API back-admin, UI front-admin, fichiers matrice et catalogues actes.
• 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 (fichier dans le dépôt ia_dev).
• 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/<site_code>/<env>/.env.<env> (layout imbriqué obligatoire pour le multisite ; migration depuis l’ancien plat : SITE_CODE=lecoffreio bash deploy/scripts_v2/sites/lecoffreio/migrate-secrets-legacy-to-nested-lecoffreio.sh <env>…> depuis la racine du monorepo LeCoffre ; gabarits locaux optionnels : node deploy/scripts_v2/materialize-nested-secrets-mandatory.mjs). 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 : deploy.sh (LeCoffre) ne modifie pas la branche locale test (pas de git pull ni git stash sur test avec --sync-origin). Les fichiers déployés depuis l’orchestrateur (scripts, import-v1) proviennent d’un worktree détaché au ref kogus/<branche d’env> ; le working tree du clone principal peut donc contenir du WIP non poussé sans être écrasé — seul le tip kogus/test (ou branche alignée pour pprod/prod) part sur la cible après git push. Pour pprod/prod, l’index du clone principal doit rester propre (local_git_require_clean_index_strict).
• Versions : version.package_json_paths (backend, frontend) ; splash_app_name pour la notice.
• Dépendances npm (fiabilité avant phases distantes) : deploy.sh exécute hooks/verify-npm-lockfiles.sh sur la racine du worktree de déploiement (ref kogus/<branche>), après préparation de ce worktree et après le hook de concurrence. Pour chaque build_dir (ressources-common, back-common, front-common) : présence de package-lock.json, JSON valide, npm install --package-lock-only --dry-run (cohérence package.json ↔ lockfile), puis npm audit --audit-level=high. Sur la cible, deploy/scripts_v2/remote/deploy-app.sh exécute npm_ci_strict (suppression de node_modules puis npm ci sans repli npm install) pour les trois mêmes répertoires. Contournements documentés : DEPLOY_SKIP_NPM_LOCKFILE_VERIFY=1, DEPLOY_SKIP_NPM_AUDIT=1.
• Secrets / injection BDD : .secrets/<site_code>/<env>/env-full-<env>-for-bdd-injection.txt pour l’injection en BDD (répertoire imbriqué ; ancien plat .secrets/<env>/ uniquement le temps d’une migration). Super-admins systématiques après déploiement : clé SUPERADMIN_IDNOTS (liste users.idNot, virgules) — succède à SUPERADMIN_EMAILS ; voir deploy/scripts_v2/remote/sql/list-lecoffreio-users-by-office-name-pattern-readonly.sql et deploy/scripts_v2/remote/promote-super-admins.sh. 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.
• ShellCheck : npm run lint:shell exécute scripts/run-shellcheck.sh sur deploy/**/*.sh, scripts/*.sh et back-common/scripts/**/*.sh (options : --external-sources, --source-path=SCRIPTDIR, --severity=warning). Helpers déploiement : _lib/deploy-export-ssh-from-infos-json.sh (chargement infos.json), _lib/ssh-run-app-script.sh (lecoffre_ssh_run_remote_deploy_script, lecoffre_ssh_run_remote_mkdir_p, etc.). Détail : deploy/scripts_v2/hooks/README.md.