# Outils et Technologies

Ce document liste les technologies utilisées dans le projet suivi_produit.

---

## Backend

| Outil | Version | Description |
|-------|---------|-------------|
| **Python** | 3.11+ | Langage principal du backend |
| **FastAPI** | ^0.109 | Framework web asynchrone, génération automatique OpenAPI |
| **Uvicorn** | ^0.24 | Serveur ASGI haute performance pour FastAPI |
| **Pydantic** | ^2.5 | Validation des données et sérialisation JSON |
| **APScheduler** | ^3.11 | Planificateur de tâches pour le scraping périodique |
| **Loguru** | ^0.7 | Logging simplifié avec rotation automatique |
| **python-dotenv** | ^1.0 | Chargement des variables d'environnement depuis `.env` |

### Gestion des dépendances
| Outil | Description |
|-------|-------------|
| **Poetry** | Gestionnaire de dépendances et environnements virtuels Python |

---

## Scraping

| Outil | Version | Description |
|-------|---------|-------------|
| **Playwright** | ^1.40 | Automatisation navigateur (Chromium) pour le scraping |
| **BeautifulSoup4** | ^4.12 | Parsing HTML pour extraction des données |

### Configuration Playwright
- **Navigateur** : Chromium (headless par défaut)
- **Locale** : `fr-FR`
- **Timezone** : `Europe/Paris`
- **Viewport** : 1366x768
- **Délais aléatoires** : 1-3s entre les requêtes (anti-détection)

---

## Base de Données

| Outil | Description |
|-------|-------------|
| **SQLite** | Base de données relationnelle légère, fichier unique |
| **SQLAlchemy** | ORM Python pour la gestion des modèles et requêtes |

### Structure des tables
- `products` : informations produits (URL, ASIN, titre, catégorie)
- `product_snapshots` : historique des prix et états (prix, stock, note, badges)
- `scrape_runs` : métadonnées des exécutions de scraping

### Stockage fichiers
- **Raw JSON** : sauvegarde brute des scrapes dans `backend/data/raw/`
- **Screenshots** : captures debug dans `backend/data/screenshots/`

---

## Frontend

| Outil | Version | Description |
|-------|---------|-------------|
| **React** | ^18.3 | Bibliothèque UI composants |
| **Vite** | ^5.1 | Bundler et serveur de développement rapide |
| **Zustand** | ^4.4 | Gestion d'état globale légère |
| **React Router** | ^6.22 | Routage SPA |
| **SCSS/Sass** | ^1.77 | Préprocesseur CSS |

### Graphiques
| Outil | Version | Description |
|-------|---------|-------------|
| **Chart.js** | ^4.5 | Bibliothèque de graphiques |
| **react-chartjs-2** | ^5.3 | Wrapper React pour Chart.js |
| **chartjs-plugin-annotation** | ^3.1 | Plugin pour lignes de référence |

### Icônes
| Outil | Version | Description |
|-------|---------|-------------|
| **Font Awesome** | ^6.5 | Bibliothèque d'icônes (Free) |

---

## Thème UI

### Palette Gruvbox Dark
Le thème utilise la palette **Gruvbox** en mode sombre :

| Couleur | Hex | Usage |
|---------|-----|-------|
| Background | `#282828` | Fond principal |
| Background Alt | `#3c3836` | Cartes, modales |
| Background Light | `#504945` | Hover, bordures |
| Foreground | `#ebdbb2` | Texte principal |
| Foreground Dim | `#a89984` | Texte secondaire |
| Orange | `#fe8019` | Accent principal, liens |
| Yellow | `#fabd2f` | Warnings, tendance stable |
| Green | `#b8bb26` | Succès, baisse de prix |
| Red | `#fb4934` | Erreurs, hausse de prix |
| Blue | `#83a598` | Info, badges |
| Purple | `#d3869b` | Badges spéciaux |
| Aqua | `#8ec07c` | Stock disponible |

