Documentation Dev

Billoff Pipeline V1 — Génération automatique de pages de résiliation SEO. Ce doc couvre l'architecture, les scripts, la logique conditionnelle, et les prochaines étapes pour ton dev.

🗺️ Vue d'ensemble

Le pipeline prend un nom de service + une catégorie en entrée, fait 4 recherches web en temps réel, rédige les textes éditoriaux en parallèle, puis assemble une page HTML complète (~120 Ko) en ~90 secondes.

⚙️ Installation

# 1. Cloner / dézipper le projet
unzip billoff-pipeline-v1.zip
cd scripts

# 2. Installer les dépendances Python
pip install -r requirements.txt

# 3. Configurer la clé API OpenAI
export OPENAI_API_KEY="sk-..."

# 4. Vérifier que tout est OK
python3 -c "from openai import OpenAI; print('OK')"

🚀 Quickstart

cd scripts/scripts

# Telecom mobile (pas de blocs partage Spliiit/Sharesub)
python3 01_generate_v1.py \
  --service "SFR Mobile" \
  --category "telecom-mobile" \
  --output ../../billoff-sfr.html

# Streaming vidéo (active les blocs partage)
python3 01_generate_v1.py \
  --service "Netflix" \
  --category "streaming-video" \
  --output ../../billoff-netflix.html

# Re-render depuis JSON existant (0 coût API)
python3 render_page.py \
  ../data/service_data_sfr-mobile.json \
  ../../billoff-sfr-rerender.html

🔄 Pipeline 3 phases

Phase 1 — Recherche web (4 passes séquentielles)

Chaque passe appelle gpt-4o-search-preview avec web_search_options. Elle retourne un JSON structuré + une liste d'URLs vérifiées (HTTP HEAD).

Pass 1 → résiliation, remboursement, avis, droits, discussions
Pass 2 → tarifs, plans, essai gratuit, alternatives (suspension/downgrade/FAQ)
Pass 3 → 3-5 concurrents directs avec prix, pros, cons
Pass 4 → infos société (PDG, siège, filiale EU, support, date création)

Phase 2 — Rédaction éditoriale (3 prompts en parallèle)

Utilise ThreadPoolExecutor(max_workers=3) pour paralléliser les 3 appels à gpt-5-mini.

Prompt SEO       → title, meta_description, h1, keywords, canonical_path
Prompt Content   → intros par section, checklist, dark_patterns, avertissements
Prompt Témoins  → 6 avis fictifs réalistes (profils variés, notes 3-5)

Phase 3 — Rendu HTML

render_page.py assemble JSON + éditorial + templates statiques. Les sections sans données suffisantes sont automatiquement skippées via les seuils de compétude (voir ci-dessous).

📁 Arborescence

📜 Scripts détaillés

🎛️ Seuils conditionnels (logique de compétude)

Chaque section de la page a un score de compétude calculé sur ses données réelles. Si ce score est inférieur au seuil, la section est skippée — aucun bloc vide n'est affiché.

Modifier un seuil

# Dans render_page.py, modifier le dict SECTION_THRESHOLDS :
SECTION_THRESHOLDS = {
    "concurrents": 0.40,   # ← augmenter si trop de pages s'affichent avec 1 seul concurrent
    "temoignages": 0.50,   # ← baisser à 0.30 si les témoignages LLM sont souvent absents
    "faq":         0.00,   # ← mettre 0.0 pour toujours forcer l'affichage FAQ
}

🔗 Liens externes — nofollow

🏷️ Catégories et logique de partage

Les blocs Spliiit / Sharesub / GamsGo ne s'affichent que pour les catégories "partageables".

# Catégories avec blocs partage actifs
streaming-video | music-streaming | software-saas | gaming

# Catégories sans blocs partage
telecom-mobile | internet-fai | energy | insurance | bank-finance | transport | health

📋 Schéma JSON de sortie

Chaque service produit un fichier service_data_[slug].json réutilisable pour tout front-end ou CMS.

{
  "service_identity": { name, slug, category, tagline, platforms, ... },
  "company_info":     { full_legal_name, parent_company, ceo, headquarters, ... },
  "pricing":          { plans: [{name, price_monthly, features}], free_trial_days, ... },
  "cancellation":     { difficulty, methods: [{platform, label, steps[]}], dark_patterns },
  "post_cancellation": { keep: [], lose: [], access_until_end_of_period },
  "refund":           { has_refund, refund_policy, cooling_off_days, exceptions[] },
  "reviews":          { overall_rating, positive_themes[], negative_themes[] },
  "competitors":      { items: [{name, price_monthly, pros[], cons[], website}] },
  "alternatives_to_cancel": { can_suspend, can_downgrade, can_share, sharing_platforms[] },
  "consumer_rights":  { laws: [{title, description, legal_ref}] },
  "faq":              { items: [{question, answer}] },
  "community_threads":{ items: [{title, author, excerpt, best_answer, url}] },
  "testimonials":     { items: [{text, author, date, stars}] },
  "verified_sources": { items: [url, ...] }
}

📌 TODO — Priorités pour le dev

🔴 Urgent / Sécurité

🔴 Infrastructure de base

🟡 Améliorations pipeline

🟢 Qualité & SEO

🧪 Tester sur d'autres services

# Services recommandés pour tester la robustesse :

# 1. Streaming — teste les blocs partage Spliiit/Sharesub
python3 01_generate_v1.py --service "Netflix" --category "streaming-video" --output ../../test-netflix.html

# 2. Music streaming — variante moins de concurrents
python3 01_generate_v1.py --service "Spotify" --category "music-streaming" --output ../../test-spotify.html

# 3. Énergie — teste catégorie sans partage, droits spécifiques
python3 01_generate_v1.py --service "EDF" --category "energy" --output ../../test-edf.html

# 4. SaaS — teste suspension/downgrade, cas international
python3 01_generate_v1.py --service "Adobe Creative Cloud" --category "software-saas" --output ../../test-adobe.html

# 5. Banque — teste droits bancaires, peu d'infos partage
python3 01_generate_v1.py --service "Boursorama" --category "bank-finance" --output ../../test-boursorama.html

Ce qu'il faut vérifier sur chaque page de test

💡 Améliorations suggérées

Court terme (1-2 jours)

# Ajouter un mode --dry-run qui simule sans appeler les APIs
python3 01_generate_v1.py --service "Netflix" --category "streaming-video" --dry-run

# Ajouter --verbose pour voir les JSON bruts de chaque passe
python3 01_generate_v1.py --service "Netflix" --category "streaming-video" --verbose

Moyen terme (1-2 semaines)

# API FastAPI avec queue de jobs
POST /api/generate
Body: { "service": "Amazon Prime", "category": "streaming-video" }
→ { "job_id": "abc123", "status": "queued" }

GET /api/job/abc123
→ { "status": "done", "html_url": "/pages/amazon-prime.html", "json_url": "/data/..." }

Long terme (roadmap)

📦 Téléchargements

Scripts individuels