gmao/docs/ui-audit/PLANNING_ENGINE_PROPOSAL.md

Moteur de planification interne — proposition d'architecture

Statut : étude et spécification uniquement. Aucun modèle, route, migration, synchronisation ou changement applicatif n'est créé par ce document.

A. Architecture actuelle

Le dépôt possède déjà plusieurs briques réutilisables :

• Room et RoomSchedule (app_new/core/models/college.py) pour les salles et un emploi du temps hebdomadaire (week_start, jour, début/fin, matière, enseignant, classe) ;
• WorkSchedule, WorkScheduleTemplate, TechnicianAvailability, PersonalLeave, Training, CollegeClosure, ClosureSchedule et ClosureWorkDay (app_new/core/models/planning.py) pour horaires, pauses, absences, formations, fermetures et permanences ;
• PreventiveTask (durée, lot, équipement/catégorie, fenêtre autorisée), LotTask (durée, périodicité, sécurité) et ScheduledTask (date, début, fin, durée, salle, équipement, entreprise, contrat, technicien, statut) ;
• Intervention avec date planifiée, priorité, salle/équipement, technicien et entreprise ;
• AdminTask, actuellement récurrente avec heure et durée ;
• PlanningDay/PlanningItem, qui représentent déjà prévention, curatif, administratif et formation avec durée, salle, priorité et statut.

planning_service.py sait produire une journée et calculer des heures de travail, mais schedule_task ne place pas réellement de créneau et la disponibilité de salle n'est pas croisée avec toutes les tâches internes. L'implémentation interroge en outre un symbole PronoteSchedule alors que le modèle local de salle observé est RoomSchedule : cette dette doit être résolue avant d'automatiser la disponibilité.

B. Limites actuelles

1. RoomSchedule ne conserve pas de provenance, identifiant externe, validité ou récurrence explicite.
2. Le service de planification peut retomber sur 08:00–17:00 et certaines requêtes d'horaires/indisponibilités ne filtrent pas toujours par agent.
3. Les conflits salle, tâches, pauses, fermetures et interventions ne sont pas évalués dans un même calendrier.
4. AdminTask ne porte ni statut d'exécution, priorité, agent ou fenêtre.
5. PlanningItem et ScheduledTask se recouvrent partiellement, ce qui peut produire des doublons d'affichage.
6. L'import Pronote est optionnel dans les routes mais ne doit jamais être une dépendance du calcul interne.

C. Principe de vérité interne

La GMAO possède des créneaux internes d'occupation. Chaque créneau conserve sa source : manual, pronote, import ou une future source. Les champs conceptuels sont source, external_id, last_synced_at, source_updated_at, période de validité et statut actif. Le métier parle de créneau d'occupation interne ; il ne dépend jamais d'une réponse en direct de Pronote.

L'application doit démarrer et rester pleinement utilisable avec PRONOTE_ENABLED=false, sans token et sans synchronisation.

D. Saisie manuelle en début d'année

Une fonction de gestion crée les RoomSchedule de source manual à partir des salles, périodes, jours, heures et types d'occupation : cours, réunion, examen, réservation, travaux, intervention, fermeture ou autre. Les règles de validation refusent début ≥ fin et signalent les chevauchements. Une saisie manuelle est toujours conservée, même lorsqu'une source externe est absente.

E. Pronote facultatif

Pronote peut fournir des créneaux après configuration, mais ne possède jamais la source interne de vérité. La synchronisation ne doit lire/écrire que les créneaux qu'elle a créés (source=pronote, external_id connu).

F. Synchronisation et conflits

• Créneau manuel : jamais modifié ni supprimé automatiquement par Pronote.
• Créneau Pronote identique : mise à jour de ses champs et de last_synced_at.
• Créneau supprimé côté Pronote : désactivation du seul créneau Pronote correspondant ; aucune suppression manuelle.
• Collision manuel/Pronote : le manuel gagne, le conflit est signalé à l'utilisateur avec les deux provenances.
• Pronote indisponible : conserver les dernières données importées, marquer leur fraîcheur et afficher un avertissement ; ne jamais vider le planning.
• Donnée Pronote obsolète : elle peut être désactivée selon une politique de rétention explicite, jamais effacée silencieusement.

G. Disponibilité des salles

Le calcul croise les occupations internes, fermetures de salle/collège, interventions, tâches planifiées, rendez-vous d'entreprises et permanence. Les catégories d'occupation sont celles de la saisie manuelle. Une tâche de 45 minutes peut occuper 12:00–12:45 entre deux cours si le technicien est également disponible ; les créneaux hors horaires, pause ou fermeture sont exclus.

Le futur service doit utiliser RoomSchedule pour les cours importés ou manuels et ScheduledTask/PlanningItem/Intervention pour les activités internes, sans appeler Pronote en direct.

H. Préventif et lots

PreventiveTask et LotTask fournissent la périodicité, la durée, la portée, les restrictions d'accès et le caractère critique. ScheduledTask est la source d'exécution d'un travail généré : lot, tâche, équipement/local, date cible, durée, début/fin, priorité, statut, entreprise/contrat et technicien.

Les créneaux proposés doivent afficher quoi, où, quand, durée et refuser une date dépassant une échéance de conformité. Une intervention convertie ne doit pas être affichée deux fois.

I. Horaires de travail

Le moteur utilise le WorkSchedule de l'agent, les templates, pauses, TechnicianAvailability, congés, formations, fermetures et ClosureWorkDay. Il ne planifie jamais sur la pause ou hors intervalle. La V1 doit exiger un agent explicite pour une proposition automatique et ne pas inventer 08:00–17:00 lorsque la configuration manque ; l'absence de données doit être expliquée.

J. Tâches administratives

Les tâches administratives sont des activités planifiables qui consomment du temps : commande, devis, compte rendu, registre, dossier ou appels. La V1 doit compléter le modèle actuel par une durée, priorité, statut, fenêtre/date, heure planifiée et responsable, ou projeter ces données dans PlanningItem. Une récurrence ne doit pas masquer l'instance réellement faite ou reportée.

K. Entreprises extérieures

Un rendez-vous doit représenter au minimum entreprise, date/heure fixe, intervention/contrat lié, durée d'accueil, accompagnement, éventuels passages et temps administratif final. Pour la V1, réutiliser ScheduledTask/PlanningItem avec company_id et un type d'étape simple (accueil, contrôle, signature) plutôt que créer un système de calendrier externe. Une entité ExternalCompanyAppointment séparée ne sera justifiée que si plusieurs étapes doivent être suivies indépendamment.

L. Urgences et contraintes

Les niveaux compréhensibles sont :

• Fixe : rendez-vous entreprise ou examen à heure imposée ;
• Urgent : fuite, sécurité ou panne critique ;
• Échéance : conformité ou tâche à terminer avant une date ;
• Déplaçable : prévention réalisable dans la fenêtre ;
• Administratif : travail planifiable avant une échéance.

Une urgence peut interrompre ou repousser, mais le système conserve chaque tâche, son ancien créneau, sa raison et sa nouvelle proposition.

M. Optimisation géographique

La première version calcule un coût ordinal simple : même salle (0), même zone (1), même bâtiment (2), autre bâtiment (3). Ce coût ne passe jamais avant sécurité, rendez-vous fixe, échéance, disponibilité, horaires et compétences. Il sert uniquement à départager des créneaux équivalents, sans GPS ni tournée complexe.

Ordre d'arbitrage : urgence/sécurité, rendez-vous fixe, échéance, disponibilité salle, horaires, compétence/affectation, regroupement géographique, réduction des trous.

N. Replanification et contrôle humain

Lorsqu'une urgence arrive à 10:00, l'interface propose les tâches décalables, les conserve avec leur historique et expose les créneaux alternatifs. Elle classe chaque élément en conservé, décalé, non planifiable ou nouvelle proposition. Une validation humaine est obligatoire ; aucun déplacement silencieux.

Un déplacement manuel revalide conflit salle, horaires, pauses, autre tâche, rendez-vous fixe et fermeture. Le message doit être métier : « Salle 101 occupée jusqu'à 11:00 », avec créneaux disponibles.

O. Multi-techniciens futur

La colonne actuelle assigned_to_id convient à la V1 mono-agent, mais ne doit pas devenir une contrainte conceptuelle. Une évolution pourra ajouter une association PlannedTaskAssignee (tâche, utilisateur, rôle), avec preferred_technician, required_skill et required_people_count. Une personne préférée n'est pas une personne assignée ; une compétence requise est une contrainte, pas une préférence. Deux personnes seront représentées par deux affectations liées à la même activité.

P. Modèle de données recommandé

Réutiliser au maximum les tables présentes :

1. Étendre RoomSchedule : source, external_id, horodatage de synchronisation, validité, type/libellé et statut actif. Index futur sur (room_id, week_start, day_of_week, start_time, end_time, source).
2. Conserver ScheduledTask comme échéance/exécution préventive ; ajouter ultérieurement contrainte de priorité et fenêtre si les champs existants ne suffisent pas.
3. Utiliser PlanningItem comme projection de placement (date, début, fin, durée, salle, statut, priorité) et imposer une règle anti-doublon avec les références scheduled_task_id/intervention_id/admin_task_id.
4. Étendre AdminTask ou sa projection pour responsable, statut, priorité et fenêtre, sans perdre la récurrence.
5. Rendez-vous entreprise : d'abord ScheduledTask/PlanningItem avec company_id; créer ExternalCompanyAppointment seulement si les étapes deviennent des objets suivis.

Chaque futur index doit couvrir les requêtes par date/statut, salle/intervalle et agent. Aucune table de planning parallèle ne doit être créée sans preuve que PlanningItem ne peut pas être consolidé.

