Effi/docs/WORKFLOW.md

# 🔄 Workflow de Gestion - Guide Pratique

## Objectif

Ce guide t'aide à gérer les modifications de ton infrastructure Effi sans stress, tout en maintenant ton dépôt Gitea à jour.

---

## 🎯 Le Workflow Recommandé (KISS)

**Principe** : Toujours deux sources de vérité cohérentes
- **Production** (effi-server) : Fait tourner les services
- **Gitea** (dépôt) : Archive et documente la config

```
┌─────────────────┐         ┌─────────────────┐
│   effi-server   │  ←────→ │     Gitea       │
│   (Production)  │  sync   │   (Archive)     │
└────────┬────────┘         └─────────────────┘
         │
    ┌────┴────┐
    │  Test   │  ← Tu fais tes tests ici
    └────┬────┘
         │
    ┌────┴────┐
    │  Push   │  ← Quand ça marche, tu pousses
    └─────────┘
```

---

## 📋 Procédure Standard

### Quand tu veux faire une modification :

#### ÉTAPE 1 : Sauvegarde (30 secondes)

```bash
cd ~/effi
docker compose down  # Optionnel, mais plus sûr
cd ..
cp -r Effi Effi-BACKUP-$(date +%Y%m%d)
cd Effi
```

> 💡 **Pourquoi ?** Si tu casses quelque chose, tu peux revenir en arrière en 10 secondes.

#### ÉTAPE 2 : Modification (5-30 minutes)

Fais tes changements sur effi-server :
```bash
# Exemple: Ajouter un service
nano docker-compose.yml

# Tester
docker compose up -d

# Vérifier que ça marche
docker compose ps
docker logs [nom-du-service]
```

#### ÉTAPE 3 : Audit (1 minute)

```bash
./scripts/audit-production.sh
```

Note les différences affichées.

#### ÉTAPE 4 : Synchronisation avec Gitea (2 minutes)

**Sur ton PC (pas sur effi-server) :**

```bash
cd ~/Documents/OpenCode/Projets/Effi

# 1. Récupérer les fichiers depuis effi-server
scp effi@192.168.1.27:~/effi/docker-compose.yml .
scp effi@192.168.1.27:~/effi/.env .env.production  # Si nouvelles variables

# 2. Comparer avec git diff
git diff

# 3. Si c'est bon, commiter
git add .
git commit -m "Ajout service XXX - [date]"

# 4. Pousser
git push
```

#### ÉTAPE 5 : Documentation (optionnel, 5 minutes)

Si tu as ajouté un service important, mets à jour la doc :
```bash
# Modifier docs/02-configuration/...
nano docs/02-configuration/nouveau-service.md

git add .
git commit -m "Documentation: Ajout service XXX"
git push
```

---

## 🆘 En Cas de Problème

### Si tu as cassé quelque chose :

```bash
# 1. Retour arrière rapide
cd ~/effi
docker compose down
cd ..
rm -rf Effi
cp -r Effi-BACKUP-YYYYMMDD Effi  # Date de ta dernière sauvegarde
cd Effi
docker compose up -d

# 2. C'est réparé !
```

### Si tu as oublié de sauvegarder :

```bash
# Récupérer la dernière version stable depuis Gitea
cd ~/effi
docker compose down
cd ..
rm -rf Effi
git clone https://gitea.folzocorp.fr/Folzo/effi.git
cd effi
cp .env.example .env  # Recréer le .env
# Éditer .env avec tes vraies valeurs
docker compose up -d
```

---

## 📝 Checklist Avant Modification

Avant chaque changement, vérifie :

- [ ] Sauvegarde créée (`cp -r Effi Effi-BACKUP-...`)
- [ ] Services actuels notés (`docker compose ps`)
- [ ] Espace disque suffisant (`df -h`)
- [ ] Connexion à folzo-Corp OK (`ping 192.168.1.11`)

---

## 🔄 Fréquence de Synchronisation

| Situation | Action |
|-----------|--------|
| **Modification mineure** (port, variable) | Sync immédiate |
| **Nouveau service testé** | Sync quand stable (après 24-48h) |
| **Correction bug** | Sync immédiate avec message explicite |
| **Grosse refonte** | Sync par étapes, avec commits intermédiaires |
| **Rien ne marche plus** | Restore backup, ne pas sync la config cassée |

---

## 🎓 Exemple Concret

**Scénario** : Tu veux ajouter un service de monitoring (Uptime Kuma)

```bash
# 1. Backup
cd ~/effi/..
cp -r Effi Effi-BACKUP-$(date +%Y%m%d)

# 2. Modification
cd ~/effi
nano docker-compose.yml
# Ajouter le service uptime-kuma...

# 3. Test
docker compose up -d uptime-kuma
docker compose ps  # Vérifier qu'il démarre
curl http://192.168.1.27:3001  # Vérifier l'interface

# 4. Attendre 24h pour être sûr que c'est stable

# 5. Sync avec Gitea (sur ton PC)
scp effi@192.168.1.27:~/effi/docker-compose.yml ~/Documents/OpenCode/Projets/Effi/
cd ~/Documents/OpenCode/Projets/Effi
git add .
git commit -m "Ajout Uptime Kuma pour monitoring (port 3001)"
git push
```

---

## 💡 Bonnes Pratiques

### 1. Commits atomiques

Un commit = une modification logique

```bash
# ❌ Mauvais
git commit -m "Modifications diverses"

# ✅ Bon
git commit -m "Ajout service Watchtower (màj auto containers)"
git commit -m "Fix: Correction port CouchDB 5984->5985"
```

### 2. Messages descriptifs

```bash
git commit -m "Ajout: Service n8n pour automatisation (port 5678)"
git commit -m "Update: Upgrade Qdrant v1.8 -> v1.9"
git commit -m "Fix: Résolution conflit port 8200"
```

### 3. Tester avant de synchroniser

Jamais de sync direct sans test !

### 4. Garder l'historique

```bash
# Voir ce qui a changé
git log --oneline -10

# Comparer avec une version ancienne
git diff HEAD~5 docker-compose.yml
```

---

## 🔧 Commandes Essentielles (à garder sous la main)

```bash
# Sur effi-server
~/effi/scripts/audit-production.sh    # Audit complet
docker compose ps                      # Voir les services
docker compose logs -f [service]       # Voir les logs
docker compose down && docker compose up -d  # Redémarrer propre

# Sur ton PC (synchronisation)
git status                             # Voir les changements
git diff                               # Voir les différences
git add . && git commit -m "message"   # Commiter
git push                               # Pousser sur Gitea
git pull                               # Récupérer depuis Gitea
```

---

## 📚 Ressources

- **Dépôt Gitea** : https://gitea.folzocorp.fr/Folzo/effi
- **Audit** : `~/effi/scripts/audit-production.sh`
- **Documentation** : `~/Documents/OpenCode/Projets/Effi/docs/`

---

*Dernière mise à jour : Avril 2026*