chore: sync project files

PROJECT_SPEC.md

@@ -0,0 +1,250 @@
+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