# Note de conception — panneau « Intrants de base » du GUI

> **Pour qui :** le **mainteneur** du GUI.

But : saisir depuis **un endroit unique** les [intrants communs](intrants-communs.md)
de l'écosystème, en distinguant **constantes** et **défauts surchargeables**.

> Extension assumée du plan de contrôle (gelé — cf. [`positionnement.md`](positionnement.md)),
> au même titre que le [dimensionnement](dimensionnement-ressources.md). Décidée le
> 2026-06-26.

> **Statut, revu le 2026-09-06 : le panneau est construit.** Ce document reste la note de
> *conception* — il explique les arbitrages, pas l'état. Trois écarts entre ce qui était
> proposé et ce qui a été fait, et ils comptent :
>
> 1. **La migration en répertoires n'a eu lieu que pour `all/`.** `group_vars/all/` porte
>    bien `00-instance.yml` (tenu à la main) et `10-intrants.yml` (écrit par le GUI) ;
>    `proxmox.yml` et `modeles_vm.yml` sont restés des **fichiers plats**. Le §3 les
>    présente encore comme des répertoires.
> 2. **Les constantes Proxmox ont déménagé chez l'hébergeur.** L'accès au cluster
>    (`proxmox_api_*`) n'est plus un intrant du tenant : il vit dans
>    `proxmox-hebergeur.yml`, à côté d'`underlay.yml`, parce qu'un cluster appartient à
>    qui possède le matériel. Cf. `config-proxmox.md`.
> 3. **Les « points ouverts » du §8 sont tranchés** par ce qui a été bâti : la liste de
>    rappel des secrets attendus est bien dans le panneau, en lecture seule, et elle se
>    *recense* (`scripts/voute.py lister`) au lieu d'être recopiée — trois copies manuelles
>    avaient existé, toutes avaient divergé.

## 1. Décisions cadre (validées)

1. **Secrets : hors périmètre.** Le GUI n'affiche ni ne stocke aucun secret. Les
   `vault_*` et tokens Proxmox restent édités via Ansible Vault en ligne de commande.
   Le panneau peut, au plus, afficher une **liste de rappel en lecture seule** des
   secrets attendus (sans valeur).
