towercontrol/BACKUP.md

# 🔒 Système de Sauvegarde TowerControl

## Vue d'ensemble

TowerControl dispose d'un système de sauvegarde automatique et manuel complet pour protéger vos données SQLite.

## Fonctionnalités

- ✅ **Sauvegardes automatiques** avec planification configurable
- ✅ **Sauvegardes manuelles** via UI et CLI
- ✅ **Compression gzip** optionnelle pour économiser l'espace
- ✅ **Rétention automatique** des anciennes sauvegardes
- ✅ **Vérification d'intégrité** de la base de données
- ✅ **Restauration** complète (développement uniquement)
- ✅ **Interface graphique** dans les paramètres avancés
- ✅ **CLI** pour l'administration système

## Configuration

### Paramètres par défaut

```typescript
{
  enabled: true,              // Sauvegardes automatiques activées
  interval: 'daily',          // Fréquence: 'hourly', 'daily', 'weekly'
  maxBackups: 7,              // Nombre maximum de sauvegardes conservées
  backupPath: './backups',    // Dossier de stockage
  compression: true,          // Compression gzip activée
}
```

### Modification via l'interface

1. Aller dans **Paramètres** → **Avancé**
2. Section **💾 Sauvegarde et données**
3. Cliquer sur **"Gérer les sauvegardes"**
4. Modifier la configuration selon vos besoins

### Modification via CLI

```bash
# Voir la configuration actuelle
pnpm run backup:config

# Modifier la fréquence
pnpm tsx scripts/backup-manager.ts config-set interval=daily

# Modifier le nombre max de sauvegardes
pnpm tsx scripts/backup-manager.ts config-set maxBackups=10

# Activer/désactiver la compression
pnpm tsx scripts/backup-manager.ts config-set compression=true
```

### Personnalisation du dossier de sauvegarde

```bash
# Via variable d'environnement permanente (.env)
BACKUP_STORAGE_PATH="./custom-backups"

# Via variable temporaire (une seule fois)
BACKUP_STORAGE_PATH="./my-backups" pnpm run backup:create

# Exemple avec un chemin absolu
BACKUP_STORAGE_PATH="/var/backups/towercontrol" pnpm run backup:create
```

## Utilisation

### Interface graphique

#### Paramètres Avancés

- **Visualisation** du statut en temps réel
- **Création manuelle** de sauvegardes
- **Vérification** de l'intégrité
- **Lien** vers la gestion complète

#### Page de gestion complète

- **Configuration** détaillée du système
- **Liste** de toutes les sauvegardes
- **Actions** (supprimer, restaurer)
- **Statistiques** et métriques

### Ligne de commande

```bash
# Créer une sauvegarde immédiate
pnpm run backup:create

# Lister toutes les sauvegardes
pnpm run backup:list

# Vérifier l'intégrité de la base
pnpm run backup:verify

# Voir la configuration
pnpm run backup:config

# Démarrer le planificateur
pnpm run backup:start

# Arrêter le planificateur
pnpm run backup:stop

# Statut du planificateur
pnpm run backup:status

# Commandes avancées (pnpm tsx requis)
pnpm tsx scripts/backup-manager.ts delete <filename>
pnpm tsx scripts/backup-manager.ts restore <filename> --force
```

## Planificateur automatique

### Fonctionnement

Le planificateur fonctionne en arrière-plan et crée des sauvegardes selon la fréquence configurée :

- **Hourly** : Toutes les heures
- **Daily** : Une fois par jour (recommandé)
- **Weekly** : Une fois par semaine

### Auto-démarrage

En production, le planificateur démarre automatiquement 30 secondes après le lancement de l'application.

### Gestion

```bash
# Démarrer manuellement
pnpm run backup:start

# Arrêter
pnpm run backup:stop

# Voir le statut
pnpm run backup:status
```

## Fichiers de sauvegarde

### Format des noms

```
towercontrol_2025-01-15T10-30-00-000Z.db      # Non compressé
towercontrol_2025-01-15T10-30-00-000Z.db.gz   # Compressé
```

### Localisation

Par défaut : `./backups/` (relatif au dossier du projet)

### Métadonnées

Chaque sauvegarde contient :

- **Horodatage** précis de création
- **Taille** du fichier
- **Type** (manuelle ou automatique)
- **Statut** (succès, échec, en cours)

## Restauration

⚠️ **ATTENTION** : La restauration remplace complètement la base de données actuelle.

### Sécurités

1. **Sauvegarde automatique** de la base actuelle avant restauration
2. **Confirmation** obligatoire
3. **Environnement** : Bloqué en production via API
4. **CLI uniquement** pour les restaurations en production

### Procédure

#### Via interface (développement uniquement)

1. Aller dans la gestion des sauvegardes
2. Cliquer sur **"Restaurer"** à côté du fichier souhaité
3. Confirmer l'action

#### Via CLI

```bash
# Restaurer avec confirmation
pnpm tsx scripts/backup-manager.ts restore towercontrol_2025-01-15T10-30-00-000Z.db.gz

# Restaurer en forçant (sans confirmation)
pnpm tsx scripts/backup-manager.ts restore towercontrol_2025-01-15T10-30-00-000Z.db.gz --force
```

