157 lines
11 KiB
Markdown
157 lines
11 KiB
Markdown
# Gestion des bénévoles - Comité des fêtes de Beaupont
|
||
|
||
## Présentation du projet
|
||
|
||
L'association organise régulièrement des événements et projets mobilisant des bénévoles, mais sa coordination interne est rendue difficile par l'usage d'outils dispersés, et non communicants.
|
||
|
||
La création d'une plateforme web unique vise donc à centraliser et simplifier la gestion des utilisateurs, des rôles, des événements, des tâches et de la communication. Elle vise à améliorer la collaboration entre tous les bénévoles de l'association.
|
||
|
||
## Objectifs de l’application
|
||
|
||
L’application a pour objectifs principaux de :
|
||
|
||
- Gérer les utilisateurs et leurs rôles au sein de l’association.
|
||
- Organiser et planifier les événements et les tâches associées.
|
||
- Permettre aux bénévoles de s’inscrire en ligne aux événements et aux tâches.
|
||
- Offrir aux responsables un tableau de bord pour suivre la participation et les besoins en ressources humaines.
|
||
- Centraliser les informations et la communication autour des projets associatifs.
|
||
|
||
## Initialisation du projet
|
||
|
||
### 1. Configuration du fichier `.env` principal
|
||
|
||
1. Créez un fichier `.env` à la racine du projet.
|
||
2. Copiez le contenu du fichier `.env.example` dans le fichier `.env`.
|
||
3. Renseignez les variables suivantes :
|
||
|
||
| Variable | Description |
|
||
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `BACKEND_GIT_REPO` | URL HTTPS du dépôt backend sans le préfixe `https://` <br>(ex : `gitlab.com/user/repo-backend.git`) |
|
||
| `FRONTEND_GIT_REPO` | URL HTTPS du dépôt frontend sans le préfixe `https://` |
|
||
| `BACKEND_GIT_BRANCH` | Branche de votre dépôt backend à utiliser (ex : `main`, `dev`) |
|
||
| `FRONTEND_GIT_BRANCH` | Branche de votre dépôt frontend à utiliser |
|
||
| `GIT_TOKEN` | Token GitLab à générer depuis *Préférences → User settings → Personal access tokens* <br>Permissions requises :<br>- `read_repository` (obligatoire)<br>- `write_repository` (optionnel, uniquement en développement) |
|
||
| `DB_CONNECTION` | Type de base de données utilisée (ex : `mysql`, `mariadb`) |
|
||
| `DB_HOST` | Adresse du serveur de base de données (ex : `localhost`, `db`) |
|
||
| `DB_PORT` | Port de la base de données (ex : `3306` pour MySQL/MariaDB) |
|
||
| `DB_DATABASE` | Nom de la base de données |
|
||
| `DB_USERNAME` | Nom d’utilisateur de la base de données |
|
||
| `DB_PASSWORD` | Mot de passe de l’utilisateur de la base de données |
|
||
| `DB_ROOT_PASSWORD` | Mot de passe du compte root de la base de données |
|
||
| `FORCE_CLONE` | Mettre à `true` pour forcer le clonage du dépôt backend même si la branche configurée diffère de la branche actuelle. |
|
||
| `DEV` | Mettre `1` en environnement de développement, laisser vide sinon. |
|
||
| `VITE_API_URL` | URL du frontend hébergé et exposé par le conteneur Nginx (par défaut sur le port 80) |
|
||
|
||
### 2. Configuration du fichier `.env` php
|
||
|
||
Répétez la même opération pour le fichier `docker/php/.env` en copiant depuis `docker/php/.env.example`.
|
||
|
||
De plus, un utilisateur administrateur est automatiquement créé avec les informations suivantes :
|
||
- **Prénom :** `admin`
|
||
- **Nom :** `admin`
|
||
- **Adresse e-mail :** `admin@mail.com`
|
||
- **Mot de passe :** `admin`
|
||
- **Numéro de téléphone :** `0909090909`
|
||
|
||
> Il est bien sûr possible de modifier ces valeurs dans le fichier ``docker/php/.env`` avant le premier lancement du seeder, en utilisant les variables : ``ADMIN_NAME``, ``ADMIN_LASTNAME``, ``ADMIN_MAIL``, ``ADMIN_PASSWORD``et ``ADMIN_PHONE_NUMBER``
|
||
|
||
### 3. Note importante
|
||
|
||
> ⚠️ Si vous êtes sous **Windows**, assurez-vous que tous les fichiers `.sh` utilisent des fins de ligne **LF** et non **CRLF**, sous peine d’erreurs lors de l’exécution des scripts.
|
||
|
||
## Installation et lancement
|
||
|
||
Une fois la configuration terminée :
|
||
|
||
1. Ouvrez un terminal.
|
||
2. Placez-vous à la racine du projet.
|
||
3. Exécutez les commandes suivantes dans l'ordre :
|
||
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
> Arrête et supprime les conteneurs existants ainsi que les volumes associés.
|
||
> Cette étape permet de repartir sur une base propre.
|
||
|
||
```bash
|
||
compose up --build -d
|
||
```
|
||
|
||
> Reconstruit les images Docker et démarre l’ensemble des services en arrière-plan.
|
||
|
||
## Point technique
|
||
|
||
### 1. Le nommage
|
||
|
||
Nous avons adopté une convention de nommage en **camelCase** pour les variables, fonctions et fichiers JavaScript côté frontend.
|
||
Pour les composants React, nous utilisons la convention **PascalCase** afin de les différencier des éléments HTML.
|
||
|
||
Côté backend (Laravel), nous respectons les conventions PHP :
|
||
- **camelCase** pour les variables et méthodes
|
||
- **PascalCase** pour les classes (Controllers, Models, Policies, etc.)
|
||
|
||
Les noms sont choisis de manière explicite et descriptive afin de faciliter la compréhension du code et sa maintenance.
|
||
|
||
### 2. Les commentaires
|
||
|
||
### 3. La documentation
|
||
|
||
La documentation du projet est assurée à plusieurs niveaux :
|
||
- Un **README** structuré expliquant l’installation, la configuration et le fonctionnement global
|
||
- Une documentation des routes API via **Bruno**
|
||
- L’utilisation de **Storybook** pour documenter et tester visuellement les composants UI
|
||
|
||
### 4. La programmation défensive
|
||
|
||
Nous avons appliqué la programmation défensive afin de rendre notre application plus robuste, sécurisée et fiable face aux erreurs potentielles.
|
||
|
||
Dans notre projet, cela se traduit notamment par :
|
||
- Validation des données côté backend (Laravel) avant utilisation
|
||
- Vérification des entrées utilisateur afin d’éviter les données incohérentes ou malveillantes
|
||
- Gestion des rôles et permissions pour empêcher l’accès à des ressources non autorisées (utilisation de policies Laravel)
|
||
- Gestion des cas d’erreur (ex : utilisateur inexistant, tâche non trouvée, accès interdit) avec des réponses HTTP adaptées
|
||
- Utiliser des valeurs par défaut ou des vérifications avant utilisation pour éviter les erreurs inattendues
|
||
|
||
Enfin, grâce à Docker, nous limitons les problèmes liés à l’environnement (configuration, versions, dépendances), ce qui contribue également à une approche défensive globale du projet.
|
||
|
||
### 5. La gestion des erreurs
|
||
|
||
La gestion des erreurs est assurée à plusieurs niveaux :
|
||
- Backend Laravel : gestion des exceptions et retour de codes HTTP appropriés (200, 401, 404, 422, etc.)
|
||
- Frontend React : gestion des erreurs utilisateur (formulaires, affichage de messages d’erreur)
|
||
|
||
### 6. Le débogage
|
||
|
||
Le débogage a été réalisé grâce à plusieurs outils et méthodes :
|
||
- Utilisation des outils de développement du navigateur (console, réseau)
|
||
- Tests des routes API avec Bruno
|
||
- Logs côté backend pour analyser le comportement du serveur
|
||
- Tests manuels réguliers lors du développement
|
||
|
||
### 7. L'architecture
|
||
|
||
Nous avons choisi d’adopter une architecture basée sur trois dépôts Git distincts, afin de séparer clairement les responsabilités et de faciliter la maintenance du projet :
|
||
- **Dépôt frontend** : contient le code de l’application développée en React
|
||
- **Dépôt backend** : contient le code de l’API développée avec Laravel
|
||
- **Dépôt Docker** : contient toute la configuration nécessaire à l’installation et au déploiement du projet sur n’importe quelle machine
|
||
|
||
Ce troisième dépôt permet de déployer l’ensemble de l’application de manière reproductible grâce à Docker, en centralisant la configuration des services.
|
||
Notre environnement de déploiement repose sur plusieurs conteneurs Docker :
|
||
- **Backend (Laravel)** : gestion de la logique métier et de l’API
|
||
- **Frontend (React)** : interface utilisateur (version temporaire pour le déploiement)
|
||
- **Base de données (MariaDB)** : stockage des données
|
||
- **Nginx** : serveur web utilisé pour exposer les services et gérer les requêtes HTTP
|
||
- **Typesense** : moteur de recherche utilisé pour améliorer les performances des recherches
|
||
- **Backup** : conteneur dédié à la sauvegarde de la base de données
|
||
- **Serveur WebSocket (Laravel Reverb)** : gestion des communications en temps réel
|
||
|
||
### 8. Concepts de programmation
|
||
|
||
Nous avons appliqué plusieurs concepts de programmation :
|
||
- Programmation orientée objet (POO) côté backend (Laravel)
|
||
- Composants réutilisables côté frontend (React)
|
||
- Gestion d’état via les Contexts React
|
||
- API REST pour la communication entre frontend et backend
|
||
- Programmation modulaire pour une meilleure organisation du code
|