# 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