# 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.