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
une provenance (`manual`, `pronote`, `import`) et, conceptuellement, un
booléen `protected_from_sync`, un `external_id`, les horodatages de
synchronisation et une période de validité.

La distinction métier est la suivante :

- **manuel initial** : `source=manual`, protection désactivée ; il permet de
  démarrer avant Pronote et peut être supplanté par une donnée Pronote fiable ;
- **manuel protégé** : `source=manual`, protection activée ; il représente une
  décision locale explicite et ne peut être écrasé automatiquement ;
- **Pronote** : `source=pronote`, géré uniquement par la synchronisation qui
  l'a créé ;
- **import** : donnée issue d'une autre importation connue ou historique.

L'occupation active présentée au moteur de maintenance est une vue résolue :
elle ne contient pas deux fois un créneau manuel initial et son équivalent
Pronote. Pronote est une source de synchronisation, jamais le moteur de
planning de la GMAO. 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 des `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. Par défaut,
une saisie de cours destinée à l'initialisation est **non protégée**. Pour une
réunion exceptionnelle, un examen local, des travaux, une réservation,
intervention ou fermeture, l'utilisateur peut cocher une formulation métier
telle que « Ne pas modifier automatiquement ce créneau ».

La validation refuse début ≥ fin et signale les chevauchements. L'interface
affiche « Saisi manuellement » et, si nécessaire, « Protégé des mises à jour
automatiques » ; elle ne montre jamais le nom technique
`protected_from_sync`.

## E. Pronote facultatif

Lorsque Pronote devient disponible et fiable, il peut prendre progressivement
le relais sur les créneaux manuels **non protégés** correspondant à son emploi
du temps. Il ne modifie ni ne supprime les créneaux manuels protégés. Il ne
possède jamais la source interne de vérité : le service de synchronisation
résout d'abord les provenances et les conflits, puis le moteur consomme la vue
interne active.

## F. Synchronisation et conflits

### Rapprochement déterministe

Un créneau Pronote peut être rapproché automatiquement d'un manuel initial
uniquement si les critères stables concordent : même salle, même période de
validité, même jour/date et horaires identiques ou suffisamment proches,
complétés si disponibles par classe/groupe, matière et enseignant. La V1 ne
déduit pas une correspondance à partir d'un seul critère. Si la correspondance
est ambiguë, elle conserve les deux lignes, signale un conflit et demande une
validation humaine.

### Règles

- Manuel initial non protégé + Pronote correspondant : le créneau Pronote
  devient actif et le manuel initial est marqué supplanté/archivé ; il n'y a
  pas de doublon dans la vue d'occupation.
- Manuel initial non protégé + horaire Pronote modifié : le Pronote remplace
  l'ancien intervalle, qui n'est plus considéré comme une occupation active.
- Manuel protégé + Pronote chevauchant : le manuel reste actif, Pronote reste
  visible comme conflit ; rien n'est écrasé automatiquement.
- Créneau Pronote identique ou modifié : seule la ligne `source=pronote` avec
  `external_id` correspondant est mise à jour et son `last_synced_at` avancé.
- Suppression côté Pronote : désactivation de la ligne Pronote propriétaire.
  Un manuel initial supplanté reste archivé comme historique et ne redevient
  actif automatiquement que si une règle de réactivation explicite est
  validée ; par défaut, l'interface propose à l'utilisateur de le restaurer.
  Aucun manuel protégé n'est supprimé.
- Pronote indisponible : conserver tous les créneaux actifs connus, afficher
  la date de dernière synchronisation et un avertissement de fraîcheur ; ne
  jamais vider le planning.

Chaque transition laisse une trace minimale : créé manuellement, protégé ou
déprotégé, repris par Pronote, modifié par synchronisation, conflit détecté ou
désactivé car absent de Pronote. Cette trace doit rester compréhensible sans
imposer un moteur d'audit complexe en V1.

Le moteur de maintenance demande uniquement « quels sont les créneaux
d'occupation internes actifs de cette salle ? ». Il ne connaît ni la priorité
Pronote ni les règles de rapprochement.

## 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`, `protected_from_sync`,
   `external_id`, horodatage de synchronisation, validité, type/libellé,
   statut actif et, si nécessaire, référence au créneau supplanté. 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

Une migration non destructive ajoutera à `RoomSchedule` la provenance, la
protection, les identifiants/horodatages de synchronisation, la validité et le
statut. Les lignes existantes seront initialisées avec `source=manual` et
`protected_from_sync=false`, puis un écran de validation permettra de protéger
les exceptions locales. Les données Pronote historiques d'origine inconnue
seront marquées `import` et soumises à validation, jamais fusionnées à
l'aveugle. Le statut supplanté/archivé doit conserver le lien historique sans
réactiver automatiquement un faux créneau.

## 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 prend le relais sur un manuel initial non protégé ;
- Pronote modifie l'heure d'un manuel initial ;
- manuel protégé jamais écrasé ;
- conflit Pronote/réservation protégée ;
- Pronote désactivé ou indisponible ;
- retour de Pronote après plusieurs jours et fraîcheur affichée ;
- suppression côté Pronote et manuel initial supplanté ;
- absence de doublon manuel + Pronote ;
- rapprochement ambigu nécessitant validation humaine ;
- 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. **Rentrée progressive** : le gestionnaire saisit le planning manuellement,
   planifie immédiatement la maintenance, puis Pronote fonctionne quelques
   jours plus tard. Les cours compatibles reprennent les manuels initiaux,
   sans doublon ; une réservation protégée reste intacte.
2. **Mise à jour Pronote** : importer un cours correspondant, modifier son
   heure puis vérifier que seul le manuel initial non protégé est supplanté et
   que l'historique reste lisible.
3. **Panne Pronote** : simuler une semaine sans connexion, conserver le
   dernier planning Pronote connu et tous les manuels, avec date de fraîcheur.
4. **Retour de Pronote** : après plusieurs jours, synchroniser une nouvelle
   version, traiter une suppression distante et demander validation pour un
   rapprochement ambigu.
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/protection ;
2. la règle « Pronote peut supplanter le manuel initial non protégé, mais ne
   modifie jamais le manuel protégé » ;
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.

### Décision recommandée

Retenir l'**option A** : `source = manual | pronote | import` complétée par
`protected_from_sync` et un statut historique (actif, supplanté, désactivé).
Elle évite de multiplier les valeurs de provenance tout en distinguant
clairement le manuel initial du manuel protégé. La vue interne résolue est la
seule entrée du moteur de maintenance ; Pronote ne devient jamais une
dépendance fonctionnelle.