chore: sync project files
This commit is contained in:
Gilles Soulier
185
CLAUDE.md
Executable file
185
CLAUDE.md
Executable file
@@ -0,0 +1,185 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user