2. **Nomenclature : lecture seule** dans le panneau — à une exception près, l'**`index`**,
   qui est le seul champ d'adressage saisissable (panneau *Réseau*, écrit chirurgicalement).
   Tout le reste — supernet, sous-réseaux, passerelles, VLAN, VMID — se **dérive** et **P20
   refuse qu'on l'écrive**. *(Ce point disait « l'édition de `supernet`/VLAN/catégories reste
   dans `plan/nomenclature.yml` » : ces valeurs n'y sont plus du tout.)*
3. **Conception avant code** (cette note).

## 2. Modèle : constante vs défaut surchargeable

- **Constante** — une seule valeur, pas de surcharge. Éditée *uniquement* au panneau ;
  apparaît en **lecture seule** dans les formulaires d'hôte (contexte).
- **Défaut surchargeable** — valeur globale qui **ressurgit** comme défaut là où
  l'intrant réapparaît (hôte / groupe). Le formulaire d'hôte la montre **pré-remplie
  et marquée « hérité »** ; toute saisie locale devient une **surcharge** (badge
  « surchargé » + bouton « rétablir le défaut »).

Classification de départ : voir [`intrants-communs.md` §2](intrants-communs.md).
Résumé : *Constantes* = `domaine_interne`, nomenclature, accès Proxmox, golden
template, secrets. *Défauts* = timezone, nœud/stockage/pont Proxmox, DNS internes,
politiques de durcissement, relais SMTP, `ciuser`/compte `ansible`.

## 3. Persistance — fichiers cibles, sans perte de commentaires

Contrainte : pas de dépendance non-stdlib (souveraineté) → pas de round-trip YAML
préservant les commentaires (ruamel). Solution : **fichiers possédés par le GUI**,
réécrits en bloc avec un **en-tête généré** (comme `hosts.genere.yml`), à côté des
fichiers tenus à la main.

| Domaine | Fichier possédé par le GUI | Tenu à la main (coexiste) |
| --- | --- | --- |
| Identité + politiques (défauts) | `group_vars/all/10-intrants.yml` | `group_vars/all/00-instance.yml` |
| Proxmox (constantes + défauts) | `group_vars/proxmox/10-intrants.yml` | `group_vars/proxmox/00-base.yml` |
| Template/durcissement (défauts) | `group_vars/modeles_vm/10-intrants.yml` | `group_vars/modeles_vm/00-base.yml` |

> Migration légère : convertir `group_vars/all.yml` → répertoire `group_vars/all/`
> (Ansible le supporte nativement). Idem `proxmox.yml`, `modeles_vm.yml`. Les valeurs
> existantes sont scindées : commentaires/contexte dans `00-*`, valeurs pilotées par
> le GUI dans `10-intrants.yml`. La précédence Ansible reste identique.

Les **surcharges par hôte** continuent de vivre dans `plan/serveurs.yml` (déjà
supporté) ; par groupe, dans le `group_vars/<groupe>/` correspondant.

## 4. Mécanique d'héritage (côté générateur)

- Le panneau écrit les **défauts** dans les `10-intrants.yml`.
- `instancier.py` / les formulaires lisent ces défauts pour **pré-remplir** et
  marquer « hérité » ; une valeur présente dans `serveurs.yml` (hôte) **prime** et
  s'affiche « surchargé » (même logique `setdefault` que le dimensionnement).
- Les **constantes** ne sont jamais réémises par hôte : un seul point de vérité.

## 5. Écran (UI)

- Bouton **« Intrants de base »** dans l'en-tête du GUI → panneau modal/plein écran.
- Sections repliables par domaine : **Identité**, **Proxmox**, **Politiques de
  durcissement**, **Services centraux**, **Nomenclature (lecture seule)**,
  **Secrets attendus (lecture seule)**.
- Chaque champ porte un badge **Constante** / **Défaut**, et l'info-bulle d'aide
  (réutilise le mécanisme `AIDES` déjà en place).
- Bandeau d'avertissement sur `domaine_interne` (changement à fort impact : re-dérive
  zones, FQDN, base DN…) → confirmation explicite.

## 6. Garde-fous

- `--syntax-check` + `ansible-inventory --list` doivent rester verts après écriture.
- Discipline **diff-vide** : `make instancier` montre l'impact, application via FORCE
  si intentionnel.
- Aucune valeur secrète n'entre dans un fichier écrit par le GUI (vérifié par un test).

## 7. Périmètre proposé (MVP → suite)

- **MVP** : `domaine_interne` (constante, avec garde-fou), `fuseau_horaire`
  (défaut), accès Proxmox (constantes), golden template (constantes), placement
  Proxmox par défaut (nœud/stockage/pont), + nomenclature et secrets en lecture seule.
- **Suite** : politiques de durcissement (défauts par groupe), DNS internes, relais
  SMTP, endpoints services centraux.

## 8. Points ouverts — tranchés par ce qui a été construit

| Question de juin | Réponse, telle que le code la donne |
|---|---|
| Migrer `group_vars/*.yml` → répertoires ? | **Pour `all/` seulement.** `proxmox.yml` et `modeles_vm.yml` sont restés plats — la migration n'a payé que là où le GUI écrivait vraiment. |
| Afficher la liste de rappel des secrets ? | **Oui, en lecture seule** — et *recensée*, jamais recopiée (`scripts/voute.py lister`, gardée par **P18**). |
| Périmètre MVP suffisant ? | Oui, et il a été dépassé : la couverture du GUI est désormais **prouvée** par **P19**, qui refuse un champ du plan que la console ne saurait pas éditer. |