suivi_produit/docs/plans/2026-01-18-frontend-phase2-design.md

Plan Frontend Phase 2 - suivi_produits

Date : 2026-01-18 Statut : Validé Priorité : Fonctionnel d'abord, puis visualisation

---

Contexte

Le backend (Phase 1) est terminé :

• Scraper Playwright fonctionnel (9/9 produits OK)
• API FastAPI avec CRUD produits complet
• Modèles SQLAlchemy (products, snapshots, scrape_runs)
• Scheduler APScheduler
• Tests unitaires (7 tests OK)

Le frontend est squelettique : App.jsx basique, ProductCard vide, pas de store.

---

Décisions de design

Question	Choix
Priorité	Fonctionnel d'abord
Ajout produit	URL seule (backend extrait ASIN + scrape immédiat)
State management	Zustand
Page debug	Dès le début (utile pendant le dev)
Routing	React Router (évolutivité multi-stores)

---

Architecture Frontend

frontend/src/
├── api/
│   └── client.js          # API calls (extensible par store)
├── components/
│   ├── common/            # Composants réutilisables
│   │   ├── Modal.jsx
│   │   ├── Badge.jsx
│   │   └── PriceDisplay.jsx
│   ├── products/
│   │   ├── ProductCard.jsx
│   │   ├── ProductGrid.jsx
│   │   └── AddProductForm.jsx
│   └── debug/
│       ├── DbTable.jsx
│       └── LogViewer.jsx
├── pages/
│   ├── HomePage.jsx       # Grille produits
│   ├── DebugPage.jsx      # Tables + logs
│   └── SettingsPage.jsx   # (futur) Config frontend/backend
├── stores/
│   └── useProductStore.js
├── hooks/                 # (futur) Custom hooks
├── styles/
│   ├── _variables.scss    # Couleurs Gruvbox
│   └── global.scss
├── App.jsx                # React Router setup
└── main.jsx

---

Endpoints API

Endpoint	Méthode	Statut	Description
/products	GET	Existe	Liste paginée
/products	POST	Existe	Créer produit
/products/{id}	GET/PUT/DELETE	Existe	CRUD
/products/{id}/snapshots	GET	À créer	Historique prix
/products/{id}/scrape	POST	À vérifier	Scrape un produit
/scrape/all	POST	À vérifier	Scrape tous
/debug/tables	GET	À créer	Dump tables SQLite
/debug/logs	GET	À créer	Derniers logs scrap

---

Plan d'implémentation

Étape 1 : Page Debug (fondation)

Objectif : Avoir une vue sur les données pendant le développement

Backend :

• Créer endpoint GET /debug/tables (dump products, snapshots, scrape_runs)
• Créer endpoint GET /debug/logs (lecture backend/logs/scrap.log)

Frontend :

• Installer react-router-dom
• Setup React Router avec 2 routes (/, /debug)
• Créer DebugPage.jsx avec composants DbTable et LogViewer
• Afficher les 3 tables SQLite dans des sections distinctes
• Afficher les logs JSON de scraping

---

Étape 2 : Store Zustand + Liste produits

Objectif : Connexion frontend-backend fonctionnelle

Frontend :

• Installer zustand
• Créer useProductStore.js avec actions (fetch, add, delete, scrape)
• Enrichir client.js avec toutes les fonctions fetch
• Connecter HomePage.jsx au store
• Afficher les produits existants (version basique)

---

Étape 3 : Ajout de produit

Objectif : Permettre d'ajouter un produit via URL Amazon

Backend :

• Modifier POST /products pour accepter juste l'URL
• Extraire automatiquement l'ASIN de l'URL
• Déclencher scrape automatique après création

Frontend :

• Créer Modal.jsx (composant réutilisable)
• Créer AddProductForm.jsx (input URL + validation)
• Intégrer dans Header avec bouton "Add Product"
• Gestion loading/error dans l'UI
• Refresh automatique après ajout

---

Étape 4 : Actions sur produit

Objectif : Pouvoir scraper et supprimer un produit

Backend :

• Vérifier/créer endpoint POST /products/{id}/scrape

Frontend :

• Ajouter boutons Scrap/Delete sur ProductCard
• Modal de confirmation avant suppression
• Feedback visuel pendant le scraping (spinner)
• Refresh automatique après action

---

Étape 5 : Amélioration visuelle ProductCard

Objectif : Vignette produit complète selon le schéma CLAUDE.md

Frontend :

• Image non tronquée (object-fit: contain)
• Section prix (actuel, conseillé, réduction)
• Badges (Prime, Choix Amazon, Deal, Exclusivité)
• Note + nombre d'avis
• Stock status
• Responsive grid (colonnes configurables via config_frontend.json)

---

Étape 6 : Graphique historique (Phase 2.5)

Objectif : Visualiser l'évolution des prix sur 30 jours

Backend :

• Créer endpoint GET /products/{id}/snapshots

Frontend :

• Installer chart.js + react-chartjs-2
• Créer composant PriceChart
• Intégrer dans ProductCard
• Afficher min/max/tendance sous le graphique
• Couleurs selon tendance (vert baisse, orange stable, rouge hausse)

---

Thème visuel

Gruvbox vintage dark (défini dans CLAUDE.md) :

• Fond : #282828
• Cartes : #3c3836
• Texte : #ebdbb2
• Accent orange : #fe8019
• Accent jaune : #fabd2f
• Accent vert : #b8bb26

Icônes : Font Awesome

---

Critères de succès Phase 2

• Un utilisateur peut ajouter un produit via URL Amazon
• Le scraping se déclenche automatiquement
• Les produits s'affichent dans une grille responsive
• On peut supprimer un produit
• On peut déclencher un scrape manuel
• La page debug montre l'état des tables et logs