Livraison d ela gestion des opérations v0.4.0
This commit is contained in:
d6soft
339
api/docs/README-UPLOAD.md
Normal file
339
api/docs/README-UPLOAD.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# Système de Gestion des Fichiers - API Geosector
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Ce document décrit l'organisation et la gestion des fichiers uploadés dans l'API Geosector. Le système permet de stocker et organiser différents types de fichiers par entité, utilisateur, opération et passage.
|
||||
|
||||
## Structure des Dossiers
|
||||
|
||||
```
|
||||
uploads/
|
||||
├── entites/
|
||||
│ ├── {entite_id}/
|
||||
│ │ ├── documents/ # PDF, Excel généraux de l'entité
|
||||
│ │ ├── images/ # Images de l'entité
|
||||
│ │ ├── users/ # Dossier pour les fichiers des utilisateurs
|
||||
│ │ │ └── {user_id}/ # Images par utilisateur (avatars, etc.)
|
||||
│ │ └── operations/ # Dossier pour les opérations
|
||||
│ │ └── {operation_id}/
|
||||
│ │ ├── documents/ # Fichiers Excel de l'opération
|
||||
│ │ └── passages/ # Fichiers des passages de cette opération
|
||||
│ │ └── {passage_id}/ # PDF et images par passage
|
||||
│ └── temp/ # Fichiers temporaires avant validation
|
||||
```
|
||||
|
||||
### Exemples de chemins
|
||||
|
||||
- Document d'entité : `uploads/entites/5/documents/reglement_2024.pdf`
|
||||
- Avatar utilisateur : `uploads/entites/5/users/123/avatar.jpg`
|
||||
- Excel d'opération : `uploads/entites/5/operations/2644/documents/planning.xlsx`
|
||||
- Photo de passage : `uploads/entites/5/operations/2644/passages/789/photo_1.jpg`
|
||||
|
||||
## Structure de la Table `medias`
|
||||
|
||||
### Table existante enrichie
|
||||
|
||||
```sql
|
||||
-- Structure complète de la table medias
|
||||
CREATE TABLE `medias` (
|
||||
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
|
||||
`support` varchar(45) NOT NULL DEFAULT '' COMMENT 'Type de support (entite, user, operation, passage)',
|
||||
`support_id` int(10) unsigned NOT NULL DEFAULT 0 COMMENT 'ID de l\'élément associé',
|
||||
`fichier` varchar(250) NOT NULL DEFAULT '' COMMENT 'Nom du fichier stocké',
|
||||
`file_type` varchar(50) DEFAULT NULL COMMENT 'Extension du fichier (pdf, jpg, xlsx, etc.)',
|
||||
`file_size` int(10) unsigned DEFAULT NULL COMMENT 'Taille du fichier en octets',
|
||||
`mime_type` varchar(100) DEFAULT NULL COMMENT 'Type MIME du fichier',
|
||||
`original_name` varchar(255) DEFAULT NULL COMMENT 'Nom original du fichier uploadé',
|
||||
`fk_entite` int(10) unsigned DEFAULT NULL COMMENT 'ID de l\'entité propriétaire',
|
||||
`fk_operation` int(10) unsigned DEFAULT NULL COMMENT 'ID de l\'opération (pour passages)',
|
||||
`file_path` varchar(500) DEFAULT NULL COMMENT 'Chemin complet du fichier',
|
||||
`original_width` int(10) unsigned DEFAULT NULL COMMENT 'Largeur originale de l\'image',
|
||||
`original_height` int(10) unsigned DEFAULT NULL COMMENT 'Hauteur originale de l\'image',
|
||||
`processed_width` int(10) unsigned DEFAULT NULL COMMENT 'Largeur après traitement',
|
||||
`processed_height` int(10) unsigned DEFAULT NULL COMMENT 'Hauteur après traitement',
|
||||
`is_processed` tinyint(1) unsigned DEFAULT 0 COMMENT 'Image redimensionnée (1) ou originale (0)',
|
||||
`description` varchar(100) NOT NULL DEFAULT '' COMMENT 'Description du fichier',
|
||||
`created_at` timestamp NOT NULL DEFAULT current_timestamp(),
|
||||
`fk_user_creat` int(10) unsigned NOT NULL DEFAULT 0,
|
||||
`updated_at` timestamp NULL DEFAULT NULL ON UPDATE current_timestamp(),
|
||||
`fk_user_modif` int(10) unsigned NOT NULL DEFAULT 0,
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `id_UNIQUE` (`id`),
|
||||
KEY `idx_entite` (`fk_entite`),
|
||||
KEY `idx_operation` (`fk_operation`),
|
||||
KEY `idx_support_type` (`support`, `support_id`),
|
||||
KEY `idx_file_type` (`file_type`),
|
||||
CONSTRAINT `fk_medias_entite` FOREIGN KEY (`fk_entite`) REFERENCES `entites` (`id`) ON UPDATE CASCADE ON DELETE CASCADE,
|
||||
CONSTRAINT `fk_medias_operation` FOREIGN KEY (`fk_operation`) REFERENCES `operations` (`id`) ON UPDATE CASCADE ON DELETE CASCADE
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
|
||||
```
|
||||
|
||||
### Migration SQL pour table existante
|
||||
|
||||
```sql
|
||||
-- Ajout des nouvelles colonnes à la table existante
|
||||
ALTER TABLE `medias`
|
||||
ADD COLUMN `file_type` varchar(50) DEFAULT NULL COMMENT 'Extension du fichier (pdf, jpg, xlsx, etc.)' AFTER `fichier`,
|
||||
ADD COLUMN `file_size` int(10) unsigned DEFAULT NULL COMMENT 'Taille du fichier en octets' AFTER `file_type`,
|
||||
ADD COLUMN `mime_type` varchar(100) DEFAULT NULL COMMENT 'Type MIME du fichier' AFTER `file_size`,
|
||||
ADD COLUMN `original_name` varchar(255) DEFAULT NULL COMMENT 'Nom original du fichier uploadé' AFTER `mime_type`,
|
||||
ADD COLUMN `fk_entite` int(10) unsigned DEFAULT NULL COMMENT 'ID de l\'entité propriétaire' AFTER `support_id`,
|
||||
ADD COLUMN `fk_operation` int(10) unsigned DEFAULT NULL COMMENT 'ID de l\'opération (pour passages)' AFTER `fk_entite`,
|
||||
ADD COLUMN `file_path` varchar(500) DEFAULT NULL COMMENT 'Chemin complet du fichier' AFTER `original_name`,
|
||||
ADD COLUMN `original_width` int(10) unsigned DEFAULT NULL COMMENT 'Largeur originale de l\'image' AFTER `file_path`,
|
||||
ADD COLUMN `original_height` int(10) unsigned DEFAULT NULL COMMENT 'Hauteur originale de l\'image' AFTER `original_width`,
|
||||
ADD COLUMN `processed_width` int(10) unsigned DEFAULT NULL COMMENT 'Largeur après traitement' AFTER `original_height`,
|
||||
ADD COLUMN `processed_height` int(10) unsigned DEFAULT NULL COMMENT 'Hauteur après traitement' AFTER `processed_width`,
|
||||
ADD COLUMN `is_processed` tinyint(1) unsigned DEFAULT 0 COMMENT 'Image redimensionnée (1) ou originale (0)' AFTER `processed_height`;
|
||||
|
||||
-- Ajout des index pour optimiser les requêtes
|
||||
ALTER TABLE `medias`
|
||||
ADD INDEX `idx_entite` (`fk_entite`),
|
||||
ADD INDEX `idx_operation` (`fk_operation`),
|
||||
ADD INDEX `idx_support_type` (`support`, `support_id`),
|
||||
ADD INDEX `idx_file_type` (`file_type`);
|
||||
|
||||
-- Ajout des contraintes de clés étrangères
|
||||
ALTER TABLE `medias`
|
||||
ADD CONSTRAINT `fk_medias_entite` FOREIGN KEY (`fk_entite`) REFERENCES `entites` (`id`) ON UPDATE CASCADE ON DELETE CASCADE,
|
||||
ADD CONSTRAINT `fk_medias_operation` FOREIGN KEY (`fk_operation`) REFERENCES `operations` (`id`) ON UPDATE CASCADE ON DELETE CASCADE;
|
||||
```
|
||||
|
||||
## Types de Support
|
||||
|
||||
### 1. Entité (`support = 'entite'`)
|
||||
|
||||
- **Fichiers autorisés** : PDF, Excel, Images (JPG, PNG)
|
||||
- **Taille max** : 20 MB
|
||||
- **Usage** : Documents généraux de l'entité (règlements, statuts, etc.)
|
||||
- **Chemin** : `uploads/entites/{entite_id}/documents/`
|
||||
|
||||
### 2. Utilisateur (`support = 'user'`)
|
||||
|
||||
- **Fichiers autorisés** : Images uniquement (JPG, PNG, GIF, WebP)
|
||||
- **Taille max** : 5 MB
|
||||
- **Usage** : Avatars, photos de profil
|
||||
- **Chemin** : `uploads/entites/{entite_id}/users/{user_id}/`
|
||||
- **Traitement** : Redimensionnement automatique
|
||||
|
||||
### 3. Opération (`support = 'operation'`)
|
||||
|
||||
- **Fichiers autorisés** : Excel uniquement (XLS, XLSX)
|
||||
- **Taille max** : 20 MB
|
||||
- **Usage** : Plannings, listes, données d'opération
|
||||
- **Chemin** : `uploads/entites/{entite_id}/operations/{operation_id}/documents/`
|
||||
|
||||
### 4. Passage (`support = 'passage'`)
|
||||
|
||||
- **Fichiers autorisés** : PDF et Images (JPG, PNG, PDF)
|
||||
- **Taille max** : 10 MB par fichier
|
||||
- **Usage** : Reçus, photos de passage, justificatifs
|
||||
- **Chemin** : `uploads/entites/{entite_id}/operations/{operation_id}/passages/{passage_id}/`
|
||||
- **Traitement** : Redimensionnement automatique pour les images
|
||||
|
||||
## Traitement Automatique des Images
|
||||
|
||||
### Règles de redimensionnement
|
||||
|
||||
- **Dimension maximale** : 250px (hauteur ou largeur, selon la plus grande)
|
||||
- **Résolution** : 72 DPI (optimisé web)
|
||||
- **Préservation du ratio** : Redimensionnement proportionnel
|
||||
- **Formats supportés** : JPG, PNG, GIF, WebP
|
||||
- **Qualité JPEG** : 85% (bon compromis qualité/poids)
|
||||
|
||||
### Exemples de transformation
|
||||
|
||||
```
|
||||
Image originale 1000x800px → Image traitée 250x200px
|
||||
Image originale 600x1200px → Image traitée 125x250px
|
||||
Image originale 200x150px → Pas de redimensionnement (déjà < 250px)
|
||||
```
|
||||
|
||||
### Workflow de traitement
|
||||
|
||||
1. **Upload** → Validation du type MIME
|
||||
2. **Analyse** → Détection des dimensions originales
|
||||
3. **Traitement** → Redimensionnement si nécessaire
|
||||
4. **Optimisation** → Compression et résolution web
|
||||
5. **Sauvegarde** → Image optimisée + métadonnées
|
||||
6. **Nettoyage** → Suppression du fichier temporaire
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Routes de gestion des fichiers
|
||||
|
||||
```php
|
||||
// Upload de fichiers
|
||||
POST /api/medias/upload
|
||||
Content-Type: multipart/form-data
|
||||
Body: {
|
||||
"file": [fichier],
|
||||
"support": "entite|user|operation|passage",
|
||||
"support_id": 123,
|
||||
"description": "Description du fichier"
|
||||
}
|
||||
|
||||
// Récupération d'un fichier
|
||||
GET /api/medias/{id}
|
||||
|
||||
// Liste des fichiers par support
|
||||
GET /api/medias/list/{support}/{support_id}
|
||||
|
||||
// Suppression d'un fichier
|
||||
DELETE /api/medias/{id}
|
||||
```
|
||||
|
||||
### Exemples de requêtes
|
||||
|
||||
#### Upload d'un avatar utilisateur
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.geosector.fr/medias/upload" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-F "file=@avatar.jpg" \
|
||||
-F "support=user" \
|
||||
-F "support_id=123" \
|
||||
-F "description=Avatar utilisateur"
|
||||
```
|
||||
|
||||
#### Upload d'une photo de passage
|
||||
|
||||
```bash
|
||||
curl -X POST "https://api.geosector.fr/medias/upload" \
|
||||
-H "Authorization: Bearer {token}" \
|
||||
-F "file=@photo_passage.jpg" \
|
||||
-F "support=passage" \
|
||||
-F "support_id=789" \
|
||||
-F "description=Photo du passage"
|
||||
```
|
||||
|
||||
## Sécurité et Contrôles
|
||||
|
||||
### Validation des fichiers
|
||||
|
||||
- **Types MIME** : Vérification stricte du type de fichier
|
||||
- **Extensions** : Validation de l'extension par rapport au contenu
|
||||
- **Taille** : Limite selon le type de support
|
||||
- **Contenu** : Scan antivirus recommandé en production
|
||||
|
||||
### Contrôles d'accès
|
||||
|
||||
- **Authentification** : Token JWT requis
|
||||
- **Autorisation** : Utilisateur ne peut accéder qu'aux fichiers de son entité
|
||||
- **Vérification** : Contrôle que l'utilisateur appartient à l'entité du fichier
|
||||
- **Logs** : Traçabilité complète des uploads et accès
|
||||
|
||||
### Nommage des fichiers
|
||||
|
||||
```php
|
||||
// Format : {timestamp}_{random}_{sanitized_name}.{extension}
|
||||
// Exemple : 1640995200_a1b2c3_document_reglement.pdf
|
||||
```
|
||||
|
||||
## Gestion des Erreurs
|
||||
|
||||
### Codes d'erreur HTTP
|
||||
|
||||
- **400** : Fichier invalide ou paramètres manquants
|
||||
- **401** : Non authentifié
|
||||
- **403** : Accès refusé à cette entité
|
||||
- **413** : Fichier trop volumineux
|
||||
- **415** : Type de fichier non supporté
|
||||
- **500** : Erreur serveur lors du traitement
|
||||
|
||||
### Messages d'erreur
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"message": "Type de fichier non autorisé pour ce support",
|
||||
"code": "INVALID_FILE_TYPE",
|
||||
"allowed_types": ["jpg", "png", "gif", "webp"]
|
||||
}
|
||||
```
|
||||
|
||||
## Maintenance et Nettoyage
|
||||
|
||||
### Nettoyage automatique
|
||||
|
||||
- **Fichiers temporaires** : Suppression après 24h
|
||||
- **Fichiers orphelins** : Détection et suppression des fichiers sans référence en base
|
||||
- **Anciennes opérations** : Suppression en cascade lors de la suppression d'une opération
|
||||
|
||||
### Commandes de maintenance
|
||||
|
||||
```bash
|
||||
# Nettoyage des fichiers temporaires
|
||||
php scripts/cleanup_temp_files.php
|
||||
|
||||
# Détection des fichiers orphelins
|
||||
php scripts/find_orphan_files.php
|
||||
|
||||
# Statistiques d'utilisation
|
||||
php scripts/storage_stats.php
|
||||
```
|
||||
|
||||
## Performances et Optimisation
|
||||
|
||||
### Optimisations
|
||||
|
||||
- **CDN** : Recommandé pour la distribution des fichiers
|
||||
- **Cache** : Headers de cache appropriés pour les fichiers statiques
|
||||
- **Compression** : Gzip pour les réponses API
|
||||
- **Index** : Index optimisés sur la table medias
|
||||
|
||||
### Monitoring
|
||||
|
||||
- **Espace disque** : Surveillance de l'utilisation
|
||||
- **Performance** : Temps de traitement des images
|
||||
- **Erreurs** : Logs des échecs d'upload et de traitement
|
||||
|
||||
## Exemples d'Utilisation
|
||||
|
||||
### Cas d'usage typiques
|
||||
|
||||
1. **Upload d'avatar utilisateur**
|
||||
|
||||
- Fichier JPG de 2MB
|
||||
- Redimensionnement automatique à 250x250px
|
||||
- Stockage dans `uploads/entites/5/users/123/`
|
||||
|
||||
2. **Document d'opération**
|
||||
|
||||
- Fichier Excel de planning
|
||||
- Stockage dans `uploads/entites/5/operations/2644/documents/`
|
||||
- Pas de traitement (fichier conservé tel quel)
|
||||
|
||||
3. **Photo de passage**
|
||||
- Photo JPG de 8MB prise sur mobile
|
||||
- Redimensionnement automatique à 250px max
|
||||
- Stockage dans `uploads/entites/5/operations/2644/passages/789/`
|
||||
|
||||
### Intégration frontend
|
||||
|
||||
```javascript
|
||||
// Upload avec progress
|
||||
const uploadFile = async (file, support, supportId, description) => {
|
||||
const formData = new FormData();
|
||||
formData.append('file', file);
|
||||
formData.append('support', support);
|
||||
formData.append('support_id', supportId);
|
||||
formData.append('description', description);
|
||||
|
||||
const response = await fetch('/api/medias/upload', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
},
|
||||
body: formData,
|
||||
});
|
||||
|
||||
return response.json();
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Version** : 1.0
|
||||
**Date** : Juin 2025
|
||||
**Auteur** : API Geosector Team
|
||||
Reference in New Issue
Block a user