# 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

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

# Install Playwright browsers
playwright install
```

### CLI Commands (To be implemented)

```bash
# 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

```bash
# 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:
```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
```

**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