feat: Add offer_url to energy offers and update scrapers

- Added `offer_url` field to energy offers in the database.
- Updated TotalEnergies and Vattenfall scrapers to set `offer_url` for each parsed offer.
- Modified price update service to handle the new `offer_url` field.
- Enhanced the EnergyOffer interface in the web app to include `offer_url`.
- Improved onboarding tour and page headers with data attributes for better user guidance.
- Updated ALPIQ scraper URLs to point to official PDFs and ensured the provider exists in the database.
- Implemented a migration script to add `offer_url` to the energy_offers table.
- Enhanced the Simulator component to display detailed pricing for the new ZEN_FLEX offer type.

Author: Clément VALENTIN

apps/api/alembic/versions/20251211_2100_006_add_offer_url_to_energy_offers.py

@@ -0,0 +1,28 @@
+"""add offer_url to energy_offers
+
+Revision ID: 006
+Revises: 005
+Create Date: 2025-12-11
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '006'
+down_revision: Union[str, None] = '005'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Add offer_url column to energy_offers table
+    op.add_column('energy_offers', sa.Column('offer_url', sa.String(length=1024), nullable=True))
+
+
+def downgrade() -> None:
+    # Remove offer_url column from energy_offers table
+    op.drop_column('energy_offers', 'offer_url')

apps/api/migrations/update_alpiq_scraper_url.py

@@ -0,0 +1,72 @@
+"""
+Migration: Update ALPIQ scraper URLs to use official PDFs
+
+This migration ensures the ALPIQ provider exists and has the correct
+scraper URLs pointing to the official PDFs:
+- PRIX_STABLE_18.pdf: Électricité Stable -21,5% (prix fixe jusqu'au 30/11/2027)
+- gtr_elec_part.pdf: Électricité Stable -8% + Électricité Référence -4%
+"""
+import asyncio
+import uuid
+from datetime import datetime, UTC
+from sqlalchemy import text, select
+from src.models.database import get_db
+from src.models import EnergyProvider
+
+
+async def migrate():
+    """Create/update ALPIQ provider with official PDF URLs"""
+    async for db in get_db():
+        try:
+            # Check if ALPIQ provider exists
+            result = await db.execute(
+                select(EnergyProvider).where(EnergyProvider.name == "ALPIQ")
+            )
+            provider = result.scalar_one_or_none()
+
+            alpiq_pdf_urls = [
+                "https://particuliers.alpiq.fr/grille-tarifaire/particuliers/PRIX_STABLE_18.pdf",
+                "https://particuliers.alpiq.fr/grille-tarifaire/particuliers/gtr_elec_part.pdf",
+            ]
+
+            if not provider:
+                # Create ALPIQ provider
+                provider = EnergyProvider(
+                    id=str(uuid.uuid4()),
+                    name="ALPIQ",
+                    website="https://particuliers.alpiq.fr",
+                    scraper_urls=alpiq_pdf_urls,
+                    is_active=True,
+                )
+                db.add(provider)
+                print("✅ Created ALPIQ provider with PDF URLs")
+            else:
+                # Update scraper_urls if different
+                current_urls = provider.scraper_urls or []
+                if current_urls != alpiq_pdf_urls:
+                    provider.scraper_urls = alpiq_pdf_urls
+                    provider.updated_at = datetime.now(UTC)
+                    print(f"✅ Updated ALPIQ scraper_urls from {current_urls} to {alpiq_pdf_urls}")
+                else:
+                    print("ℹ️  ALPIQ already has correct scraper_urls")
+
+            await db.commit()
+            print("\n✅ Migration completed successfully")
+            print("   ALPIQ scraper URLs:")
+            for url in alpiq_pdf_urls:
+                print(f"   - {url}")
+            print("\nNext step: Run the price refresh for ALPIQ:")
+            print("  POST /api/admin/offers/refresh/ALPIQ")
+
+        except Exception as e:
+            await db.rollback()
+            print(f"❌ Migration failed: {e}")
+            import traceback
+            traceback.print_exc()
+            raise
+        finally:
+            break
+
+
+if __name__ == "__main__":
+    asyncio.run(migrate())

apps/api/src/models/energy_provider.py

@@ -79,6 +79,9 @@ class EnergyOffer(Base):
     valid_from: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)  # Date from which this tariff is valid
     valid_to: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)  # Date until which this tariff is valid (NULL = current)
 
+    # Link to offer page
+    offer_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)  # URL to the offer page on provider's website
+
     is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC), nullable=False)
     updated_at: Mapped[datetime] = mapped_column(

apps/api/src/routers/energy_offers.py

@@ -101,6 +101,7 @@ async def list_offers(
                 "price_updated_at": o.price_updated_at.isoformat() if o.price_updated_at else None,
                 "valid_from": o.valid_from.isoformat() if o.valid_from else None,
                 "valid_to": o.valid_to.isoformat() if o.valid_to else None,
+                "offer_url": o.offer_url,
                 "is_active": o.is_active,
                 "created_at": o.created_at.isoformat() if o.created_at else None,
             }