EVOLUTIONS — Faire évoluer capbe-agro (avec IA ou sans)

📄 Source : CAPBE-AGRO/docs/EVOLUTIONS.md 🕒 Généré le 06/08/2026 09:56
Sommaire

Guide pratique pour faire évoluer l'application capbe-agro. Les mêmes commandes servent avec ou sans IA : une IA (agent de code) peut manipuler les fichiers locaux puis utiliser les scripts deploy/ pour publier.

Règle d'or : jamais d'édition directe dans les conteneurs. On travaille en local (kit + source dev), puis on publie avec les scripts.

🚀 05/08/2026 — Messagerie centralisée (compte agro@ + audit + alias)

  • Compte applicatif agro@capbe.ovh créé sur Stalwart (587 STARTTLS, MAIL_APP_AGRO_PASS dans playbook/config/secrets.env) — prêt pour tout envoi futur (cf. section « Mail sortant » ci-dessous).
  • Alias postmaster@capbe.ovh → admin@capbe.ovh (RFC 5321).
  • Audit délivrabilité global : playbook/audit-deliverability.sh (4 comptes, sonde MX Gmail, chaîne DNS) — modes --alert et --install-cron (cron mensuel root).
  • Smoke-test §7 --app-accounts : auth SMTP 587 des 4 comptes.

