geo/api/docs/EXPORT-SYSTEM.md

# Système d'Export/Import d'Opérations - Geosector API

## Vue d'ensemble

Le système d'export/import permet de sauvegarder et restaurer des opérations complètes avec toutes leurs données associées (passages, utilisateurs, secteurs, relations).

## Architecture

### Routes API

#### Exports

- `GET /api/operations/{id}/export/excel` - Export Excel (consultation)
- `GET /api/operations/{id}/export/json` - Export JSON (sauvegarde)
- `GET /api/operations/{id}/export/full` - Export combiné (Excel + JSON)

#### Gestion des sauvegardes

- `GET /api/operations/{id}/backups` - Liste des sauvegardes
- `GET /api/operations/{id}/backups/{backup_id}` - Télécharger une sauvegarde
- `DELETE /api/operations/{id}/backups/{backup_id}` - Supprimer une sauvegarde

### Structure des fichiers

```
uploads/entites/{entite_id}/operations/{operation_id}/documents/exports/
├── excel/
│   └── geosector-export-{operation_id}-{timestamp}.xlsx
└── json/
    └── geosector-backup-{operation_id}-{type}-{timestamp}.json
```

## Export Excel

### Contenu

Le fichier Excel contient 4 feuilles :

#### 1. Feuille "Passages"

- **Colonnes** : ID_Passage, Date, Heure, Prénom, Nom, Tournée, Type, N°, Rue, Ville, Habitat, Donateur, Email, Tél, Montant, Règlement, Remarque, FK_User, FK_Sector, FK_Operation
- **Données déchiffrées** : Noms, emails, téléphones
- **Formatage** : Dates françaises (dd/mm/yyyy), types traduits

#### 2. Feuille "Utilisateurs"

- **Colonnes** : ID_User, Nom, Prénom, Email, Téléphone, Mobile, Rôle, Date_création, Actif, FK_Entite
- **Données déchiffrées** : Informations personnelles

#### 3. Feuille "Secteurs"

- **Colonnes** : ID_Sector, Libellé, Couleur, Date_création, Actif, FK_Operation

#### 4. Feuille "Secteurs-Utilisateurs"

- **Colonnes** : ID_Relation, FK_Sector, Nom_Secteur, FK_User, Nom_Utilisateur, Date_assignation, FK_Operation

### Paramètres optionnels

- `?user_id={id}` - Filtrer les passages par utilisateur

### Exemple d'utilisation

```bash
# Export complet
GET /api/operations/2644/export/excel

# Export filtré par utilisateur
GET /api/operations/2644/export/excel?user_id=123
```

## Export JSON

### Structure du fichier JSON

```json
{
  "export_metadata": {
    "version": "1.0",
    "export_date": "2025-06-21T16:19:23Z",
    "source_entite_id": 5,
    "export_type": "full_operation"
  },
  "operation": {
    "id": 2644,
    "libelle": "OPE 2024-25",
    "date_deb": "2024-09-01",
    "date_fin": "2025-05-30",
    "fk_entite": 5,
    "chk_distinct_sectors": 1,
    "created_at": "2024-08-15T10:00:00Z"
  },
  "users": [...],
  "sectors": [...],
  "passages": [...],
  "user_sectors": [...]
}
```

### Types d'export JSON

- **manual** : Export à la demande (par défaut)
- **auto** : Sauvegarde automatique (avant modifications importantes)

### Paramètres

- `?type=manual|auto` - Type d'export

## Sécurité

### Contrôles d'accès

- ✅ Authentification obligatoire
- ✅ Vérification d'appartenance à l'entité
- ✅ Isolation des données par entité
- ✅ Logs détaillés de toutes les opérations

### Données sensibles

- ✅ Chiffrement/déchiffrement automatique
- ✅ Données personnelles protégées
- ✅ Pas d'exposition des clés de chiffrement

## Stockage et organisation

### Enregistrement en base

Tous les fichiers sont enregistrés dans la table `medias` :

```sql
support = 'operation'
support_id = {operation_id}
file_type = 'xlsx' | 'json'
description = 'Export Excel opération - {libelle}'
```

### Métadonnées des fichiers

- **ID** : Identifiant unique en base
- **Filename** : Nom du fichier généré
- **Path** : Chemin relatif depuis la racine
- **Size** : Taille en octets
- **Type** : excel | json

## Exemples de réponses API

### Export Excel réussi

```json
{
  "status": "success",
  "message": "Export Excel généré avec succès",
  "file": {
    "id": 123,
    "filename": "geosector-export-2644-20250621-161923.xlsx",
    "path": "uploads/entites/5/operations/2644/documents/exports/excel/geosector-export-2644-20250621-161923.xlsx",
    "size": 45678,
    "type": "excel"
  }
}
```

### Export complet réussi

```json
{
  "status": "success",
  "message": "Export complet généré avec succès",
  "files": {
    "excel": {
      "id": 123,
      "filename": "geosector-export-2644-20250621-161923.xlsx",
      "path": "uploads/entites/5/operations/2644/documents/exports/excel/geosector-export-2644-20250621-161923.xlsx",
      "size": 45678,
      "type": "excel"
    },
    "json": {
      "id": 124,
      "filename": "geosector-backup-2644-manual-20250621-161923.json",
      "path": "uploads/entites/5/operations/2644/documents/exports/json/geosector-backup-2644-manual-20250621-161923.json",
      "size": 12345,
      "type": "json"
    }
  }
}
```

### Liste des sauvegardes

```json
{
  "status": "success",
  "backups": [
    {
      "id": 124,
      "fichier": "geosector-backup-2644-manual-20250621-161923.json",
      "file_type": "json",
      "file_size": 12345,
      "description": "Sauvegarde JSON opération - manual - OPE 2024-25",
      "created_at": "2025-06-21 16:19:23",
      "fk_user_creat": 1
    },
    {
      "id": 123,
      "fichier": "geosector-export-2644-20250621-161923.xlsx",
      "file_type": "xlsx",
      "file_size": 45678,
      "description": "Export Excel opération - OPE 2024-25",
      "created_at": "2025-06-21 16:19:23",
      "fk_user_creat": 1
    }
  ]
}
```

## Installation et dépendances

### PhpSpreadsheet

```bash
composer require phpoffice/phpspreadsheet
```

### Permissions de dossiers

```bash
chmod 755 uploads/
chmod 755 uploads/entites/
```

## Gestion des erreurs

### Erreurs courantes

- **401** : Non authentifié
- **403** : Pas d'accès à l'entité
- **404** : Opération non trouvée
- **500** : Erreur de génération

### Logs

Tous les événements sont loggés via `LogService` :

- Exports réussis (level: info)
- Erreurs de génération (level: error)
- Tentatives d'accès non autorisées (level: warning)

## Maintenance

### Nettoyage automatique (à implémenter)

- Sauvegardes auto > 30 jours
- Fichiers temporaires > 24h
- Vérification cohérence base/fichiers

### Monitoring

- Espace disque utilisé
- Nombre de fichiers par entité
- Fréquence des exports

## Évolutions futures

### Import/Restauration

- Validation des fichiers JSON
- Import transactionnel
- Gestion des conflits d'IDs
- Mapping entités source/cible

### Optimisations

- Compression des fichiers
- Export asynchrone pour gros volumes
- Cache des exports fréquents
- API de streaming pour téléchargements