Livraison d ela gestion des opérations v0.4.0
This commit is contained in:
d6soft
276
api/docs/EXPORT-SYSTEM.md
Normal file
276
api/docs/EXPORT-SYSTEM.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user