# Application Next.js

`app/nextjs` est le workspace privé `@data-asso/nextjs`. Il utilise Next.js 16.4.5 et React 19.3.0, App Router, TypeScript strict, ESLint et Cache Components. Les instructions [AGENTS.md](../../AGENTS.md) à la racine et le [complément Next](../../app/nextjs/AGENTS.md) s’appliquent.

## Consulter la nomenclature WALDEC

Depuis l’accueil, suivre « Nomenclature WALDEC ». La page affiche le code à six chiffres, le libellé et le parent immédiat. Le parent technique est indiqué par son code et peut situer un enfant. Il n’apparaît pas comme objet consultable.

La recherche compare les six chiffres tels quels, y compris les zéros initiaux. Toute autre saisie valide est un fragment littéral de libellé, insensible à la casse et sensible aux accents. Une saisie vide affiche le début de la liste. Les résultats sont triés par code et limités à 50. Quand d’autres correspondent, la page invite à affiner. « Aucun résultat » signale une recherche exécutée sur un référentiel disponible.

La fonction serveur applicative valide la saisie et transmet une connexion explicite à l’opération privée `@data-asso/common/server`. Celle-ci lit l’état et les objets via Prisma dans une transaction en lecture seule. La page consulte l’état actuel à chaque requête. Le pool appartient au processus Next et les paramètres de connexion sont réservés au serveur.

## Exécuter sur l’hôte

Depuis la racine, utiliser l’authentification du miroir Synaltic fournie à la session.

```sh
nvm use
corepack yarn install --immutable
corepack yarn build:nextjs:deps
```