### Style
- **Arrondis** : `border-radius: 8px` (cartes), `4px` (boutons)
- **Ombres** : `box-shadow: 0 4px 6px rgba(0,0,0,0.3)`
- **Police** : System fonts stack (sans-serif)
- **Responsive** : Grille configurable (1-4 colonnes)

---

## Tests

| Outil | Version | Description |
|-------|---------|-------------|
| **Pytest** | ^8.4 | Framework de tests Python |
| **Coverage** | - | Mesure de couverture de code |

### Commandes
```bash
# Tests unitaires
poetry run pytest

# Avec couverture
poetry run coverage run -m pytest
poetry run coverage report -m

# Test scraper CLI
SCRAPE_TEST_MAX=0 poetry run python backend/app/scraper/run_scrape_tests.py
```

---

## Qualité de Code

| Outil | Version | Description |
|-------|---------|-------------|
| **Ruff** | ^0.1 | Linter Python ultra-rapide (remplace flake8, isort) |
| **MyPy** | ^1.9 | Vérification de types statique |
| **Pre-commit** | ^3.5 | Hooks Git pour qualité automatique |

### Configuration Pre-commit
```bash
# Installation des hooks
pre-commit install

# Exécution manuelle
pre-commit run --all-files
```

---

## Déploiement

### Docker
| Outil | Description |
|-------|-------------|
| **Docker** | Conteneurisation des services |
| **Docker Compose** | Orchestration multi-conteneurs |
| **Nginx** | Serveur web pour le frontend (reverse proxy) |

### Images Docker
| Service | Base | Description |
|---------|------|-------------|
| Backend | `python:3.11-slim` | FastAPI + Playwright + Chromium |
| Frontend | `node:20-alpine` → `nginx:alpine` | Build Vite + serveur Nginx |

### Volumes
| Volume | Contenu |
|--------|---------|
| `suivi_produit_data` | SQLite + raw JSON |
| `suivi_produit_logs` | Fichiers de log |

### Ports
| Service | Port interne | Port exposé |
|---------|--------------|-------------|
| Backend | 8008 | 8008 |
| Frontend | 80 | 8080 |

---

## Versionnement

| Outil | Description |
|-------|-------------|
| **Git** | Contrôle de version |
| **Gitea** | Serveur Git self-hosted |

### Conventions de commit
Format : `type: description`

| Type | Description |
|------|-------------|
| `feat` | Nouvelle fonctionnalité |
| `fix` | Correction de bug |
| `refactor` | Refactorisation sans changement fonctionnel |
| `docs` | Documentation |
| `style` | Formatage, pas de changement de code |
| `test` | Ajout ou modification de tests |
| `chore` | Maintenance, dépendances |

---

## Structure des Fichiers de Configuration

| Fichier | Description |
|---------|-------------|
| `pyproject.toml` | Config Poetry, dépendances Python, scripts |
| `backend/config_backend.json` | Paramètres scraping, stores, taxonomie |
| `frontend/config_frontend.json` | Thème, layout, champs visibles |
| `.env` | Variables d'environnement (non versionné) |
| `.env.example` | Template des variables d'environnement |
| `.env.docker` | Config pour déploiement Docker |
| `docker-compose.yml` | Définition des services Docker |

---

## Diagramme d'Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Client (Browser)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Frontend (Nginx :8080)                   │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  React 18 + Vite + Zustand + Chart.js               │    │
│  │  Thème Gruvbox Dark                                  │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │ /api/*
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Backend (FastAPI :8008)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   API REST   │  │  Scheduler   │  │   Scraper    │       │
│  │   (Routes)   │  │ (APScheduler)│  │ (Playwright) │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                              │                               │
│                              ▼                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              SQLAlchemy ORM + SQLite                 │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Stockage Persistant                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   suivi.db   │  │  data/raw/   │  │    logs/     │       │
│  │   (SQLite)   │  │  (JSON)      │  │  (Loguru)    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
```