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

# Document d'Exploitation — La Voix du Peuple

**Version** : 1.1  
**Date** : Avril 2026

---

## Historique des versions

| Version | Date | Modifications |
|---------|------|---------------|
| 1.0 | Avril 2026 | Version initiale |
| 1.1 | Avril 2026 | Ajout section flyer QR, export PDF, partage horodaté |

---

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

# Mettre à jour les dépendances Node si package.json a changé
pnpm install

# Reconstruire le frontend si le code frontend a changé
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. Gestion du flyer QR code

La page `/flyer` génère un flyer A4 imprimable avec un QR code.

### Changer l'URL de destination

**Méthode 1 — Interface (sans code)** : ouvrir `/flyer`, modifier le champ "Destination du QR code", cliquer "Appliquer", puis imprimer.

**Méthode 2 — Paramètre URL** : ajouter `?url=` à l'adresse de la page, ex. :
```
https://lavoixdupeuple.fr/flyer?url=https://autresite.fr
```

**Méthode 3 — Modification permanente dans le code** : éditer la ligne 10 de `artifacts/voix-du-peuple/src/pages/flyer.tsx` :
```ts
const DEFAULT_QR_URL = "https://lavoixdupeuple.fr";
```
Reconstruire ensuite le frontend (`pnpm build`).

### Imprimer / exporter en PDF

Sur la page `/flyer`, cliquer **Imprimer / Exporter PDF**. La barre de configuration disparaît automatiquement à l'impression, seul le flyer A4 est produit. Pour obtenir un PDF, choisir "Enregistrer en PDF" dans la boîte de dialogue du navigateur.

---

## 9. Export de la synthèse

Deux boutons sont disponibles dans l'en-tête de la colonne de synthèse (page principale) :

### Partager / Copier

- Sur mobile (navigateurs supportant Web Share) : ouvre le menu de partage natif du système
- Sur bureau : copie le texte dans le presse-papier avec horodatage et compteur de contributions ; un message de confirmation apparaît

### PDF

Génère et ouvre une page HTML mise en page (tricolore, titre, date, texte de synthèse, pied de page) puis déclenche l'impression. Choisir "Enregistrer en PDF" dans la boîte de dialogue pour obtenir un fichier.

> Ces deux fonctions s'exécutent entièrement côté client — aucune donnée n'est envoyée au serveur.

---

## 10. 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.

---

## 11. 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 |
| QR code ne redirige pas | URL incorrecte dans le champ ou la constante | Vérifier `DEFAULT_QR_URL` dans `flyer.tsx`, ou passer `?url=` en paramètre |
| Bouton "Copier" sans retour visuel | Navigateur sans accès au presse-papier (HTTP non sécurisé) | Servir le site en HTTPS |
| Fenêtre PDF bloquée | Bloqueur de popups actif | Autoriser les popups pour ce site dans le navigateur |

---

## 12. Contacts et ressources

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