# 📋 RÉCAPITULATIF - Migration Arborescence Uploads

## ✅ Modifications effectuées

### 1. **EntiteController.php** (ligne 736)
```php
// Avant : "/entites/{$entiteId}/logo"
// Après : "/{$entiteId}/logo"
```
✅ Les logos sont maintenant stockés dans : `uploads/{entite_id}/logo/`

### 2. **ReceiptService.php** (ligne 95)
```php
// Avant : "/entites/{$entiteId}/recus/{$operationId}"
// Après : "/{$entiteId}/recus/{$operationId}"
```
✅ Les reçus PDF sont maintenant stockés dans : `uploads/{entite_id}/recus/{operation_id}/`

### 3. **ExportService.php** (lignes 40 et 141)
```php
// Avant Excel : "/{$entiteId}/operations/{$operationId}/exports/excel"
// Après Excel : "/{$entiteId}/operations/{$operationId}"

// Avant JSON : "/{$entiteId}/operations/{$operationId}/exports/json"
// Après JSON : "/{$entiteId}/operations/{$operationId}"
```
✅ Les exports sont maintenant stockés directement dans : `uploads/{entite_id}/operations/{operation_id}/`

## 📂 Nouvelle structure complète

```
uploads/
└── {entite_id}/              # Ex: 5, 1230, etc.
    ├── logo/                  # Logo de l'entité
    │   └── logo_{entite_id}_{timestamp}.{jpg|png}
    ├── operations/            # Exports d'opérations
    │   └── {operation_id}/    # Ex: 1525, 3124
    │       ├── geosector-export-{operation_id}-{timestamp}.xlsx
    │       └── backup-{operation_id}-{timestamp}.json.enc
    └── recus/                 # Reçus fiscaux
        └── {operation_id}/    # Ex: 3124
            └── recu_{passage_id}.pdf
```

## 🔧 Script de migration

Un script a été créé pour migrer les fichiers existants :

**Fichier :** `/scripts/migrate_uploads_structure.php`

**Usage :**
```bash
# Mode simulation (voir ce qui sera fait sans modifier)
php scripts/migrate_uploads_structure.php --dry-run

# Mode réel (effectue la migration)
php scripts/migrate_uploads_structure.php
```

**Ce que fait le script :**
1. Déplace tout le contenu de `uploads/entites/*` vers `uploads/*`
2. Fusionne les dossiers si nécessaire
3. Simplifie la structure des exports (supprime `/documents/exports/excel/`)
4. Applique les bonnes permissions (nginx:nobody 775/664)
5. Crée un log détaillé dans `/logs/migration_uploads_YYYYMMDD_HHMMSS.log`

## 🚀 Procédure de déploiement

### Sur DEV (déjà fait)
✅ Code modifié
✅ Script de migration créé

### Sur REC
```bash
# 1. Déployer le nouveau code
./livre-api.sh rec

# 2. Faire un backup des uploads actuels
cd /var/www/geosector/api
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz uploads/

# 3. Tester en mode dry-run
php scripts/migrate_uploads_structure.php --dry-run

# 4. Si OK, lancer la migration
php scripts/migrate_uploads_structure.php

# 5. Vérifier la nouvelle structure
ls -la uploads/
ls -la uploads/*/
```

### Sur PROD
Même procédure que REC après validation

## ⚠️ Points d'attention

1. **Backup obligatoire** avant migration
2. **Vérifier l'espace disque** disponible
3. **Tester d'abord en dry-run**
4. **Surveiller les logs** après migration
5. **Tester** upload logo, génération reçu, et export Excel

## 📊 Gains obtenus

| Aspect | Avant | Après |
|--------|-------|-------|
| **Profondeur max** | 8 niveaux | 4 niveaux |
| **Complexité** | 2 structures parallèles | 1 structure unique |
| **Clarté** | Confus (entites + racine) | Simple et logique |
| **Navigation** | Difficile | Intuitive |

## 🔍 Vérification post-migration

Après la migration, vérifier :

```bash
# Structure attendue pour l'entité 5
tree uploads/5/
# Devrait afficher :
# uploads/5/
# ├── logo/
# │   └── logo_5_*.png
# ├── operations/
# │   ├── 1525/
# │   │   └── *.xlsx
# │   └── 3124/
# │       └── *.xlsx
# └── recus/
#     └── 3124/
#         └── recu_*.pdf

# Vérifier les permissions
ls -la uploads/*/
# Devrait montrer : nginx:nobody avec 775 pour dossiers, 664 pour fichiers
```

## ✅ Checklist finale

- [ ] Code modifié et testé en DEV
- [ ] Script de migration créé
- [ ] Documentation mise à jour
- [ ] Backup effectué sur REC
- [ ] Migration testée en dry-run sur REC
- [ ] Migration exécutée sur REC
- [ ] Tests fonctionnels sur REC
- [ ] Backup effectué sur PROD
- [ ] Migration exécutée sur PROD
- [ ] Tests fonctionnels sur PROD

---

**Date de création :** 20/08/2025
**Auteur :** Assistant Claude
**Status :** Prêt pour déploiement