From 450e5463b5bf5845d8403d51bebad004e66999b8 Mon Sep 17 00:00:00 2001 From: Giovanni-Josserand Date: Wed, 1 Apr 2026 11:04:53 +0200 Subject: [PATCH] add prerequisites part and feedbacks from our teacher --- README.md | 55 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 46fecc8..163216d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ 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. +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 @@ -16,6 +16,20 @@ L’application a pour objectifs principaux de : - 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. +## Prérequis + +Comme notre architecture se base sur l'utilisation de Docker, les seules prérequis pour la machine sur laquelle vous souhaitez installer cette application sont : +- [Docker](https://www.docker.com/) +- [Git](https://git-scm.com/) + +## Installation + +Pour installer ce projet il vous suffit de cloner le dépôt avec la commande suivante : + +```bash +git clone +``` + ## Initialisation du projet ### 1. Configuration du fichier `.env` principal @@ -25,7 +39,7 @@ L’application a pour objectifs principaux de : 3. 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`) | @@ -53,13 +67,13 @@ De plus, un utilisateur administrateur est automatiquement créé avec les infor - **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`` +> 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 +## Lancement Une fois la configuration terminée : @@ -69,22 +83,21 @@ Une fois la configuration terminée : ```bash docker compose down -v -``` - -> Arrête et supprime les conteneurs existants ainsi que les volumes associés. +``` +> 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 -``` +```bash +docker compose up --build -d +``` +> Reconstruit les images Docker et démarre l’ensemble des services en arrière-plan. -> 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. +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 : @@ -93,7 +106,7 @@ Côté backend (Laravel), nous respectons les conventions PHP : Les noms sont choisis de manière explicite et descriptive afin de faciliter la compréhension du code et sa maintenance. -### 2. Les commentaires +### 2. Les commentaires Nous avons fait le choix de limiter l’utilisation des commentaires dans le code. En effet, nous privilégions un code clair, lisible et auto-documenté, notamment grâce à : - un nommage explicite des variables, fonctions et classes @@ -134,7 +147,8 @@ La gestion des erreurs est assurée à plusieurs niveaux : 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 +- Logs côté docker et backend pour analyser le comportement du serveur + - Par exemple un membre de notre groupe rencontré quelques problèmes lors du lancement des conteneurs docker. Il a donc accédé aux logs du conteneur en question, qui indiquait un problème de clonage du repo git : `unable to access to {url du depot git}` (cela peut être du a un `Personal Access Token` expiré, ou une mauvaise connexion internet) - Tests manuels réguliers lors du développement ### 7. L'architecture @@ -144,7 +158,7 @@ Nous avons choisi d’adopter une architecture basée sur trois dépôts Git dis - **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. +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) @@ -154,6 +168,9 @@ Notre environnement de déploiement repose sur plusieurs conteneurs Docker : - **Backup** : conteneur dédié à la sauvegarde de la base de données - **Serveur WebSocket (Laravel Reverb)** : gestion des communications en temps réel +> Un schéma du fonctionnement global de l'application est disponible dans le dossier final de rendus. + + ### 8. Concepts de programmation Nous avons appliqué plusieurs concepts de programmation : @@ -163,12 +180,12 @@ Nous avons appliqué plusieurs concepts de programmation : - API REST pour la communication entre frontend et backend - Programmation modulaire pour une meilleure organisation du code -Pour améliorer la qualité et la robustesse du code, nous avons migré une partie du projet de JavaScript vers TypeScript. +Pour améliorer la qualité et la robustesse du code, nous avons migré une partie du projet de JavaScript vers TypeScript. Cette conversion permet : - Moins d’erreurs grâce au typage statique. - Un code plus lisible et documenté avec des interfaces claires. -- Une meilleure collaboration grâce à des types explicites. -Les interfaces TypeScript sont regroupées dans des fichiers dédiés, ce qui centralise les définitions et simplifie les mises à jour. +- Une meilleure collaboration grâce à des types explicites. + Les interfaces TypeScript sont regroupées dans des fichiers dédiés, ce qui centralise les définitions et simplifie les mises à jour. ### 9. Tests unitaires @@ -185,7 +202,7 @@ Nous avons donc choisi de nous concentrer sur quelques cas représentatifs, afin 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 : +Nous avons mis en place tous les outils qui permettent à termes l'intégration continu de l'application : - 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)