# Phase 1 — implémentation documentaire et planning interne

Date : 22 août 2026  
Base de vérification : copie locale de la base MariaDB issue de la VM  
Périmètre : fondations V1, sans moteur d'optimisation complet.

Version : `0.1.0-dev.4` → `0.1.0-dev.5` (`676becd`).

## Migration

`g1a2b3c4d5e6_phase1_documents_planning.py` (depuis
`9f4a1b2c3d5e`) ajoute :

- `document_type` indexé à `intervention_documents` et
  `equipment_documents`, avec valeur historique `autre` ;
- provenance, identifiant externe, synchronisation, protection, statut de
  résolution, période de validité, type d'événement et conflit à
  `room_schedules` ;
- permission `documents.view` et ses attributions aux rôles métier existants.

La migration est idempotente sur les colonnes et préserve les lignes
existantes. Aucun fichier ni document métier n'est copié.

## Centre documentaire

Le service `app_new/documents/service.py` fournit des adaptateurs de lecture
pour `InterventionDocument`, `EquipmentDocument` et `ProductDocument`.
Chaque résultat expose sa source, son objet parent, son type, sa date, son
contexte, son téléchargement et sa localisation calculée. Les produits avec
plusieurs soldes affichent plusieurs emplacements.

Routes ajoutées :

- `/documents/` : recherche, filtres source/type/période, pagination ;
- `/documents/fds` : vue FDS des produits accessibles ;
- `/documents/download/<source>/<id>` : contrôle RBAC, racine de stockage,
  existence du fichier et nom de téléchargement.

Le lien de navigation est conditionné à `documents.view`. Les permissions de
lecture du module source restent obligatoires ; aucune permission
`documents.manage` ou `documents.download` n'est créée.

## Planning interne des salles

`app_new/core/services/room_planning.py` est la vue résolue commune. Elle
ignore les créneaux désactivés/supplantés, permet à Pronote de supplanter un
manuel non protégé, conserve un manuel protégé et signale les conflits.
`sync_pronote_schedules()` reçoit uniquement des données normalisées et ne
contacte pas Pronote.

Routes ajoutées : `/planning/rooms` et `/planning/rooms/new`, avec protection
manuelle exprimée en français. Les détails de salle et l'affichage Pronote
réutilisent la résolution interne.

## Préventif et disponibilité

`PlanningService` délègue désormais la disponibilité de salle au service
interne. La durée existante d'une `ScheduledTask` est utilisée pour le contrôle
de créneau ; aucun solveur, replanificateur ou moteur multi-techniciens n'est
inclus dans cette phase.

## Tests et données

- `tests/integration/test_phase1_documents_planning.py` : 3 scénarios ciblés ;
- `tests/unit/test_version.py` + scénarios Phase 1 : **5 passed** ;
- suites P1/formulaires/stock/interventions : 20 tests passants ;
- compte local `TEST_UI_PHASE1_ADMIN` conservé pour inspection manuelle ;
- aucune donnée `TEST_UI_*` supprimée et `alban` inchangé.

Après rebuild `gmao-college:0.1.0-dev.5`, les routes `/health/`,
`/documents/`, `/documents/fds` et `/planning/rooms` ont été revalidées en
HTTP 200 avec ce compte local.

La suite complète a donné **125 passed, 1 failed, 1 error**. Le seul échec
reste le test historique de configuration/lookback GMAO et son teardown
`gmao_context.user_id` ; cette zone est interdite et aucun nouvel échec n'a
été introduit.

## Limites restantes

- synchronisation Pronote réelle et résolution de rapprochements ambigus à
  brancher sur l'intégration existante ;
- optimisation journalière, replanification, tâches multi-techniciens et
  classeur FDS hors périmètre ;
- revalidation VM distante et campagne complète responsive/accessibilité à
  effectuer séparément.
