First commit

README.md

@@ -0,0 +1,181 @@
+# Cheque Scanner - Extraction d'informations de chèques
+
+Système containerisé pour l'extraction d'informations à partir d'images de chèques, avec une API REST accessible depuis PHP.
+
+## Fonctionnalités
+
+- Téléchargement d'images de chèques via une API REST
+- Extraction des informations principales (montant, date, bénéficiaire, numéro de chèque)
+- Traitement asynchrone avec files d'attente prioritaires
+- Scaling horizontal des workers de traitement
+- API sécurisée par clé d'API
+- Documentation Swagger intégrée
+- Intégration simple depuis PHP
+
+## Architecture
+
+Le système est composé de plusieurs services containerisés :
+
+- **API REST** (FastAPI) : Point d'entrée pour les applications clientes
+- **Workers** : Traitent les images et extraient les informations
+- **Redis** : Gère les files d'attente et stocke les résultats
+- **Volumes partagés** : Stockent les images et les résultats
+
+```
+Application PHP → API REST → Redis Queue → Workers → Résultats JSON
+```
+
+## Prérequis
+
+- Docker et Docker Compose
+- Git (pour cloner le dépôt)
+
+## Installation
+
+1. Cloner le dépôt :
+   ```bash
+   git clone https://github.com/votre-utilisateur/cheque-scanner.git
+   cd cheque-scanner
+   ```
+
+2. Configurer les variables d'environnement :
+   ```bash
+   # Copier le fichier d'exemple
+   cp .env.example .env
+   
+   # Modifier les valeurs selon vos besoins
+   nano .env
+   ```
+   
+   **Important** : Modifiez la valeur de `API_KEY` pour sécuriser votre API !
+
+3. Construire et démarrer les services :
+   ```bash
+   docker-compose up -d --build
+   ```
+
+4. Vérifier que les services sont en cours d'exécution :
+   ```bash
+   docker-compose ps
+   ```
+
+## Utilisation
+
+### Via l'API REST
+
+L'API est accessible à l'adresse `http://localhost:8000/api/v1/`
+
+Documentation de l'API : `http://localhost:8000/api/v1/docs`
+
+#### Endpoints principaux :
+
+- `POST /api/v1/upload` : Télécharge une image et crée une tâche d'extraction
+- `GET /api/v1/status/{job_id}` : Vérifie l'état d'une tâche
+- `GET /api/v1/result/{job_id}` : Récupère les résultats d'une tâche terminée
+- `GET /api/v1/health` : Vérifie l'état de l'API
+
+### Via l'intégration PHP
+
+Un exemple d'intégration PHP est fourni dans `examples/php-integration.php`. Pour l'utiliser :
+
+1. Modifier les variables de configuration :
+   ```php
+   $api_url = 'http://localhost:8000/api/v1';  // URL de l'API
+   $api_key = 'your-secret-api-key-change-me'; // Clé API (doit correspondre à celle définie dans .env)
+   $imagePath = '/path/to/cheque_image.jpg';   // Chemin vers l'image à traiter
+   ```
+
+2. Exécuter le script :
+   ```bash
+   php examples/php-integration.php
+   ```
+
+## Fonctionnement
+
+1. L'application PHP envoie une image à l'API
+2. L'API stocke l'image et crée une tâche dans Redis
+3. Un worker prend la tâche et traite l'image
+4. Le worker extrait les informations et les stocke dans Redis
+5. L'application PHP interroge l'API pour récupérer les résultats
+
+## Scaling
+
+Pour augmenter le nombre de workers et améliorer les performances :
+
+```bash
+# Modifier le nombre de répliques dans .env
+WORKER_REPLICAS=4
+
+# Redémarrer les services
+docker-compose up -d --scale worker=4
+```
+
+## Maintenance
+
+### Logs
+
+Pour voir les logs des services :
+
+```bash
+# Tous les services
+docker-compose logs -f
+
+# Un service spécifique
+docker-compose logs -f api
+docker-compose logs -f worker
+```
+
+### Nettoyage des données
+
+Les données sont stockées dans des volumes Docker. Pour les nettoyer :
+
+```bash
+# Arrêter les services
+docker-compose down
+
+# Supprimer les volumes
+docker volume rm cheque-scanner-shared-data cheque-scanner-redis-data
+
+# Redémarrer les services
+docker-compose up -d
+```
+
+## Sécurité
+
+- L'API est protégée par une clé d'API
+- Les images sont stockées temporairement
+- Les communications entre les services sont limitées au réseau Docker interne
+
+## Dépannage
+
+### L'API ne répond pas
+
+Vérifier que les services sont en cours d'exécution :
+```bash
+docker-compose ps
+```
+
+Vérifier les logs de l'API :
+```bash
+docker-compose logs -f api
+```
+
+### Les traitements échouent
+
+Vérifier les logs des workers :
+```bash
+docker-compose logs -f worker
+```
+
+S'assurer que Tesseract OCR est correctement installé dans le conteneur :
+```bash
+docker-compose exec worker tesseract --version
+```
+
+## Contribution
+
+Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.
+
+## Licence
+
+Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.