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

Créez un fichier .env à la racine du projet.
Copiez le contenu du fichier .env.example dans le fichier .env.
Renseignez les variables suivantes :

Variable	Description
`BACKEND_GIT_REPO`	URL HTTPS du dépôt backend sans le préfixe `https://` (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 Permissions requises : - `read_repository` (obligatoire) - `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_PASSWORDet 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 :

Ouvrez un terminal.
Placez-vous à la racine du projet.
Exécutez les commandes suivantes dans l'ordre :

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.

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

9. Tests unitaires

Nous avons mis en place quelques tests unitaires sur certaines fonctions utilitaires, par exemple :

utils/auth/login.test.js
utils/auth/logout.test.js

Suite à un échange avec notre professeur, il nous a été indiqué qu’un nombre limité de tests suffisait pour démontrer notre compréhension et notre mise en pratique de ce concept. En effet, tester l’ensemble du projet aurait demandé un temps de développement trop important au regard des contraintes du projet.

Nous avons donc choisi de nous concentrer sur quelques cas représentatifs, afin de valider notre approche des tests unitaires tout en respectant les délais impartis.

10. Intégration continu

Dans notre projet, l’intégration continue repose sur les outils et pratiques utilisés tout au long du développement.

Nous avons appliqué les principes de l’intégration continue de la manière suivante :

Utilisation de Git pour gérer les versions du projet et intégrer régulièrement les modifications de chaque membre de l’équipe
Utilisation de Docker pour garantir un environnement de développement et de déploiement identique et reproductible
Tests réguliers des fonctionnalités à chaque ajout de code (tests manuels et tests API avec Bruno)
Validation continue du projet, afin de s’assurer qu’une version fonctionnelle reste disponible à tout moment

README.md Unescape Escape

Gestion des bénévoles - Comité des fêtes de Beaupont

Présentation du projet