scrap/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PriceWatch - Application Python de suivi de prix e-commerce (Amazon, Cdiscount, extensible à d'autres sites).

L'objectif est de construire une application modulaire et testable en CLI pour tracker les prix de produits, avec scraping robuste (HTTP + Playwright fallback), avant d'ajouter une base de données et une interface web.

Langue du projet: Les commentaires de code et discussions sont en français.

Commands

Development Setup

# Install dependencies (when pyproject.toml exists)
pip install -e .

# Install Playwright browsers
playwright install

CLI Commands (To be implemented)

# Main scraping pipeline
pricewatch run --yaml scrap_url.yaml --out scraped_store.json

# Detect store from URL
pricewatch detect <url>

# Fetch a single URL (HTTP or Playwright)
pricewatch fetch <url> --http
pricewatch fetch <url> --playwright

# Parse HTML file with specific store parser
pricewatch parse <store> --in fichier.html

# System health check
pricewatch doctor

# All commands support --debug flag for detailed logging

Testing

# Run all tests
pytest

# Run tests for a specific store
pytest tests/stores/amazon/
pytest tests/stores/cdiscount/

# Run with coverage
pytest --cov=pricewatch

Architecture

Le projet suit une architecture modulaire stricte:

pricewatch/
  app/
    core/
      schema.py          # Modèle Pydantic ProductSnapshot (canonique)
      registry.py        # Détection automatique du store depuis URL
      io.py              # Lecture YAML / écriture JSON
      logging.py         # Configuration des logs
    scraping/
      http_fetch.py      # Récupération HTTP simple
      pw_fetch.py        # Récupération Playwright (fallback anti-bot)
    stores/
      base.py            # Classe abstraite BaseStore
      amazon/
        store.py         # Implémentation AmazonStore
        selectors.yml    # Sélecteurs XPath/CSS
        fixtures/        # Fichiers HTML de test
      cdiscount/
        store.py         # Implémentation CdiscountStore
        selectors.yml    # Sélecteurs XPath/CSS
        fixtures/        # Fichiers HTML de test
    cli/
      main.py            # CLI Typer
  tests/                 # Tests pytest par module/store
  scrap_url.yaml         # Fichier de configuration des URLs à scraper
  scraped_store.json     # Sortie du scraping
  scraped/               # Dossier pour HTML/screenshots de debug

Core Concepts

ProductSnapshot (Pydantic model) - Modèle canonique contenant:

• Métadonnées: source, url, fetched_at
• Données produit: title, price, currency, shipping_cost, stock_status, reference, images, category, specs
• Debug: method (http/playwright), errors, notes, status

BaseStore (Abstract) - Chaque store doit implémenter:

• match(url) -> score: Détection du site
• canonicalize(url): Normalisation de l'URL
• extract_reference(...): Extraction de la référence produit (ASIN, SKU)
• fetch(...): Récupération de la page
• parse(...) -> ProductSnapshot: Parsing vers le modèle canonique

Registry - Système de détection automatique qui teste tous les stores enregistrés avec match() et sélectionne celui avec le meilleur score.

Scraping Strategy:

1. Tenter HTTP d'abord (rapide)
2. Si échec (403, captcha, etc.), fallback Playwright
3. Logging systématique: méthode, durée, taille HTML, erreurs
4. Sauvegarde optionnelle HTML/screenshot pour debug

Configuration Files

scrap_url.yaml - Input:

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

scraped_store.json - Output: Liste de ProductSnapshot sérialisés en JSON.

selectors.yml (par store) - Contient les sélecteurs XPath/CSS pour extraire chaque champ du ProductSnapshot.

Technical Requirements

• Python: 3.12
• CLI Framework: Typer
• Data Validation: Pydantic
• Scraping: requests + Playwright Python
• Testing: pytest avec fixtures HTML
• Target: Application finale en Docker

Development Rules

1. Justification technique: Chaque décision doit être justifiée en 1-3 phrases
2. Documentation obligatoire: Maintenir README.md, TODO.md, CHANGELOG.md à jour à chaque étape
3. Code exécutable: Chaque étape livrée doit être testable avec des exemples CLI
4. Robustesse: Les erreurs (403, captcha, anti-bot) sont attendues - prioriser l'observabilité
5. Pas d'optimisation prématurée: Implémenter ce qui est demandé, pas plus
6. Tests: pytest obligatoire, au moins un fixture HTML par store
7. Logs détaillés: Méthode, durée, taille HTML, erreurs systématiquement loggées
8. Ne jamais crasher silencieusement: En cas d'échec, remplir snapshot.debug.errors

Playwright Specifics

• Mode headless/headful via CLI
• Sauvegarde HTML optionnelle dans scraped/
• Screenshot optionnel pour debug
• Timeout configurable
• Mode debug renforcé avec logs détaillés

Testing Strategy

• Tests de parsing sur fixtures HTML réels
• Un dossier tests/ par store
• Tests unitaires des fonctions match(), canonicalize(), extract_reference()
• Tests d'intégration du pipeline complet

Future Roadmap (Non implémenté)

Les étapes suivantes sont prévues mais pas encore codées:

1. Base de données PostgreSQL + Alembic
2. Worker + planification (Redis + RQ ou Celery)
3. Web UI responsive, dark theme type Gruvbox
4. Historique prix avec graphiques
5. Alertes (baisse prix, retour stock)
6. Système de plugins pour nouveaux stores

Notes

• SQLite sera utilisé initialement avant PostgreSQL
• L'application finale sera conteneurisée (Docker)
• Playwright pourra tourner dans Docker
• Le projet est en phase 1: CLI d'abord, infrastructure ensuite