CERFA Auto (Codex + Claude)

Objectifs

• Automatiser la génération de CERFA 16702-01 pour les installations photovoltaïques à partir d’emails structurés.
• Centraliser la logique métier (analyse emails, géocodage, cadastre, projection PDF) dans une API FastAPI exploitable par Codex et Claude.
• Fournir une base PRO : Docker, CI GitHub Actions, tests et documentation complète.

Architecture

.
├── app
│   ├── main.py                # Entrée FastAPI
│   ├── services/
│   │   ├── email_parser.py    # Analyse brute email
│   │   ├── geocoder.py        # API adresse.data.gouv.fr
│   │   ├── cadastre.py        # API apicarto.ign.fr
│   │   └── cerfa_builder.py   # Fusion PyMuPDF + templates
│   └── models/
│       ├── client.py
│       ├── cadastre.py
│       └── project.py
├── templates/                 # PDF statiques (CERFA base, overlay)
├── dp_generes/                # CERFA produits
├── tests/                     # pytest : API, services, e2e
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── .github/workflows/deploy.yml

Workflow Email → API → CERFA

1. Email entrant : Codex/Claude poste le corps brut via /api/v1/cerfa.
2. Parsing : email_parser extrait nom, adresse, panneaux, puissance, scénarios.
3. Géocodage : geocoder requête api-adresse.data.gouv.fr pour obtenir lon/lat.
4. Cadastre : cadastre interroge apicarto.ign.fr (point → parcelle) pour sections, superficies, IDU.
5. Projet : project calcule puissance kWc, description standardisée.
6. CERFA builder : cerfa_builder applique PyMuPDF + modèle templates/cerfa_overlay_base.pdf, exporte dans dp_generes/.
7. Réponse API : renvoie JSON (métadonnées) + binaire PDF (ou URL local) prêt à signer/envoyer.

Installation

1. Cloner le dépôt :

git clone git@github.com:yohand-byte/cerfa_auto_codex_claude.git
cd cerfa_auto_codex_claude

2. (Optionnel) créer un venv puis installer :

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Lancer FastAPI :

uvicorn app.main:app --reload

4. Documentation interactive : http://localhost:8000/docs

API Endpoints

POST /api/v1/cerfa

• Body multipart :
  • email_text (str, requis)
  • coords_map (fichier JSON optionnel pour override overlay)
• Réponse 200 :

{
  "client": {...},
  "cadastre": {...},
  "project": {...},
  "pdf_path": "dp_generes/DP_GAUFRETEAU_2025-11-18T18-30-00.pdf"
}

• Retourne aussi le fichier PDF (StreamingResponse).

GET /api/v1/health

• Ping simple (status/service version).

GET /api/v1/templates

• Liste des PDF disponibles dans templates/.

Workflow complet Codex + Claude

1. Codex récupère l’email client, appelle /api/v1/cerfa avec email_text.
2. FastAPI déclenche la chaîne complète (parser → geocode → cadastre → builder).
3. Codex vérifie la réponse, poste lien + résumé dans le ticket.
4. Claude peut consommer la même API pour générer ou valider les PDF ; instructions :
   • envoyer l’email brut.
   • optionnel : fournir coords_map si de nouvelles cases apparaissent.
5. Stockage : PDF généré dans dp_generes/, versionné si besoin.

Utilisation Codex + Claude

• Codex : utiliser curl ou python httpx pour POST. Toujours vérifier les retours d’erreur (400 si parsing impossible, 502 si API Géo indispo).
• Claude : même protocole. Ajouter résumé final : puissance, section cadastrale, chemin PDF.
• En cas d’erreur API externe, les services lèvent HTTPException explicites (GEOCODER_DOWN, CADASTRE_NOT_FOUND).

Notes PRO

• dp_generes/ reste versionné (vide par défaut) pour audit.
• templates/ doit contenir cerfa_overlay_base.pdf et autres gabarits (placer via SCP ou objet Git LFS si volumineux).
• CI GitHub Actions : lint (ruff/flake8), tests, build Docker, push image (placeholder) et job de déploiement personnalisable.