Optimisation et solveur

En-tête

Domaine	Optimisation — lancer un calcul, le suivre, arbitrer son résultat, et voir ce qu’il fait quand ça se passe mal
Durée	~12 min
Niveau	complet
Étiquette	manuel — la progression d’un calcul n’est pas déterministe, et le bloc 4 exige deux sessions simultanées

Préparation

Socle A — le jeu de démonstration. Le montage est sur la préparation commune.

Le solveur Le moteur de calcul qui cherche, parmi des milliards de combinaisons, celle qui satisfait le mieux vos règles. doit répondre :

curl http://localhost:8082/q/health/ready

Compte : demo@delacroix.example. Le bloc 5 a besoin d’un second compte sans planning.solve — sur le socle A, créez-en un ou jouez ce bloc sur le socle B avec bob.

État de départ : les cinq cours DEMO-MULTI-* n’ont aucune séance placée. C’est le lot que le scénario fait placer.

1. Le lancement

#	Action	Résultat attendu
1.1	Planification → repérer la barre d’actions	le bouton « Placement optimisé » est présent
1.2	Cliquer dessus	le panneau « Placement multi-cours optimisé » s’ouvre, avec son avertissement : « L’EDT existant est figé et les salles verrouillées sont respectées — le système propose, vous disposez. »
1.3	Taper « DEMO-MULTI » dans « Rechercher un cours ou un enseignant… »	les cinq cours apparaissent, chacun avec son enseignant et son nombre de séances
1.4	Cocher les cinq	le bouton devient « Calculer (5) »
1.5	Sans rien cocher	le bouton « Calculer (0) » est inactif
1.6	Régler « Durée max du calcul » sur 60 s, lancer	le panneau bascule sur la progression

2. Le suivi

#	Action	Résultat attendu
2.1	Observer immédiatement	« Optimisation en cours — première solution en préparation… »
2.2	Attendre quelques secondes	« Optimisation en cours — meilleure solution actuelle : … %. », et la barre progresse
2.3	Observer la valeur	elle peut stagner puis sauter — c’est la qualité de la meilleure solution, pas un temps écoulé
2.4	Cliquer « Arrêter et proposer » avant la fin	le calcul s’interrompt et la suggestion s’affiche quand même

3. L’arbitrage

#	Action	Résultat attendu
3.1	Lire l’en-tête du résultat	« Taux de satisfaction global : … / 100 »
3.2	Lire les lignes	une par séance : le cours, la cellule visée, la salle, et son score
3.3	Cliquer « Détail » sur une ligne	la checklist de contraintes se déplie — la même que sur la grille
3.4	Cliquer « Ajuster » sur une ligne	trois sélecteurs : « Semaine », « Créneau », « Salle »
3.5	Changer la semaine puis choisir une salle, « Appliquer l’ajustement »	la ligne porte l’étiquette « Ajusté », et le taux global se recalcule
3.6	Cliquer « Revenir à la suggestion » sur cette ligne	l’étiquette disparaît, la valeur d’origine revient
3.7	Cliquer « Autre combinaison »	un nouveau calcul démarre sur le même périmètre
3.8	Une fois terminé, cliquer « Appliquer tout (…) »	« … séance(s) créée(s) en brouillon. » ; le panneau se ferme
3.9	Regarder la grille	les séances apparaissent, en brouillon — contour pointillé

4. Un seul calcul à la fois

#	Action	Résultat attendu
4.1	Relancer un calcul et le laisser tourner	la progression défile
4.2	Dans une seconde session (autre navigateur, même établissement), ouvrir « Placement optimisé » et lancer un calcul	« Un calcul est déjà en cours pour l’établissement. »
4.3	Attendre la fin du premier	le second devient possible

5. Sans la permission

#	Action	Résultat attendu
5.1	Se connecter avec un compte sans planning.solve mais avec planning.edit	la grille s’affiche normalement
5.2	Regarder la barre d’actions	le bouton « Placement optimisé » est absent — ni grisé, ni cadenassé

6. Quand ça se passe mal

