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)

# 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

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

# 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

# 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

# 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

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

Requêtes utiles

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

# 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

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

{"status": "ok"}

---

7. Changement de modèle IA

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

# 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

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