From 3ce31244576218d7481399aaca208c2455d3eb4a Mon Sep 17 00:00:00 2001 From: Yannick Le Duc Date: Wed, 27 Aug 2025 13:50:05 +0200 Subject: [PATCH] =?UTF-8?q?update=20README=20(mettant=20aussi=20en=20avant?= =?UTF-8?q?=20les=20solutions=20de=20d=C3=A9ploiement=20solutions=20=C3=A9?= =?UTF-8?q?thiques/libres,=20en=20particulier=20celles=20h=C3=A9berg=C3=A9?= =?UTF-8?q?es=20en=20France)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 303 +++++++++++++++++++++++------------------ REFACTORING_SUMMARY.md | 158 --------------------- 2 files changed, 173 insertions(+), 288 deletions(-) delete mode 100644 REFACTORING_SUMMARY.md diff --git a/README.md b/README.md index 6a9f136..77aa6c2 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,18 @@ # Mes Budgets Participatifs -Une application web moderne pour gérer des campagnes de budgets participatifs, permettant aux collectifs de décider collectivement de leurs dépenses budgétaires. +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 +- **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 @@ -12,7 +21,8 @@ Une application web moderne pour gérer des campagnes de budgets participatifs, - **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 -- **Déploiement**: Compatible Vercel, Netlify, etc. +- **Tests**: Jest + React Testing Library + Playwright +- **Déploiement**: Compatible avec les solutions éthiques et libres ## 📋 Fonctionnalités @@ -114,7 +124,7 @@ npm install #### Créer un projet Supabase 1. Allez sur [supabase.com](https://supabase.com) 2. Créez un nouveau projet -3. Notez votre URL et votre clé anon +3. Notez votre URL et vos clés #### Configurer la base de données 1. Dans votre projet Supabase, allez dans l'éditeur SQL @@ -131,14 +141,28 @@ npm install 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 +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 @@ -148,6 +172,18 @@ 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` @@ -176,6 +212,7 @@ L'application sera accessible sur `http://localhost:3000` - `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` @@ -192,146 +229,103 @@ L'application sera accessible sur `http://localhost:3000` - `category`: Catégorie (email, general, etc.) - `description`: Description de la configuration -## 📚 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 - -- **[Sécurité](docs/SECURITY-SUMMARY.md)** - Résumé de la sécurisation -- **[Paramètres](docs/SETTINGS.md)** - Configuration avancée - -## 🎨 Interface utilisateur - -### Page d'accueil -- **Design moderne** : Hero section avec gradient et call-to-action -- **Présentation claire** : Fonctionnalités principales expliquées -- **Navigation intuitive** : Accès à l'administration sécurisée - -### Espace d'administration (protégé) -- **Dashboard complet** : Vue d'ensemble avec statistiques -- **Gestion des campagnes** : CRUD complet avec interface moderne -- **Navigation fluide** : Liens vers les pages de gestion détaillées -- **Recherche** : Filtrage en temps réel des campagnes -- **Paramètres** : Configuration SMTP et autres paramètres - -### Pages de gestion détaillées -- **Propositions** : Interface complète avec avatars et informations détaillées -- **Participants** : Gestion avec statuts de vote et liens personnels -- **Statistiques** : Métriques en temps réel (participation, budget voté) - -### Pages publiques -- **Dépôt de propositions** : Interface épurée et accessible -- **Vote** : Interface intuitive avec slider et validation - -## 🔧 Architecture technique - -### Structure des fichiers -``` -src/ -├── app/ # Pages Next.js (App Router) -│ ├── page.tsx # Page d'accueil -│ ├── admin/ # Pages d'administration (protégées) -│ │ ├── page.tsx # Dashboard principal -│ │ ├── settings/ # Paramètres SMTP -│ │ └── campaigns/[id]/ # Pages de gestion par campagne -│ ├── api/ # API Routes -│ │ ├── send-participant-email/ -│ │ ├── test-email/ -│ │ └── test-smtp/ -│ └── campaigns/[id]/ # Pages publiques -│ ├── propose/ # Dépôt de propositions -│ └── vote/[participantId] # Vote public -├── components/ # Composants React -│ ├── ui/ # Composants Shadcn/ui -│ ├── AuthGuard.tsx # Protection des routes -│ ├── Navigation.tsx # Navigation principale -│ ├── SmtpSettingsForm.tsx # Configuration SMTP -│ └── [Modals] # Modales de gestion -├── lib/ # Services et configuration -│ ├── supabase.ts # Configuration Supabase -│ ├── services.ts # Services de données -│ ├── email.ts # Service d'envoi d'emails -│ ├── encryption.ts # Chiffrement des données sensibles -│ └── utils.ts # Utilitaires -└── types/ # Types TypeScript - └── index.ts # Définitions des types -``` - -### Services de données -- **campaignService** : Gestion des campagnes et statistiques -- **propositionService** : CRUD des propositions -- **participantService** : CRUD des participants -- **voteService** : Gestion des votes et statuts -- **settingsService** : Gestion des paramètres de configuration - -### Authentification -- **AuthGuard** : Composant de protection des routes -- **Supabase Auth** : Authentification sécurisée -- **Session management** : Gestion des sessions utilisateur - -### Système d'email -- **Configuration SMTP** : Interface d'administration -- **Envoi d'emails** : Service Nodemailer -- **Chiffrement** : Protection des mots de passe SMTP -- **Templates** : Messages personnalisables +### 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 -### Vercel (recommandé) +### Solutions éthiques et libres (recommandées) -#### Configuration automatique -1. Connectez votre repo Git à Vercel -2. Configurez les variables d'environnement dans Vercel -3. Déployez automatiquement +#### 🇫🇷 **Hébergement en France - Solutions éthiques** -#### Configuration manuelle -Le projet est configuré pour un déploiement sans problème sur Vercel : +##### 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) -1. **Configuration ESLint** : Les erreurs ESLint sont traitées comme des avertissements et n'empêchent pas le déploiement -2. **Variables d'environnement** : Assurez-vous d'avoir configuré : - ```env - NEXT_PUBLIC_SUPABASE_URL=votre_url_supabase_production - NEXT_PUBLIC_SUPABASE_ANON_KEY=votre_cle_anon_supabase_production - ``` +##### 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) -#### Correction des erreurs avant déploiement (optionnel) -```bash -# Corriger les erreurs ESLint automatiquement -npm run lint:fix +##### 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) -# Vérifier les erreurs restantes -npm run lint +##### 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) -# Tester le build localement -npm run build -``` +#### 🌍 **Solutions libres et éthiques internationales** -#### Résolution des problèmes courants +##### 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) -**Erreurs ESLint lors du déploiement** : -- Les erreurs sont automatiquement traitées comme des avertissements -- Le build continuera même avec des avertissements ESLint -- Utilisez `npm run lint:fix` pour corriger automatiquement les erreurs corrigibles +##### 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) -**Erreurs de build** : -- Vérifiez que toutes les variables d'environnement sont configurées -- Assurez-vous que la base de données Supabase est accessible -- Consultez les logs de build dans Vercel pour plus de détails +##### 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) -### Variables d'environnement de production +### 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 ``` -### Autres plateformes -L'application peut être déployée sur n'importe quelle plateforme supportant Next.js : -- Netlify -- Railway -- DigitalOcean App Platform -- AWS Amplify +#### 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é @@ -350,6 +344,11 @@ L'application peut être déployée sur n'importe quelle plateforme supportant N - **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 @@ -382,10 +381,39 @@ L'application peut être déployée sur n'importe quelle plateforme supportant N 2. Analyser les résultats 3. Clôturer la campagne -## 📚 Documentation supplémentaire +## 🧪 Tests -- **SETUP.md** : Guide de configuration détaillé -- **SETTINGS.md** : Documentation des paramètres et configurations +### 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 @@ -395,6 +423,11 @@ L'application peut être déployée sur n'importe quelle plateforme supportant N 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. @@ -402,10 +435,20 @@ 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 Supabase +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** diff --git a/REFACTORING_SUMMARY.md b/REFACTORING_SUMMARY.md deleted file mode 100644 index d4eb784..0000000 --- a/REFACTORING_SUMMARY.md +++ /dev/null @@ -1,158 +0,0 @@ -# 🔄 Résumé du Refactoring - Élimination des Duplications - -## 📊 **Bilan des améliorations** - -### ✅ **Code mort supprimé** -- **Supprimé** : `ImportCSVModal.tsx` (100% identique à `ImportFileModal.tsx`) -- **Économie** : ~323 lignes de code dupliqué - -### ✅ **Composants de base créés** -- **`BaseModal.tsx`** : Composant modal de base réutilisable -- **`FormModal.tsx`** : Composant pour formulaires modaux -- **`DeleteModal.tsx`** : Composant générique pour suppressions -- **`ErrorDisplay.tsx`** : Composant d'affichage d'erreurs - -### ✅ **Hooks personnalisés créés** -- **`useFormState.ts`** : Hook pour gestion d'état des formulaires -- **Économie** : ~15 patterns répétitifs d'état de formulaire - -### ✅ **Utilitaires centralisés créés** -- **`form-utils.ts`** : Gestion d'erreurs et validation de formulaires -- **`file-utils.ts`** : Parsing CSV/Excel centralisé -- **`smtp-utils.ts`** : Validation et configuration SMTP - -### ✅ **Composants génériques créés** -- **`PropositionFormModal.tsx`** : Fusion Add/Edit propositions -- **`CampaignFormModal.tsx`** : Fusion Create/Edit campagnes - ---- - -## 📈 **Impact quantifié** - -### **Réduction de code** -- **Avant** : 20+ composants modaux (~2000 lignes) -- **Après** : 6 composants de base + wrappers (~800 lignes) -- **Économie** : ~60% de réduction du code modal - -### **Composants refactorisés** -| Composant Original | Nouveau Composant | Lignes économisées | -|-------------------|------------------|-------------------| -| `AddPropositionModal` | `PropositionFormModal` | ~150 | -| `EditPropositionModal` | `PropositionFormModal` | ~150 | -| `AddParticipantModal` | `FormModal` + `useFormState` | ~100 | -| `EditParticipantModal` | `FormModal` + `useFormState` | ~100 | -| `CreateCampaignModal` | `CampaignFormModal` | ~200 | -| `EditCampaignModal` | `CampaignFormModal` | ~200 | -| `DeleteCampaignModal` | `DeleteModal` | ~80 | -| `DeleteParticipantModal` | `DeleteModal` | ~80 | -| `DeletePropositionModal` | `DeleteModal` | ~80 | -| `ImportFileModal` | `BaseModal` + utilitaires | ~100 | - -**Total économisé** : ~1240 lignes de code - ---- - -## 🎯 **Améliorations de maintenabilité** - -### **Patterns uniformes** -- ✅ Gestion d'erreurs standardisée -- ✅ États de formulaire centralisés -- ✅ Validation SMTP unifiée -- ✅ Parsing de fichiers centralisé - -### **Réutilisabilité** -- ✅ Composants modaux réutilisables -- ✅ Hooks personnalisés -- ✅ Utilitaires centralisés -- ✅ Patterns cohérents - -### **Cohérence** -- ✅ Interface utilisateur uniforme -- ✅ Gestion d'erreurs cohérente -- ✅ Messages d'erreur standardisés -- ✅ Comportements prévisibles - ---- - -## 🔧 **Nouveaux composants créés** - -### **Composants de base** (`src/components/base/`) -``` -├── BaseModal.tsx # Modal de base réutilisable -├── FormModal.tsx # Modal pour formulaires -├── DeleteModal.tsx # Modal de suppression générique -└── ErrorDisplay.tsx # Affichage d'erreurs -``` - -### **Composants génériques** (`src/components/base/`) -``` -├── PropositionFormModal.tsx # Add/Edit propositions -└── CampaignFormModal.tsx # Create/Edit campagnes -``` - -### **Hooks personnalisés** (`src/hooks/`) -``` -└── useFormState.ts # Gestion d'état des formulaires -``` - -### **Utilitaires** (`src/lib/`) -``` -├── form-utils.ts # Utilitaires de formulaires -├── file-utils.ts # Utilitaires de fichiers -└── smtp-utils.ts # Utilitaires SMTP -``` - ---- - -## 🚀 **Avantages obtenus** - -### **Pour les développeurs** -- ✅ Code plus facile à maintenir -- ✅ Patterns réutilisables -- ✅ Moins de duplication -- ✅ Tests plus faciles à écrire - -### **Pour l'application** -- ✅ Interface utilisateur cohérente -- ✅ Gestion d'erreurs uniforme -- ✅ Performance améliorée -- ✅ Taille du bundle réduite - -### **Pour l'équipe** -- ✅ Onboarding plus facile -- ✅ Code reviews simplifiées -- ✅ Bugs moins fréquents -- ✅ Développement plus rapide - ---- - -## 📝 **Migration effectuée** - -### **Composants remplacés** -- ✅ `AddPropositionModal` → Wrapper vers `PropositionFormModal` -- ✅ `EditPropositionModal` → Wrapper vers `PropositionFormModal` -- ✅ `AddParticipantModal` → Utilise `FormModal` + `useFormState` -- ✅ `EditParticipantModal` → Utilise `FormModal` + `useFormState` -- ✅ `CreateCampaignModal` → Wrapper vers `CampaignFormModal` -- ✅ `EditCampaignModal` → Wrapper vers `CampaignFormModal` -- ✅ `DeleteCampaignModal` → Utilise `DeleteModal` -- ✅ `DeleteParticipantModal` → Utilise `DeleteModal` -- ✅ `DeletePropositionModal` → Utilise `DeleteModal` -- ✅ `ImportFileModal` → Utilise `BaseModal` + utilitaires - -### **API routes refactorisées** -- ✅ `/api/test-smtp` → Utilise `smtp-utils.ts` -- ✅ `/api/test-email` → Utilise `smtp-utils.ts` - ---- - -## 🎉 **Résultat final** - -Le refactoring a permis de : -- **Éliminer** ~1240 lignes de code dupliqué -- **Créer** 6 composants de base réutilisables -- **Standardiser** la gestion d'erreurs et des formulaires -- **Améliorer** la maintenabilité et la cohérence du code -- **Faciliter** les développements futurs - -Le code est maintenant plus propre, plus maintenable et plus cohérent ! 🚀