Create documentation for project architecture, deployment, and usage

Add DAT, DEX, GITEA_TUTO, and WIKI markdown files to the docs directory, and update agent_assets_metadata.toml to include these new documents. Replit-Commit-Author: Agent Replit-Commit-Session-Id: 923ae0e3-a363-4db8-b04a-e8baca2a1330 Replit-Commit-Checkpoint-Type: full_checkpoint Replit-Commit-Event-Id: 4bb1a658-d577-451e-965c-fa15e2c21ca9 Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/8af7d2ec-2cc3-4ece-8af3-9f071488d072/923ae0e3-a363-4db8-b04a-e8baca2a1330/RusmVRz Replit-Helium-Checkpoint-Created: true
2026-04-04 06:56:49 +00:00
parent e2a0b6401d
commit 213a67e612
5 changed files with 727 additions and 0 deletions
@@ -0,0 +1,244 @@
+# 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`