Initial commit

2026-05-13 16:04:17 +02:00
commit b66612d672
43 changed files with 10515 additions and 0 deletions
@@ -0,0 +1,157 @@
+# Architecture cible
+
+## Vue d'ensemble
+
+L'application est un outil batch lance une fois par jour. Elle collecte les donnees depuis l'API Proxmox VE, les transforme en objets internes, calcule la couverture de sauvegarde, puis genere un rapport PDF horodate.
+
+Le conteneur Docker execute une commande unique et se termine avec un code de retour explicite.
+
+Etat actuel du depot : la CLI, la configuration, le logging, la collecte PVE/PBS, l'analyse de couverture et la generation PDF WeasyPrint sont implementes. Le conteneur Docker integre les dependances systeme necessaires au rendu PDF.
+
+## Composants
+
+### CLI
+
+La CLI est le point d'entree du script.
+
+Responsabilites :
+
+- charger la configuration ;
+- initialiser les logs ;
+- lancer la collecte ;
+- lancer l'analyse ;
+- generer le PDF ;
+- retourner un code de sortie adapte.
+
+### Configuration
+
+Le module de configuration lit les variables d'environnement et valide les valeurs obligatoires.
+
+Il ne doit pas contenir de logique d'appel API.
+
+### Client PVE
+
+Le client PVE encapsule les appels HTTP vers l'API Proxmox VE.
+
+Le client utilise `requests` et une session reutilisable.
+
+Il implemente :
+
+- authentification par API token ;
+- verification TLS configurable ;
+- CA bundle optionnel ;
+- timeout reseau ;
+- erreurs dediees pour connexion, HTTP et reponse invalide ;
+- methodes de verification pour `/nodes`, `/storage` et `/cluster/backup`.
+
+Il gere :
+
+- l'URL de base ;
+- l'authentification par token ;
+- la verification TLS ;
+- les erreurs HTTP ;
+- les timeouts ;
+- la deserialisation JSON.
+
+### Collecteurs
+
+Les collecteurs recuperent les informations brutes :
+
+- stockages ;
+- jobs de sauvegarde ;
+- ressources du cluster ;
+- informations utiles sur les VM et CT.
+- notes des VM/CT depuis leur configuration par noeud ;
+- prune jobs PBS, si la collecte PBS est configuree ;
+- snapshots PBS par datastore et namespace, si la collecte PBS correspondante est configuree.
+
+Chaque collecteur doit retourner des donnees structurees, pas du JSON brut disperse dans l'application.
+
+Etat actuel : la collecte des stockages PBS via `/storage`, des jobs de sauvegarde via `/cluster/backup`, des VM/CT via `/cluster/resources`, des pools via `/pools`, des dernieres taches `vzdump` via `/cluster/tasks` et `/nodes/{node}/tasks`, ainsi que des prune jobs et snapshots via l'API PBS, est implementee.
+
+### Modeles
+
+Les modeles representent les entites internes :
+
+- `PbsStorage` ;
+- `PbsRetentionPolicy` ;
+- `PbsBackupSnapshotSummary` ;
+- `Guest` ;
+- `BackupJob` ;
+- `BackupCoverage` ;
+- `ReportData` ;
+- `ReportSummary` ;
+- `CollectionIssue`.
+
+Les modeles peuvent etre implementes avec `dataclasses` ou Pydantic selon les choix du projet.
+
+### Analyse de couverture
+
+Le module d'analyse compare l'inventaire des VM/CT avec les jobs de sauvegarde actifs.
+
+Il produit un statut par VM/CT :
+
+- `sauvegarde_planifiee` ;
+- `non_sauvegardee` ;
+- `indetermine`.
+
+Etat actuel : la couverture par `vmid` explicitement listes, `all=1` et `pool=<nom>` est calculee. Les exclusions simples sont prises en compte.
+
+### Generation PDF
+
+Le generateur PDF prend un objet `ReportData` complet et produit un fichier.
+
+Il ne doit pas appeler l'API PVE.
+
+Il ne doit pas relire la configuration globale sauf pour les options de rendu strictement necessaires.
+
+Le rendu principal utilise `WeasyPrint` a partir d'un template HTML/CSS. Cette approche garde la logique metier separee de la presentation et rend les evolutions visuelles plus simples.
+
+Le PDF contient actuellement le resume, les stockages PBS declares sur PVE, les espaces de stockage PBS, les politiques de retention PBS, les jobs de sauvegarde, les VM/CT non sauvegardees, la couverture VM/CT, les retentions de sauvegarde VM/CT par PBS avec nombre attendu de versions et delta, et les anomalies.
+
+## Flux de donnees
+
+1. Chargement de la configuration.
+2. Connexion a l'API PVE.
+3. Connexion optionnelle aux API PBS configurees.
+4. Collecte des stockages.
+5. Filtrage des stockages PBS.
+6. Collecte des prune jobs et des snapshots PBS, si configures.
+7. Collecte des jobs de sauvegarde.
+8. Collecte des VM et CT.
+9. Calcul de couverture.
+10. Construction du modele de rapport.
+11. Generation du PDF.
+12. Log du resultat et code de sortie.
+
+Une etape de preparation assemble un `ReportData` final avec un `ReportSummary` calcule. La commande `--dump-report-data` permet de previsualiser ce modele en JSON.
+
+La commande `--generate-pdf` rend ce modele en PDF avec WeasyPrint. En Docker Compose, elle doit etre lancee explicitement :
+
+```sh
+docker compose run --rm pve-backup-report --generate-pdf
+```
+
+## Gestion des erreurs
+
+Les erreurs bloquantes arretent l'execution :
+
+- configuration invalide ;
+- echec d'authentification ;
+- API PVE totalement indisponible ;
+- impossibilite d'ecrire le PDF.
+
+Les erreurs partielles peuvent etre ajoutees au rapport :
+
+- un noeud ne repond pas ;
+- un champ attendu manque ;
+- un job ne peut pas etre interprete ;
+- un storage reference n'existe pas dans la collecte.
+
+## Idempotence
+
+L'execution quotidienne ne doit pas modifier l'etat PVE.
+
+L'outil est en lecture seule vis-a-vis du cluster.
+
+Le seul effet de bord attendu est la creation d'un nouveau rapport dans le repertoire de sortie.