petitspas/docs/32_MINI-SPEC-BULLES-CARTES.md

# Mini-spec · Bulles / file d’attention (#173)

*Front · octobre 2026 — alignement product / API.*

---

## 1. Contexte / objectif

Les bulles (cartes) sont la **file d’attention** du quotidien parent / AM : décisions et infos proches (congés, arrêt maladie AM, absences, soins / bobos enfant…).

**Différence fondamentale avec le blog :**  
les cartes de ce fil sont des **événements d’agenda** (période, placement, historique métier loggé).  
Le **blog** = récit / mémoire narrative du jour (photos, texte) — pas une ligne d’agenda.

Les cartes restent une **mémoire courte** de file (`purge_at` sur la bulle) ; la **source de vérité agenda** reste le back métier.

Table agenda : **`evenements_agenda`** (ex-`absences_garde`, [#205](https://git.ptits-pas.fr/jmartin/petitspas/issues/205) fait) — conteneur ouvert (absences, congés, soins, école, mairie, sorties…). Les bulles notifient ; l’agenda historise.

Voir aussi `31_MINI-SPEC-QUOTIDIEN-PARENT-AM.md`.

Cette note formalise :
1. Ce qui est en place côté front (#173).
2. Le contrat API (sans couleur).
3. La **palette UI** (front only, dérivée du `type_code`).
4. La nouvelle famille **soins / bobo enfant** (rose) — AM → parents.
5. Idées futures.

---

## 2. Contrat API

Endpoint principal : `GET /api/v1/cards` (filtre couple / placement).

| Champ | Rôle UI |
|-------|---------|
| `type_code` | Layout + libellé + **couleur / icône (mapping front)** |
| `titre` | Fallback si `type_code` inconnu |
| `statut` | `ouverte` · `refusee` · `traitee` |
| `response_mode` | `none` · `ack` · `accept_refuse` |
| `is_creator` | Masque les boutons réponse pour le créateur |
| `payload.date_debut` / `date_fin` | Période (agenda) |
| `payload.motif` | Texte libre / détail |
| `last_refuse_comment` | Si `refusee` |
| `id_evenement` | Lien métier agenda (`evenements_agenda`, si applicable) — ex-`id_absence` (#205) |
| `purge_at` | Péremption de la bulle dans la file |

> **Front** : parser `id_evenement` (fallback éventuel `id_absence` uniquement pour anciennes fixtures / caches). Ne plus documenter ni dépendre de `id_absence` comme contrat.

**Pas de champ `couleur` dans l’API.**  
La teinte pastel est **100 % front** : table de mapping `type_code` → asset (`card_*_h.png`). Le back ne gère pas la charte graphique.

**Règle front :** le destinataire peut répondre si `!is_creator && statut == ouverte && response_mode != none`.

---

## 3. Évolutions front déjà livrées (#173)

### 3.1 Feed

- Widget partagé `CartesFeed` (parent + AM).
- Fond via widget `Carte` (9-slice horizontal) selon mapping local.
- Actions via **modales** accepter / refuser / ack.
- Libellés UI :
  - `conge_am` → « Demande de congés »
  - `arret_maladie_am` → « Arrêt maladie »
  - `absence_enfant` → « Notification d’absence »

### 3.2 Carte **congés** (`conge_am`)

| Élément | Comportement |
|---------|----------------|
| Fond | **Aqua** (mapping front) |
| Encre | Pétrole `#315F63` / dates `#4A7276` |
| Icône | Valise |
| Période | « Du … au … » + calendrier |
| Actions | Pilules ✓ / ✕ si `accept_refuse` |
| Lien | « Ouvrir dans l’agenda ↗ » |
| Opacité | Atténuée si `traitee` (sauf règle arrêt ci-dessous) |

### 3.3 Arrêt maladie AM (`arret_maladie_am`)

- Reste **visible / opaque** tant que `date_fin` (jour inclus) n’est pas passée, même si `traitee`.
- Fond **bleu** (mapping front).

### 3.4 Assets

Teintes UI : `red` · `pink` · `peach` · `lime` · `lavender` · `green` · `blue` · `aqua`.  
Clé = **choix front**, pas une valeur API.

---

## 4. Palette UI (front only — dérivée du `type_code`)

| Couleur UI | Famille | Types |
|------------|---------|--------|
| **`aqua`** | Congés AM | `conge_am` |
| **`blue`** | Arrêt maladie AM | `arret_maladie_am` |
| **`peach`** | Absence enfant / info pratique | `absence_enfant` |
| **`pink`** | Soins / bobo / problème **enfant** (AM → parents) | `soin_enfant` *(nouveau — voir §5)* |
| **`lavender`** | Admin / divers | futurs types admin |

**Hors scope V1 cartes** : `absence_enfant_modif` (ack AM sur modif).  
Les **modifications d’absence** se font via l’**agenda / calendrier**, pas via une bulle dédiée. On rebranchera une notif éventuelle quand le calendrier sera implémenté.

**Principes**

- Couleur = famille visuelle (lisible sans tout lire).
- Icône précise l’événement (surtout sur rose : thermomètre, pansement, flacon…).
- Rose = doux / rassurant, **pas** une alerte médicale forte.
- Congés ≠ lavande (trop « admin »).

---

## 5. Nouvelle bulle rose — soins / bobo enfant (AM → parents)

### Intention produit

La nounou signale un **événement concernant l’enfant** (maladie légère, bobo, crème, température, souci du jour…) **vers les parents**.

Pourquoi **pas seulement la messagerie** ?
- C’est **loggé** dans la file d’attention.
- C’est un **événement d’agenda** (période / jour, placement, historique).
- Les parents peuvent **acquitter** (`ack`) sans noyer le chat.

### Proposition V1 (à brancher ultérieurement)

| | |
|--|--|
| `type_code` | `soin_enfant` (nom exact à figer) |
| Émetteur | AM |
| Destinataires | parents du couple / placement |
| `response_mode` | `ack` |
| Couleur UI | `pink` |
| Back métier | ligne agenda liée (même esprit que `absences_garde` : période + placement + motif) ; la bulle = collecte / notification |
| Payload | `date_debut` / `date_fin` (+ motif / sous-type optionnel : temperature, bobo, medicament…) |

**Hors scope immédiat #173** : implémentation complète ; cette section fige l’intention pour le contrat types + UI.

---

## 6. Idées futures (hors scope)

| Famille | Couleur UI | Exemples | `response_mode` |
|---------|------------|----------|-----------------|
| Soins (détail) | `pink` | `soin_temperature`, `soin_medicament`, `soin_bobo` — ou sous-types dans payload | `ack` |
| Modif absence | `peach` | `absence_enfant_modif` — **via calendrier** d’abord ; bulle ack AM éventuelle ensuite | `ack` |
| Sortie | `peach` / `lavender` | `sortie_a_valider` | `accept_refuse` |
| Admin | `lavender` | `info_admin`, `document_a_fournir` | `ack` / `none` |

Variante soins : un seul fond rose ; l’icône / sous-type change.

---

## 7. Comportements métier à ne pas casser

- Créateur : pas de boutons réponse ; éventuel « En attente de réponse ».
- Refus : afficher `last_refuse_comment`.
- Congé : `accept_refuse` côté destinataire.
- Absence enfant : **info seule** (`response_mode: none`) — pas de veto ni ack AM en V1.
- Absence enfant : audience = **AM + tous les parents du foyer** (créateur + co-parent), pas seulement le déclarant.
- Modif / édition d’absence : **agenda**, pas les cartes (V1).
- File courte : `purge_at` ; l’**agenda** conserve l’historique métier.

---

## 8. Fichiers front de référence

- `frontend/lib/models/carte_bulle.dart` — mapping type → libellé / icône / fond
- `frontend/lib/widgets/quotidien/cartes_feed.dart`
- `frontend/lib/models/card_assets.dart`
- Assets : `frontend/assets/cards/`, `valise.png`, `btn_*_pilule.png`

---

## 9. Recettes

- [ ] API cartes **sans** champ `couleur` (ni feed ni `/types`).
- [ ] Contrat lien agenda : champ API `id_evenement` (plus `id_absence`).
- [ ] Front mappe `conge_am` → aqua, `arret_maladie_am` → blue, `absence_enfant` → peach.
- [ ] Accept / refuse congé OK.
- [ ] Arrêt : ack parent « Bien reçu » ; traité + période en cours → reste visible.
- [ ] Absence enfant : pas de bouton (info).
- [ ] Filtre couple / placement.
- [ ] (Plus tard) `soin_enfant` rose AM → parents + ligne agenda.
- [ ] (Plus tard / calendrier) modifs d’absence + éventuel `absence_enfant_modif`.

---

## 10. Références

- Ticket front : **#173**
- Module cartes : **#194**
- Quotidien : `docs/31_MINI-SPEC-QUOTIDIEN-PARENT-AM.md`
- Décision projet : `docs/24_DECISIONS-PROJET.md` §32
- Maquette congés : `ressources/bulle_congés.jpg`