geo/api/docs/FILE-SYSTEM-API.md

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 :

GET /api/files/browse?path=entites/5/operations&search=2024&type=xlsx&page=1

Réponse :

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

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 :

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 :

{
  "status": "success",
  "message": "Fichier supprimé avec succès"
}

GET /api/files/info/{id}

Informations détaillées d'un fichier.

Réponse :

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

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

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

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

GET /api/files/browse?path=entites/5/operations&sort=name&order=asc

Recherche de tous les exports Excel

GET /api/files/search?q=export&type=xlsx&category=export

Statistiques de stockage

GET /api/files/stats

Téléchargement d'un fichier

GET /api/files/download/123

Suppression d'un fichier

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 :

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