feat(docs): add detailed planning objectives and optimization rules documentation

2026-10-08 23:20:40 +02:00
1 parent 0c266a4b9d
commit 209bf05f36
@@ -0,0 +1,25 @@
+# 01 — Unifier l’évaluation et la comparaison des objectifs
+
+**GitLab:** [#70](https://gitlab.nessar.fr/nessar/vac-optimizer/-/work_items/70)
+
+**What to build:** Le planificateur conserve ses résultats actuels pendant une préparation qui rend les six objectifs évaluables à partir de configurations de règles. Le contrat commun permet ensuite aux règles fournies et aux règles personnelles d’utiliser les mêmes mesures, sans dépendre de leur nom ou de leur identité.
+
+**Blocked by:** None — can start immediately.
+
+**Status:** ready-for-agent
+
+Préparation du remplacement décrit par l’ADR 0008, justifiée par les comparaisons aujourd’hui dispersées dans le moteur. Ouvrir une branche d’intégration consacrée à cette évolution ; la mise en service de l’ensemble dépend du ticket 06. Préserver les données utilisateur est une décision explicite du cadrage.
+
+**Hypothèses de travail :** Pour clore les détails techniques restés ouverts dans la spécification, partir du catalogue minimal nécessaire aux six préréglages : somme, comptage et maximum, directions minimiser ou maximiser, valeur zéro sur ensemble vide. Le déficit de reprise possède un seuil entier positif, initialement cinq ; la pondération des semaines fériées reste la mesure métier existante. Les autres agrégations et filtres ne sont pas requis par ce découpage.
+
+- [ ] Décrire le contrat composé : éléments observés, conditions applicables, mesure, agrégation et direction. Définir une table finie des combinaisons compatibles et des paramètres acceptés, avec les unités en jours travaillés ou calendaires selon la mesure. Le catalogue permet de composer des configurations, sans se réduire à six identifiants d’objectifs.
+- [ ] Exprimer dans ce contrat les six préréglages : somme des soldes à risque non placés à minimiser ; somme des valeurs des semaines fériées complètes à maximiser ; gain de jours non ouvrés à maximiser ; longueur maximale des séquences de travail à minimiser ; déficit des courtes séquences internes à minimiser ; nombre de placements d’appoint à minimiser.
+- [ ] Conserver les définitions exactes : pondération des fériés du lundi au vendredi de 1, 2, 3, 2, 1 ; déficit de cinq moins la longueur pour chaque séquence interne non vide de moins de cinq jours ; séquences aux bords de l’horizon incluses dans le maximum et exclues du déficit interne.
+- [ ] Définir explicitement zéro pour le comptage, la somme et le maximum sur un ensemble vide, en reprenant les résultats actuels. Valider le domaine et l’unité des paramètres ; une combinaison non prise en charge est identifiable.
+- [ ] Une même configuration appliquée au même plan produit la même valeur quels que soient le nom et l’identité de la règle. Vérifier aussi une configuration paramétrée distincte du préréglage, par exemple le déficit à trois jours, sans inventer une nouvelle mesure métier.
+- [ ] Regrouper l’évaluation et les comparaisons nécessaires à la sélection des solutions d’obligations, aux déplacements, aux placements d’appoint, aux départages et aux explications. Remplacer les calculs dupliqués concernés ; ne pas ajouter un second moteur ou un adaptateur de compatibilité.
+- [ ] Cette préparation conserve l’ordre historique pour ses scénarios de référence : prévention des pertes, préférences, semaines fériées, gain de jours non ouvrés, séquence maximale, déficit des reprises, placements d’appoint, expiration puis dates.
+- [ ] Les tests existants de placements, soldes, obligations conjointes, congés gagnés et trace de qualité conservent leurs résultats observables pendant ce prefactoring. Les mesures sont également vérifiées sur des plans concrets comportant des jours déclarés et des périodes aux limites de l’horizon.
+- [ ] Consigner le contrat minimal et ses cas limites pour les tickets suivants, en distinguant les décisions déjà confirmées des hypothèses techniques retenues. Les tickets suivants partagent ce contrat et cette branche d’intégration.
+
+**Vérification de bout en bout :** Comparer les résultats et les explications des scénarios de référence avant et après la préparation ; vérifier que les six recettes et une variante paramétrée évaluent correctement les mêmes plans.
@@ -0,0 +1,24 @@
+# 02 — Piloter la prévention des pertes depuis les règles
+
+**GitLab:** [#71](https://gitlab.nessar.fr/nessar/vac-optimizer/-/work_items/71)
+
+**What to build:** L’utilisateur crée une règle d’optimisation de prévention des pertes, l’enregistre, la déplace parmi ses préférences et constate son effet sur les congés placés et les soldes restants. La désactiver retire réellement sa priorité automatique.
+
+**Blocked by:** 01 — Unifier l’évaluation et la comparaison des objectifs.
+
+**Status:** ready-for-agent
+
+Première tranche fonctionnelle du modèle commun de l’ADR 0008. Continuer la branche d’intégration du ticket 01 ; l’ajout des six préréglages aux données existantes et la mise en service sont traités au ticket 06. Les scénarios de cette tranche soumettent explicitement leurs règles.
+
+- [ ] Proposer la famille Optimisation dans la liste existante et permettre de créer, nommer, éditer, activer, désactiver, supprimer et réordonner une règle utilisant la somme des soldes à risque non placés. Seul le mode préférence est disponible pour cette famille.
+- [ ] L’édition, les résumés et les commandes utilisent le contrat du ticket 01, sont traduits et accessibles au clavier. La configuration complète est sauvegardée localement et restaurée, avec son identité, ses paramètres, son activation et sa position.
+- [ ] Le calcul résout les obligations conjointement puis utilise l’ordre des préférences actives pour arbitrer les placements. Placer la prévention des pertes sous une préférence personnelle peut laisser davantage de congés à risque inutilisés ; la remonter restaure sa priorité.
+- [ ] Remplacer l’exécution implicite de la prévention des pertes par l’exécution de sa configuration explicite. Mettre en place le parcours ordonné partagé des règles ; aucun objectif n’est ajouté implicitement à une requête pour compenser une règle absente ou une configuration non prise en charge.
+- [ ] Une règle désactivée donne le même plan que son absence, à autres entrées identiques. Une requête sans règle active n’ajoute aucun congé, même avec des soldes à risque, et conserve les jours déclarés. Les départages par expiration et dates ne déclenchent aucun placement.
+- [ ] Les quantités, disponibilités, expirations, jours éligibles et jours déclarés restent des contraintes de validité. Une configuration active incompatible ou mal formée produit une erreur d’entrée rattachable à la règle, sans devenir un conflit d’obligations ni réactiver un défaut.
+- [ ] Les chemins direct et worker conservent tous les paramètres de la règle dans l’instantané du calcul. L’explication, la trace et les analyses contrefactuelles suivent le même ordre actif ; une modification ultérieure dans l’éditeur ne change pas le résultat soumis.
+- [ ] Adapter les consommateurs concernés, notamment ceux qui supposent qu’une règle comporte toujours un nombre de jours à poser. L’estimation de durée reste finie et les règles existantes Si… alors… et Période restent utilisables.
+- [ ] Les tests de comportement couvrent création et rechargement, déplacement au clavier, priorité inversée contre une préférence personnelle, désactivation équivalente à suppression, absence de règles, entrée invalide et passage par le worker. S’appuyer sur les suites existantes de gestion des règles, de planification et d’instantané immuable.
+- [ ] Les fonctionnalités communes de cette tranche sont réutilisables par les familles des tickets 03 à 05. Ne pas conserver une exécution historique parallèle comme solution transitoire ; la série est livrée après sa validation commune.
+
+**Vérification de bout en bout :** Avec un solde à risque et une préférence personnelle concurrente, déplacer la prévention des pertes, recalculer et comparer les placements et soldes ; désactiver ensuite toutes les règles et vérifier l’absence de nouveaux congés.
@@ -0,0 +1,23 @@
+# 03 — Composer les règles de semaines fériées et de repos
+
+**GitLab:** [#72](https://gitlab.nessar.fr/nessar/vac-optimizer/-/work_items/72)
+
+**What to build:** L’utilisateur crée et règle les préférences « Compléter les semaines avec un jour férié » et « Profiter des week-ends et jours fériés », puis choisit laquelle prime dans le planning et dans ses explications.
+
+**Blocked by:** 02 — Piloter la prévention des pertes depuis les règles.
+
+**Status:** ready-for-agent
+
+Tranche de calendrier de l’ADR 0008, sur la branche d’intégration commune. Elle utilise l’édition, la persistance, le transport et l’ordre actif introduits au ticket 02. Elle peut avancer indépendamment du ticket 04 ; la mise en service reste conditionnée au ticket 06.
+
+- [ ] Permettre de composer, enregistrer et modifier les règles sur les semaines fériées et les périodes de repos avec les conditions, mesures et agrégations compatibles du contrat commun. Les deux préréglages sont des configurations du même modèle que les règles personnelles.
+- [ ] Le préréglage des semaines fériées maximise la somme des valeurs des semaines complètes. Compter chaque férié du lundi au vendredi selon sa distance au week-end le plus proche ; additionner les contributions de plusieurs fériés dans une semaine sans compter la semaine deux fois.
+- [ ] Le préréglage du gain maximise les dates distinctes de week-end et de jour férié contenues dans les périodes de repos. Les jours de congé posés ne constituent pas eux-mêmes ce gain.
+- [ ] Conserver les contributions des jours déclarés et les règles d’adjacence aux limites de l’horizon. Les placements restent dans l’horizon et sur des dates éligibles ; une semaine ordinaire entièrement déclarée ne devient pas une semaine fériée.
+- [ ] Les règles s’arbitrent selon leur position parmi toutes les préférences actives. Un scénario où la meilleure semaine fériée concurrence un gain de jours non ouvrés plus élevé démontre les deux ordres possibles.
+- [ ] Une préférence de calendrier peut être placée avant ou après Samedi Malin et les autres préférences. Aucun ancien garde-fou ne rétablit automatiquement la priorité d’une semaine fériée ou d’une prévention des pertes désactivée.
+- [ ] La recherche peut utiliser des placements d’appoint admissibles lorsque l’objectif actif les justifie et que les préférences supérieures et obligations sont préservées. Leur classification est conservée pour le ticket 05.
+- [ ] La configuration éditée et sauvegardée est celle utilisée par le calcul direct, le worker, les explications, la trace et les comparaisons de dates. Les libellés et commandes sont traduits et accessibles.
+- [ ] Adapter les scénarios de comportement existants sur les semaines fériées, le gain, les jours déclarés et les placements d’appoint : férié du mercredi, plusieurs fériés, horizon partiel, concurrence entre objectifs et désactivation équivalente à absence. Les requêtes de référence fournissent explicitement leurs règles.
+
+**Vérification de bout en bout :** Créer les deux règles, inverser leur ordre sur un cas concurrent, recalculer et constater la modification du planning et du premier objectif décisif dans l’explication ; recharger et retrouver la configuration.
@@ -0,0 +1,23 @@
+# 04 — Composer les règles de séquences de travail
+
+**GitLab:** [#73](https://gitlab.nessar.fr/nessar/vac-optimizer/-/work_items/73)
+
+**What to build:** L’utilisateur compose des préférences sur ses séquences de travail : réduire la plus longue séquence ou limiter le déficit des reprises courtes, avec un seuil configurable. Leur position parmi les autres préférences influence le planning.
+
+**Blocked by:** 02 — Piloter la prévention des pertes depuis les règles.
+
+**Status:** ready-for-agent
+
+Tranche de séquences de travail de l’ADR 0008, sur la branche d’intégration commune. Elle utilise le contrat minimal et les fonctions de gestion du ticket 02 et peut avancer indépendamment du ticket 03. Le seuil initial de cinq jours reproduit le comportement existant.
+
+- [ ] Permettre de créer, éditer, sauvegarder et réordonner une règle sur la longueur maximale des séquences de travail et une règle sur le déficit des séquences internes, à partir du même modèle composable.
+- [ ] Le préréglage de la séquence maximale minimise son nombre de jours travaillés, en incluant les séquences situées aux deux bords de l’horizon. Les week-ends et jours fériés ne comptent pas et ne coupent pas une séquence.
+- [ ] Le préréglage des reprises courtes minimise la somme des déficits pour les séquences internes non vides : avec le seuil initial de cinq jours, une reprise d’un jour contribue quatre et une reprise de quatre jours contribue un. Les séquences aux bords de l’horizon sont exclues de cette mesure.
+- [ ] Le seuil de la mesure de déficit est un entier strictement positif, initialement cinq. Une règle personnelle utilisant un autre seuil, par exemple trois, calcule son propre déficit et peut produire un autre arbitrage ; il ne s’agit pas d’un seuil impératif de validité.
+- [ ] Les conditions de sélection, mesures, unités et paramètres compatibles sont contrôlés à l’édition et à l’entrée du calcul. Une collection vide ou des séquences internes vides respectent la valeur zéro définie au ticket 01.
+- [ ] Deux règles portant sur la même famille mais ayant des paramètres distincts sont évaluées séparément selon leur position. L’évaluation et les caches éventuels ne confondent pas les configurations sur la seule base du type de mesure.
+- [ ] Les placements choisis respectent les obligations, les préférences supérieures et les jours déclarés. Désactiver une règle retire son influence, y compris lors de la recherche de placements d’appoint, sans conserver une protection fixe de la longueur maximale ou du déficit.
+- [ ] L’interface, la restauration, le worker, l’explication, la trace et les comparaisons contrefactuelles utilisent la même configuration capturée. Les libellés distinguent jours travaillés, seuil de préférence et unité de la mesure.
+- [ ] Les tests prolongent les suites de statistiques et de planification : bords de l’horizon, séquences vides, jours déclarés, seuil initial, autre seuil, deux règles paramétrées, priorité face à une règle personnelle et désactivation. Les vérifications portent sur les placements et valeurs observables, y compris après rechargement.
+
+**Vérification de bout en bout :** Créer une préférence de reprise courte à cinq jours, constater sa mesure et le plan, puis la modifier à trois jours et recalculer un cas discriminant ; retrouver le seuil et son effet après rechargement.
@@ -0,0 +1,22 @@
+# 05 — Piloter l’économie des jours d’appoint
+
+**GitLab:** [#74](https://gitlab.nessar.fr/nessar/vac-optimizer/-/work_items/74)
+
+**What to build:** L’utilisateur ajoute une préférence « Économiser les jours d’appoint » et décide, par sa position, jusqu’où les améliorations du planning peuvent consommer des congés qui expirent après l’horizon.
+
+**Blocked by:** 03 — Composer les règles de semaines fériées et de repos ; 04 — Composer les règles de séquences de travail.
+
+**Status:** ready-for-agent
+
+Tranche d’économie des placements d’appoint de l’ADR 0008, sur la branche d’intégration commune. Les tickets 03 et 04 fournissent les objectifs qui peuvent justifier ces placements et contre lesquels cette préférence doit être vérifiée. La migration globale est réservée au ticket 06.
+
+- [ ] Permettre de créer, éditer, activer, désactiver, supprimer, réordonner et sauvegarder une règle qui minimise le nombre de placements d’appoint selon le contrat commun.
+- [ ] Compter uniquement les placements d’appoint au sens du domaine : des placements supplémentaires issus de soldes expirant après l’horizon pour améliorer le plan. Les placements explicitement demandés par une règle ne deviennent pas tous des placements d’appoint parce que leur solde expire plus tard.
+- [ ] En position supérieure aux objectifs de calendrier ou de séquences de travail, cette préférence peut empêcher des ajouts d’appoint qui amélioreraient seulement ces objectifs inférieurs. En position inférieure, elle économise des placements sans dégrader les objectifs supérieurs ni les obligations.
+- [ ] La suppression, le déplacement ou la réaffectation d’un placement conserve une classification et une provenance cohérentes. Les conditions chronologiques des congés gagnés et les soldes disponibles restent valides.
+- [ ] Désactiver cette règle retire son critère de comparaison ; aucune étape fixe ne rétablit la minimisation du nombre de placements d’appoint. Sa désactivation ne déclenche pas à elle seule de nouveaux placements : un objectif actif doit justifier un ajout.
+- [ ] Les cas à égalité sur les règles actives conservent les départages finaux par expiration puis dates. Un objectif supprimé ne réapparaît pas sous forme de départage caché.
+- [ ] La gestion dans l’interface, la persistance et les commandes au clavier traversent jusqu’au calcul réel. Explications, trace et analyses contrefactuelles rendent compte de la règle active et de la contribution des placements concernés.
+- [ ] Adapter les tests existants sur la conservation de provenance et l’économie des placements d’appoint. Ajouter des arbitrages vérifiables contre une amélioration de calendrier et contre une amélioration des séquences de travail, avec inversion des priorités et comparaison entre désactivation et absence.
+
+**Vérification de bout en bout :** Comparer un plan qui ajoute des jours d’appoint pour améliorer le repos à un plan où la préférence d’économie est remontée ; montrer les jours consommés, les soldes conservés et l’objectif décisif.
@@ -0,0 +1,26 @@
+# 06 — Migrer les règles sauvegardées et valider l’ensemble
+
+**GitLab:** [#75](https://gitlab.nessar.fr/nessar/vac-optimizer/-/work_items/75)
+
+**What to build:** Au prochain chargement, l’utilisateur retrouve ses règles et les six anciens comportements du moteur sous forme de préréglages actifs. Il peut ensuite les modifier ou les supprimer durablement, et l’ensemble est validé avant sa mise en service.
+
+**Blocked by:** 05 — Piloter l’économie des jours d’appoint.
+
+**Status:** ready-for-agent
+
+Livraison intégrée de l’ADR 0008 sur la branche commune aux tickets 01 à 05. La préservation des données enregistrées et la migration unique ont été explicitement approuvées : ne pas réinitialiser les données pour simplifier le changement de contrat.
+
+- [ ] À l’initialisation, fournir les six préréglages actifs avec cet ordre : prévention des pertes, règles personnelles ou règles initiales existantes dans leur ordre, semaines fériées, gain de jours non ouvrés, séquence maximale, déficit des reprises et économie des placements d’appoint.
+- [ ] Migrer une seule fois les listes enregistrées avant cette évolution, y compris une ancienne liste vide. Préserver intégralement l’identité, le nom, les paramètres, les dates, la force, l’activation et l’ordre relatif des règles existantes.
+- [ ] Enregistrer de façon cohérente les règles migrées et le fait que la migration a eu lieu. Ne pas considérer l’opération terminée si les règles n’ont pas été sauvegardées ; gérer les échecs de stockage sans écraser les données utilisateur valides.
+- [ ] Les chargements suivants ne dupliquent pas les préréglages, ne rétablissent pas ceux supprimés et ne réactivent pas ceux désactivés. Une liste vidée volontairement après migration reste vide. Les nouveaux utilisateurs reçoivent directement la nouvelle configuration initiale.
+- [ ] La restauration et la migration précèdent le premier calcul utilisant ces données. L’utilisateur peut immédiatement éditer les six configurations avec les mêmes commandes que ses règles personnelles et retrouver ses choix après rechargement.
+- [ ] Vérifier de bout en bout les six préréglages dans l’ordre initial, leurs réordonnancements et leurs désactivations. Une configuration personnelle différente d’un préréglage traverse édition, sauvegarde, worker, calcul et explication ; les paramètres ont un effet vérifiable.
+- [ ] La liste entièrement désactivée, la liste supprimée après migration et une requête directe sans règle active n’ajoutent aucun congé malgré des soldes à risque. Les jours déclarés, les quantités restantes et les raisons pertinentes restent cohérents.
+- [ ] Les obligations conjointes, les conditions des congés gagnés et les contraintes de validité sont respectées pour tout ordre des préférences. Une annulation restitue le meilleur plan valide disponible et sa trace originale selon la configuration soumise.
+- [ ] Les explications et analyses contrefactuelles utilisent le même ordre actif que le calcul. Modifier les règles durant le calcul ou pendant la livraison tardive de la trace ne change pas ses résultats. Les anciens objectifs implicites n’interviennent plus dans aucune comparaison ou protection.
+- [ ] Les fixtures et scénarios de benchmark qui dépendaient d’une optimisation implicite demandent explicitement les préréglages nécessaires. Les tests d’absence de règles n’utilisent aucun défaut implicite pour retrouver l’ancien résultat.
+- [ ] Exécuter les suites concernées de règles, interface, moteur, worker réel, explication, annulation et estimation de durée, ainsi que les contrôles habituels de compilation et de qualité. Vérifier les scénarios de benchmark existants, dont les horizons longs, pour le déterminisme, la réactivité et les durées, sans introduire de délai d’arrêt automatique.
+- [ ] La vérification commune des tickets 01 à 06 est la condition de mise en service. Documenter les choix finaux du contrat composable et les limites mesurées ; ne laisser ni double moteur, ni chemin historique implicite, ni adaptateur provisoire ajouté pour rendre les étapes indépendamment livrables.
+
+**Vérification de bout en bout :** Partir d’une ancienne sauvegarde contenant des règles personnalisées et désactivées, charger la nouvelle version, vérifier le premier calcul, modifier ou supprimer des préréglages, recharger et constater la conservation exacte des choix.