la-voix-du-peuple/docs/DEX.md

# Document d'Exploitation — La Voix du Peuple

**Version** : 1.0  
**Date** : Avril 2026

---

## 1. Démarrage et arrêt des services

### Sur Replit

Les services sont gérés par les **Workflows** Replit. Ils démarrent automatiquement.

| Workflow | Commande | Port |
|----------|----------|------|
| API Server | `PORT=8080 sh artifacts/flask-api/start.sh` | 8080 |
| Frontend | `pnpm --filter @workspace/voix-du-peuple run dev` | auto |

Pour redémarrer manuellement : onglet **Workflows** → bouton restart.

---

### En auto-hébergement (RockyLinux / Debian)

```bash
# Démarrer le backend
systemctl start voix-du-peuple-api

# Arrêter le backend
systemctl stop voix-du-peuple-api

# Redémarrer après mise à jour
systemctl restart voix-du-peuple-api

# Voir le statut
systemctl status voix-du-peuple-api

# Activer au démarrage
systemctl enable voix-du-peuple-api
```

```bash
# Redémarrer Nginx après modification de la config
nginx -t && systemctl reload nginx
```

---

## 2. Variables d'environnement

Fichier de référence : `.env.example` à la racine du projet.

En production, créer `/etc/voix-du-peuple/.env` :

```bash
# Base de données
DATABASE_URL=postgresql://user:password@localhost:5432/voix_du_peuple

# IA — choisir l'un des deux
MISTRAL_API_KEY=sk-...
# OPENAI_API_KEY=sk-...

# Modèles (optionnel — valeurs par défaut ci-dessous)
FILTER_MODEL=mistral-small-latest
SYNTHESIS_MODEL=mistral-large-latest

# Sécurité Flask
SESSION_SECRET=une-longue-chaine-aleatoire-securisee
```

> **Important** : Après toute modification du fichier `.env`, redémarrer le service API.

---

## 3. Mise à jour du code

```bash
# Depuis votre serveur, après un git pull
cd /opt/voix-du-peuple

git pull gitea main

# Mettre à jour les dépendances Python si requirements.txt a changé
pip install -r artifacts/flask-api/requirements.txt

# Reconstruire le frontend si le code frontend a changé
pnpm install
pnpm --filter @workspace/voix-du-peuple run build --config vite.config.selfhost.ts

# Redémarrer l'API
systemctl restart voix-du-peuple-api
```

---

## 4. Consultation des logs

### Sur Replit

Voir les logs dans l'onglet **Workflows** → cliquer sur le workflow concerné.

### En auto-hébergement

```bash
# Logs du service systemd (temps réel)
journalctl -u voix-du-peuple-api -f

# 100 dernières lignes
journalctl -u voix-du-peuple-api -n 100

# Logs d'une journée spécifique
journalctl -u voix-du-peuple-api --since "2026-04-01" --until "2026-04-02"

# Logs Nginx
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
```

---

## 5. Base de données

### Connexion directe

```bash
psql "$DATABASE_URL"
# ou
psql -U voix_user -d voix_du_peuple -h localhost
```

### Requêtes utiles

```sql
-- Nombre de contributions par statut
SELECT accepted, COUNT(*) FROM ideas GROUP BY accepted;

-- Dernières contributions
SELECT id, author, left(content, 60), accepted, created_at
FROM ideas ORDER BY created_at DESC LIMIT 10;

-- Contributions refusées avec motif
SELECT id, left(content, 60), rejection_reason, created_at
FROM ideas WHERE accepted = false ORDER BY created_at DESC;

-- État de la synthèse
SELECT idea_count, left(text, 200), updated_at FROM synthesis;
```

### Sauvegarde

```bash
# Dump complet
pg_dump "$DATABASE_URL" > backup_$(date +%Y%m%d_%H%M).sql

# Restauration
psql "$DATABASE_URL" < backup_20260401_0800.sql
```

---

## 6. Vérification du bon fonctionnement

```bash
# Health check API
curl http://localhost:8080/health

# Test de soumission
curl -X POST http://localhost:8080/api/ideas \
  -H "Content-Type: application/json" \
  -d '{"content": "Test de fonctionnement de la plateforme.", "author": "Admin"}'

# Lecture de la synthèse
curl http://localhost:8080/api/synthesis | python3 -m json.tool

# Statistiques
curl http://localhost:8080/api/ideas/stats
```

Réponse attendue du health check :
```json
{"status": "ok"}
```

---

## 7. Changement de modèle IA

Pour basculer vers un modèle différent sans toucher au code :

```bash
# Exemple : passer à mistral-medium
# Éditer le .env
FILTER_MODEL=mistral-medium-latest
SYNTHESIS_MODEL=mistral-medium-latest

# Redémarrer
systemctl restart voix-du-peuple-api
```

Modèles Mistral disponibles (avril 2026) :
- `mistral-small-latest` — Rapide, économique (filtre)
- `mistral-medium-latest` — Équilibré
- `mistral-large-latest` — Meilleure qualité (synthèse)

---

## 8. Purge des données

```sql
-- Supprimer toutes les contributions (irréversible)
TRUNCATE ideas;
TRUNCATE synthesis;

-- Supprimer uniquement les contributions refusées
DELETE FROM ideas WHERE accepted = false;

-- Forcer une re-synthèse (supprimer le cache)
DELETE FROM synthesis;
```

Après une purge, la synthèse se régénère automatiquement à la prochaine contribution acceptée.

---

## 9. Dépannage courant

| Symptôme | Cause probable | Solution |
|----------|---------------|----------|
| `Service temporairement indisponible` sur soumission | Clé Mistral invalide ou quota dépassé | Vérifier `MISTRAL_API_KEY`, consulter console.mistral.ai |
| Synthèse non mise à jour | Erreur silencieuse en arrière-plan | Consulter les logs, vérifier la connexion à l'API IA |
| Erreur 500 sur toutes les routes | `DATABASE_URL` incorrect ou PostgreSQL arrêté | `systemctl status postgresql`, vérifier le `.env` |
| Frontend vide (page blanche) | Build manquant ou `BASE_URL` incorrect | Relancer le build Vite, vérifier la config Nginx |
| Rate limit atteint (429) | Trop de soumissions depuis la même IP | Normal — attendre 1 minute |
| Modèle IA introuvable (404) | Nom de modèle incorrect dans `FILTER_MODEL` | Corriger le nom, redémarrer le service |

---

## 10. Contacts et ressources

- Documentation Mistral : https://docs.mistral.ai
- PostgreSQL : https://www.postgresql.org/docs/
- Flask : https://flask.palletsprojects.com
- Guide de déploiement complet : `DEPLOIEMENT.md`
- Architecture : `docs/DAT.md`