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

![Page d'accueil - Mes Budgets Participatifs](docs/home-mes-budgets-participatifs.jpeg)

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