PROMPT CLAUDE CODE — DÉVELOPPEMENT D’UNE APPLICATION DE SUIVI DE PRIX E-COMMERCE
==========================================================================

Tu es Claude Code, assistant de développement logiciel.
Tu dois analyser, concevoir et implémenter une application Python de suivi de produits e-commerce
(Amazon, Cdiscount en priorité, puis extensible).

L’objectif est de construire une base solide, modulaire, testable en CLI, avant l’ajout d’une base
de données, d’une interface web et d’un historique.

---------------------------------------------------------------------------
RÈGLES DE TRAVAIL (OBLIGATOIRES)
---------------------------------------------------------------------------

1. Langage principal : Python 3.12
2. Toute décision technique doit être justifiée brièvement (1 à 3 phrases).
3. Le projet doit maintenir en permanence les fichiers suivants :
   - README.md : description générale, installation, usage CLI, structure du projet.
   - TODO.md : liste des tâches, priorisées, cochables.
   - CHANGELOG.md : journal des modifications, mis à jour à chaque étape.
4. Chaque étape livrée doit fournir :
   - du code exécutable,
   - au moins un exemple de commande CLI,
   - des logs de debug exploitables.
5. Les modules de scraping doivent être testables indépendamment.
6. Les erreurs sont attendues (anti-bot) : la priorité est la robustesse et l’observabilité.
7. Pas d’optimisation prématurée.

---------------------------------------------------------------------------
OBJECTIF FONCTIONNEL GLOBAL
---------------------------------------------------------------------------

L’application doit permettre :

- Saisie d’une URL produit pour scrapper et faire un suivi
- Détection automatique du site marchand (Amazon, Cdiscoun, puis extensible)
- Scan régulier (1 fois par jour à terme)
- Récupération des informations suivantes :
  - nom du produit (title)
  - prix
  - devise
  - frais de port (option)
  - statut de stock (option)
  - référence produit (ASIN, SKU…)
  - images
  - catégorie / type si disponible
  - caractéristiques techniques (specs)
- Historisation des scans (implémentée plus tard)

Contraintes :
- Sites dynamiques
- Anti-bot fréquents
- Besoin d’un fallback Playwright
- Beaucoup de debug en CLI

- le site final, sera responsive, moderne, theme sombre type gruvbox
- commentaire de code et discussion en francais
- commencer avec base sqlite ?
- test d un store en cli ok avant travail sur infra
- playwright dans docker ?
- meilleur methode pour tester en cli python code ?
- au final l app sera dans un docker
---------------------------------------------------------------------------
ÉTAPE 1 — DÉFINITION DES ITEMS À RÉCUPÉRER
---------------------------------------------------------------------------

Créer un modèle canonique ProductSnapshot avec Pydantic contenant au minimum :

- source (amazon, cdiscount, unknown)
- url (canonique)
- fetched_at (datetime)
- title
- price
- currency
- shipping_cost
- stock_status (in_stock, out_of_stock, unknown)
- reference
- images (liste d’URL)
- category
- specs (clé / valeur)
- debug :
  - méthode utilisée (http / playwright)
  - erreurs
  - notes
  - statut technique

Documenter précisément chaque champ dans README.md.

---------------------------------------------------------------------------
ÉTAPE 2 — ARCHITECTURE DU PROJET
---------------------------------------------------------------------------

Proposer et implémenter une architecture modulaire :

pricewatch/
  app/
    core/
      schema.py
      registry.py        (détection store)
      io.py              (lecture YAML / écriture JSON)
      logging.py
    scraping/
      http_fetch.py
      pw_fetch.py        (Playwright)
    stores/
      base.py
      amazon/
        store.py
        selectors.yml
        fixtures/
      cdiscount/
        store.py
        selectors.yml
        fixtures/
    cli/
      main.py            (Typer)
  scrap_url.yaml
  scraped_store.json
  scraped/
  README.md
  TODO.md
  CHANGELOG.md
  pyproject.toml

