457 lines
16 KiB
Markdown
457 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
|
|
- **Transparence totale** 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**
|
|
- **Configuration SMTP** : Interface d'administration pour configurer les paramètres email
|
|
- **Envoi d'emails** : Notifications aux participants
|
|
- **Test d'envoi** : Fonctionnalité de test des paramètres SMTP
|
|
- **Templates personnalisables** : Messages d'email configurables
|
|
|
|
#### 🎨 **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
|
|
|
|
## 🛠️ Installation
|
|
|
|
### Prérequis
|
|
- Node.js 18+
|
|
- npm ou yarn
|
|
- Compte Supabase
|
|
|
|
### 1. Cloner le projet
|
|
```bash
|
|
git clone <votre-repo>
|
|
cd mes-budgets-participatifs
|
|
```
|
|
|
|
### 2. Installer les dépendances
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 3. Configuration Supabase
|
|
|
|
#### Créer un projet Supabase
|
|
1. Allez sur [supabase.com](https://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 :
|
|
|
|
```env
|
|
# 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
|
|
|
|
# Configuration email (optionnelle)
|
|
SMTP_HOST=smtp.votre-provider.com
|
|
SMTP_PORT=587
|
|
SMTP_USER=votre_email@domaine.com
|
|
SMTP_PASS=votre_mot_de_passe
|
|
SMTP_FROM=votre_email@domaine.com
|
|
```
|
|
|
|
**⚠️ 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 :
|
|
```sql
|
|
INSERT INTO admin_users (user_id, role)
|
|
VALUES ('votre_user_id', 'admin');
|
|
```
|
|
3. **Connectez-vous** avec les identifiants créés
|
|
|
|
### 5. Lancer l'application
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
L'application sera accessible sur `http://localhost:3000`
|
|
|
|
### 6. 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 `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](https://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](https://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](https://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](https://alwaysdata.com)
|
|
|
|
#### 🌍 **Solutions libres et éthiques internationales**
|
|
|
|
##### 5. **Railway** (États-Unis)
|
|
- **Avantages** : Déploiement simple, base de données incluse, éthique
|
|
- **Déploiement** : Connectez votre repo Git
|
|
- **Prix** : Gratuit pour les projets open source, puis 5$/mois
|
|
- **Site** : [railway.app](https://railway.app)
|
|
|
|
##### 6. **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](https://render.com)
|
|
|
|
##### 7. **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](https://digitalocean.com)
|
|
|
|
### Configuration du déploiement
|
|
|
|
#### Variables d'environnement de production
|
|
```env
|
|
# 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
|
|
|
|
# Configuration email (optionnelle)
|
|
SMTP_HOST=smtp.votre-provider.com
|
|
SMTP_PORT=587
|
|
SMTP_USER=votre_email@domaine.com
|
|
SMTP_PASS=votre_mot_de_passe
|
|
SMTP_FROM=votre_email@domaine.com
|
|
```
|
|
|
|
#### Commandes de build
|
|
```bash
|
|
# Installation des dépendances
|
|
npm install
|
|
|
|
# Build de production
|
|
npm run build
|
|
|
|
# Démarrage en production
|
|
npm start
|
|
```
|
|
|
|
### Solutions alternatives
|
|
|
|
#### Vercel (États-Unis)
|
|
- **Avantages** : Optimisé pour Next.js, déploiement automatique
|
|
- **Inconvénients** : Hébergement aux États-Unis, moins éthique
|
|
- **Prix** : Gratuit pour les projets personnels
|
|
- **Site** : [vercel.com](https://vercel.com)
|
|
|
|
#### Netlify (États-Unis)
|
|
- **Avantages** : Interface simple, déploiement automatique
|
|
- **Inconvénients** : Hébergement aux États-Unis
|
|
- **Prix** : Gratuit pour les projets personnels
|
|
- **Site** : [netlify.com](https://netlify.com)
|
|
|
|
## 🔒 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
|
|
- **Tests d'intégration** : Services et API
|
|
- **Tests E2E** : Flux complets (Playwright)
|
|
|
|
## 📚 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
|
|
- **[Paramètres](docs/SETTINGS.md)** - Configuration avancée
|
|
- **[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
|
|
|
|
## 🤝 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 et toutes les fonctionnalités de gestion de budgets participatifs.*
|