From b7354b8448be7d1ac673a2575b30a1ff1bf6eb88 Mon Sep 17 00:00:00 2001 From: Mathias STRASSER Date: Sun, 1 Feb 2026 14:57:08 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20Makefile=20autodocument=C3=A9=20et=20RE?= =?UTF-8?q?ADME=20simplifi=C3=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit L'installation du projet nécessitait plusieurs commandes manuelles et le Makefile listait les commandes dans un bloc help statique, difficile à maintenir et susceptible de devenir obsolète. Le Makefile utilise maintenant le pattern "## description" qui génère automatiquement l'aide à partir des commentaires inline. Le README est simplifié avec un `make install` unique qui orchestre tout le setup. --- Makefile | 187 ++++++++++++++++++++++++++---------------------------- README.md | 117 +++++++++++++++++++++------------- 2 files changed, 163 insertions(+), 141 deletions(-) diff --git a/Makefile b/Makefile index 41cc1bf..e076360 100644 --- a/Makefile +++ b/Makefile @@ -1,176 +1,158 @@ -.PHONY: help up down restart rebuild logs ps test lint phpstan arch cs-fix warmup frontend-lint frontend-test e2e clean shell bash console token token-alpha token-beta - -# Default target -help: - @echo "Classeo - Commandes disponibles" - @echo "" - @echo "Docker:" - @echo " make up - Lancer tous les services" - @echo " make down - Arreter tous les services" - @echo " make restart - Redemarrer tous les services" - @echo " make rebuild - Reconstruire et relancer les services" - @echo " make build - Reconstruire les images" - @echo " make logs - Voir les logs (Ctrl+C pour quitter)" - @echo " make ps - Statut des services" - @echo " make clean - Supprimer volumes et images" - @echo "" - @echo "Shell:" - @echo " make shell - Shell bash dans le container PHP" - @echo " make bash - Alias pour make shell" - @echo " make console - Console Symfony (ex: make console c='debug:router')" - @echo " make shell-frontend - Shell dans le container frontend" - @echo "" - @echo "Backend:" - @echo " make phpstan - Analyse statique PHPStan" - @echo " make arch - Tests d'architecture (PHPat)" - @echo " make cs-fix - Correction code style PHP" - @echo " make test-php - Tests PHPUnit" - @echo " make warmup - Warmup du cache Symfony" - @echo "" - @echo "Frontend:" - @echo " make lint - ESLint frontend" - @echo " make test-js - Tests Vitest" - @echo " make e2e - Tests Playwright" - @echo "" - @echo "All:" - @echo " make test - Tous les tests" - @echo " make check - Tous les linters" - @echo "" - @echo "Setup:" - @echo " make jwt-keys - Generer les cles JWT (requis apres clone)" - @echo "" - @echo "Dev:" - @echo " make token - Creer un token d'activation (interactif)" - @echo " make token-alpha - Token sur ecole-alpha (+ email=, role=, minor=1)" - @echo " make token-beta - Token sur ecole-beta (+ email=, role=, minor=1)" +.DEFAULT_GOAL := help # ============================================================================= # Docker # ============================================================================= -up: +.PHONY: up +up: ## Lancer tous les services docker compose up -d -down: +.PHONY: down +down: ## Arrêter tous les services docker compose down -restart: +.PHONY: restart +restart: ## Redémarrer tous les services docker compose down docker compose up -d -rebuild: +.PHONY: rebuild +rebuild: ## Reconstruire et relancer les services (sans cache) docker compose down docker compose build --no-cache docker compose up -d -build: +.PHONY: build +build: ## Reconstruire les images Docker (sans cache) docker compose build --no-cache -logs: +.PHONY: logs +logs: ## Voir les logs de tous les services (Ctrl+C pour quitter) docker compose logs -f -ps: +.PHONY: ps +ps: ## Afficher le statut des services docker compose ps -clean: +.PHONY: clean +clean: ## Supprimer volumes et images locales docker compose down -v --rmi local # ============================================================================= # Shell # ============================================================================= -shell: +.PHONY: shell +shell: ## Ouvrir un shell dans le container PHP docker compose exec php sh -bash: shell +.PHONY: bash +bash: shell ## Alias pour 'make shell' -console: +.PHONY: console +console: ## Exécuter une commande Symfony (ex: make console c='debug:router') docker compose exec php php bin/console $(c) -shell-frontend: +.PHONY: shell-frontend +shell-frontend: ## Ouvrir un shell dans le container frontend docker compose exec frontend sh # ============================================================================= -# Backend +# Backend - Qualité # ============================================================================= -phpstan: +.PHONY: phpstan +phpstan: ## Analyse statique PHPStan (level 9) docker compose exec php composer phpstan -arch: +.PHONY: arch +arch: ## Tests d'architecture PHPat docker compose exec php composer arch -cs-fix: +.PHONY: cs-fix +cs-fix: ## Corriger le code style PHP (PHP-CS-Fixer) docker compose exec php composer cs-fix -cs-check: +.PHONY: cs-check +cs-check: ## Vérifier le code style PHP sans corriger docker compose exec php composer cs-check -test-php: +.PHONY: test-php +test-php: ## Lancer les tests PHPUnit docker compose exec php composer test -warmup: +.PHONY: warmup +warmup: ## Préchauffer le cache Symfony docker compose exec php php bin/console cache:warmup # ============================================================================= -# Frontend +# Frontend - Qualité # ============================================================================= -lint: +.PHONY: lint +lint: ## Lancer ESLint sur le frontend docker compose exec frontend pnpm run lint -check-types: +.PHONY: check-types +check-types: ## Vérifier les types TypeScript (svelte-check) docker compose exec frontend pnpm run check -test-js: +.PHONY: test-js +test-js: ## Lancer les tests Vitest docker compose exec frontend pnpm run test -e2e: +.PHONY: e2e +e2e: ## Lancer les tests E2E Playwright docker compose exec frontend pnpm run test:e2e # ============================================================================= -# All +# Tout-en-un # ============================================================================= -test: test-php test-js +.PHONY: test +test: test-php test-js ## Lancer tous les tests (PHPUnit + Vitest) -check: phpstan cs-check lint check-types +.PHONY: check +check: phpstan cs-check lint check-types ## Lancer tous les linters et checks # ============================================================================= # Scripts # ============================================================================= -check-bc: +.PHONY: check-bc +check-bc: ## Vérifier l'isolation des Bounded Contexts ./scripts/check-bc-isolation.sh -check-naming: +.PHONY: check-naming +check-naming: ## Vérifier les conventions de nommage ./scripts/check-naming.sh -check-tenants: +.PHONY: check-tenants +check-tenants: ## Vérifier que les tenants répondent ./scripts/check-tenants.sh +# ============================================================================= +# Setup initial +# ============================================================================= + +.PHONY: install +install: up jwt-keys warmup ## Installation complète après clone + +.PHONY: jwt-keys +jwt-keys: ## Générer les clés JWT (requis après clone) + @echo "Génération des clés JWT..." + @docker compose exec php mkdir -p config/jwt + @docker compose exec php openssl genpkey -out config/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096 -pass pass:$${JWT_PASSPHRASE:-classeo_jwt_passphrase_change_me} + @docker compose exec php openssl pkey -in config/jwt/private.pem -out config/jwt/public.pem -pubout -passin pass:$${JWT_PASSPHRASE:-classeo_jwt_passphrase_change_me} + @echo "Clés JWT générées dans backend/config/jwt/" + # ============================================================================= # Dev helpers # ============================================================================= -# Generer les cles JWT (a faire une seule fois apres clone) -# Les cles sont gitignored pour la securite -jwt-keys: - @echo "Generation des cles JWT..." - @docker compose exec php mkdir -p config/jwt - @docker compose exec php openssl genpkey -out config/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096 -pass pass:$${JWT_PASSPHRASE:-classeo_jwt_passphrase_change_me} - @docker compose exec php openssl pkey -in config/jwt/private.pem -out config/jwt/public.pem -pubout -passin pass:$${JWT_PASSPHRASE:-classeo_jwt_passphrase_change_me} - @echo "Cles JWT generees dans backend/config/jwt/" - -# Creer un token d'activation de test (mode interactif par defaut) -# Usage: -# make token - Mode interactif (pose des questions) -# make token tenant=ecole-beta - Sur le tenant beta -# make token role=PROF - Creer un prof -# make token email=x@y.com role=ADMIN tenant=ecole-beta minor=1 -# -# Options: email, role (PARENT|ELEVE|PROF|ADMIN), tenant (ecole-alpha|ecole-beta), minor -token: +.PHONY: token +token: ## Créer un token d'activation (interactif). Options: email=, role=, tenant=, minor=1 docker compose exec php php bin/console app:dev:create-test-activation-token \ $(if $(email),--email=$(email),) \ $(if $(role),--role=$(role),) \ @@ -178,17 +160,30 @@ token: $(if $(minor),--minor,) \ --base-url=http://localhost:5174 -# Raccourcis pour creer rapidement des tokens sur chaque tenant (non-interactif) -token-alpha: +.PHONY: token-alpha +token-alpha: ## Créer un token sur ecole-alpha. Options: email=, role=, minor=1 docker compose exec -T php php bin/console app:dev:create-test-activation-token -n \ --tenant=ecole-alpha --base-url=http://ecole-alpha.classeo.local:5174 \ $(if $(email),--email=$(email),--email=alpha@test.com) \ $(if $(role),--role=$(role),) \ $(if $(minor),--minor,) -token-beta: +.PHONY: token-beta +token-beta: ## Créer un token sur ecole-beta. Options: email=, role=, minor=1 docker compose exec -T php php bin/console app:dev:create-test-activation-token -n \ --tenant=ecole-beta --base-url=http://ecole-beta.classeo.local:5174 \ $(if $(email),--email=$(email),--email=beta@test.com) \ $(if $(role),--role=$(role),) \ $(if $(minor),--minor,) + +# ============================================================================= +# Help +# ============================================================================= + +.PHONY: help +help: ## Afficher cette aide + @echo "" + @echo " Classeo - Commandes disponibles" + @echo "" + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}' + @echo "" diff --git a/README.md b/README.md index 02a990f..aca8c8a 100644 --- a/README.md +++ b/README.md @@ -4,39 +4,56 @@ Application de gestion scolaire moderne - Backend Symfony 8 + Frontend SvelteKit ## Quick Start -### Prerequis +### Prérequis - Docker Desktop 24+ avec Docker Compose 2.20+ - Git -### Configuration /etc/hosts (multi-tenant) - -Classeo utilise une architecture multi-tenant basée sur les sous-domaines. Ajoutez cette ligne à `/etc/hosts` : +### Installation ```bash -sudo sh -c 'echo "127.0.0.1 classeo.local ecole-alpha.classeo.local ecole-beta.classeo.local" >> /etc/hosts' -``` - -### Lancement - -```bash -# Cloner le repo +# 1. Cloner le repo git clone https://github.com/ClasseoEdu/classeo.git cd classeo -# Lancer tous les services -docker compose up -d +# 2. Configurer /etc/hosts pour le multi-tenant +sudo sh -c 'echo "127.0.0.1 classeo.local ecole-alpha.classeo.local ecole-beta.classeo.local" >> /etc/hosts' -# Verifier le statut -docker compose ps +# 3. Installation complète (démarre les services, génère les clés JWT, warmup cache) +make install -# Verifier que les tenants répondent +# 4. Vérifier que tout fonctionne +make ps make check-tenants ``` +C'est tout ! L'application est prête. + +### Commandes utiles + +```bash +make help # Afficher toutes les commandes disponibles +make logs # Voir les logs des services +make test # Lancer tous les tests +make check # Lancer tous les linters +``` + +### Créer un utilisateur de test + +```bash +# Mode interactif +make token + +# Créer rapidement un parent sur ecole-alpha +make token-alpha + +# Créer un prof sur ecole-beta +make token-beta role=ROLE_PROF email=prof@test.com +``` + ### URLs -#### Multi-tenant (recommandé) +#### Multi-tenant | Service | URL | Description | |---------|-----|-------------| @@ -61,8 +78,8 @@ make check-tenants - **PHP 8.5** avec property hooks et asymmetric visibility - **Symfony 8.0** - Framework DDD-friendly -- **API Platform 4.x** - API REST auto-generee -- **Doctrine ORM 3.x** - Persistence avec mappings separes +- **API Platform 4.x** - API REST auto-générée +- **Doctrine ORM 3.x** - Persistence avec mappings séparés - **PHPStan level 9** - Analyse statique stricte ### Frontend @@ -75,7 +92,7 @@ make check-tenants ### Infrastructure -- **PostgreSQL 18.1** - Base de donnees +- **PostgreSQL 18.1** - Base de données - **Redis 7.4** - Cache + Sessions - **RabbitMQ 4.2** - Message queue - **Mercure** - Real-time SSE @@ -88,20 +105,20 @@ make check-tenants ``` backend/src/ -├── Administration/ # Gestion etablissement, utilisateurs +├── Administration/ # Gestion établissement, utilisateurs ├── Scolarite/ # Notes, classes, emploi du temps ├── VieScolaire/ # Absences, retards, sanctions ├── Communication/ # Messages, notifications -└── Shared/ # Kernel partage (EntityId, DomainEvent, etc.) +└── Shared/ # Kernel partagé (EntityId, DomainEvent, etc.) ``` ### Structure DDD -Chaque Bounded Context suit la meme structure : +Chaque Bounded Context suit la même structure : ``` {BC}/ -├── Domain/ # Pure PHP - ZERO dependance framework +├── Domain/ # Pure PHP - ZERO dépendance framework │ ├── Model/ # Aggregates, Entities, Value Objects │ ├── Event/ # Domain Events │ ├── Repository/ # Interfaces repository @@ -110,42 +127,52 @@ Chaque Bounded Context suit la meme structure : │ ├── Command/ # Write operations │ ├── Query/ # Read operations │ └── EventHandler/ # Domain event handlers -└── Infrastructure/ # Implementations framework +└── Infrastructure/ # Implémentations framework ├── Persistence/ # Doctrine repositories ├── Api/ # API Platform resources └── Messaging/ # RabbitMQ handlers ``` -## Developpement +## Développement -### Commandes utiles +### Workflow quotidien ```bash -# Backend -docker compose exec php composer phpstan # Analyse statique -docker compose exec php composer test # Tests PHPUnit -docker compose exec php composer cs-fix # Correction code style - -# Frontend -docker compose exec frontend pnpm run lint # ESLint -docker compose exec frontend pnpm run check # TypeScript check -docker compose exec frontend pnpm run test # Vitest -docker compose exec frontend pnpm run test:e2e # Playwright +make up # Démarrer les services +make logs # Suivre les logs +make test # Lancer les tests avant commit +make check # Vérifier la qualité du code ``` -### Makefile (raccourcis) +### Backend ```bash -make up # docker compose up -d -make down # docker compose down -make logs # docker compose logs -f -make test # Run all tests -make lint # Run all linters +make phpstan # Analyse statique +make test-php # Tests PHPUnit +make cs-fix # Corriger le code style +make arch # Tests d'architecture +make console c='...' # Commande Symfony +``` + +### Frontend + +```bash +make lint # ESLint +make check-types # TypeScript check +make test-js # Tests Vitest +make e2e # Tests Playwright +``` + +### Shell + +```bash +make shell # Shell dans le container PHP +make shell-frontend # Shell dans le container frontend ``` ## Tests -- **PHPUnit** - Tests unitaires et integration backend +- **PHPUnit** - Tests unitaires et intégration backend - **Vitest** - Tests unitaires frontend - **Playwright** - Tests E2E @@ -153,7 +180,7 @@ make lint # Run all linters - [Architecture Decision Records](./docs/adr/) - [Contributing Guide](./CONTRIBUTING.md) -- [API Documentation](http://localhost:8000/api/docs) +- [API Documentation](http://ecole-alpha.classeo.local:18000/api/docs) ## Licence