✉️ 05/08/2026 — Mail sortant : capbe-mail (prêt à l'emploi)

Les notifications AGRO sont in-app (pas d'envoi email dans le backend). Si un envoi email est ajouté plus tard, il doit passer par capbe-mail (mail.capbe.ovh:587 STARTTLS + auth, compte agro@capbe.ovh, MAIL_APP_AGRO_PASS dans playbook/config/secrets.env) — DKIM/SPF/DMARC signés par capbe-mail (domaine capbe.ovh).

1. Cycle d'évolution de l'API (FastAPI)

1.1 Récupérer le code (une seule fois, ou à chaque base de travail)

sudo ./deploy/deploy-api.sh --pull
# → copie /srv/agro/api (capbe-pgis) → ./api-work/  (sans .env ni __pycache__)

1.2 Modifier

Édite les fichiers dans ./api-work/ (ou dans la source dev src/backend puis copie). Pour une évolution guidée par IA, fournis à l'IA : le code local (./api-work/), la carte d'identité (README.md), les conventions (docs/MIGRATION.md) et le point d'entrée app/main.py.

NB : l'API agro gère ses migrations avec Alembic (alembic/, alembic.ini) — après modification des modèles, lance la migration : alembic revision --autogenerate -m "..." && alembic upgrade head (dans ./api-work/, avec les bonnes variables de connexion).

1.3 Tester en local (si possible)

# Dans ./api-work/ avec un venv :
#   pip install -r requirements.txt
#   uvicorn app.main:app --port 8001   (ou pytest, voir tests/)

1.4 Publier

sudo ./deploy/deploy-api.sh --push        # code → pgis + restart agro-api
sudo ./ops/smoke-agro.sh                  # validation front + API + tenant

deploy-api.sh : - ne pousse jamais le .env (les secrets restent sur pgis) ; - réinstalle les dépendances uniquement si requirements.txt / pyproject.toml a changé ; - fait un healthcheck interne (/health sur :8001) après redémarrage.

1.5 Convention d'URL

L'API agro sert ses routes sous /api/v1/* (le front l'appelle ainsi). Le bloc Caddy agro.app.ci.capbe.ovh relaye tout /api/* → pgis:8001 sans rewrite (contrairement à meca). Nouveau endpoint = aucune modification Caddy nécessaire (tout /api/* est relayé).

2. Cycle d'évolution du front (Flutter)

# 1. Modifier le code Flutter dans src/frontend
# 2. Builder :
cd src/frontend && flutter build web
# 3. Publier :
sudo ./deploy/deploy-front.sh      # → capbe-agro:/var/www/html + restart nginx
# 4. Valider :
sudo ./ops/smoke-agro.sh

Le front est un build statique (SPA) : la logique métier vit dans l'API. Si l'appelleur doit changer d'URL d'API, préfère le même-origine (/api/v1/*) déjà en place — aucun changement de build nécessaire.

3. Évolution du tenant Odoo (base agro)

# Tenant vierge initialisé à la migration (odoo -i base) : les données
# ERP se construisent via l'interface (https://agro.ci.capbe.ovh).
sudo ./ops/db.sh --write --shell odoo      # psql interactif sur la base agro

⚠️ Le tenant agro est une base vierge (initialisée sans données métier) : toute donnée ERP est à créer via Odoo. Les modifications de schéma doivent passer par les mécanismes Odoo (install/upgrade de modules).

4. Sauvegarde / restauration projet

sudo ./ops/backup-agro.sh        # dumps agro_api + agro + snapshot front + code API
# Restauration d'un dump :
sudo ./ops/db.sh --write --shell api        # psql interactif → \i /tmp/dump.sql

La sauvegarde globale de l'infrastructure reste playbook/10-backup.sh (cron 02h00) — ce kit est complémentaire (ciblé projet).

💾 Automatisée : backup-agro.sh tourne chaque nuit à 02h45 (cron root, décalé de la globale à 02h00) → log /var/log/capbe-agro-backup.log. Garde flock : un run manuel pendant le cron est refusé proprement.

⏱️ NB pool ZFS fichier-image : la création du snapshot front peut prendre 5-15 min quand le pool est chargé (constaté en réel). Piège évité : un timeout client tue l'opération SERVEUR Incus — le script lance donc la création en arrière-plan sans timeout puis attend la présence effective du dataset ZFS (borne 20 min) avant de conclure (✓ ou WARN).

5. Supervision au quotidien

sudo /data/CAPBE/scripts/status-global.sh   # 🌍 résumé GLOBAL des 2 kits en 1 commande
sudo ./ops/status.sh            # tableau de bord complet
sudo ./ops/check-nightly.sh     # ✅ le matin : le run de nuit (02h45) s'est-il bien passé ?
sudo ./ops/monitor-agro.sh      # surveillance endpoints (manuel, ou cron auto toutes les 5 min)
sudo ./ops/logs.sh api          # journaux agro-api (api|front|odoo|all, -f pour suivre)
sudo ./ops/api.sh --list        # endpoints connus de l'API
sudo ./ops/api.sh health        # exemple d'appel GET (lecture seule)

🌍 scripts/status-global.sh (racine du dépôt) : conteneurs Incus, santé des 2 kits (front/API/tenant Odoo), sauvegardes de nuit, crons, alertes récentes et état git — tout en une commande, sortie 0 = tout vert, 1 = point(s) rouge(s). ⏰ Automatisé : cron root 07h40 avec --alert → trace journalière /var/log/capbe-status.log, et mail de synthèse (rapport complet, sujet [CAPBE] État global : N point(s) rouge(s)) uniquement si le statut n'est pas vert — rien n'est envoyé quand tout est vert (aucun bruit).

🌙 check-nightly.sh : vérifie en une commande que la sauvegarde de nuit s'est bien passée (run présent et terminé, dumps SQL < 26 h, snapshot ZFS du kit < 26 h, snapshot global 10-backup.sh < 26 h, aucune alerte mail depuis le run). Sortie 0 = nuit saine, 1 = problème(s) détaillés.

⏰ Automatisé : lancé par cron chaque matin à 07h35 avec --alert → en cas d'échec, un mail [CAPBE-AGRO] Check nightly : échec est envoyé à admin@capbe.ovh (SMTP 587 STARTTLS, mdp par environnement). Log : /var/log/capbe-check-nightly.log. Rien n'est envoyé quand la nuit est saine (aucun bruit).

📮 Envoi des mails centralisé : send_alert_mail() dans lib/mail.sh (racine du dépôt — source UNIQUE, sourcée par la lib de kit) — SMTP 587 STARTTLS, mdp par environnement --env, jamais en argv — utilisée par monitor-agro.sh, check-nightly.sh et status-global.sh.

📡 Monitoring automatique : monitor-agro.sh tourne toutes les 5 minutes (cron root) → log /var/log/capbe-monitor.log. En cas d'échec (front, API public/interne, endpoint kit, tenant Odoo, sauvegardes), une alerte mail est envoyée à admin@capbe.ovh via capbe-mail (SMTP 587 STARTTLS — mot de passe par environnement, jamais en argv).

💾 Checks sauvegardes (fraîcheur < 26 h) : dumps SQL du kit, snapshot ZFS de capbe-agro, snapshot ZFS global (10-backup.sh via capbe-pgis) — un cron backup manqué est donc détecté et alerté automatiquement. 📧 Alerte testée en réel (sur meca) : arrêt volontaire du service API → échecs détectés → mail reçu dans l'INBOX, puis redémarrage → tout vert.

6. Checklist d'une évolution livrée

  • [ ] Code testé (tests de ./api-work/tests/ si l'API, ou smoke manuel)
  • [ ] Migrations Alembic appliquées si les modèles ont changé
  • [ ] deploy-api.sh --push / deploy-front.sh exécutés
  • [ ] ops/smoke-agro.sh 100 % vert
  • [ ] ops/backup-agro.sh lancé après une évolution majeure
  • [ ] Aucun secret dans le code poussé (.env jamais copié)