geo/api/docs/UPLOAD-MIGRATION-RECAP.md

📋 RÉCAPITULATIF - Migration Arborescence Uploads

✅ Modifications effectuées

1. EntiteController.php (ligne 736)

// Avant : "/entites/{$entiteId}/logo"
// Après : "/{$entiteId}/logo"

✅ Les logos sont maintenant stockés dans : uploads/{entite_id}/logo/

2. ReceiptService.php (ligne 95)

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

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

# 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

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

# 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