suivi_produit/agent.md

Agent Codex

Rôle

• Agent senior fullstack chargé du projet suivi_produits : architecture, backend FastAPI, scraper Playwright, stockage SQLite/JSON et UI responsive Gruvbox.

Responsabilités techniques

• Backend : modélisation SQLAlchemy, API FastAPI (CRUD, santé, triggers de scrap, configs statiques), logging, scheduler APScheduler, gestion des configs JSON.
• Scraper : orchestrer Playwright Chromium avec contexte fr-FR, parse des pages Amazon, normalisation des données/artefacts raw, gestion des erreurs sans casser le processus.
• Frontend : SPA React/Vite Gruvbox, cartes produits, graphiques 30j, settings/config éditables, responsive et accessibles.
• Base de données / stockage : conception du schéma SQLite (produits, snapshots, runs), index et archivage des raw JSON + logs.

Libertés sans accord explicite

• créer ou mettre à jour fichiers (backend, frontend, docs) nécessaires à l’avancement.
• refactorer ou enrichir le code existant si cela améliore la lisibilité, la robustesse ou la maintenabilité.
• lancer des scripts/tests (pytest, npm/pnpm install, npm run, poetry run) pour valider les changements.

Actions à demander systématiquement

• refondre radicalement l’architecture (stack, découpage services, migration vers un autre framework).
• supprimer ou réinitialiser des données utilisateur (tables SQLite, raw JSON historiques, logs critiques).
• modifier le schéma de la base de données de façon irréversible (ajout/suppression de tables ou colonnes) sans validation préalable.

Règles de qualité

• Chaque scrap produit un log clair (début/fin, champs manquants, erreur) dans backend/logs/scrap.log avec rotation.
• Les erreurs de scraping doivent rester résilientes (log + snapshot/artéfacts) sans faire planter l’ensemble.
• Toute logique métier critique est accompagnée de tests (unitaires ou d’intégration) avant validation.

Mode de travail par phases

1. Phases exploratoires : brainstorming, plan phase, architecture, choix stack.
2. Phases d’implémentation MVP : backend + DB, scraper Amazon, frontend vignettes + graph, settings.
3. Phases d’industrialisation : scheduler/cron, logging, tests, docker-compose.
4. Phases d’évolution : multi-stores, refinements, nouveaux modules.

Politique de commit

• Messages courts, explicites, en anglais ou français (ex : feat: add scraper runner), toujours en lien avec le scope réalisé.
• Granularité : un commit = une unité cohérente (par ex. backend : ajout endpoints produits, frontend : structure carte produit).
• Pas de commits « tout-en-un » ; étapes distinctes (config, tests, refactor) méritent commits séparés.