#	Action	Résultat attendu
6.1	Lancer un calcul, puis « Annuler le calcul »	« Calcul annulé — aucune suggestion. » — rien n’est proposé, contrairement à « Arrêter et proposer »
6.2	Arrêter le solveur (docker compose stop solver) et lancer un calcul	le job finit en échec : « Le calcul a échoué : … » ; aucune séance n’est créée
6.3	Redémarrer le solveur, attendre sa disponibilité, relancer	le calcul repart normalement
6.4	Lancer un calcul, et pendant qu’il tourne, déplacer une séance dans une autre session sur les mêmes salles	au résultat, le bandeau « Le planning a bougé pendant le calcul — la suggestion peut être périmée. » avec un bouton « Relancer »
6.5	Tenter « Appliquer tout » malgré le bandeau	« Le planning a bougé pendant le calcul : la suggestion est périmée. Relancez le calcul. »
6.6	Si une ligne porte « Invalide »	le bouton « Appliquer tout » est inactif — une suggestion en violation dure n’est jamais applicable

Pièges connus

• La progression n’est pas un pourcentage de temps. C’est la qualité moyenne de la meilleure solution trouvée ; elle ne dit rien du temps restant.
• Le solveur ne retouche pas l’existant. Tout ce qui est déjà placé est figé — il remplit les trous, il ne réorganise pas la semaine. Un lot qui revient avec des séances non placées est un résultat, pas une panne.
• Une publication ne périme pas un calcul. Seules les mutations d’occupation le font : placement, déplacement, annulation, réservation, indisponibilité.

Fermer le panneau perd la suggestion, pas le calcul — et bloque le suivant

Le calcul vit sur le serveur : fermer la fenêtre ou recharger la page ne l’interrompt pas. Mais l’application ne se rebranche pas dessus. En rouvrant « Placement optimisé », vous retombez sur l’étape de sélection, comme si de rien n’était.

Et un nouveau « Calculer » répond alors « Un calcul est déjà en cours pour l’établissement. » Vous êtes dans la seule situation vraiment inconfortable du panneau : un calcul tourne, vous ne pouvez pas le voir, et vous ne pouvez pas en lancer un autre.

Pendant la recette : ne fermez pas le panneau pendant un calcul. Si vous devez l’écourter, « Arrêter et proposer » rend la main immédiatement avec ce qui a été trouvé.

Si c’est arrivé : attendez la fin du calcul en cours — sa suggestion est perdue, mais le verrou se libère. Vérifié dans le code : l’API sait lister les calculs de l’établissement, l’interface web n’utilise pas cette liste.

Les pièges transverses — environnement, authentification, fraîcheur des données — sont rassemblés sur Les pièges connus.

Traçabilité

Ce qui est couvert	Story	Vue
Microservice solveur	STORY-031	—
Orchestration, suivi, application, époque de planification	STORY-032	—
Panneau de placement optimisé, ajustement, autre combinaison	STORY-035	V16
Checklist de contraintes réutilisée	STORY-028	V13
Permission planning.solve	STORY-004	—

Couvert par les tests automatisés : apps/api/src/solve/solve.e2e.spec.ts et apps/api/scripts/seeding/solve-chain.e2e.spec.ts. Le cycle de vie d’un calcul, l’unicité par établissement, la péremption et l’application y sont couverts ; le suivi de progression et l’arbitrage à l’écran ne le sont pas.

Checklist

• curl http://localhost:8082/q/health/ready → le solveur répond
• « Placement optimisé » → les cinq cours DEMO-MULTI-* sont sélectionnables
• Sans sélection → « Calculer (0) » inactif
• Lancement → « Optimisation en cours — première solution en préparation… » puis un pourcentage
• « Arrêter et proposer » → la suggestion s’affiche quand même
• « Taux de satisfaction global : … / 100 » affiché
• « Détail » → la checklist de contraintes se déplie
• « Ajuster » puis « Appliquer l’ajustement » → étiquette « Ajusté », taux recalculé
• « Revenir à la suggestion » → la valeur d’origine revient
• « Appliquer tout (…) » → « … séance(s) créée(s) en brouillon. », blocs en pointillés sur la grille
• Second calcul en parallèle → « Un calcul est déjà en cours pour l’établissement. »
• Compte sans planning.solve → le bouton est absent
• « Annuler le calcul » → « Calcul annulé — aucune suggestion. »
• Solveur arrêté → « Le calcul a échoué : … », aucune séance créée
• Modification concurrente → « Le planning a bougé pendant le calcul — la suggestion peut être périmée. »
• Ligne « Invalide » → « Appliquer tout » inactif

Écrans concernés

• Panneau d'optimisation — l’écran principal.
• Grille de planning — la grille qui reçoit les brouillons.
• Pastilles de contrainte et explicabilité — la checklist que « Détail » déplie.
• Publication du planning — l’étape d’après.