mes-budgets-participatifs/README.md

Mes Budgets Participatifs

Une application web moderne et éthique pour gérer des campagnes de budgets participatifs, permettant aux collectifs de décider collectivement de leurs dépenses budgétaires.

🌟 Pourquoi cette application ?

Mes Budgets Participatifs est conçue pour démocratiser la prise de décision budgétaire. Elle permet aux organisations, associations, collectifs et institutions de :

• Impliquer les citoyens dans les décisions budgétaires
• Utilisation de l'intelligence collective sur l'utilisation des fonds
• Démocratie participative accessible à tous
• Gestion éthique des données et de la vie privée

🚀 Technologies utilisées

• Frontend: Next.js 15 avec TypeScript et App Router
• UI/UX: Tailwind CSS 4 + Shadcn/ui + Lucide React
• Base de données: PostgreSQL via Supabase avec RLS sécurisé
• Authentification: Supabase Auth avec système de rôles admin/super_admin
• Sécurité: Row Level Security (RLS) avec politiques granulaires
• Email: Nodemailer avec support SMTP
• Tests: Jest + React Testing Library + Playwright
• Déploiement: Compatible avec les solutions éthiques et libres

📋 Fonctionnalités

✅ Implémentées

🏠 Page d'accueil

• Présentation moderne de l'application
• Design responsive avec sections Hero, Features et CTA
• Navigation vers l'espace administration sécurisé

🔐 Authentification et Sécurité

• Système de rôles : Administrateurs et Super Administrateurs
• Authentification robuste : Supabase Auth avec validation côté serveur
• Politiques RLS sécurisées : Row Level Security avec permissions granulaires
• Protection des routes admin : Toutes les pages d'administration sont protégées
• Clé de service sécurisée : Opérations sensibles côté serveur uniquement
• Session persistante : Maintien de la connexion entre les pages
• Interface moderne : Formulaires de connexion avec validation

🛠️ Administration complète

• Gestion des campagnes : Création, modification, suppression
• Support Markdown : Éditeur avec prévisualisation pour les descriptions de campagnes
• États de campagne : Dépôt de propositions, vote, terminé
• Statistiques en temps réel : Nombre de propositions, participants, taux de participation
• Recherche : Filtrage des campagnes par titre ou description
• Interface moderne : Design Shadcn/ui avec cartes et badges

📝 Gestion des propositions

• Page dédiée : Interface complète pour gérer les propositions par campagne
• CRUD complet : Création, lecture, modification, suppression
• Support Markdown : Éditeur avec prévisualisation pour les descriptions
• Informations détaillées : Auteur, email, date de création
• Interface moderne : Cartes avec avatars et badges

👥 Gestion des participants

• Page dédiée : Interface complète pour gérer les participants par campagne
• Statuts de vote : Indication visuelle des participants ayant voté
• Liens de vote personnels : URLs uniques pour chaque participant
• Statistiques : Taux de participation et budget total voté

🌐 Pages publiques

• Dépôt de propositions : Interface publique pour soumettre des propositions
  • URL unique et partageable
  • Formulaire avec validation
  • Support Markdown pour les descriptions
  • Informations d'auteur obligatoires
• Vote public : Interface de vote pour les participants
  • Slider interactif pour les choix de budget
  • Validation du budget total
  • Affichage des descriptions avec support Markdown
  • Sauvegarde des votes

📧 Système d'email avancé

• Configuration SMTP : Interface d'administration pour configurer les paramètres email
• Envoi d'emails personnalisés : Envoi d'emails individuels aux participants avec liens de vote
• Templates personnalisables : Messages d'email configurables avec placeholders [PRENOM] et [NOM]
• Envoi en masse : Envoi d'emails à tous les participants d'une campagne
• Test d'envoi : Fonctionnalité de test des paramètres SMTP
• Footer personnalisable : Messages de pied de page avec liens cliquables
• HTML responsive : Emails avec design moderne et boutons d'action
• Gestion d'erreurs : Messages d'erreur détaillés pour les problèmes SMTP

📊 Export des données

• Export ODS : Export des statistiques de vote en format tableur
• Format LibreOffice : Compatible avec LibreOffice Calc, OpenOffice, Excel
• Données complètes : Toutes les propositions, participants et votes
• Totaux automatiques : Calculs des totaux par ligne et colonne

🎨 Interface moderne

• Shadcn/ui : Composants modernes et accessibles
• Design responsive : Adaptation mobile/desktop
• Thème sombre : Support du mode sombre
• Animations : Transitions fluides
• Icônes Lucide : Icônes modernes et cohérentes

🔄 Fonctionnalités avancées

• Support Markdown : Éditeur avec prévisualisation pour les descriptions
  • Formatage de texte : Gras, italique, souligné, barré
  • Titres : H1, H2, H3 pour structurer le contenu
  • Listes : Listes à puces et numérotées
  • Liens : URLs externes avec validation de sécurité
  • Validation : Contrôle de la longueur et des contenus dangereux
• URLs publiques : Liens partageables pour le dépôt et le vote
• Copie de liens : Boutons pour copier les URLs dans le presse-papiers
• Validation en temps réel : Vérification des budgets lors du vote
• Gestion d'erreurs : Messages d'erreur informatifs
• États de chargement : Feedback visuel pendant les opérations
• Personnalisation des emails : Placeholders [PRENOM] et [NOM] dans les messages
• Footer dynamique : Messages de pied de page avec liens cliquables vers le projet
• Interface d'envoi d'emails : Modales dédiées pour l'envoi personnalisé
• Suivi des envois : Indicateurs de progression pour les envois en masse

🛠️ Installation

Prérequis

• Node.js 18+
• npm ou yarn
• Compte Supabase

1. Cloner le projet

git clone <votre-repo>
cd mes-budgets-participatifs

2. Installer les dépendances

npm install

3. Configuration Supabase

Créer un projet Supabase

1. Allez sur supabase.com
2. Créez un nouveau projet
3. Notez votre URL et vos clés

Configurer la base de données

1. Dans votre projet Supabase, allez dans l'éditeur SQL
2. Copiez et exécutez le contenu du fichier database/supabase-schema.sql

Configurer l'authentification

1. Dans Supabase Dashboard > Authentication > Settings
2. Activez l'authentification par email
3. Désactivez "Enable email confirmations" pour les administrateurs
4. Créez les utilisateurs dans Authentication > Users
5. Ajoutez les administrateurs dans la table admin_users via l'éditeur SQL

Configurer les variables d'environnement

Créez un fichier .env.local à la racine du projet :

# Configuration Supabase (obligatoire)
NEXT_PUBLIC_SUPABASE_URL=votre_url_supabase
NEXT_PUBLIC_SUPABASE_ANON_KEY=votre_cle_anon_supabase
SUPABASE_SERVICE_ROLE_KEY=votre_cle_service_supabase

⚠️ Important : La SUPABASE_SERVICE_ROLE_KEY est obligatoire pour les opérations d'administration. Elle permet d'effectuer des opérations privilégiées côté serveur (création d'utilisateurs, gestion des campagnes, etc.).

4. Configuration des administrateurs

1. Créez les utilisateurs dans Supabase Dashboard > Authentication > Users
2. Ajoutez les administrateurs dans la table admin_users via l'éditeur SQL :

   INSERT INTO admin_users (user_id, role) 
   VALUES ('votre_user_id', 'admin');
   

3. Connectez-vous avec les identifiants créés

5. Configuration email (optionnelle)

Une fois connecté à l'administration, vous pouvez configurer les paramètres SMTP via l'interface :

1. Allez dans Paramètres > Configuration SMTP
2. Renseignez vos paramètres de serveur SMTP
3. Testez la configuration

6. Lancer l'application

npm run dev

L'application sera accessible sur http://localhost:3000

7. Tests (optionnel)

# Lancer les tests fonctionnels
npm run test:working

# Lancer tous les tests
npm test

# Tests avec couverture
npm run test:coverage

📊 Structure de la base de données

Table campaigns

• id: Identifiant unique (UUID)
• title: Titre de la campagne
• description: Description détaillée
• status: État de la campagne (deposit, voting, closed)
• budget_per_user: Budget alloué par participant (en euros)
• spending_tiers: Paliers de dépenses disponibles (séparés par des virgules)
• created_at: Date de création
• updated_at: Date de dernière modification

Table propositions

• id: Identifiant unique (UUID)
• campaign_id: Référence vers la campagne
• title: Titre de la proposition
• description: Description détaillée
• author_first_name: Prénom de l'auteur
• author_last_name: Nom de l'auteur
• author_email: Email de l'auteur
• created_at: Date de création

Table participants

• id: Identifiant unique (UUID)
• campaign_id: Référence vers la campagne
• first_name: Prénom du participant
• last_name: Nom du participant
• email: Adresse email
• short_id: Identifiant court pour les URLs de vote
• created_at: Date de création

Table votes

• id: Identifiant unique (UUID)
• participant_id: Référence vers le participant
• proposition_id: Référence vers la proposition
• amount: Montant voté (en euros)
• created_at: Date de création
• updated_at: Date de dernière modification

Table settings

• key: Clé de configuration
• value: Valeur de configuration
• category: Catégorie (email, general, etc.)
• description: Description de la configuration

Table admin_users

• user_id: Référence vers l'utilisateur Supabase
• role: Rôle (admin, super_admin)
• created_at: Date de création

🚀 Déploiement

Solutions éthiques et libres (recommandées)

🇫🇷 Hébergement en France - Solutions éthiques

1. OVHcloud (Lyon, France)

• Avantages : Hébergeur français, RGPD compliant, prix compétitifs
• Déploiement : VPS ou Cloud avec Docker
• Prix : À partir de 3,50€/mois
• Site : ovhcloud.com

2. Scaleway (Paris, France)

• Avantages : Cloud français, éco-responsable, API complète
• Déploiement : App Platform ou VPS
• Prix : À partir de 2,99€/mois
• Site : scaleway.com

3. Clever Cloud (Nantes, France)

• Avantages : PaaS français, déploiement automatique, support français
• Déploiement : Platform as a Service
• Prix : À partir de 7€/mois
• Site : clever-cloud.com

4. AlwaysData (Paris, France)

• Avantages : Hébergeur français, support Next.js, éco-responsable
• Déploiement : Hosting avec déploiement Git
• Prix : À partir de 5€/mois
• Site : alwaysdata.com

🌍 Autres solutions possibles (liste non exhaustive)

5. Render (États-Unis)

• Avantages : Déploiement automatique, base de données PostgreSQL
• Déploiement : Connectez votre repo Git
• Prix : Gratuit pour les projets personnels, puis 7$/mois
• Site : render.com

6. Railway (États-Unis)

• Avantages : Déploiement simple, base de données incluse, éthique
• Déploiement : Connectez votre repo Git
• Prix : 5$/mois (plus de gratuité pour l'open source)
• Site : railway.app

7. Vercel (États-Unis)

• Avantages : Optimisé pour Next.js, déploiement automatique, gratuit pour l'open source
• Déploiement : Connectez votre repo Git
• Prix : Gratuit pour les projets personnels et open source
• Site : vercel.com

8. Netlify (États-Unis)

• Avantages : Interface simple, déploiement automatique, généreux pour l'open source
• Déploiement : Connectez votre repo Git
• Prix : Gratuit pour les projets personnels et open source
• Site : netlify.com

9. DigitalOcean App Platform (États-Unis)

• Avantages : Déploiement simple, base de données gérée
• Déploiement : Interface graphique simple
• Prix : À partir de 5$/mois
• Site : digitalocean.com

Configuration du déploiement

Variables d'environnement de production

# Configuration Supabase (obligatoire)
NEXT_PUBLIC_SUPABASE_URL=votre_url_supabase_production
NEXT_PUBLIC_SUPABASE_ANON_KEY=votre_cle_anon_supabase_production
SUPABASE_SERVICE_ROLE_KEY=votre_cle_service_supabase_production

Commandes de build

# Installation des dépendances
npm install

# Build de production
npm run build

# Démarrage en production
npm start

🔒 Sécurité

Authentification

• Routes protégées : Toutes les pages admin nécessitent une authentification
• Session sécurisée : Gestion des sessions via Supabase
• Pas d'inscription publique : Seuls les comptes pré-autorisés peuvent accéder

Base de données

• Row Level Security (RLS) : Protection des données au niveau de la base
• Validation côté serveur : Vérification des données avant sauvegarde
• URLs sécurisées : Liens publics avec identifiants uniques

Données sensibles

• Chiffrement SMTP : Mots de passe SMTP chiffrés en base
• Variables d'environnement : Configuration sécurisée
• Validation des entrées : Protection contre les injections

Clés Supabase

• Clé anonyme (NEXT_PUBLIC_SUPABASE_ANON_KEY) : Utilisée côté client, limitée par les politiques RLS
• Clé de service (SUPABASE_SERVICE_ROLE_KEY) : Utilisée côté serveur uniquement, contourne les politiques RLS
• Sécurité : La clé de service ne doit jamais être exposée côté client

🎯 Workflow d'utilisation

1. Configuration initiale

1. Créer un compte Supabase
2. Configurer la base de données
3. Créer un utilisateur admin
4. Configurer les paramètres SMTP (optionnel)
5. Déployer l'application

2. Création d'une campagne

1. Se connecter à l'administration
2. Créer une nouvelle campagne
3. Définir le budget et les paliers
4. Passer en mode "Dépôt de propositions"

3. Collecte des propositions

1. Partager le lien public de dépôt
2. Les participants soumettent leurs propositions
3. Gérer les propositions via l'interface admin

4. Phase de vote

1. Ajouter les participants
2. Passer en mode "En cours de vote"
3. Partager les liens de vote personnels
4. Suivre la participation en temps réel
5. Envoyer des rappels par email (optionnel)

5. Résultats

1. Consulter les statistiques de vote
2. Analyser les résultats
3. Clôturer la campagne

🧪 Tests

Tests disponibles

# Tests fonctionnels
npm run test:working

# Tous les tests
npm test

# Tests avec couverture
npm run test:coverage

# Tests en mode watch
npm run test:watch

Couverture des tests

• Tests unitaires : Utilitaires, validation, formatage, parsing de messages
• Tests d'intégration : Services et API, système d'email
• Tests E2E : Flux complets (Playwright)
• Tests de sécurité : Vérification des politiques RLS et authentification
• Tests de composants : Interface utilisateur et modales

📚 Documentation

Pour une documentation complète, consultez le dossier docs/ :

• Guide de démarrage - Vue d'ensemble de la documentation
• Configuration - Installation et configuration détaillée
• Sécurité - Résumé de la sécurisation
• Gestion des administrateurs - Configuration des utilisateurs admin
• Paramètres - Configuration avancée et SMTP
• Tests - Guide complet des tests
• Tests - Résumé - Résumé de la suite de tests
• Tests - Démarrage rapide - Démarrage rapide des tests
• Export ODS - Fonctionnalité d'export des statistiques
• Architecture - Nouvelle architecture simplifiée
• Structure du projet - Organisation du code

🤝 Contribution

1. Fork le projet
2. Créez une branche pour votre fonctionnalité
3. Committez vos changements
4. Poussez vers la branche
5. Ouvrez une Pull Request

Standards de contribution

• Tests : Ajoutez des tests pour les nouvelles fonctionnalités
• Documentation : Mettez à jour la documentation si nécessaire
• Code : Respectez les conventions TypeScript et ESLint

📝 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🆘 Support

Pour toute question ou problème :

1. Vérifiez la documentation dans le dossier docs/
2. Consultez les issues Git
3. Créez une nouvelle issue si nécessaire

🌱 Éthique et valeurs

Cette application est développée avec des valeurs éthiques :

• Souveraineté numérique : Privilégier les solutions hébergées en France
• Logiciel libre : Code source ouvert et réutilisable
• Protection des données : Respect du RGPD et de la vie privée
• Accessibilité : Interface utilisable par tous
• Transparence : Code et processus transparents

---

Développé avec ❤️ pour faciliter la démocratie participative

Application complète et prête pour la production avec authentification, interface moderne, système d'email avancé, tests complets et toutes les fonctionnalités de gestion de budgets participatifs.

---

📈 Version actuelle : 0.2.0

🆕 Dernières améliorations

• Système d'email avancé : Envoi personnalisé avec templates et placeholders
• Interface d'envoi d'emails : Modales dédiées pour l'envoi individuel et en masse
• Footer personnalisable : Messages de pied de page avec liens cliquables
• Tests étendus : Couverture complète des fonctionnalités email
• Gestion d'erreurs améliorée : Messages d'erreur détaillés pour SMTP
• HTML responsive : Emails avec design moderne et boutons d'action