Skip to content

feat(install): assistant d'installation web (pays, niveaux multiples, devise, sécurité) - #343

Merged
horacioskrp merged 7 commits into
developfrom
feat/web-installer
Nov 17, 2026
Merged

horacioskrp merged 7 commits into
developfrom
feat/web-installer

Conversation

@horacioskrp

Copy link
Copy Markdown
Collaborator

Assistant d'installation web

Ajoute un assistant « première configuration » (façon WordPress) : sur une base vierge, l'application redirige vers /install, guide l'opérateur en 4 étapes, puis exécute réellement l'installation et se verrouille. Aucune ligne de commande requise.

Parcours (4 étapes)

  1. Langue — fixe la langue de l'assistant et de l'application (FR / EN), live.
  2. Administrateur — compte principal ; mot de passe soumis à la politique de l'app (min. 12, casse mixte, chiffres, symboles, vérifié contre les fuites en prod).
  3. Sécurité — HTTPS forcé, debug coupé, journalisation Sentry (2FA facultative).
  4. École — identité groupée par sections : identité (nom, code, monnaie, devise/slogan), direction & contact, localisation (pays, région, ville, BP, adresse), organisation pédagogique (niveaux multiples, année, périodes).

Exécution (idempotente)

migrate → création de l'école → ReferenceDataSeeder → rattachement des types de classe aux niveaux cochés → périodes + année active → administrateur (rôle + owner_id de l'école) → réglages sécurité (.env) → verrou storage/app/installed.json. Reprise après échec sans doublon.

Modèle École

  • Pays : nouvelle colonne schools.country (défaut TG) + liste ISO via App\Constants\Countries (source unique, consommée aussi par CountrySeeder).
  • Niveaux multiples : une école peut cumuler plusieurs cycles, rattachés comme types de classe (School::classTypes) ; l'enum level garde le cycle principal.
  • Devise/slogan (devise) distincte de la monnaie (currency, code ISO).

Sécurité (durcissement)

  • Mot de passe admin chiffré en session (APP_KEY) jusqu'à l'exécution, puis purgé — la base reste l'unique stockage final, en haché.
  • Base de données = source de vérité de l'état « installé » (le fichier-verrou n'est qu'un cache).
  • Throttling des routes de l'assistant, masquage du SQL dans les journaux d'erreur, config:clear après écriture .env.
  • Bascule automatique des stores session/cache sur le pilote file avant installation (tables absentes sur base neuve).

i18n & qualité

  • lang/{fr,en}/validation.php : messages de formulaire traduits (bloc password + attributs lisibles).
  • admin/school : nettoyage des erreurs à la saisie (clearErrors) — fin de l'erreur « figée » sur la confirmation de mot de passe.
  • Cartes de niveaux de dimension uniforme, champs groupés sans card.

Nettoyage & doc

  • Suppression du seeder obsolète DemoSeeder (non référencé).
  • Documentation : README (section assistant web), page dédiée documentations/prise-en-main/installation-web.md, index de doc, CHANGELOG.

Tests

InstallWizardTest : parcours, exécution réelle, pays, multi-niveaux, devise, propriétaire, verrou, sessions altérées, garde-fous config↔seeder. PHPStan (niveau 5, 0 erreur), Pint, tsc, ESLint verts.

Assistant d'installation style WordPress, calqué sur le design de la page
de connexion (hero + DalibiLogo). Quatre étapes visibles : langue, école,
administrateur, protocole de sécurité, puis écran d'exécution.

Cette phase couvre l'ossature et l'UI ; l'exécution réelle (migrations,
seed, création école/admin, pose du verrou) arrive en Phase 2 — l'écran
'running' est pour l'instant un espace réservé.

- InstallState : source de vérité (verrou storage/app/installed.json +
  auto-cicatrisation si la base contient déjà des utilisateurs)
- RequirementsChecker : contrôle PHP/extensions/droits/APP_KEY sans base
- EnsureAppInstalled / EnsureAppNotInstalled : redirection vers/hors
  l'assistant, priorisé avant l'authentification
- Session forcée en driver 'file' avant installation (pas de base requise)
- Écrans Inertia : welcome, school, admin, security, running, requirements
- i18n FR/EN, tests fonctionnels (8) ; TestCase considère l'app installée
Branche l'orchestration réelle derrière l'écran de progression : à
l'affichage, le front déclenche POST /install/execute qui exécute le
service Installer puis redirige vers la connexion.

Service App\Support\Install\Installer :
- migrate --force (idempotent)
- création de l'école (avant le seed, pour les en-têtes/bulletins par défaut)
- db:seed ReferenceDataSeeder (rôles & permissions, catalogues) — rejouable
- découpage des périodes (trimestre/semestre) appliqué aux types de classe
- année scolaire active
- administrateur + rôle « administrateur » + matricule (sans changement de
  mot de passe imposé : il vient de le choisir)
- réglages de sécurité best-effort sur .env (APP_DEBUG, APP_URL en HTTPS),
  jamais sous tests ; choix consignés dans le verrou
- pose du verrou storage/app/installed.json

Chaque étape est idempotente (firstOrCreate/firstOrNew) : une reprise après
échec ne crée pas de doublon. En cas d'erreur, l'écran propose de relancer.

