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