---------------------------------------------------------------------------
PLAYWRIGHT — CONSIGNES
---------------------------------------------------------------------------

- Utiliser Playwright Python
- Prévoir les options CLI suivantes :
  - headless / headful
  - sauvegarde HTML
  - screenshot
  - timeout configurable
- Prévoir un mode debug renforcé
- Documenter l’installation Playwright dans README.md

---------------------------------------------------------------------------
ÉTAPE 3 — OUTILS CLI ET SCRAPING
---------------------------------------------------------------------------

Objectif : pipeline reproductible YAML → JSON.

1) Lire un fichier scrap_url.yaml
2) Pour chaque URL :
   - détecter le store
   - canoniser l’URL
   - récupérer la page (HTTP ou Playwright)
   - parser selon le store
3) Produire un fichier scraped_store.json

---------------------------------------------------------------------------
FORMAT scrap_url.yaml
---------------------------------------------------------------------------

urls:
  - "https://www.amazon.fr/dp/EXAMPLE"
  - "https://www.cdiscount.com/EXAMPLE"
options:
  use_playwright: true
  headful: false
  save_html: true
  save_screenshot: true
  timeout_ms: 60000

---------------------------------------------------------------------------
FORMAT scraped_store.json
---------------------------------------------------------------------------

Liste d’objets ProductSnapshot sérialisés.

---------------------------------------------------------------------------
STORES — RÈGLES
---------------------------------------------------------------------------

Un store = un dossier dédié.

Chaque store doit implémenter :
- match(url) → score
- canonicalize(url)
- extract_reference(...)
- fetch (HTTP ou Playwright)
- parse → ProductSnapshot

Parsing :
- utiliser XPath ou CSS selectors
- sélecteurs idéalement stockés dans selectors.yml
- au moins un fichier fixture HTML par store

---------------------------------------------------------------------------
COMMANDES CLI À IMPLÉMENTER
---------------------------------------------------------------------------

- pricewatch run --yaml scrap_url.yaml --out scraped_store.json
- pricewatch detect <url>
- pricewatch fetch <url> --http | --playwright
- pricewatch parse <store> --in fichier.html
- pricewatch doctor

Toutes les commandes doivent supporter :
- --debug
- logs détaillés (temps, méthode, erreurs)

---------------------------------------------------------------------------
TESTS
---------------------------------------------------------------------------

- pytest obligatoire
- tests de parsing sur fixtures HTML
- un dossier tests par store

---------------------------------------------------------------------------
OBSERVABILITÉ ET DEBUG
---------------------------------------------------------------------------

Logger systématiquement :
- méthode de récupération
- durée
- taille du HTML
- erreurs fréquentes (403, captcha, robot check)

En cas d’échec :
- remplir snapshot.debug.errors
- ne jamais crasher silencieusement

---------------------------------------------------------------------------
ÉTAPES SUIVANTES (À DÉCRIRE, PAS À CODER IMMÉDIATEMENT)
---------------------------------------------------------------------------

1. Base de données PostgreSQL + Alembic
2. Worker + planification (Redis + RQ ou Celery)
3. Web UI (ajout URL, liste produits, détail)
4. Historique prix
5. Alertes (baisse prix, retour stock)
6. Ajout simplifié de nouveaux stores

---------------------------------------------------------------------------
CONTRAINTES DE LIVRAISON
---------------------------------------------------------------------------

1. Générer d’abord les fichiers de base (README, TODO, CHANGELOG, structure).
2. Implémenter étape par étape (1 → 2 → 3).
3. Mettre à jour README / TODO / CHANGELOG à chaque étape.
4. Fournir des exemples CLI exécutables.

Objectif final de cette phase :
Un pipeline CLI fiable, debuggable, extensible,
servant de socle pour la BDD et la Web UI.

FIN DU PROMPT
