Ajoute 33_MINI-SPEC-AGENDA.md (référence produit/API), versionne la maquette agenda-semaine-v4 et archive v2/v3, pointe 31/32 vers la 33 pour les règles Agenda obsolètes. Co-authored-by: Cursor <cursoragent@cursor.com>
241 lines
12 KiB
Markdown
241 lines
12 KiB
Markdown
# 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
|
||
|
||
> Numéros Gitea à reporter ici après création (`link-numbers`).
|
||
|
||
| Id | Périmètre |
|
||
|----|-----------|
|
||
| **B0** | Migration BDD (bloquant) |
|
||
| **B1** | GET :id + DTO enrichi |
|
||
| **B2** | Matrice + soft-cancel + no-DELETE carte + cron + ack arrêt sans maj événement + tests |
|
||
| **B3** | Filtres from/to, historique placement terminé |
|
||
| **B4** | Prefs `jours_affiches_semaine` |
|
||
| **B5** | Lots / unanimité / chevauchements / nouvel accueil / cartes ranimées |
|
||
| **B6** | Tri fil `COALESCE(remonte_le, cree_le) DESC` |
|
||
| **D1** | Pack ~10 illustrations jour vide |
|
||
| **F1** | Coquille + sous-bandeau + store |
|
||
| **F4** | Vue semaine (prioritaire) — maquette v4 |
|
||
| **F5** | Multi-agendas + dédoublonnage `id_lot` |
|
||
| **F6** | Prefs UI |
|
||
| **F7** | Sockets + recalc hauteur ligne |
|
||
| **F8** | Filtres type — **V1.1** |
|
||
| Hygiène | #187 stub Contrat ; #165 ; notes 31/32 |
|
||
|
||
**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.
|