385 lines
16 KiB
Markdown
385 lines
16 KiB
Markdown
# 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 avancé**
|
|
- **Formats multiples** : ODS (OpenDocument), CSV, XLS (Microsoft Excel)
|
|
- **Export des statistiques** : Matrice complète des votes avec 6 onglets de tri
|
|
- **Export des propositions** : Liste détaillée des propositions par campagne
|
|
- **Anonymisation RGPD** : 3 niveaux de protection des données personnelles
|
|
- **Anonymisation complète** : Noms remplacés par "XXXX" (recommandé)
|
|
- **Initiales uniquement** : Premières lettres des noms/prénoms
|
|
- **Aucune anonymisation** : Noms complets (avec avertissement RGPD)
|
|
- **Données complètes** : Toutes les propositions, participants et votes
|
|
- **Totaux automatiques** : Calculs des totaux par ligne et colonne
|
|
- **Formatage professionnel** : En-têtes, bordures, colonnes dimensionnées
|
|
- **Configuration centralisée** : Paramètres d'export dans l'interface admin
|
|
|
|
#### 🎨 **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
|
|
- **Export multi-formats** : ODS, CSV, XLS avec configuration centralisée
|
|
- **Anonymisation configurable** : Protection RGPD avec 3 niveaux de sécurité
|
|
- **Export des propositions** : Export séparé des propositions par campagne
|
|
- **Formatage professionnel** : Exports avec mise en forme et totaux automatiques
|
|
|
|
## 🛠️ Installation
|
|
|
|
### 🚀 **Installation simplifiée (recommandée)**
|
|
|
|
L'application dispose d'un **assistant de configuration automatique** qui guide pas à pas l'installation complète.
|
|
|
|
#### Prérequis
|
|
- Node.js 18+
|
|
- npm ou yarn
|
|
- Compte Supabase
|
|
|
|
#### 1. Cloner et installer
|
|
```bash
|
|
git clone <votre-repo>
|
|
cd mes-budgets-participatifs
|
|
npm install
|
|
```
|
|
|
|
#### 2. Lancer l'assistant de configuration
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Puis accédez à `http://localhost:3000/setup` pour l'**assistant de configuration automatique**.
|
|
|
|
#### 3. Suivre l'assistant pas à pas
|
|
L'assistant vous guide automatiquement pour :
|
|
- ✅ **Configuration Supabase** : Création du projet et récupération des clés
|
|
- ✅ **Base de données** : Exécution automatique du schéma SQL
|
|
- ✅ **Authentification** : Configuration des utilisateurs admin
|
|
- ✅ **Variables d'environnement** : Génération automatique du fichier `.env.local`
|
|
- ✅ **Premier administrateur** : Création du compte admin initial
|
|
- ✅ **Test de connexion** : Vérification que tout fonctionne
|
|
|
|
#### 4. Configuration email (optionnelle)
|
|
Une fois l'assistant terminé, connectez-vous à l'administration :
|
|
1. Allez dans **Paramètres** > **Configuration SMTP**
|
|
2. Renseignez vos paramètres de serveur SMTP
|
|
3. Testez la configuration
|
|
|
|
### 📚 **Installation manuelle (avancée)**
|
|
|
|
Si vous préférez une installation manuelle, consultez le [Guide de configuration détaillé](docs/SETUP.md).
|
|
|
|
### 🧪 **Tests (optionnel)**
|
|
```bash
|
|
# 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 `user_permissions`
|
|
- `user_id`: Référence vers l'utilisateur Supabase
|
|
- `is_admin`: Booléen indiquant si l'utilisateur est administrateur
|
|
- `is_super_admin`: Booléen indiquant si l'utilisateur est super administrateur
|
|
- `created_at`: Date de création
|
|
- `updated_at`: Date de dernière modification
|
|
|
|
## 🔒 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
|
|
```bash
|
|
# 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/](docs/) :
|
|
|
|
- **[Guide de démarrage](docs/README.md)** - Vue d'ensemble de la documentation
|
|
- **[Configuration](docs/SETUP.md)** - Installation et configuration détaillée
|
|
- **[Sécurité](docs/SECURITY-SUMMARY.md)** - Résumé de la sécurisation
|
|
- **[Gestion des administrateurs](docs/ADMIN-MANAGEMENT.md)** - Configuration des utilisateurs admin
|
|
- **[Paramètres](docs/SETTINGS.md)** - Configuration avancée et SMTP
|
|
- **[Tests](docs/TESTING.md)** - Guide complet des tests
|
|
- **[Tests - Résumé](docs/TESTING_SUMMARY.md)** - Résumé de la suite de tests
|
|
- **[Tests - Démarrage rapide](docs/README-TESTS.md)** - Démarrage rapide des tests
|
|
- **[Export avancé](docs/EXPORT-FEATURE.md)** - Fonctionnalités d'export multi-formats et anonymisation
|
|
- **[Architecture](docs/NEW-ARCHITECTURE.md)** - Nouvelle architecture simplifiée
|
|
- **[Structure du projet](docs/PROJECT-STRUCTURE.md)** - 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
|
|
- **Export multi-formats** : Support ODS, CSV, XLS avec configuration centralisée
|
|
- **Anonymisation RGPD** : 3 niveaux de protection des données personnelles
|
|
- **Export des propositions** : Export séparé des propositions par campagne
|
|
- **Tests étendus** : Couverture complète des fonctionnalités email et export
|
|
- **Gestion d'erreurs améliorée** : Messages d'erreur détaillés pour SMTP
|
|
- **HTML responsive** : Emails avec design moderne et boutons d'action
|