Tests : 2 nouveaux cas (garde-fou session, installation complète + verrou),
nettoyage du verrou en tearDown. Suite complète verte (515).
…durcissement sécurité

Affinements de l'assistant d'installation après la Phase 2.

Étapes
- Ordre revu : Langue → Administrateur → Sécurité → École (l'école clôt et
  déclenche l'installation). Stepper, redirections et liens « Retour » alignés.
- Le choix de la langue bascule désormais toute l'interface : l'étape écrit
  session('locale') (lue par SetLocale), les étapes suivantes suivent.

École & propriétaire
- Formulaire école calqué sur le modèle School (niveau, code, devise,
  directeur, email, téléphone, adresse, ville, région, description) ; la devise
  est un sélecteur alimenté par la constante Currencies (validation sur les codes).
- Suivi du propriétaire : migration owner_id (FK users, nullOnDelete),
  relation School::owner(), renseigné par l'Installer (= administrateur créé).

Sécurité (suite audit)
- H1 : le mot de passe de l'administrateur applique la politique de l'app
  (trait PasswordValidationRules → Password::default()).
- H2 : réglages honnêtes. 2FA retirée (non imposée, laissée au choix de chaque
  utilisateur) ; force_https réellement effectif via FORCE_HTTPS lu par
  AppServiceProvider (hors local) ; app_debug_off inchangé.

Tests : nouvel ordre, propagation de langue, owner, champs modèle, politique mdp.
Suite complète verte (516). PHPStan 0, Pint, tsc, ESLint, build OK.
… de vérité)

M2 — plus de mot de passe en clair pendant l'assistant :
- l'étape admin chiffre le mot de passe en session (Crypt::encryptString, APP_KEY) ;
  le payload de session fichier ne contient plus de secret exploitable au repos.
- execute le déchiffre juste avant de créer le compte ; une session altérée
  (déchiffrement impossible) renvoie à l'étape admin sans rien installer.
- stockage final inchangé : base de données, mot de passe haché, session purgée.

M3 — la base de données fait foi, le fichier-verrou n'est qu'un cache :
- InstallState::isInstalled() regarde d'abord la base (présence d'un utilisateur),
  puis se rabat sur installed.json uniquement si la base est injoignable.
- un verrou périmé sur une base vide ne bloque plus une réinstallation légitime.
- sonde allégée : une requête exists indexée, mémoïsée, sans Schema::hasTable.

Tests : installation avec mot de passe chiffré + Hash::check, session altérée
rejetée. Suite complète verte (517). PHPStan 0, Pint OK.
L1 — logs : en cas d'échec d'installation, journaliser le type et
l'emplacement de l'exception, mais masquer le message d'une QueryException
(il contient le SQL et ses bindings, dont l'email).

L2 — écran prérequis : ne plus afficher la version exacte de PHP lorsque le
prérequis passe (empreinte système) ; visible uniquement en cas d'échec.

L3 — throttling : limiter toutes les étapes de l'assistant (throttle:30,1) en
plus de la limite stricte propre à l'exécution (throttle:6,1).

L4 — cache de config : après écriture du .env (APP_DEBUG, FORCE_HTTPS…),
appeler config:clear pour que les nouvelles valeurs soient lues au prochain
boot (no-op sans cache ; jamais exécuté sous tests).

Suite complète verte (517). PHPStan 0, Pint OK.
Le throttle des routes d'installation (ajouté en L3) s'appuie sur le store de
cache. Avec CACHE_STORE=database, la table cache n'existe pas avant les
migrations : l'affichage de l'assistant levait une QueryException
(relation « cache » inexistante), comme le faisait la session.

AppServiceProvider bascule désormais session ET cache sur le pilote file tant
que l'application n'est pas installée (useFileStoresBeforeInstall). Après
migration, les stores database reprennent normalement.

Vérifié en live : GET /install répond 200 (plus de QueryException). 12 tests
install verts, PHPStan 0, Pint OK.
Étape « École » de l'assistant :
- Select pays (liste ISO via App\Constants\Countries, source unique du
  CountrySeeder) + colonne schools.country (défaut TG).
- Niveaux multiples : cases à cocher rattachées comme types de classe
  (School::classTypes) ; l'enum level garde le cycle principal.
- Champ devise/slogan distinct de la monnaie (currency), relibellé « Monnaie ».
- Champs groupés par logique (identité/contact/localisation/pédagogie), sans
  card ; cartes de niveaux de dimension uniforme.

Autres :
- Messages d'erreur de formulaire traduits : lang/{fr,en}/validation.php
  (bloc password + attributs lisibles).
- admin/school : nettoyage des erreurs à la saisie (clearErrors) — fin de
  l'erreur « figée » sur la confirmation de mot de passe.
- Suppression du seeder obsolète DemoSeeder (non référencé).
- Documentation : README (section assistant web), page dédiée
  installation-web.md, index de doc, CHANGELOG.

Tests : InstallWizardTest (pays, multi-niveaux, devise, garde-fous
config/seeder) ; PHPStan, Pint, ESLint OK.
@horacioskrp
horacioskrp merged commit cef8498 into develop Nov 17, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant