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 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 ""

117
README.md
View File

@@ -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