Files
petitspas/docs/33_MINI-SPEC-AGENDA.md
jmartinandCursor 7f43dc1778 docs(agenda): lier mini-spec 33 aux tickets #214–#227
Table de découpage avec liens Gitea ; croisement #187/#165.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 16:10:27 +02:00

239 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Mini-spec — Agenda desktop (vue semaine)
> **Statut :** figée pour backlog (oct. 2026) — **vue semaine uniquement**
> **Réf. visuelle :** [maquettes/courantes/maquette-agenda-semaine-v4.jpg](./maquettes/courantes/maquette-agenda-semaine-v4.jpg)
> **Remplace :** règles Agenda / absences des [31](./31_MINI-SPEC-QUOTIDIEN-PARENT-AM.md) §5 et [32](./32_MINI-SPEC-BULLES-CARTES.md) quand elles contredisent ce document
> **Hors lot :** vue mois, mobile, RPE, export Contrat, filtres type (F8 V1.1), Google/offline
## 1. Objectif
Remplacer le corps du TdB par un **Agenda desktop** (parent + AM) en **vue semaine** : lecture dense du planning, création / modification / annulation douce des événements métier, accept/refus via la **même API cartes** que le Cahier.
La **source de vérité** est `evenements_agenda`. Les cartes du fil Cahier sont une **projection éphémère** (`purge_at`) du même objet.
## 2. Sous-bandeau
`Ajouter` · `Semaine` · `Mois` · `Tous mes agendas` · `Aujourd’hui` · `−3` · `+3`
| Bouton | V1 |
|--------|-----|
| Semaine | Vue active (défaut) |
| Mois | Présent ; message « Vue mois bientôt disponible » ; reste en semaine |
| Tous mes agendas | Superposition multi-placements (fantômes multi-agendas + regroupement `id_lot`) |
| Aujourd’hui | Recentré : semaine ISO courante au milieu de la zone visible (1–4 lignes) |
| −3 / +3 | Exactement **trois semaines ISO** (`Europe/Paris`) |
| Ajouter | Modale type Bulletin : congé/arrêt AM → toutes les familles ; soin → choix enfant ; absence → choix enfant + case « toutes mes nounous » (décochée) |
Préférence V1 : `jours_affiches_semaine` seulement (défaut lun–ven). `vue_agenda_defaut` reportée au lot mois.
## 3. Grammaire vue semaine
### Structure
- 1 **ligne** = 1 **semaine ISO** (`Europe/Paris`) ; n° à gauche (`S41`…).
- En-têtes colonnes **une seule fois** : Lundi…Vendredi (selon prefs).
- Case : libellé **`5 oct`** (jour + mois 3 lettres) + contenu.
- Scroll rouleau + fade haut/bas.
- **Hauteur d’une ligne** = hauteur du jour le plus chargé de cette semaine ; les autres colonnes prennent la même hauteur.
### Ordre dans une journée
1. Événements journée entière / multi-jours (maître ou fantôme).
2. Événements avec heure, ordre chronologique.
3. À égalité : `cree_le`.
### Multi-jours (fantômes de plage)
- **Carte maître** (infos + actions) sur le 1er jour de la plage **dans les colonnes affichées**.
- Si le vrai début est hors viewport : le **premier jour visible** devient maître temporaire.
- Autres jours : fantôme même teinte, plus léger, libellé court (`Congé`) — pas de détails.
- Clic fantôme → **même fiche** que la maître ; aucune action sur le fantôme.
- A11y : `Semantics` complet sur la maître ; `ExcludeSemantics` sur fantômes et illustrations. Un maître temporaire ne duplique pas les actions dans l’arbre sémantique.
### Densité des cartes Agenda
- Texte + couleur ; grosse illustre métier **interdite**.
- Ex. soin : `18h19 · Piqûre` + motif court.
- Pas de lien « Ouvrir dans l’agenda » (réservé au Cahier).
### Jour vide
- Illustre décorative **uniquement** si la case n’a ni événement ni fantôme.
- Choix **déterministe** dérivé de la date.
- Pack ~10 assets (ticket D1) ; F4 peut démarrer avec 2 provisoire.
### Chargement
- Préchargement **2–3 semaines** avant et après le visible ; cache ; debounce ; **pas d’éviction** V1.
- Même store pour scroll, −3/+3, Aujourd’hui.
- Dédupliquer les requêtes concurrentes ; après reconnexion socket, recharger la fenêtre visible.
- Ancre de scroll = première semaine visible (pas un offset pixel).
### Jours masqués
- Indicateur discret « N événements samedi » cliquable → liste accessible.
- Prefs invalides → repli lun–ven.
### Dates / DST
- Dates métier = type `date` calendaire ; API = `YYYY-MM-DD` (+ `HH:mm` pour l’heure soin).
- Le front **ne parse jamais** une date jour via `Date` UTC.
- Tests autour du dernier dimanche d’octobre.
## 4. Sources de vérité & annulation douce
| Couche | Rôle |
|--------|------|
| `evenements_agenda` | Vérité durable |
| `card_instances` | Projection file d’attention (`purge_at`) |
| `agenda_lots` | Cycle collectif (congé / arrêt / absence groupée) |
**Annulation douce = norme applicative** : jamais de `DELETE` physique carte/événement sur action utilisateur. Statut `annule` / `annulee` + timestamps. Cascades compte/placement = chantier RGPD (hors promesse ici).
**AC critique :** après sortie du fil (`purge_at`), `POST /cards/:id/respond` et la lecture Agenda fonctionnent encore.
Fin de placement : l’accès historique **ne dépend plus** de `date_fin IS NULL`.
## 5. Matrice temporelle
| Type | Création | Édition | Verrou |
|------|----------|---------|--------|
| `soin_enfant` | Date ∈ [hier, aujourd’hui] | Correction/suppression ≤ **24 h** depuis `cree_le` | Gelé après 24 h |
| `conge_am` | Passé OK (pas la norme) | Dates → **nouvelle `revision`** (unanimité, +7 j) ; motif seul ne relance pas | Gelé 7×24 h après soumission **sauf** congé **futur** (modifiable/annulable tant que `date_debut` non commencé) |
| `arret_maladie_am` | Passé OK | Dates ≤ 7×24 h ; **accepté dès soumission** | Pas de cycle de validation |
| `absence_enfant` | Passé OK | ≤ 7×24 h | Acceptée à la création |
- `verrouille_le` écrit à la soumission/resoumission — **jamais pendant un GET**.
- Échéances (auto-valid J+7 congé, disparition refusés J+7) : tâche `@nestjs/schedule` idempotente, rattrapée au redémarrage, fanout sockets.
- Auto-validation J+7 = **statut opérationnel P’titsPas**, pas un accord juridique.
## 6. Congé AM — unanimité (V1)
Cadre légal (IDCC 3239 art. 102.1.1) : hors V1 pour le cas « AM fixe seule ». Le RPE futur = médiateur avec bouton inaltérable dans l’outil ; côté parents = **carte AM**.
### Création
- Envoyée à tous les **placements connus et non terminés** au moment de la soumission.
- Technique : 1 lot versionné + 1 carte + 1 événement **par placement** (y compris 2 enfants d’un même foyer = 2 validations).
- Co-parents d’un placement : première réponse gagne.
### Unanimité
- Tous acceptent → validé pour tous.
- Un refus → **tout le lot refusé** (barré partout).
- Silence 7 j → auto-validé (statut P’titsPas).
### Modification / resoumission
- **Toute modification de dates** (attente, refusé ou validé futur) → nouvelle `revision`, toutes les familles revalident, nouveau cycle 7 j.
- Nouvelles dates **remplacent immédiatement** les anciennes (affichées en attente).
- Refusé visible 7 j (« refusé — à resoumettre ») puis soft-cancel auto.
- AM : Resoumettre / Modifier / Supprimer + « Disparaît dans N j ».
- Parents : « Refusé par une autre famille » / « Refusé par l’autre parent » — sans action.
### Nouvelle famille
- À la création d’un placement : congés futurs (validés ou en attente) de l’AM ajoutés **en attente** pour ce seul placement.
- Si le lot était validé : anciens parents gardent « validé » (pas de carte) ; AM voit « validé — réponse du nouvel accueil en attente ».
- Si le nouveau refuse : lot refusé ; **cartes des anciens parents ranimées** (`remonte_le` + `purge_at` recalculés).
### Annulation d’un congé futur validé
- Soft-cancel du lot + **carte ranimée** opération `cancel` (info, sans réponse) par placement — pas un socket seul.
## 7. Arrêt maladie AM
- Envoi collectif (`id_lot`) à toutes les familles.
- **Validé dès la soumission** (`accepte`) — aucun cycle ni délai 7 j de validation.
- Pastille « Bien reçu » = **informatif seulement** (ack carte ; **n’écrit plus** sur l’événement — sinon 400 avec le code actuel).
- Prolongation : édition des dates ≤ 7 j, ou second arrêt **consécutif** (pas de chevauchement).
## 8. Absence enfant
- Défaut : couple courant.
- Case « toutes mes nounous » : 1 absence par placement actif des enfants du parent, même `id_lot` (affichage groupé seulement).
- Acceptée à la création.
## 9. Chevauchements
Même placement, même famille de type, périodes qui se recoupent, hors annulés :
| Situation | Effet |
|-----------|--------|
| Nouvelle demande chevauche un **refusé** (congé) | Ancien soft-cancel + message « remplace… » |
| Chevauche **en attente / validé** | Création **bloquée** : « modifiez-le » |
| Arrêt / absence | Seule branche « bloqué » (pas de refus) |
| Dates qui se suivent | OK (pas un chevauchement) |
| Soins | Pas de règle |
## 10. Fil Cahier
- Tri : **`COALESCE(remonte_le, cree_le) DESC`** (plus de tri par statut).
- `remonte_le` nul en vie normale ; renseigné uniquement à la **réanimation**.
- Ranimer = aussi recalculer `purge_at`.
- `absence_enfant_modif` **abandonné**.
## 11. Contrat API (enrichissements)
### Événement (DTO)
`id`, `id_placement`, `id_lot`, `id_card_instance`, `type`, `date_debut`, `date_fin`, `heure`, `statut`, `statut_effectif` (vue utilisateur), motif, identité enfant/AM, droits/actions calculés, timestamps.
**Aucun secret** sur l’auteur d’un refus d’une autre famille.
### Liste
`GET` filtrable `from`/`to` inclusifs : `date_debut <= to AND date_fin >= from` ; exclusion `annule` ; historique post-fin de placement.
### Cartes
Accept/refus/ack = **`POST /cards/:id/respond`**.
PATCH/DELETE/resoumission créateur = **lot-aware** depuis n’importe quelle carte représentante.
### Préférences
`users.preferences` JSONB ; PATCH fusionne `jours_affiches_semaine` (1–7 jours ISO uniques) sans écraser le reste.
## 12. Schéma BDD (ticket B0 — premier)
- Table `agenda_lots` : `id`, type, statut global, `revision`, `soumis_le`, `verrouille_le`, `refuse_le`, `annule_*`, créateur, timestamps.
- `evenements_agenda` : enum `annule`, champs soft-cancel, `verrouille_le`, `refuse_le`, `heure`, `id_lot` FK.
- `card_instances` : `id_lot`, opération `cancel`, statut soft-cancel, `remonte_le`.
- `card_responses` : `revision_lot`.
- `users.preferences` JSONB défaut `{}`.
- Index lecture + backfill + `BDD.sql` + migration + `verify.sql`.
## 13. Invariants de recette
1. Mutation carte/événement/lot **atomique**.
2. Une réponse comptée une fois, placement + `revision` courante ; première réponse co-parents gagne.
3. Aucun GET ne change un statut.
4. Événement annulé hors vues normales, auditable ; carte purgée adressable depuis Agenda / ranimable.
5. Fin d’accueil ≠ perte d’historique autorisé.
6. Mini-specs 31/32 ne contredisent plus silencieusement la 33.
## 14. Découpage tickets
| Id | Issue | Périmètre |
|----|-------|-----------|
| **B0** | [#214](https://git.ptits-pas.fr/jmartin/petitspas/issues/214) | Migration BDD (bloquant) |
| **B1** | [#215](https://git.ptits-pas.fr/jmartin/petitspas/issues/215) | GET :id + DTO enrichi |
| **B2** | [#216](https://git.ptits-pas.fr/jmartin/petitspas/issues/216) | Matrice + soft-cancel + no-DELETE carte + cron + ack arrêt sans maj événement + tests |
| **B3** | [#217](https://git.ptits-pas.fr/jmartin/petitspas/issues/217) | Filtres from/to, historique placement terminé |
| **B4** | [#218](https://git.ptits-pas.fr/jmartin/petitspas/issues/218) | Prefs `jours_affiches_semaine` |
| **B5** | [#219](https://git.ptits-pas.fr/jmartin/petitspas/issues/219) | Lots / unanimité / chevauchements / nouvel accueil / cartes ranimées |
| **B6** | [#220](https://git.ptits-pas.fr/jmartin/petitspas/issues/220) | Tri fil `COALESCE(remonte_le, cree_le) DESC` |
| **D1** | [#221](https://git.ptits-pas.fr/jmartin/petitspas/issues/221) | Pack ~10 illustrations jour vide |
| **F1** | [#222](https://git.ptits-pas.fr/jmartin/petitspas/issues/222) | Coquille + sous-bandeau + store |
| **F4** | [#223](https://git.ptits-pas.fr/jmartin/petitspas/issues/223) | Vue semaine (prioritaire) — maquette v4 |
| **F5** | [#224](https://git.ptits-pas.fr/jmartin/petitspas/issues/224) | Multi-agendas + dédoublonnage `id_lot` |
| **F6** | [#225](https://git.ptits-pas.fr/jmartin/petitspas/issues/225) | Prefs UI |
| **F7** | [#226](https://git.ptits-pas.fr/jmartin/petitspas/issues/226) | Sockets + recalc hauteur ligne |
| **F8** | [#227](https://git.ptits-pas.fr/jmartin/petitspas/issues/227) | Filtres type — **V1.1** |
| Hygiène | [#187](https://git.ptits-pas.fr/jmartin/petitspas/issues/187) fermé ; [#165](https://git.ptits-pas.fr/jmartin/petitspas/issues/165) commenté ; notes 31/32 | Stub Contrat ; croisement quotidien |
**Ordre :** B0 → B1–B6 + D1 → F1 → F4 → F5–F7.
## 15. Hors périmètre
Mobile ; vue mois ; RPE / congé inaltérable ; export Contrat ; redesign modales ; deep-link ; F8 ; sync Google / offline.