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

# 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

{
  "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 :

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

{
  "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

{
  "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

{
  "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

composer require phpoffice/phpspreadsheet

Permissions de dossiers

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