# WALDEC — acquisition et synchronisation explicites

Le lot [22407](../work-items/22407-waldec.md) livre `@data-asso/database` et la CLI `@data-asso/data-jobs`, utilisable depuis l’hôte ou le conteneur ponctuel du [lot 22400](../work-items/22400-compose-local.md). La source `nomenclature_waldec` alimente ObjetSocial. Le traitement utilise le [modèle](../domains/referentiel-associations.md) et s’exécute après les [migrations Prisma](prisma.md).

## Préparer et identifier la cible

À la racine, après `nvm use`, installation explicite depuis le miroir configuré (sans afficher NPM_PROXY_AUTH) :

```sh
PRISMA_SKIP_POSTINSTALL_GENERATE=true corepack yarn install --immutable
corepack yarn build:data-jobs
```

Le build génère/compile Prisma puis database puis data-jobs. Aucun import métier à l'installation ou au build. Les commandes d'exécution utilisent les sorties compilées ; elles ne rebâtissent pas implicitement.

Pour sync, préparer `.env.docker` selon la [procédure locale](sites-documentaires.md#compose-local--22400), avec les paramètres de la base dont l’alimentation est autorisée. Le wrapper hôte construit `localhost:POSTGRES_PORT/POSTGRES_DB` à partir de ce fichier et affiche la cible sans identifiants. Le conteneur utilise `postgres:5432` sur le réseau Compose. Dans les deux cas, le client reçoit une connexion explicite et se ferme en fin de traitement.

La base doit avoir été migrée par une opération distincte, sur une base neuve ou une évolution autorisée. `waldec:sync` ne migre, ne reset et ne démarre aucun service. Un PostgreSQL healthy ne prouve pas que le schéma est prêt. Les tests ne lisent pas ce fichier et n'utilisent jamais cette base.

## Synchroniser le contenu distribué, sans réseau

Le [snapshot attribué et qualifié](../../packages/database/referentiels/README.md) contient 297 lignes ; sa version est son SHA, aucun millésime métier inventé. Le registre TypeScript porte provenance, licence LO-2.0, référence ressource, format/encodage/en-têtes/clé et transformation `waldec-v1`.

```sh
corepack yarn waldec:sync --file packages/database/referentiels/waldec-cd58f33f.csv --sha256 cd58f33f78dfa4a000a856c8b01412e9d41c7bbfc676b0ffbc2151223d8448bd
```

SHA attendu obligatoire, 64 caractères hexadécimaux minuscules. `--source-version` permet de préciser la qualification d'un autre fichier connu ; par défaut, identité `sha256:<empreinte attendue>`. Cette valeur ne remplace jamais le contrôle des octets. Une nouvelle version doit être qualifiée volontairement avant son application. Transformation fixée par le code, sans option force contournant la vérification. La synchronisation lit les mêmes octets pour hash et validation et ne consulte jamais data.gouv.

## Synchroniser dans Docker

Après le [déploiement des migrations](prisma.md#déployer-et-contrôler-depuis-docker) sur la base autorisée :

```sh
corepack yarn docker:jobs sync --file packages/database/referentiels/waldec-cd58f33f.csv --sha256 cd58f33f78dfa4a000a856c8b01412e9d41c7bbfc676b0ffbc2151223d8448bd
```

Le répertoire de travail du conteneur est `/repo`. Le snapshot ci-dessus y est embarqué. Pour synchroniser un autre fichier qualifié ou conserver un fichier acquis, privilégier les commandes hôte. `docker:jobs` ne monte aucun dossier de l’hôte. Les fichiers acquis dans le système de fichiers du conteneur disparaissent à sa suppression.

Pour traiter un fichier externe dans Docker, réutiliser l’image déjà construite et ajouter un montage au `docker compose run` du bon projet. Avec `project` égal au nom affiché par `docker:status`, `csv` égal au chemin absolu du fichier et `sha` égal à son empreinte qualifiée, utiliser :

```sh
docker compose -f compose.yaml --env-file .env.docker --project-name "$project" run --rm --no-deps -T \
  --volume "$csv:/data/waldec.csv:ro" data-jobs sync --file /data/waldec.csv --sha256 "$sha"
```

La commande directe suppose PostgreSQL déjà démarré et la base migrée. Appliquer les [mêmes règles de sélection du projet](sites-documentaires.md#base-technique-persistance-et-reset-ciblé). Pour `acquire`, monter un répertoire inscriptible par l’utilisateur `node` du conteneur et passer une destination dans ce répertoire. L’acquisition contacte la source HTTP et fonctionne sans PostgreSQL.

## Acquérir séparément une version attendue

Sans configuration base et sans client Prisma :

```sh
corepack yarn waldec:acquire --destination .data-jobs/waldec.csv --sha256 cd58f33f78dfa4a000a856c8b01412e9d41c7bbfc676b0ffbc2151223d8448bd
```

Utiliser `.data-jobs/` ignoré par Git ou un répertoire externe. L'export amont est vivant ; si ses octets diffèrent, l'acquisition échoue, elle ne modifie pas le pin distribué. Aucun téléchargement latest implicite. URL et ressource viennent du registre, jamais d'instructions de métadonnées distantes.

Download temporaire privé, SHA sur octets, UTF-8/CSV validés avant finalisation sans écrasement. Réutilisation d'une destination seulement si SHA identique. Maximum 1 Mio et 30 s par essai ; trois essais au plus pour réseau/5xx/429 avec pauses bornées. Pas de réessai de SHA invalide ou erreur HTTP définitive. La taille HTTP est contrôlée si déclarée et non compressée ; filesize API peut être absent. Chaque temporaire est nettoyé ; l'opérateur supprime explicitement le fichier acquis lorsqu'il n'est plus utile, sans supprimer les données de base. Les limites conviennent à ce petit jeu, leur évolution exige un besoin qualifié.

## Données, transaction et compteurs

Les quatre en-têtes et leur ordre sont stricts. BOM accepté, chiffres conservés comme chaînes avec zéros ; code et parent sur six chiffres ASCII, libellé objet non vide. Aucun doublon même identique n'est absorbé ; diagnostic avec code/numéros de lignes. Les racines auto-référencées deviennent parent NULL/niveau 1. Un parent absent est créé avec libellé/parent/niveau NULL ; une entrée existante reste entièrement préservée. Une branche de profondeur inconnue garde niveau NULL sans emprunter un niveau historique au fichier. Ordre topologique et rejet des cycles, y compris cycle résultant avec des lignes anciennes conservées.

Chaque sync traçable crée une nouvelle ExecutionImport avant lecture du fichier, sans réutiliser les anciennes. Source initialisée explicitement par l'opération, FichierSource unique source/SHA, provenance et tentative rattachées sans effacer l'historique. Pas de ligne de nomenclature dans raw/stg ; aucune association modifiée. Les codes retirés du fichier restent conservés. Upsert par code, insereLe stable, provenance et modifieLe actualisés à la publication.

Hash, lecture et préparation hors transaction de publication. Transaction Prisma READ COMMITTED, maxWait 5 s, durée maximum 30 s, attente de verrou 10 s ; advisory transactionnel réservé au jeu, pris et utilisé sur le même `tx` que les lectures/écritures malgré le pool. État courant relu sous verrou ; seuls SHA + transformation égaux et état non invalidé donnent unchanged. A→B→A, nouvelle transformation ou invalidation demandent une application. Pas de décision basée sur une empreinte rencontrée dans tout l'historique.

Publication atomique : ObjetSocial, succès de la tentative, puis EtatReferentiel vers ce succès/transformation, avec invalidation remise NULL. Le verrou est libéré par commit/rollback et fermeture de connexion. Un succès unchanged crée sa propre trace mais ne touche ni données métier ni état appliqué.

`nbLignesFichier` mesure les lignes source validées ; `nbLignesChargees` les lignes source traitées, zéro pour unchanged/échec annulé. Les placeholders ne gonflent pas ce compteur : références et créations réelles, insertions et mises à jour figurent séparément dans métadonnées/résultat. Exclusions zéro ; nombre inconnu après erreur de lecture reste NULL. Une préparation n'est pas présentée comme une publication réussie.

## Résultats et reprise

JSON stdout : source/opération, statut `acquired`, `applied`, `unchanged` ou `failed`, SHA/version/transformation, tentative de sync et fichierId si connus, compteurs/diagnostic. Identifiants BigInt en chaînes. Acquisition possède un identifiant local, pas de fausse tentative DB. Exit 0 pour succès, exit 2 pour échec bloquant la suite. L'aide est disponible via `corepack yarn waldec:sync --help` et `waldec:acquire --help`.

| Situation | Diagnostic et reprise |
| --- | --- |
| Configuration/base injoignable | Vérifier cible affichée, daemon/port/identifiants autorisés ; aucune tentative DB ne peut être inventée si la connexion échoue. |
| Mauvais SHA, encodage, en-têtes, doublon ou cycle | Aucune publication partielle. Lire code/ligne/empreinte dans le résultat, corriger/qualifier le fichier puis créer une nouvelle tentative avec sa vraie empreinte. |
| Échec d'écriture | Rollback métier/état ; tentative echec/fin/diagnostic écrits séparément si la base répond. Corriger la cause puis relancer, sans effacer l'échec. |
| Attente verrou dépassée | Échec visible de cette tentative ; vérifier le traitement concurrent avant relance, ne pas supprimer un verrou de session sur une connexion du pool. |
| Commit/résultat incertain ou diagnostic impossible | Relire ExecutionImport et EtatReferentiel avant toute reprise. Aucun rejeu aveugle ni marquage echec d'un succès déjà enregistré. |
| Tentative interrompue en_cours | Résultat non confirmé, pas un succès ni un échec déduit de l'âge. Conserver la tentative ; relire l'état puis lancer une nouvelle tentative distincte si nécessaire. Ne pas reclasser automatiquement un processus encore en préparation. |

SIGINT/SIGTERM interrompent l'acquisition et laissent la synchronisation en cours terminer sa transaction bornée puis fermer le client ; une transaction validée reste un succès réel même si un signal a été reçu. Un SIGKILL/panne ne peut garantir un diagnostic final. Le serveur annule une transaction dont la connexion est perdue. Les tentatives en_cours sont conservées, pas réinitialisées. Aucun reset destructif ou commande de reclassement automatique.

Lecture de diagnostic dans un client SQL autorisé, sans exporter de connexion ni secret :

```sql
SELECT id, fichier_id, version_transformation, debut, fin, statut,
       nb_lignes_fichier, nb_lignes_chargees, diagnostic, metadonnees_source
FROM ref.execution_import
WHERE source_code = 'nomenclature_waldec' ORDER BY id DESC LIMIT 10;
SELECT * FROM ref.etat_referentiel WHERE source_code = 'nomenclature_waldec';
```

## Vérifier le code sans base existante

Après build : `corepack yarn test:waldec:unit` (règles, HTTP simulé, CLI/config) et `corepack yarn test:waldec:integration` (Docker PostgreSQL 18 jetable). Le contexte Docker sélectionné doit joindre un daemon existant ; la suite ne le démarre pas. Réseau/conteneur UUID labellisés `dataasso.waldec-test=<campagne>`, port loopback aléatoire, tmpfs sans volume persistant et fixtures synthétiques. Pas de .env réel ni URL externe acceptée par la suite ; Docker absent est un échec visible. Nettoyage en finally par ids exacts. Si interruption avant cleanup, inspecter les ids de cette campagne et supprimer seulement ces ressources, jamais prune global. Les [preuves du lot](../work-items/22407-waldec.md) distinguent commandes exécutées et limites.

Le [job GitLab 22444](../work-items/22444-regles-pipeline-ci.md#postgresql-jetable) appelle la même suite avec `--gitlab-postgres`. La suite authentifie son service PostgreSQL 18 neuf sur le loopback du pod avant la migration. Elle garde le worktree synthétique de la CLI, les données de test et les assertions de publication, de reprise et de concurrence.