## Vérification d'intégrité

### Quand l'utiliser

- Après une restauration
- Avant une opération critique
- En cas de doute sur la base de données
- Dans une tâche de maintenance

### Commandes

```bash
# Via pnpm script
pnpm run backup:verify

# Via CLI complet
pnpm tsx scripts/backup-manager.ts verify
```

### Vérifications effectuées

1. **Test de connexion** à la base
2. **PRAGMA integrity_check** SQLite
3. **Validation** de la structure
4. **Rapport** détaillé

## Maintenance

### Nettoyage automatique

Le système supprime automatiquement les anciennes sauvegardes selon `maxBackups`.

### Nettoyage manuel

```bash
# Supprimer une sauvegarde spécifique
pnpm tsx scripts/backup-manager.ts delete towercontrol_2025-01-15T10-30-00-000Z.db.gz

# Forcer la suppression
pnpm tsx scripts/backup-manager.ts delete towercontrol_2025-01-15T10-30-00-000Z.db.gz --force
```

### Surveillance des logs

Les opérations de sauvegarde sont loggées dans la console de l'application.

## Dépannage

### Problèmes courants

#### Erreur "sqlite3 command not found"

```bash
# Sur macOS
brew install sqlite

# Sur Ubuntu/Debian
sudo apt-get install sqlite3
```

#### Permissions insuffisantes

```bash
# Vérifier les permissions du dossier de sauvegarde
ls -la backups/

# Modifier si nécessaire
chmod 755 backups/
```

#### Espace disque insuffisant

```bash
# Vérifier l'espace disponible
df -h

# Supprimer d'anciennes sauvegardes
pnpm tsx scripts/backup-manager.ts list
pnpm tsx scripts/backup-manager.ts delete <filename>
```

### Logs de debug

Pour activer le debug détaillé, modifier `services/database.ts` :

```typescript
export const prisma =
  globalThis.__prisma ||
  new PrismaClient({
    log: ['query', 'info', 'warn', 'error'], // Debug activé
  });
```

## Sécurité

### Bonnes pratiques

1. **Stockage externe** : Copier régulièrement les sauvegardes hors du serveur
2. **Chiffrement** : Considérer le chiffrement pour les données sensibles
3. **Accès restreint** : Limiter l'accès au dossier de sauvegarde
4. **Tests réguliers** : Vérifier la restauration périodiquement

### Variables d'environnement

```bash
# Configuration des chemins de base de données
DATABASE_URL="file:./prisma/dev.db"        # Pour Prisma
BACKUP_DATABASE_PATH="./prisma/dev.db"     # Base à sauvegarder (optionnel)
BACKUP_STORAGE_PATH="./backups"            # Dossier des sauvegardes (optionnel)
```

### Docker

En environnement Docker, tout est centralisé dans le dossier `data/` :

```yaml
# docker-compose.yml
environment:
  DATABASE_URL: 'file:./data/prod.db' # Base de données Prisma
  BACKUP_DATABASE_PATH: './data/prod.db' # Base à sauvegarder
  BACKUP_STORAGE_PATH: './data/backups' # Dossier des sauvegardes
volumes:
  - ./data:/app/data # Bind mount vers dossier local
```

**Structure des dossiers :**

```
./data/                    # Dossier local mappé
├── prod.db               # Base de données production
├── dev.db                # Base de données développement
└── backups/              # Sauvegardes (créé automatiquement)
    ├── towercontrol_*.db.gz
    └── ...
```

## API

### Endpoints disponibles

```
GET    /api/backups              # Lister les sauvegardes
POST   /api/backups              # Actions (create, verify, config, scheduler)
DELETE /api/backups/[filename]   # Supprimer une sauvegarde
POST   /api/backups/[filename]   # Restaurer (dev seulement)
```

### Exemples d'utilisation

```typescript
// Créer une sauvegarde
const response = await fetch('/api/backups', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ action: 'create' }),
});

// Lister les sauvegardes
const response = await fetch('/api/backups');
const data = await response.json();
```

## Architecture

```
services/
├── backup.ts           # Service principal de sauvegarde
└── backup-scheduler.ts # Planificateur automatique

src/app/api/backups/
├── route.ts           # API endpoints principaux
└── [filename]/route.ts # Actions sur fichiers spécifiques

clients/
└── backup-client.ts   # Client HTTP pour l'interface

components/settings/
├── AdvancedSettingsPageClient.tsx    # Vue d'ensemble dans paramètres
└── BackupSettingsPageClient.tsx      # Gestion complète

scripts/
└── backup-manager.ts  # CLI d'administration
```

## Roadmap

### Version actuelle ✅

- Sauvegardes automatiques et manuelles
- Interface graphique complète
- CLI d'administration
- Compression et rétention

### Améliorations futures 🚧

- Sauvegarde vers cloud (S3, Google Drive)
- Chiffrement des sauvegardes
- Notifications par email
- Métriques de performance
- Sauvegarde incrémentale