Roukmoute/Classeo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Makefile autodocumenté et README simplifié

Browse Source 
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.
This commit is contained in:
Mathias STRASSER
2026-02-01 14:57:08 +01:00
parent b9d9f48305
commit b7354b8448
2 changed files with 163 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
Makefile
View File

@@ -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_GOAL := help
# 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)"
# ============================================================================= # =============================================================================
# Docker # Docker
# ============================================================================= # =============================================================================
up: .PHONY: up
up: ## Lancer tous les services
docker compose up -d docker compose up -d
down: .PHONY: down
down: ## Arrêter tous les services
docker compose down docker compose down
restart: .PHONY: restart
restart: ## Redémarrer tous les services
docker compose down docker compose down
docker compose up -d docker compose up -d
rebuild: .PHONY: rebuild
rebuild: ## Reconstruire et relancer les services (sans cache)
docker compose down docker compose down
docker compose build --no-cache docker compose build --no-cache
docker compose up -d docker compose up -d
build: .PHONY: build
build: ## Reconstruire les images Docker (sans cache)
docker compose build --no-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 docker compose logs -f
ps: .PHONY: ps
ps: ## Afficher le statut des services
docker compose ps docker compose ps
clean: .PHONY: clean
clean: ## Supprimer volumes et images locales
docker compose down -v --rmi local docker compose down -v --rmi local
# ============================================================================= # =============================================================================
# Shell # Shell
# ============================================================================= # =============================================================================
shell: .PHONY: shell
shell: ## Ouvrir un shell dans le container PHP
docker compose exec php sh 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) 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 docker compose exec frontend sh
# ============================================================================= # =============================================================================
# Backend # Backend - Qualité
# ============================================================================= # =============================================================================
phpstan: .PHONY: phpstan
phpstan: ## Analyse statique PHPStan (level 9)
docker compose exec php composer phpstan docker compose exec php composer phpstan
arch: .PHONY: arch
arch: ## Tests d'architecture PHPat
docker compose exec php composer arch 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 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 docker compose exec php composer cs-check
test-php: .PHONY: test-php
test-php: ## Lancer les tests PHPUnit
docker compose exec php composer test docker compose exec php composer test
warmup: .PHONY: warmup
warmup: ## Préchauffer le cache Symfony
docker compose exec php php bin/console cache:warmup 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 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 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 docker compose exec frontend pnpm run test
e2e: .PHONY: e2e
e2e: ## Lancer les tests E2E Playwright
docker compose exec frontend pnpm run test:e2e 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 # Scripts
# ============================================================================= # =============================================================================
check-bc: .PHONY: check-bc
check-bc: ## Vérifier l'isolation des Bounded Contexts
./scripts/check-bc-isolation.sh ./scripts/check-bc-isolation.sh
check-naming: .PHONY: check-naming
check-naming: ## Vérifier les conventions de nommage
./scripts/check-naming.sh ./scripts/check-naming.sh
check-tenants: .PHONY: check-tenants
check-tenants: ## Vérifier que les tenants répondent
./scripts/check-tenants.sh ./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 # Dev helpers
# ============================================================================= # =============================================================================
# Generer les cles JWT (a faire une seule fois apres clone) .PHONY: token
# Les cles sont gitignored pour la securite token: ## Créer un token d'activation (interactif). Options: email=, role=, tenant=, minor=1
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:
docker compose exec php php bin/console app:dev:create-test-activation-token \ docker compose exec php php bin/console app:dev:create-test-activation-token \
$(if $(email),--email=$(email),) \ $(if $(email),--email=$(email),) \
$(if $(role),--role=$(role),) \ $(if $(role),--role=$(role),) \
@@ -178,17 +160,30 @@ token:
$(if $(minor),--minor,) \ $(if $(minor),--minor,) \
--base-url=http://localhost:5174 --base-url=http://localhost:5174
# Raccourcis pour creer rapidement des tokens sur chaque tenant (non-interactif) .PHONY: token-alpha
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 \ 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 \ --tenant=ecole-alpha --base-url=http://ecole-alpha.classeo.local:5174 \
$(if $(email),--email=$(email),--email=alpha@test.com) \ $(if $(email),--email=$(email),--email=alpha@test.com) \
$(if $(role),--role=$(role),) \ $(if $(role),--role=$(role),) \
$(if $(minor),--minor,) $(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 \ 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 \ --tenant=ecole-beta --base-url=http://ecole-beta.classeo.local:5174 \
$(if $(email),--email=$(email),--email=beta@test.com) \ $(if $(email),--email=$(email),--email=beta@test.com) \
$(if $(role),--role=$(role),) \ $(if $(role),--role=$(role),) \
$(if $(minor),--minor,) $(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 ""

117
README.md
View File

@@ -4,39 +4,56 @@ Application de gestion scolaire moderne - Backend Symfony 8 + Frontend SvelteKit
## Quick Start ## Quick Start
### Prerequis ### Prérequis
- Docker Desktop 24+ avec Docker Compose 2.20+ - Docker Desktop 24+ avec Docker Compose 2.20+
- Git - Git
### Configuration /etc/hosts (multi-tenant) ### Installation
Classeo utilise une architecture multi-tenant basée sur les sous-domaines. Ajoutez cette ligne à `/etc/hosts` :
```bash ```bash
sudo sh -c 'echo "127.0.0.1 classeo.local ecole-alpha.classeo.local ecole-beta.classeo.local" >> /etc/hosts' # 1. Cloner le repo
```
### Lancement
```bash
# Cloner le repo
git clone https://github.com/ClasseoEdu/classeo.git git clone https://github.com/ClasseoEdu/classeo.git
cd classeo cd classeo
# Lancer tous les services # 2. Configurer /etc/hosts pour le multi-tenant
docker compose up -d sudo sh -c 'echo "127.0.0.1 classeo.local ecole-alpha.classeo.local ecole-beta.classeo.local" >> /etc/hosts'
# Verifier le statut # 3. Installation complète (démarre les services, génère les clés JWT, warmup cache)
docker compose ps make install
# Verifier que les tenants répondent # 4. Vérifier que tout fonctionne
make ps
make check-tenants 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 ### URLs
#### Multi-tenant (recommandé) #### Multi-tenant
| Service | URL | Description | | Service | URL | Description |
|---------|-----|-------------| |---------|-----|-------------|
@@ -61,8 +78,8 @@ make check-tenants
- **PHP 8.5** avec property hooks et asymmetric visibility - **PHP 8.5** avec property hooks et asymmetric visibility
- **Symfony 8.0** - Framework DDD-friendly - **Symfony 8.0** - Framework DDD-friendly
- **API Platform 4.x** - API REST auto-generee - **API Platform 4.x** - API REST auto-générée
- **Doctrine ORM 3.x** - Persistence avec mappings separes - **Doctrine ORM 3.x** - Persistence avec mappings séparés
- **PHPStan level 9** - Analyse statique stricte - **PHPStan level 9** - Analyse statique stricte
### Frontend ### Frontend
@@ -75,7 +92,7 @@ make check-tenants
### Infrastructure ### Infrastructure
- **PostgreSQL 18.1** - Base de donnees - **PostgreSQL 18.1** - Base de données
- **Redis 7.4** - Cache + Sessions - **Redis 7.4** - Cache + Sessions
- **RabbitMQ 4.2** - Message queue - **RabbitMQ 4.2** - Message queue
- **Mercure** - Real-time SSE - **Mercure** - Real-time SSE
@@ -88,20 +105,20 @@ make check-tenants
``` ```
backend/src/ backend/src/
├── Administration/ # Gestion etablissement, utilisateurs ├── Administration/ # Gestion établissement, utilisateurs
├── Scolarite/ # Notes, classes, emploi du temps ├── Scolarite/ # Notes, classes, emploi du temps
├── VieScolaire/ # Absences, retards, sanctions ├── VieScolaire/ # Absences, retards, sanctions
├── Communication/ # Messages, notifications ├── Communication/ # Messages, notifications
└── Shared/ # Kernel partage (EntityId, DomainEvent, etc.) └── Shared/ # Kernel partagé (EntityId, DomainEvent, etc.)
``` ```
### Structure DDD ### Structure DDD
Chaque Bounded Context suit la meme structure : Chaque Bounded Context suit la même structure :
``` ```
{BC}/ {BC}/
├── Domain/ # Pure PHP - ZERO dependance framework ├── Domain/ # Pure PHP - ZERO dépendance framework
│ ├── Model/ # Aggregates, Entities, Value Objects │ ├── Model/ # Aggregates, Entities, Value Objects
│ ├── Event/ # Domain Events │ ├── Event/ # Domain Events
│ ├── Repository/ # Interfaces repository │ ├── Repository/ # Interfaces repository
@@ -110,42 +127,52 @@ Chaque Bounded Context suit la meme structure :
│ ├── Command/ # Write operations │ ├── Command/ # Write operations
│ ├── Query/ # Read operations │ ├── Query/ # Read operations
│ └── EventHandler/ # Domain event handlers │ └── EventHandler/ # Domain event handlers
└── Infrastructure/ # Implementations framework └── Infrastructure/ # Implémentations framework
├── Persistence/ # Doctrine repositories ├── Persistence/ # Doctrine repositories
├── Api/ # API Platform resources ├── Api/ # API Platform resources
└── Messaging/ # RabbitMQ handlers └── Messaging/ # RabbitMQ handlers
``` ```
## Developpement ## Développement
### Commandes utiles ### Workflow quotidien
```bash ```bash
# Backend make up # Démarrer les services
docker compose exec php composer phpstan # Analyse statique make logs # Suivre les logs
docker compose exec php composer test # Tests PHPUnit make test # Lancer les tests avant commit
docker compose exec php composer cs-fix # Correction code style make check # Vérifier la qualité du code
# 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
``` ```
### Makefile (raccourcis) ### Backend
```bash ```bash
make up # docker compose up -d make phpstan # Analyse statique
make down # docker compose down make test-php # Tests PHPUnit
make logs # docker compose logs -f make cs-fix # Corriger le code style
make test # Run all tests make arch # Tests d'architecture
make lint # Run all linters 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 ## Tests
- **PHPUnit** - Tests unitaires et integration backend - **PHPUnit** - Tests unitaires et intégration backend
- **Vitest** - Tests unitaires frontend - **Vitest** - Tests unitaires frontend
- **Playwright** - Tests E2E - **Playwright** - Tests E2E
@@ -153,7 +180,7 @@ make lint # Run all linters
- [Architecture Decision Records](./docs/adr/) - [Architecture Decision Records](./docs/adr/)
- [Contributing Guide](./CONTRIBUTING.md) - [Contributing Guide](./CONTRIBUTING.md)
- [API Documentation](http://localhost:8000/api/docs) - [API Documentation](http://ecole-alpha.classeo.local:18000/api/docs)
## Licence ## Licence