377 lines
8.3 KiB
Markdown
377 lines
8.3 KiB
Markdown
# API de Gestion des Fichiers - Geosector
|
|
|
|
## Vue d'ensemble
|
|
|
|
L'API de gestion des fichiers permet aux administrateurs de naviguer, rechercher et gérer les fichiers stockés dans l'application Geosector avec des contrôles d'accès basés sur les rôles.
|
|
|
|
## Contrôles d'accès
|
|
|
|
### Rôle 2 (Admin d'entité)
|
|
|
|
- Accès limité aux fichiers de son entité uniquement
|
|
- Chemin racine : `/uploads/entites/{son_entite_id}/`
|
|
- Peut naviguer dans tous les sous-dossiers de son entité
|
|
|
|
### Rôle > 2 (Super admin)
|
|
|
|
- Accès complet à tous les fichiers
|
|
- Chemin racine : `/uploads/` (accès total)
|
|
- Peut naviguer dans toutes les entités et dossiers système
|
|
|
|
## Routes disponibles
|
|
|
|
### Navigation et listing
|
|
|
|
#### `GET /api/files/browse`
|
|
|
|
Navigation dans l'arborescence avec recherche et pagination.
|
|
|
|
**Paramètres de requête :**
|
|
|
|
- `path` (string) : Chemin à explorer (ex: `entites/5/operations`)
|
|
- `page` (int) : Page (défaut: 1)
|
|
- `per_page` (int) : Éléments par page (défaut: 50, max: 100)
|
|
- `search` (string) : Recherche dans nom, nom original, description
|
|
- `type` (string) : Filtrage par extension (pdf, jpg, xlsx, etc.)
|
|
- `category` (string) : Filtrage par catégorie métier
|
|
- `sort` (string) : Tri (name, date, size, type) - défaut: date
|
|
- `order` (string) : Ordre (asc, desc) - défaut: desc
|
|
|
|
**Exemple :**
|
|
|
|
```bash
|
|
GET /api/files/browse?path=entites/5/operations&search=2024&type=xlsx&page=1
|
|
```
|
|
|
|
**Réponse :**
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"current_path": "entites/5/operations",
|
|
"parent_path": "entites/5",
|
|
"pagination": {
|
|
"current_page": 1,
|
|
"per_page": 50,
|
|
"total_items": 127,
|
|
"total_pages": 3,
|
|
"has_next": true,
|
|
"has_prev": false
|
|
},
|
|
"filters": {
|
|
"search": "2024",
|
|
"type": "xlsx",
|
|
"category": null,
|
|
"sort": "date",
|
|
"order": "desc"
|
|
},
|
|
"files": [
|
|
{
|
|
"id": 123,
|
|
"fichier": "planning_2024_op2644.xlsx",
|
|
"original_name": "Planning Opération 2024.xlsx",
|
|
"file_type": "xlsx",
|
|
"file_category": "planning",
|
|
"description": "Planning détaillé opération 2024",
|
|
"file_size": 1024000,
|
|
"file_path": "entites/5/operations/2644/documents/planning_2024_op2644.xlsx",
|
|
"created_at": "2025-06-22 08:30:00",
|
|
"creator_name": "Jean Dupont"
|
|
}
|
|
],
|
|
"summary": {
|
|
"total_files": 45,
|
|
"total_size": 25600000,
|
|
"by_category": {
|
|
"planning": 12,
|
|
"export": 20,
|
|
"backup": 13
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `GET /api/files/list/{support}/{id}`
|
|
|
|
Liste des fichiers par support (entite, user, operation, passage).
|
|
|
|
**Paramètres :**
|
|
|
|
- `support` : Type de support (entite, user, operation, passage)
|
|
- `id` : ID de l'élément
|
|
- Mêmes paramètres de requête que `/browse`
|
|
|
|
**Exemple :**
|
|
|
|
```bash
|
|
GET /api/files/list/operation/2644?category=export&page=1
|
|
```
|
|
|
|
### Recherche
|
|
|
|
#### `GET /api/files/search`
|
|
|
|
Recherche globale dans tous les fichiers accessibles.
|
|
|
|
**Paramètres de requête :**
|
|
|
|
- `q` (string, requis) : Terme de recherche
|
|
- `page`, `per_page`, `type`, `category`, `sort`, `order` : Mêmes que browse
|
|
|
|
**Exemple :**
|
|
|
|
```bash
|
|
GET /api/files/search?q=planning&type=xlsx&category=planning
|
|
```
|
|
|
|
### Actions sur fichiers
|
|
|
|
#### `GET /api/files/download/{id}`
|
|
|
|
Téléchargement sécurisé d'un fichier.
|
|
|
|
**Réponse :** Fichier en téléchargement direct avec headers appropriés.
|
|
|
|
#### `DELETE /api/files/{id}`
|
|
|
|
Suppression sécurisée d'un fichier (physique + base de données).
|
|
|
|
**Réponse :**
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "Fichier supprimé avec succès"
|
|
}
|
|
```
|
|
|
|
#### `GET /api/files/info/{id}`
|
|
|
|
Informations détaillées d'un fichier.
|
|
|
|
**Réponse :**
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"file": {
|
|
"id": 123,
|
|
"fichier": "planning_2024.xlsx",
|
|
"original_name": "Planning Opération 2024.xlsx",
|
|
"file_type": "xlsx",
|
|
"file_category": "planning",
|
|
"file_size": 1024000,
|
|
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
|
"description": "Planning détaillé",
|
|
"support": "operation",
|
|
"support_id": 2644,
|
|
"fk_entite": 5,
|
|
"created_at": "2025-06-22 08:30:00",
|
|
"updated_at": "2025-06-22 08:30:00",
|
|
"creator_name": "Jean Dupont",
|
|
"modifier_name": null,
|
|
"file_exists": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### Statistiques
|
|
|
|
#### `GET /api/files/stats`
|
|
|
|
Statistiques d'utilisation des fichiers.
|
|
|
|
**Pour admin d'entité (rôle 2) :**
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"entite_id": 5,
|
|
"storage": {
|
|
"total_files": 245,
|
|
"total_size": 157286400,
|
|
"by_support": {
|
|
"entite": { "count": 12, "size": 45000000 },
|
|
"operation": { "count": 180, "size": 98000000 },
|
|
"user": { "count": 45, "size": 12000000 },
|
|
"passage": { "count": 8, "size": 2286400 }
|
|
},
|
|
"by_category": {
|
|
"document": 25,
|
|
"export": 120,
|
|
"avatar": 45,
|
|
"photo": 55
|
|
},
|
|
"by_type": {
|
|
"xlsx": 85,
|
|
"jpg": 120,
|
|
"pdf": 40
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Pour super admin (rôle > 2) :**
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"global_stats": {
|
|
"total_files": 2450,
|
|
"total_size": 1572864000,
|
|
"entites_count": 25,
|
|
"by_entite": [
|
|
{ "entite_id": 5, "files": 245, "size": 157286400 },
|
|
{ "entite_id": 12, "files": 180, "size": 98000000 }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Métadonnées
|
|
|
|
#### `GET /api/files/metadata`
|
|
|
|
Informations sur les catégories, extensions et limites autorisées.
|
|
|
|
**Réponse :**
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"categories": {
|
|
"entite": ["logo", "document", "reglement", "statut"],
|
|
"user": ["avatar", "photo"],
|
|
"operation": ["planning", "liste", "export", "backup"],
|
|
"passage": ["recu", "photo", "justificatif", "carte"]
|
|
},
|
|
"extensions": ["pdf", "jpg", "jpeg", "png", "gif", "webp", "xlsx", "xls", "json", "csv"],
|
|
"mime_types": {
|
|
"pdf": "application/pdf",
|
|
"jpg": "image/jpeg",
|
|
"xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
|
|
},
|
|
"max_file_sizes": {
|
|
"entite": 20971520, // 20 MB
|
|
"user": 5242880, // 5 MB
|
|
"operation": 20971520, // 20 MB
|
|
"passage": 10485760 // 10 MB
|
|
}
|
|
}
|
|
```
|
|
|
|
## Catégories de fichiers
|
|
|
|
### Distinction Extension vs Catégorie
|
|
|
|
- **Extension** (`file_type`) : Type technique (pdf, jpg, xlsx, png, etc.)
|
|
- **Catégorie** (`file_category`) : Type métier (logo, carte, photo, document, planning, etc.)
|
|
|
|
### Catégories par support
|
|
|
|
#### Entité
|
|
|
|
- `logo` : Logo de l'entité
|
|
- `document` : Documents généraux
|
|
- `reglement` : Règlements internes
|
|
- `statut` : Statuts de l'entité
|
|
|
|
#### Utilisateur
|
|
|
|
- `avatar` : Photo de profil
|
|
- `photo` : Photos diverses
|
|
|
|
#### Opération
|
|
|
|
- `planning` : Plannings d'opération
|
|
- `liste` : Listes diverses
|
|
- `export` : Exports de données
|
|
- `backup` : Sauvegardes automatiques
|
|
|
|
#### Passage
|
|
|
|
- `recu` : Reçus de passage
|
|
- `photo` : Photos de passage
|
|
- `justificatif` : Justificatifs divers
|
|
- `carte` : Cartes et plans
|
|
|
|
## Sécurité
|
|
|
|
### Validation des chemins
|
|
|
|
- Empêche les traversées de répertoire (`../`)
|
|
- Validation stricte selon le rôle utilisateur
|
|
- Contrôle d'accès au niveau fichier
|
|
|
|
### Logs
|
|
|
|
- Tous les téléchargements sont loggés
|
|
- Toutes les suppressions sont tracées
|
|
- Erreurs d'accès enregistrées
|
|
|
|
### Contrôles d'intégrité
|
|
|
|
- Vérification de l'existence physique des fichiers
|
|
- Validation des permissions avant chaque action
|
|
- Contrôle de cohérence base/fichiers
|
|
|
|
## Exemples d'utilisation
|
|
|
|
### Navigation dans les opérations d'une entité
|
|
|
|
```bash
|
|
GET /api/files/browse?path=entites/5/operations&sort=name&order=asc
|
|
```
|
|
|
|
### Recherche de tous les exports Excel
|
|
|
|
```bash
|
|
GET /api/files/search?q=export&type=xlsx&category=export
|
|
```
|
|
|
|
### Statistiques de stockage
|
|
|
|
```bash
|
|
GET /api/files/stats
|
|
```
|
|
|
|
### Téléchargement d'un fichier
|
|
|
|
```bash
|
|
GET /api/files/download/123
|
|
```
|
|
|
|
### Suppression d'un fichier
|
|
|
|
```bash
|
|
DELETE /api/files/123
|
|
```
|
|
|
|
## Codes d'erreur
|
|
|
|
- **401** : Non authentifié
|
|
- **403** : Accès refusé (rôle insuffisant ou fichier d'une autre entité)
|
|
- **404** : Fichier ou chemin non trouvé
|
|
- **400** : Paramètres invalides (terme de recherche manquant, etc.)
|
|
- **500** : Erreur serveur
|
|
|
|
## Migration base de données
|
|
|
|
Pour utiliser le système, exécuter la migration :
|
|
|
|
```sql
|
|
-- Ajout de la colonne file_category
|
|
ALTER TABLE `medias`
|
|
ADD COLUMN `file_category` varchar(50) DEFAULT NULL COMMENT 'Catégorie du fichier (logo, carte, photo, document, etc.)' AFTER `file_type`;
|
|
|
|
-- Index pour optimiser les requêtes
|
|
ALTER TABLE `medias`
|
|
ADD INDEX `idx_file_category` (`file_category`);
|
|
```
|
|
|
|
---
|
|
|
|
**Version** : 1.0
|
|
**Date** : Juin 2025
|
|
**Auteur** : API Geosector Team
|