📦 Stock Manager - Gestion de stocks alimentaires

Une Progressive Web App (PWA) complète pour gérer les stocks alimentaires et utiles d'un ménage de 2 adultes et 4 enfants.

🎯 Fonctionnalités

✅ Gestion des produits

• ✓ Créer des produits avec image
• ✓ Scanner les codes-barres (caméra ou upload d'image)
• ✓ Définir un stock minimum à maintenir
• ✓ Catégoriser les produits
• ✓ Associer à un commerce spécifique

🛒 Liste de courses automatique

• ✓ Ajout automatique quand stock < minimum
• ✓ Organisation par commerce (Auchan, Lidl, Carrefour, etc.)
• ✓ Marquer les articles comme achetés
• ✓ Ajout automatique au stock lors de l'achat

📊 Suivi du stock

• ✓ Ajouter/retirer du stock facilement
• ✓ Historique des mouvements
• ✓ Alertes visuelles pour stock faible
• ✓ Vue d'ensemble par catégorie

🏪 Gestion des commerces

• ✓ Créer des commerces avec couleur personnalisée
• ✓ Filtrer les produits par commerce
• ✓ Liste de courses séparée par magasin

📱 PWA

• ✓ Installation sur mobile/desktop
• ✓ Fonctionne hors ligne (cache)
• ✓ Scanner de code-barres intégré
• ✓ Interface responsive

🚀 Démarrage rapide avec Docker

Prérequis

• Docker et Docker Compose installés
• Port 3000 (frontend dev) ou 80 (frontend prod) et 8000 (backend) disponibles

Mode Développement (avec Hot Reload ⚡)

Recommandé pour modifier le code - Les changements sont visibles immédiatement sans rebuild !

# 1. Première installation
docker-compose up -d --build

# 2. Accéder à l'application
# Frontend: http://localhost:3000 (avec hot reload!)
# Backend: http://localhost:8000

✨ Avantages :

• ✅ Modifications du code instantanées (backend et frontend)
• ✅ Pas besoin de rebuild à chaque changement
• ✅ Rechargement automatique dans le navigateur
• ✅ Logs en temps réel

📝 Modifications en live :

# Modifier n'importe quel fichier dans :
# - backend/app/  → uvicorn recharge automatiquement
# - frontend/src/ → Vite recharge automatiquement
# → Juste sauvegarder et voir les changements !

Mode Production

Pour déploiement final - Version optimisée et compilée.

# Utiliser le fichier de production
docker-compose -f docker-compose.prod.yml up -d --build

# Accéder à l'application
# Frontend: http://localhost (port 80)
# Backend: http://localhost:8000

Arrêter l'application

docker-compose down

Commandes utiles

Voir les logs en temps réel

docker-compose logs -f
# Ou pour un service spécifique :
docker-compose logs -f backend
docker-compose logs -f frontend

Initialiser avec des données d'exemple

docker-compose exec backend python app/init_sample_data.py

Redémarrer un service après modification de Dockerfile

docker-compose up -d --build backend
# ou
docker-compose up -d --build frontend

Rebuild complet (si problème)

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Reset complet (⚠️ supprime toutes les données)

docker-compose down -v
docker-compose up -d

🛠️ Développement local (sans Docker)

Backend (Python FastAPI)

cd backend
python -m venv venv
source venv/bin/activate  # Sur Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend (Vue 3)

cd frontend
npm install
npm run dev

L'application sera accessible sur http://localhost:3000

📱 Utilisation

1. Configuration initiale

1. Créer des commerces

   • Aller dans "Commerces"
   • Ajouter vos magasins (Auchan, Lidl, Carrefour, etc.)
   • Personnaliser les couleurs

2. Ajouter des produits

   • Cliquer sur "Nouveau produit"
   • Remplir les informations
   • Optionnel: ajouter une photo
   • Optionnel: scanner/saisir le code-barres
   • Définir le stock minimum

2. Gestion quotidienne

Ajouter du stock (après les courses)

1. Trouver le produit
2. Cliquer sur "Ajouter"
3. Indiquer la quantité achetée

Utiliser un produit

1. Scanner le code-barres OU trouver le produit
2. Cliquer sur "Utiliser"
3. Indiquer la quantité utilisée
4. ✅ Si stock < minimum → ajout automatique à la liste de courses

Faire les courses

1. Aller dans "Courses"
2. Voir les produits groupés par commerce
3. Faire vos courses
4. Marquer les articles comme achetés
5. ✅ Stock mis à jour automatiquement

3. Scanner des codes-barres

Méthode 1: Caméra

• Cliquer sur l'icône scanner
• Autoriser l'accès à la caméra
• Pointer vers le code-barres

Méthode 2: Upload d'image

• Prendre une photo du code-barres
• L'uploader dans le formulaire

📂 Structure du projet

stock-manager/
├── backend/                 # API FastAPI
│   ├── app/
│   │   ├── models.py       # Modèles SQLAlchemy
│   │   ├── schemas.py      # Schémas Pydantic
│   │   ├── database.py     # Configuration DB
│   │   ├── main.py         # Application principale
│   │   ├── routes/         # Routes API
│   │   │   ├── produits.py
│   │   │   ├── commerces.py
│   │   │   └── liste_courses.py
│   │   └── services/       # Logique métier
│   │       ├── produit_service.py
│   │       └── barcode_service.py
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/               # Application Vue 3
│   ├── src/
│   │   ├── components/     # Composants réutilisables
│   │   │   ├── ProductCard.vue
│   │   │   └── BarcodeScanner.vue
│   │   ├── views/          # Pages
│   │   │   ├── ProductsView.vue
│   │   │   └── ShoppingListView.vue
│   │   ├── stores/         # État Pinia
│   │   │   ├── products.js
│   │   │   ├── commerces.js
│   │   │   └── shoppingList.js
│   │   ├── composables/    # Composables Vue
│   │   │   └── useBarcodeScanner.js
│   │   ├── router/         # Configuration router
│   │   ├── App.vue
│   │   └── main.js
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── package.json
│   └── vite.config.js
│
└── docker-compose.yml      # Orchestration Docker

🔧 Technologies utilisées

Backend

• FastAPI - Framework web moderne et rapide
• SQLAlchemy - ORM pour la base de données
• SQLite - Base de données légère
• Pydantic - Validation des données
• OpenCV + pyzbar - Scan de codes-barres
• Pillow - Manipulation d'images

Frontend

• Vue 3 - Framework JavaScript progressif
• Pinia - Gestion d'état
• Vue Router - Routing
• Axios - Requêtes HTTP
• html5-qrcode - Scanner de codes-barres
• Vite - Build tool rapide
• PWA - Progressive Web App

Infrastructure

• Docker - Containerisation
• Docker Compose - Orchestration
• Nginx - Serveur web (frontend)

📊 API Endpoints

Produits

• GET /api/produits/ - Liste des produits
• GET /api/produits/{id} - Détails d'un produit
• GET /api/produits/low-stock - Produits en rupture
• POST /api/produits/ - Créer un produit
• PUT /api/produits/{id} - Modifier un produit
• DELETE /api/produits/{id} - Supprimer un produit
• POST /api/produits/{id}/image - Upload image
• POST /api/produits/{id}/stock/add - Ajouter du stock
• POST /api/produits/{id}/stock/use - Utiliser du stock
• POST /api/produits/scan-barcode - Scanner code-barres

Liste de courses

• GET /api/liste-courses/ - Liste de courses
• GET /api/liste-courses/par-commerce - Groupée par commerce
• POST /api/liste-courses/{id}/acheter - Marquer acheté
• DELETE /api/liste-courses/{id} - Retirer de la liste
• POST /api/liste-courses/add/{produit_id} - Ajouter manuellement

Commerces

• GET /api/commerces/ - Liste des commerces
• POST /api/commerces/ - Créer un commerce
• PUT /api/commerces/{id} - Modifier un commerce
• DELETE /api/commerces/{id} - Supprimer un commerce

🎨 Personnalisation

Ajouter de nouvelles catégories

Les catégories sont libres - tapez simplement le nom lors de la création d'un produit.

Modifier les couleurs des commerces

Chaque commerce peut avoir sa propre couleur pour faciliter l'identification visuelle.

Unités de mesure

Supportées: unité, kg, g, L, ml, etc. Libre à saisir.

🐛 Dépannage

Le scanner ne fonctionne pas

• Vérifier les permissions caméra du navigateur
• Utiliser HTTPS en production (requis pour la caméra)
• Essayer la méthode upload d'image

Erreur de connexion backend

docker-compose logs backend

L'image ne s'affiche pas

• Vérifier que le dossier uploads est bien monté
• Vérifier les permissions du dossier

Reset complet de la base de données

docker-compose down -v
docker-compose up -d

📄 Licence

Ce projet est fourni tel quel pour usage personnel.

👨‍👩‍👧‍👦 Parfait pour

• Familles nombreuses (2 adultes + 4 enfants comme spécifié)
• Gestion efficace des stocks alimentaires
• Optimisation des courses
• Réduction du gaspillage alimentaire
• Organisation multi-commerces

🚀 Améliorations futures possibles

• Statistiques de consommation
• Export des listes de courses (PDF, email)
• Notifications push pour ruptures
• Partage entre membres de la famille
• Recettes basées sur le stock disponible
• Import de produits depuis bases de données publiques
• Mode sombre
• Multi-langues

---

Bon usage de Stock Manager ! 🎉