xamxam/docs/export.md

Export et sauvegarde des données XAMXAM

Ce document explique le fonctionnement du système d'export pour les administrateur·ices de la plateforme. Il couvre les trois types d'export disponibles depuis le panneau d'administration, la manière de les combiner pour une restauration complète, et les détails techniques utiles en cas de problème.

---

Les trois exports disponibles

Depuis la page principale d'administration (/admin/), la barre d'outils propose trois boutons d'export :

Bouton	Fichier produit	Contenu
Exporter CSV	xamxam-export-AAAA-MM-JJ.csv	Liste complète des TFE au format compatible avec l'import CSV
Exporter DB	xamxam-db-AAAA-MM-JJ.sqlite	Copie brute du fichier de base de données SQLite
Exporter fichiers	xamxam-files-AAAA-MM-JJ.zip	Archive ZIP contenant tous les fichiers attachés aux TFE + un manifeste JSON

---

Exporter les fichiers (ZIP)

Ce que contient l'archive

xamxam-files-2026-05-07.zip
├── manifest.json        ← métadonnées de chaque TFE et ses fichiers
└── files/
    └── theses/
        ├── 2025/
        │   ├── 2025_EMMA_RENARD/
        │   │   └── EMMA_RENARD_carte_loire_a_velo_france.pdf
        │   ├── 2025_LILA_DUBOIS_KARIM_NASSAR/
        │   │   ├── nixing_the_fix_report_final.pdf
        │   │   ├── bbb_sunflower_1080p_30fps_normal_mp4.zip
        │   │   ├── carte_loire_a_velo_france.pdf
        │   │   └── LINK.txt                  ← si vidéos PeerTube présentes
        │   └── …
        └── 2026/
            └── …

Le fichier manifest.json

{
  "exported_at": "2026-05-07T15:30:00+02:00",
  "db_file": "xamxam.db",
  "total_theses": 140,
  "total_files": 312,
  "zip_added_count": 310,
  "zip_skipped_count": 2,
  "theses": {
    "2025-003": {
      "id": 42,
      "identifier": "2025-003",
      "title": "Titre du TFE",
      "year": 2025,
      "files": [
        {
          "type": "main",
          "path": "theses/2025/2025_AUTEUR/mon_fichier.pdf",
          "name": "mon_fichier.pdf",
          "size": 1234567,
          "mime": "application/pdf",
          "hash": null,
          "label": "Mémoire principal",
          "sort_order": 1
        }
      ],
      "peertube_links": [
        {
          "uuid": "abc123def",
          "url": "https://videos.erg.be/videos/watch/abc123def",
          "type": "video",
          "label": "Vidéo de présentation",
          "name": "presentation.mp4"
        }
      ]
    }
  }
}

Le manifeste fait le pont entre la base de données et les fichiers. Chaque TFE est indexé par son identifiant (ex. 2025-003), ce qui permet de retrouver ses fichiers même si l'ordre des IDs change après une restauration.

---

Restaurer une sauvegarde complète

Une sauvegarde complète se compose de trois fichiers à exporter le même jour (DB + fichiers ZIP + CSV). Voici la procédure de restauration sur un serveur neuf ou après un incident.

1. Restaurer la base de données

# Arrêter le serveur web
sudo systemctl stop nginx

# Remplacer le fichier SQLite
cp xamxam-db-AAAA-MM-JJ.sqlite /var/www/xamxam/storage/xamxam.db
chown www-data:www-data /var/www/xamxam/storage/xamxam.db
chmod 640 /var/www/xamxam/storage/xamxam.db

2. Restaurer les fichiers

# Décompresser l'archive dans le répertoire storage/
# ATTENTION : le zip contient un dossier files/ à la racine.
# On le décompresse dans /tmp puis on copie le contenu de files/theses/
# dans storage/theses/ pour préserver la structure existante.

unzip xamxam-files-AAAA-MM-JJ.zip -d /tmp/xamxam-restore
cp -r /tmp/xamxam-restore/files/theses/* /var/www/xamxam/storage/theses/
chown -R www-data:www-data /var/www/xamxam/storage/theses/
rm -rf /tmp/xamxam-restore

Pourquoi ça fonctionne : les chemins dans la table thesis_files sont relatifs (ex. theses/2025/2025_AUTEUR/fichier.pdf). En restaurant les fichiers au même emplacement sous storage/, les liens DB ↔ fichiers sont automatiquement rétablis.

3. Redémarrer

sudo systemctl start nginx

4. Vérifier

Naviguer vers /admin/ et vérifier que la liste des TFE s'affiche correctement et que les fichiers sont téléchargeables.

---

Restauration partielle ou re-linkage

Si la base de données a été perdue mais que vous avez le ZIP des fichiers et le CSV d'export, vous pouvez reconstruire les liens grâce au manifest.json :

1. Réimporter le CSV via l'interface d'administration (bouton Importer un CSV). Les identifiants (colonne Identifiant) doivent correspondre à ceux du manifeste.

2. Décompresser le ZIP dans storage/ comme décrit ci-dessus.

3. Vérifier avec le manifeste — les chemins dans manifest.json correspondent aux chemins dans thesis_files.file_path. Si les identifiants du CSV et ceux du manifeste coïncident, les fichiers seront correctement liés après l'import.

---

Détails techniques

Performance

L'export des fichiers utilise ZipArchive (extension PHP standard) et crée une archive temporaire dans /tmp. Pour un volume important de fichiers (plusieurs centaines), la création peut prendre quelques secondes. Un timeout d'exécution raisonnable (max_execution_time ≥ 60s) est recommandé.

Sécurité

• Les exports sont protégés par authentification administrateur (AdminAuth::requireLogin()).
• L'export DB et l'export fichiers sont journalisés dans le log d'audit (admin_audit_log) avec l'IP et l'User-Agent de l'administrateur.
• Les fichiers temporaires sont supprimés après envoi (unlink() dans le bloc finally implicite de export-files.php).
• Les fichiers dans le ZIP conservent leurs chemins relatifs d'origine — il n'y a pas de risque de path traversal car les chemins proviennent de la base de données et ne contiennent jamais ../.

Colonnes du CSV d'export

Le CSV utilise la même structure que l'import (21 colonnes). Il est directement ré-importable sans modification. Voir docs/import.md pour le détail des colonnes.

---

Résumé des commandes utiles

# Télécharger les trois exports (depuis le navigateur ou curl)
curl -u admin:password -O https://xamxam.erg.be/admin/actions/export-db.php
curl -u admin:password -O https://xamxam.erg.be/admin/actions/export-csv.php
curl -u admin:password -O https://xamxam.erg.be/admin/actions/export-files.php

# Restauration complète
sudo systemctl stop nginx
cp xamxam-db-*.sqlite /var/www/xamxam/storage/xamxam.db
unzip xamxam-files-*.zip -d /tmp/xamxam-restore
cp -r /tmp/xamxam-restore/files/theses/* /var/www/xamxam/storage/theses/
chown -R www-data:www-data /var/www/xamxam/storage/
sudo systemctl start nginx