CAP'2ER® Niveau 1 Bovin Lait — moteur Python et application web

Portage en Python du diagnostic environnemental CAP'2ER® Niveau 1 Bovin Lait (méthode Idele, cap2er.eu) et application web publique pour cap2er.osfarm.org : saisie guidée en moins de 5 minutes visée (carte des parcelles, aides par document, calculatrices), résultats identiques au site officiel, PDF, diagnostics sous lien secret sans compte.

Le moteur Python n'est pas réécrit à la main : il est transpilé automatiquement depuis le moteur JavaScript officiel (lui-même généré par l'Idele à partir de classeurs Excel), puis validé indicateur par indicateur.

Périmètre	Bovin Lait, France, Niveau 1
Version du moteur source	CAP'2ER Niveau 1 v17.01 (06/2026), CAP2ER.MoteurNIV1BL.js (voir source/SHA256SUMS)
Formules	1 171 formules uniques → 12 modules Python générés
Indicateurs restitués	280 (279 affichés par le site)
Validation	identique à cap2er.eu sur 3 fermes × 279 indicateurs et sur la page de résultats ; 6 179 tests Python, 49 tests de l'application
Temps de calcul	≈ 20 ms par diagnostic

Démarrage rapide

Prérequis : Python ≥ 3.11, Node ≥ 18 (uniquement pour régénérer ou tester contre l'oracle).

uv venv && uv pip install -e ".[api,dev]"   # ou pip install -e ".[api,dev]"
(cd oracle && npm ci)                  # dépendances de l'oracle et du transpileur (acorn, underscore)

python -m cap2er calcul fermes_reference/plaine_mais.reponses.json   # indicateurs principaux
python -m cap2er calcul ma_ferme.json --tout                          # 280 indicateurs en JSON
python -m pytest                                                      # 6 179 tests
(cd web && npm test)                                                  # 49 tests de l'application
python -m cap2er.api serveur                                          # API sur http://127.0.0.1:8000/docs
(cd web && npm ci && npm run dev)                                     # application sur http://localhost:5173

Depuis Python :

from cap2er.engine import calculer

r = calculer({"GEN_HA_SAU": 110, "NIV1_BL_NBTETE_VL": 80, "NIV1_BL_LAIT_VENDU": 720000, ...})
r.resultats["RES_BL_LAIT_GES_BRUTS_EQCO2_LITRE"]   # kg éq. CO2 / L de lait corrigé

Questionnaire, restitution et API :

from cap2er import questionnaire, restitution
questionnaire.schema()                                   # formulaire : sections, types, unités, bornes, listes
questionnaire.verifier(questionnaire.completer(rep))     # visibilité, erreurs et avertissements par champ
restitution.restitution(calculer(questionnaire.completer(rep)))  # page de résultats : valeurs, jauges, graphes

curl -X POST localhost:8000/api/niv1bl/calcul -H 'content-type: application/json' \
     -d '{"reponses": {...}, "restitution": true}'

Les paramètres PP/PIE sont lus dans source/ (ou dans le dossier indiqué par la variable d'environnement CAP2ER_SOURCE).

Le format des réponses (codes de questions, codes TR_* des listes) est décrit dans docs/03-moteur.md ; des exemples complets sont dans fermes_reference/.

Mettre à jour quand l'Idele publie une nouvelle version

tools/fetch_sources.sh      # retélécharge moteur JS, paramètres FR, questionnaire, listes, référentiels
tools/regenerer.sh          # AST → Python, références de l'oracle, vecteurs de test, pytest

Puis revalider contre le site (voir docs/03-moteur.md).

Arborescence

cap2er/                 Paquet Python
  engine.py             Orchestration (portage fidèle de FormulaEngine)
  questionnaire.py      Schéma du formulaire, visibilité et validation de la saisie
  restitution.py        Page de résultats (valeurs affichées, jauges, graphes) comme sur cap2er.eu
  aides_saisie.json     Aides « où trouver cette donnée » et bases des estimations Idele, par champ
  estimations.py        « Je ne sais pas » : valeurs typiques du système, signalées comme estimées
  geo/                  Communes, zonage, parcelles RPG et haies (services publics relayés par le serveur)
  api/                  API FastAPI : calcul, vérification, diagnostics sous lien secret, PDF
  pdf/                  PDF de la restitution : gabarit HTML, pictogrammes, impression Chromium
  runtime/js.py         Sémantique JavaScript (coercitions, undefined, NaN, comparaisons…)
  runtime/excel.py      Les 15 fonctions « Excel » utilisées par les formules
  generated/niv1bl/     CODE GÉNÉRÉ — ne pas modifier (formules + meta.json)
  __main__.py           CLI
deploy/                 Images Docker (api, web) et configuration Caddy ; docker-compose.yml à la racine
web/                    Application React (Vite, TypeScript, Tailwind) : saisie, aperçu en direct, restitution
tools/
  fetch_sources.sh      Téléchargement des sources publiques cap2er.eu
  dump_formulas.js      Extraction des formules en AST (Node + acorn)
  transpile.py          AST JS → Python
  generer_fermes.py     Fermes synthétiques pour la non-régression
  vecteurs_excel.js     Vecteurs de test différentiels des fonctions Excel
  regenerer.sh          Chaîne complète de régénération + tests
  import_zonage_ddt.py  Import d'un classement communal des zones défavorisées (fichiers DDT)
  pdf_references.py     Régénération des références visuelles du PDF
oracle/                 Moteur JS original exécuté sous Node (référence)
  run_oracle.js         Calcul d'une ferme ou d'un dossier de fermes
  trace.js              Arbre de dépendances d'un indicateur (débogage)
source/                 Sources téléchargées depuis cap2er.eu (moteur JS, paramètres, questionnaire…) et zonage des communes
fermes_reference/       3 fermes fictives saisies sur cap2er.eu + résultats officiels + impressions PDF
tests/                  fermes/ (entrées), golden/ (sorties oracle), tests pytest
docs/                   Documentation (voir ci-dessous)
docs_idele/             Guide méthodologique et fiches références Idele (PDF + texte)

Documentation

1. Spécification — objectifs, exigences, décisions, questions ouvertes
2. Architecture — architecture cible (moteur, API, SPA, PDF), plan et avancement
3. Moteur — fonctionnement détaillé, particularités JS reproduites, transpilation, validation
4. Sources et méthodologie — ce qu'expose cap2er.eu, méthode Idele et correspondance avec le code
5. Restitution — page de résultats officielle : blocs, formatage, jauges, graphes
6. PDF — PDF à la mise en page officielle, écarts, validation
7. Déploiement — Docker Compose, Dokploy, sécurité, variables
8. Saisie rapide — exigences, décisions et avancement (objectif : moins de 5 minutes)
9. API Ekylibre — spécification de l'agrégat CAP'2ER à développer dans Ekylibre

État

• ✅ Étape 1 — moteur de calcul : transpilation complète, identique au site officiel.
• ✅ Étape 2 — questionnaire, restitution et API : vérification de la saisie identique au moteur JS, page de résultats identique au site, API FastAPI, diagnostics sous lien secret (SQLite ou PostgreSQL, purge à 12 mois).
• ✅ Étape 3 — application React : saisie guidée, aperçu de l'empreinte en direct, enregistrement automatique sous lien secret, partage en lecture seule, restitution interactive, mobile.
• ✅ Étape 4 — PDF à la mise en page officielle (2 pages A4, Chromium via Playwright), non-régression visuelle.
• ✅ Étape 5 — déploiement : Docker Compose pour Dokploy (Caddy, API avec Chromium, PostgreSQL, purge quotidienne), vérifié en local. Mise en ligne : docs/07-deploiement.md.
• ✅ Étape 6 — saisie rapide (docs/08) : parcours par document à consulter, carte des parcelles (RPG 2025) et haies, zonage proposé (Saône-et-Loire pour l'instant), aides « où trouver », opérations et calculatrices dans les champs, estimations Idele explicites, « je ne sais pas » signalé, mesure anonyme du temps de saisie.
• ⏭️ Connecteur Ekylibre : en attente de l'agrégat CAP'2ER côté Ekylibre (docs/09).

Licence et propriété

Le code de ce dépôt (outils, runtime, moteur d'orchestration) est sous licence MIT. La méthode CAP'2ER®, la marque, le moteur JavaScript d'origine, les paramètres et référentiels ainsi que la documentation méthodologique appartiennent à l'Idele et à ses partenaires ; le code de cap2er/generated/ en est une traduction automatique. Voir docs/01-specification.md avant toute redistribution.