From 969ca37d9fa8a03954ba9d3a472a14cd8afa8f7d Mon Sep 17 00:00:00 2001 From: tristan Date: Mon, 6 Apr 2026 13:17:47 +0200 Subject: [PATCH] docs : spec phase 1 gestion applications et environnements Co-Authored-By: Claude Opus 4.6 (1M context) --- ...phase1-applications-environments-design.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-06-phase1-applications-environments-design.md diff --git a/docs/superpowers/specs/2026-04-06-phase1-applications-environments-design.md b/docs/superpowers/specs/2026-04-06-phase1-applications-environments-design.md new file mode 100644 index 0000000..d69f0af --- /dev/null +++ b/docs/superpowers/specs/2026-04-06-phase1-applications-environments-design.md @@ -0,0 +1,172 @@ +# Phase 1 — Gestion des applications et environnements + +## Contexte + +Central est un outil d'ops pour l'equipe technique Malio. Il gere les applications du SI deployees en Docker sur une meme machine (recette + prod). + +Aujourd'hui les applications gerees sont definies en YAML (`config/applications.yaml`) avec des chemins maintenance en variables d'env. Cette phase remplace ce systeme statique par une gestion dynamique en base de donnees avec une UI complete. + +## Roadmap globale + +- **Phase 1** (ce spec) : Modele de donnees apps/envs + UI CRUD +- **Phase 2** : Deploiement de version, dashboard sante, logs +- **Phase 3** : Historique deploys, rollback, gestion containers, notifications + +## Modele de donnees + +### Entity `Application` + +| Champ | Type | Contraintes | +|-------|------|-------------| +| `id` | int | PK, auto-generated | +| `name` | string (255) | not null | +| `slug` | string (255) | not null, unique | +| `registryImage` | string (255) | not null, ex: `gitea.malio.fr/malio-dev/sirh` | +| `description` | text | nullable | +| `giteaUrl` | string (255) | nullable | +| `createdAt` | DateTimeImmutable | not null, set on construct | + +- Relation : `OneToMany` vers `Environment` (cascade persist + remove, orphanRemoval) + +### Entity `Environment` + +| Champ | Type | Contraintes | +|-------|------|-------------| +| `id` | int | PK, auto-generated | +| `name` | string (255) | not null, ex: "production", "recette" | +| `containerName` | string (255) | not null, ex: "sirh-app" | +| `deployScriptPath` | string (255) | not null | +| `maintenanceFilePath` | string (255) | not null | +| `appUrl` | string (255) | nullable | +| `application` | ManyToOne | not null, vers Application | + +- Relation : `OneToMany` vers `LogFile` (cascade persist + remove, orphanRemoval) + +### Entity `LogFile` + +| Champ | Type | Contraintes | +|-------|------|-------------| +| `id` | int | PK, auto-generated | +| `label` | string (255) | not null, ex: "prod", "cron" | +| `path` | string (255) | not null | +| `environment` | ManyToOne | not null, vers Environment | + +## API Endpoints + +Tous les endpoints sont proteges par `ROLE_ADMIN`. Le slug est utilise comme identifiant URL pour Application. + +### Application + +| Route | Methode | Description | Provider/Processor | +|-------|---------|-------------|--------------------| +| `GET /api/applications` | GET | Liste des apps avec envs et logfiles | Doctrine (default) | +| `POST /api/applications` | POST | Creer une app | Doctrine (default) | +| `GET /api/applications/{slug}` | GET | Detail d'une app avec envs | Doctrine (default) | +| `PATCH /api/applications/{slug}` | PATCH | Modifier une app | Doctrine (default) | +| `DELETE /api/applications/{slug}` | DELETE | Supprimer une app (cascade envs) | Doctrine (default) | + +Groupes de serialisation : +- Lecture : `app:read` (tous les champs + envs embarques) +- Ecriture : `app:write` (name, slug, registryImage, description, giteaUrl) + +### Environment + +| Route | Methode | Description | Provider/Processor | +|-------|---------|-------------|--------------------| +| `POST /api/applications/{slug}/environments` | POST | Ajouter un env a une app | Custom processor pour lier a l'app | +| `PATCH /api/environments/{id}` | PATCH | Modifier un env | Doctrine (default) | +| `DELETE /api/environments/{id}` | DELETE | Supprimer un env | Doctrine (default) | + +Groupes de serialisation : +- Lecture : `env:read` (tous les champs + logfiles embarques) +- Ecriture : `env:write` (name, containerName, deployScriptPath, maintenanceFilePath, appUrl, logFiles) + +Les LogFiles sont geres en embedded dans l'environnement : envoyes dans le body du POST/PATCH de l'env, pas d'endpoint separe. + +### Maintenance + +| Route | Methode | Description | +|-------|---------|-------------| +| `POST /api/environments/{id}/maintenance` | POST | Toggle maintenance (body: `{ "maintenance": true/false }`) | + +Remplace l'ancien endpoint `POST /api/applications/{slug}/maintenance`. Le processor cree ou supprime le fichier maintenance sur le filesystem. + +## Frontend + +### Page liste — `/applications` + +- Grille des applications (cards) +- Chaque card : nom, description (tronquee), nombre d'environnements, lien Gitea (icone externe) +- Bouton "Ajouter une application" en haut +- Clic sur une card → navigation vers `/applications/{slug}` + +### Page detail — `/applications/{slug}` + +**Section haute : infos application** +- Nom, description, image registry, lien Gitea +- Bouton editer → formulaire inline ou modale avec les champs app:write +- Bouton supprimer (avec confirmation) + +**Section basse : environnements** +- Liste des environnements de l'app +- Chaque env affiche : nom, container, URL (lien cliquable), statut maintenance (badge) +- Actions par env : editer, supprimer, toggle maintenance +- Sous chaque env : liste des fichiers de log configures (label + path) +- Bouton "Ajouter un environnement" → formulaire avec champs env + logfiles dynamiques (ajouter/supprimer des lignes de log) + +### Sidebar + +- Lien "Applications" ajoute dans la sidebar (remplace ou complete le lien Dashboard actuel) + +### Services frontend + +- `services/applications.ts` : CRUD applications +- `services/environments.ts` : CRUD environnements + toggle maintenance +- `services/dto/application.ts` : types TypeScript +- `services/dto/environment.ts` : types TypeScript (inclut LogFile) + +### i18n + +- Nouvelles cles dans `fr.json` pour toutes les labels, messages de succes/erreur, confirmations de suppression + +## Migration des donnees existantes + +### Ce qui est cree + +Une DataFixture (ou migration SQL) cree les 3 apps existantes : + +**SIRH** +- slug: `sirh`, image: `gitea.malio.fr/malio-dev/sirh` +- Env prod : container `sirh-app`, deploy `/home/m-tristan/workspace/SIRH/deploy/docker/deploy.sh` +- Env recette : container `sirh-test-app` (si existant) + +**Lesstime** +- slug: `lesstime`, image: `gitea.malio.fr/malio-dev/lesstime` +- Env prod : container `lesstime-app` + +**Inventory** +- slug: `inventory`, image: `gitea.malio.fr/malio-dev/inventory` +- Env prod : container `inventory-app` +- Env recette : container `inventory-test-app` + +Les chemins exacts (deploy, maintenance, logs) seront renseignes lors de l'implementation en inspectant chaque projet. + +### Ce qui est supprime + +- `config/applications.yaml` +- Variables d'env `SIRH_MAINTENANCE_PATH`, `LESSTIME_MAINTENANCE_PATH`, `INVENTORY_MAINTENANCE_PATH` +- `src/ApiResource/ManagedApplication.php` +- `src/State/ManagedApplicationProvider.php` +- `src/State/MaintenanceToggleProcessor.php` +- `services/dto/managed-application.ts` (frontend) +- `services/managed-applications.ts` (frontend) + +La page d'accueil actuelle (dashboard avec toggle maintenance) est remplacee par la nouvelle page liste/detail. + +## Hors scope + +- Deploiement de version (phase 2) +- Logs en temps reel (phase 2) +- Dashboard sante containers (phase 2) +- Historique de deploiements (phase 3) +- Gestion multi-roles (pas de ROLE_USER pour l'instant)