Préparer `.env.docker` selon le [guide Compose](sites-documentaires.md#compose-local--22400), puis démarrer PostgreSQL avec `corepack yarn docker:db`. Pour une base autorisée, appliquer les [migrations](prisma.md#déployer-et-contrôler-depuis-docker), puis [synchroniser le snapshot WALDEC](waldec.md#synchroniser-dans-docker). Les deux opérations sont explicites. Lancer ensuite Next.js.

```sh
corepack yarn dev:nextjs
```

La page d’accueil répond sur [localhost:3000](http://localhost:3000). Si nécessaire, ajouter `--port <port-libre>` à la commande. Le lanceur utilise `localhost:<POSTGRES_PORT>` et les paramètres PostgreSQL du seul `.env.docker` du worktree. Le fichier est lu sans l’exécuter. L’URL n’est pas fournie en argument au CLI Next.

```sh
corepack yarn workspace @data-asso/nextjs lint
corepack yarn typecheck
corepack yarn build:nextjs
corepack yarn start:nextjs
```

Pour prévisualiser une version compilée, exécuter `start:nextjs` après `build:nextjs:deps` et `build:nextjs`. Le layout utilise `next/font/google`. La compilation des polices Geist et Geist Mono nécessite l’accès à Google Fonts.

## Exécuter le socle en Docker

Suivre le [guide Compose local](sites-documentaires.md#compose-local--22400), puis préparer les données de la base autorisée avant de lancer Next.

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

Ouvrir `http://localhost:<NEXTJS_PORT>/` (port 3000 par défaut). Le profil `full` ajoute les deux sites documentaires via `corepack yarn docker:all`. Next.js et les jobs se connectent à `postgres:5432` sur le réseau du projet. Le port PostgreSQL publié sur l’hôte n’entre pas dans cette connexion.

Le Dockerfile construit depuis la racine du monorepo. Le builder a besoin du miroir Synaltic avec le secret BuildKit et de `fonts.googleapis.com` et `fonts.gstatic.com`. Il génère et compile le client Prisma et common avant Next. Le build de Next n’a besoin d’aucune connexion PostgreSQL. Le serveur standalone s’exécute avec l’utilisateur `node` et lit sa configuration PostgreSQL lors de la première consultation.

## Diagnostiquer la disponibilité

Compose sonde une recherche exacte sur la page WALDEC depuis le conteneur. Le marqueur `data-waldec-readiness="ready"` est rendu après la lecture de l’état et de la table des objets. Un code HTTP 200 peut aussi accompagner une page d’indisponibilité. L’accueil reste accessible quand Next tourne.

`docker:app` et `docker:all` attendent la disponibilité pendant au plus 90 s après la compilation. Une commande en échec peut avoir laissé Next lancé. Vérifier d’abord `corepack yarn docker:status`. Utiliser le nom exact du conteneur Next du projet affiché pour lire le statut et les dernières sorties de la sonde.

```sh
docker inspect --format '{{.State.Health.Status}}{{range .State.Health.Log}}{{printf "\n%s" .Output}}{{end}}' <conteneur-next-du-projet>
```

| Dernier code de sonde | Situation | Action |
| --- | --- | --- |
| `ready` | Schéma du parcours lisible, état WALDEC appliqué et non invalidé, requête réussie | Ouvrir la page de consultation. |
| `database_unavailable` | PostgreSQL inaccessible ou accès interrompu | Vérifier le service, le réseau du projet et les paramètres locaux. |
| `schema_incomplete` | Une table ou colonne requise est absente | Vérifier le [statut des migrations](prisma.md#déployer-et-contrôler-depuis-docker), puis déployer si la cible est autorisée. |
| `waldec_not_loaded` | Aucun état WALDEC appliqué | Exécuter la [synchronisation qualifiée](waldec.md#synchroniser-dans-docker). |
| `waldec_invalidated` | L’état WALDEC est invalidé | Lire le [diagnostic du référentiel](waldec.md#résultats-et-reprise), puis resynchroniser sur décision de l’exploitant. |
| `configuration_unavailable` | Paramètres Next absents ou invalides | Vérifier le lanceur et le fichier du worktree. |
| `read_error` | Défaut de lecture imprévu | Examiner le schéma et la connectivité de la cible avec les outils d’exploitation autorisés. |
| `probe_timeout`, `probe_unavailable`, `unexpected_redirect`, `http_error`, `invalid_readiness_response` | Réponse Next incomplète ou inattendue | Vérifier le statut du conteneur et sa réponse HTTP locale. |

La sonde n’imprime que des codes fixes. Les commandes de migration et de synchronisation restent indépendantes. Les démarrages, sondes et consultations ne modifient aucune donnée métier.

## Reproduire la recette sur une base jetable

1. Préparer une copie avec le lockfile et ses dépendances, un `.env.docker` de test et quatre ports loopback libres, dont `POSTGRES_PORT` différent de 5432. Noter le nom de projet affiché. Démarrer seulement PostgreSQL avec `docker:db`. Contrôler avec psql que `public._prisma_migrations`, `ref.etat_referentiel` et `ref.objet_social` sont absentes.
2. Exécuter `docker:app` et contrôler le code de sortie, l’état du conteneur, le diagnostic `schema_incomplete` et le message de la page. Appliquer `docker:jobs migrate:deploy`. Garder Next lancé et vérifier, dans les 90 s, la transition vers `waldec_not_loaded`. Le schéma est présent, les objets, l’état et les tentatives WALDEC sont absents.
3. Exécuter la commande de synchronisation du snapshot ci-dessus. Relever son résultat `applied`, puis exécuter `docker:app`. Attendre `healthy` et `ready`. Redémarrer seulement Next sur la base chargée et vérifier le même état. Depuis l’accueil, chercher `001005` et vérifier son libellé et son parent `001000`. La recherche `SECOURISME` affiche deux entrées rattachées au parent technique `037000`. Une recherche de `037000` seul affiche « Aucun résultat ».
4. Identifier l’IP du conteneur Next sur le réseau du projet. Depuis ce conteneur, résoudre `postgres` avec le module Node `node:dns`. Comparer avec l’IP de PostgreSQL sur ce réseau. Sur PostgreSQL, vérifier `SHOW port` (5432) et, juste après la sonde, la présence d’une connexion de l’IP de Next dans `pg_stat_activity` pour la base de test. Arrêter seulement PostgreSQL et contrôler `database_unavailable`, puis le redémarrer sur le même volume et attendre le retour à `ready`. Next reste lancé.
5. Dans la seule base jetable, marquer la ligne `nomenclature_waldec` de `ref.etat_referentiel` invalide avec `invalide_le = clock_timestamp()` et un motif de recette. Attendre `waldec_invalidated`, puis resynchroniser le même snapshot qualifié. Contrôler `applied` et le retour à `ready` sans redémarrage de Next.
6. Autour des démarrages, sondes et consultations, comparer dans PostgreSQL les compteurs et les empreintes des lignes triées de `raw`, `stg`, `ref` et de l’historique des migrations, ainsi que les séquences de ces schémas. Après les deux synchronisations demandées, deux tentatives sont attendues. Consigner séparément la migration et l’invalidation volontaires. Nettoyer uniquement les ressources et le volume identifiés de cette copie de recette.

Pour ces opérations, reprendre les paramètres Compose explicites du [guide local](sites-documentaires.md#base-technique-persistance-et-reset-ciblé). Les [preuves du lot 22423](../work-items/22423-waldec-next.md#preuves) distinguent le déroulement attendu des résultats observés.

Pour comparer les témoins de lecture, exécuter ce bloc dans psql sur la copie de recette avant et après les phases web. Les sorties contiennent les noms, comptes et empreintes des tables, puis l’état des séquences.

```sql
BEGIN READ ONLY;
SELECT format(
  'SELECT %L, count(*), encode(sha256(convert_to(COALESCE(string_agg(to_jsonb(t)::text, %L ORDER BY to_jsonb(t)::text COLLATE "C"), %L), %L)), %L) FROM %I.%I AS t',
  schemaname || '.' || tablename, E'\n', '', 'UTF8', 'hex', schemaname, tablename
)
FROM pg_tables
WHERE schemaname IN ('raw', 'stg', 'ref')
   OR (schemaname, tablename) = ('public', '_prisma_migrations')
ORDER BY schemaname, tablename
\gexec
SELECT format(
  'SELECT %L, last_value, is_called FROM %I.%I',
  schemaname || '.' || sequencename, schemaname, sequencename
)
FROM pg_sequences
WHERE schemaname IN ('raw', 'stg', 'ref')
ORDER BY schemaname, sequencename
\gexec
COMMIT;
```

Pour l’invalidation contrôlée à l’étape 5, attendre une ligne retournée et conserver cette modification volontaire séparément des comparaisons en lecture seule.

```sql
UPDATE ref.etat_referentiel
SET invalide_le = clock_timestamp(), motif_invalidation = 'Recette 22423'
WHERE source_code = 'nomenclature_waldec' AND invalide_le IS NULL
RETURNING source_code;
```

## Reprendre une génération interrompue

`npx create-next-app` a lancé npm après avoir écrit le modèle. npm a découvert les workspaces et a échoué sur les dépendances internes `workspace:*` (`EUNSUPPORTEDPROTOCOL`). Depuis la racine, utiliser Yarn et conserver un seul lockfile. L’extension de `.yarnrc.yml` permet à ESLint de charger son parseur depuis Next.