Q. Migrations futures

Les extensions ci-dessus nécessiteront des migrations Alembic non destructives, avec valeurs par défaut (source=manual, statut actif) et backfill explicite des RoomSchedule existants. Les données Pronote historiques ne doivent pas être confondues avec le manuel : si leur origine est inconnue, les marquer import et demander validation.

R. Algorithme V1 déterministe

1. Construire les intervalles de travail de l'agent, en retirant pauses, congés, formations, fermetures et permanences incompatibles.
2. Construire les intervalles occupés de la salle et du planning interne.
3. Générer les créneaux possibles par durée et fenêtre.
4. Éliminer conflits, hors horaires, échéances et rendez-vous fixes.
5. Classer par contrainte puis coût géographique, puis heure la plus proche.
6. Retourner une proposition explicable, sans commit automatique.

Une heuristique simple est préférable à un solveur d'optimisation complet : elle est déterministe, testable, lisible et réversible.

S. Interface proposée

Vue journalière

Afficher pour chaque bloc : heure, bâtiment/zone/salle, titre, catégorie (préventif, curatif, urgent, administratif, entreprise), durée, statut et contrainte. Un panneau « Propositions » explique les créneaux refusés.

Gestion des salles

Calendrier par salle/semaine, saisie manuelle claire, provenance visible et indication « données Pronote anciennes » sans bloquer le planning interne.

Conflits

Afficher la cause, la ressource concernée et deux ou trois créneaux compatibles. L'utilisateur choisit et confirme.

T. Tests à prévoir

• salle libre/occupée et chevauchement ;
• planning manuel sans Pronote ;
• Pronote désactivé, indisponible, puis synchronisé ;
• conflit manuel/Pronote et suppression distante ;
• préventif de 45 minutes entre deux cours ;
• durée/échéance d'une tâche liée à un lot ;
• pause, horaires hors travail, fermeture et permanence ;
• tâche administrative récurrente, réalisée et reportée ;
• entreprise avec accueil, accompagnement et signature ;
• urgence décalant deux tâches sans perte d'historique ;
• regroupement même salle/zone/bâtiment ;
• déplacement manuel vers rendez-vous fixe ;
• données sans agent/horaires explicites ;
• futur multi-techniciens compatible (test de structure, pas d'optimiseur).

U. Scénarios métier de validation

1. Début d'année manuel : saisir les créneaux de plusieurs salles, planifier une maintenance et vérifier l'absence de Pronote.
2. Mise à jour Pronote : importer un nouveau cours, modifier un cours importé et vérifier qu'un créneau manuel reste intact.
3. Panne Pronote : simuler une semaine sans connexion, conserver le dernier planning et afficher sa date de fraîcheur.
4. Préventif interstitiel : proposer 45 minutes entre deux cours en respectant la pause et le temps de travail.
5. Tournée locale : cinq préventifs de la même zone sont regroupés avant un autre bâtiment.
6. Entreprise fixe : rendez-vous chaudière à 09:00, accueil, contrôle, signature et temps administratif visibles.
7. Urgence : fuite à 10:00, conserver le rendez-vous fixe, décaler deux tâches déplaçables et faire valider la proposition.
8. Journée mixte : maintenance, commande, entreprise et intervention curative avec horaires et statuts cohérents.
9. Fermeture/permanence : proposer une tâche pendant une journée rouverte de vacances, refuser les dates fermées.
10. Salle indisponible : fermeture d'une salle, replanification vers une autre salle compatible sans modifier silencieusement l'objet métier.

V. MVP obligatoire

• planning interne des salles, saisie manuelle et provenance ;
• Pronote optionnel, import limité à ses propres créneaux ;
• durée, début/fin, statut et priorité des tâches ;
• respect horaires, pauses, fermetures et absences ;
• prévention/lot, interventions, tâches administratives ;
• rendez-vous entreprise simple ;
• urgences et propositions de replanification ;
• regroupement salle/zone/bâtiment ;
• déplacement manuel avec avertissements ;
• vue journalière lisible et déterministe.

W. Évolutions futures et décisions à valider

Plus tard : multi-techniciens avancé, compétences, absences détaillées, deux personnes par tâche, optimisation complexe, calcul de trajets, import d'autres sources et statistiques de charge.

Avant développement, valider :

1. RoomSchedule comme base des occupations internes et ses champs de provenance ;
2. la règle « Pronote ne modifie jamais le manuel » ;
3. l'usage de PlanningItem comme projection anti-doublon ;
4. le périmètre des tâches administratives et des étapes entreprise ;
5. le niveau de priorité/contrainte exposé aux utilisateurs ;
6. le comportement d'une donnée Pronote obsolète ;
7. la politique lorsque les horaires d'un agent sont absents ;
8. la future association multi-techniciens ;
9. les index et volumes acceptables pour la vue semaine/année.