Paillasse/docs/runbooks/portail.md

# Runbook — Portail Laravel

## Où sont les choses

| Élément | Emplacement |
|---|---|
| Code de l'application | `/var/www/portail` (propriétaire `adam`, sauf `storage/` et `bootstrap/cache/` → `www-data`) |
| Secrets Laravel (`.env`) | `/var/www/portail/.env`, `640 adam:www-data`, généré une seule fois, jamais dans Git |
| Secrets MariaDB/Redis de l'app | `/etc/portail/.env`, `600 root:root`, générés une seule fois |
| Config Docker Compose (MariaDB + Redis app) | `/etc/portail/docker-compose.yml` |
| Vhost Nginx | `/etc/nginx/sites-available/portail.conf` |
| PHP | 8.3 (dépôt Sury), FPM sur `/run/php/php8.3-fpm.sock` |

Déployé par `ansible/portail.yml` (rôle `portail`) :
```
cd ansible && script -q /dev/null ansible-playbook portail.yml -i inventory.ini
```

## Architecture de l'app

- Laravel 13, Blade + Vite (Tailwind v4 via le plugin Vite officiel).
- Deux comptes distincts, deux guards (`config/auth.php`) :
  - `web` → `User` (profs), email + mot de passe.
  - `eleve` → `Eleve` (élèves), identifiant (`prenom.initiale`, suffixe numérique si homonyme) + code secret à 6 caractères (haché).
- **Une seule session active par compte** (`App\Models\Concerns\GereSessionUnique` + middleware `session.unique`) : un jeton est stocké en session ET en base à chaque connexion ; s'ils ne correspondent plus, la session est coupée à la requête suivante avec un message.
- Vues reprises telles quelles depuis `design/` (voir le journal du 2026-10-07, étape 8, pour les deux écarts assumés : mot de passe ajouté au formulaire d'inscription, sélecteur d'établissement retiré du formulaire de connexion).
- Écrans sans maquette, construits sobres avec les jetons visuels existants : `resources/views/mes-classes/*` (gestion des élèves, import CSV, fiches QR) et `resources/views/seances/*` (salle d'attente).

## Base de données et cache de l'app

MariaDB et Redis **dédiés à l'app**, en Docker Compose, liés à `127.0.0.1` uniquement (jamais sur `10.10.0.1`, qui est le réseau de Kolla) :

- MariaDB : port `3307` (celui de Kolla est sur `10.10.0.1:3306`).
- Redis : port `6380`.

```
cd /etc/portail && docker compose ps
```

## Déployer une mise à jour du code

```
cd ansible && script -q /dev/null ansible-playbook portail.yml -i inventory.ini
```

Le rôle synchronise le code (`rsync`, sans `vendor/`, `node_modules/`, `.env`,
ni `storage/`/`bootstrap/cache/` — ce sont de l'état runtime, jamais du code),
puis `composer install --no-dev`, `npm ci && npm run build`,
`php artisan migrate --force`, et recrée les caches
(`config:cache`, `route:cache`, `view:cache`).

**Après toute modification de code qui touche les routes ou la config**, les
caches doivent être régénérés (le rôle le fait automatiquement). Si on modifie
une vue sans repasser par Ansible, penser à `php artisan view:clear` à la main.

## Lancer les tests (en local, avant tout déploiement)

```
cd portail && ./vendor/bin/pest
```

11 tests : connexion prof, connexion élève, session unique (prof et élève),
création de classe + établissement. Base de test : SQLite en mémoire
(`phpunit.xml`), aucun rapport avec MariaDB de prod.

## Écarts au design assumés le 2026-10-07

- `auth/inscription.blade.php` : champ mot de passe ajouté (absent de la
  maquette), confirmé par Adam — sans lui, la connexion prof décrite dans le
  prompt de déploiement n'aurait pas pu fonctionner sans serveur mail.
- `auth/connexion.blade.php` : le sélecteur d'établissement du formulaire
  enseignant a été retiré (un prof qui se connecte a déjà un établissement en
  base ; ce sélecteur n'avait de sens que pour l'inscription).
- `paillasse-contenus/README.md` corrigé : `tree` n'est pas préinstallé dans
  l'image (le lab 02 demande à l'élève de l'installer lui-même).
- Gestion des élèves (ajout, import CSV, fiches QR) et salle d'attente :
  aucune maquette fournie, design minimal sobre construit avec les jetons
  visuels existants (confirmé par Adam).

## Piège vécu le 2026-10-07

Un handler Ansible qui notifie un autre handler (`recharger nginx` →
`redémarrer nginx`) ne s'est **pas** propagé avant la fin du play : Nginx a
continué de servir sa page par défaut malgré un déploiement « réussi ».
Corrigé en fusionnant les deux handlers en un seul
(`nginx -t && systemctl reload nginx`). Si un jour un changement Nginx semble
sans effet, vérifier d'abord `sudo nginx -T` sur le serveur, puis forcer
`sudo systemctl reload nginx` à la main.

## Vérifié le 2026-10-07

- `curl http://163.172.4.195/connexion` : les deux formulaires s'affichent.
- Un élève fictif (`lea.m` / code à 6 caractères) s'est connecté et a vu son
  tableau de bord (« Salut Léa », nom de sa classe) — données de test
  supprimées juste après (accord d'Adam).
- `nft list tables` après déploiement : toujours seulement `inet filter` et
  `ip nat` (+ `f2b-table` de fail2ban) — Nginx n'a rien ajouté au pare-feu.