geo/api/docs/UPLOAD-REORGANIZATION.md

Réorganisation de l'arborescence des uploads

📅 Date : 20/08/2025

🎯 Objectif

Uniformiser et simplifier l'arborescence des fichiers uploads pour une meilleure organisation et maintenance.

📂 Arborescence actuelle (PROBLÈME)

uploads/
├── entites/
│   └── 5/
│       ├── logo/
│       ├── operations/
│       │   └── 1525/
│       │       └── documents/
│       │           └── exports/
│       │               └── excel/
│       │                   └── geosector-export-*.xlsx
│       └── recus/
│           └── 3124/
│               └── recu_*.pdf
└── 5/
    └── operations/
        ├── 1525/
        └── 2021/

Problèmes identifiés :

• Duplication des structures (dossier 5 à la racine ET dans entites/)
• Chemins trop profonds pour les exports Excel (6 niveaux)
• Incohérence dans les chemins

✅ Nouvelle arborescence (SOLUTION)

uploads/
└── {entite_id}/              # Un seul dossier par entité à la racine
    ├── logo/                  # Logo de l'entité
    │   └── logo_*.{jpg,png}
    ├── operations/            # Exports par opération
    │   └── {operation_id}/
    │       └── *.xlsx         # Exports Excel directement ici
    └── recus/                 # Reçus par opération
        └── {operation_id}/
            └── recu_*.pdf

📝 Fichiers à modifier

1. EntiteController.php (Upload logo)

Actuel : /entites/{$entiteId}/logo Nouveau : /{$entiteId}/logo

2. ReceiptService.php (Stockage reçus PDF)

Actuel : /entites/{$entiteId}/recus/{$operationId} Nouveau : /{$entiteId}/recus/{$operationId}

3. ExportService.php (Export Excel)

Actuel : /{$entiteId}/operations/{$operationId}/exports/excel Nouveau : /{$entiteId}/operations/{$operationId}

4. ExportService.php (Export JSON)

Actuel : /{$entiteId}/operations/{$operationId}/exports/json Nouveau : /{$entiteId}/operations/{$operationId} (ou supprimer si non utilisé)

🔄 Plan de migration

Étape 1 : Modifier le code

1. Mettre à jour tous les chemins dans les contrôleurs et services
2. Tester en environnement DEV

Étape 2 : Script de migration des fichiers existants

Créer un script PHP pour :

1. Lister tous les fichiers existants
2. Les déplacer vers la nouvelle structure
3. Supprimer les anciens dossiers vides

Étape 3 : Déploiement

1. Exécuter le script de migration sur REC
2. Vérifier le bon fonctionnement
3. Exécuter sur PROD

🚀 Avantages de la nouvelle structure

• Plus simple : Chemins plus courts et plus logiques
• Plus cohérent : Une seule structure pour toutes les entités
• Plus maintenable : Facile de naviguer et comprendre
• Performance : Moins de niveaux de dossiers à parcourir

⚠️ Points d'attention

• Vérifier les permissions (nginx:nobody 775/664)
• S'assurer que les anciens fichiers sont bien migrés
• Mettre à jour la documentation
• Informer l'équipe du changement