PD-284 — Plan d'implémentation¶

1. Découpage en composants¶

2. Flux techniques¶

2.1 Flux A — Déclenchement urgent (POST → GET → SSE)¶

┌─────────┐     ┌──────────┐     ┌──────────┐     ┌───────────┐     ┌──────────┐
│ UI:      │     │ C6:      │     │ C6:      │     │ C7:       │     │ C3:      │
│ Button   │────>│ POST     │────>│ GET      │────>│ init      │────>│ SSE open │
│ pressed  │     │ /seals/  │     │ /status  │     │ store     │     │          │
│          │     │ urgent   │     │          │     │ (état     │     │          │
└─────────┘     └──────────┘     └──────────┘     │  initial) │     └──────────┘
                     │                │            └───────────┘          │
                     │ seal_id        │ état canonique                   │ events
                     ▼                ▼                                  ▼
                 feedback         SealStore                          C4: process
                 chargement       initialisé                        → SealStore

Séquence stricte : POST → attente seal_id → GET /seals/{seal_id}/status → init store avec état GET → ouverture SSE. Aucune étape ne peut être sautée.

Échec GET status post-POST (réserve R-02) : Si GET /seals/{id}/status échoue après un POST réussi, le client : 1. Affiche un toast d'erreur contrôlée (5s, non bloquant) 2. Initialise la carte en état RECEIVED (état conservateur — premier état de la machine) 3. Ouvre le SSE normalement — le prochain événement SSE recalera l'état réel 4. Émet un événement telemetry get_status_failed_after_post

2.1b Mapping états → étapes visuelles¶

Règle : FAILED_TIMEOUT n'est PAS une 6e étape mais un overlay rouge sur la dernière étape active au moment de l'échec.

2.2 Flux B — Suivi temps réel SSE + failover¶

                    ┌─────────────────────────────────────┐
                    │            C3: SSE Client            │
                    │                                      │
    ┌──────┐  event │  ┌──────────┐    ┌──────────────┐   │
    │ SSE  │───────>│  │ C4:      │───>│ C5: Store    │   │
    │server│        │  │ dedup +  │    │ update state │   │
    │      │        │  │ reorder  │    │              │   │
    └──────┘        │  └──────────┘    └──────────────┘   │
                    │                                      │
     SSE fail ×3    │  ┌──────────────────────────┐       │
    (1s,2s,4s)──────│─>│ Failover → polling 5s    │       │
                    │  │ + tentative SSE parallèle │       │
                    │  │   à chaque cycle polling  │       │
                    │  └──────────────────────────┘       │
                    │                                      │
     SSE reconnect  │  ┌──────────────────────────┐       │
    succès ─────────│─>│ Retour SSE + arrêt poll   │       │
                    │  └──────────────────────────┘       │
                    └─────────────────────────────────────┘

Backoff exponentiel : delay = base × factor^attempt avec base=1s, factor=2, max_attempts=3. Plafond cumulé max_cumulative_delay=30s. Si cumulé atteint avant max_attempts → failover immédiat.

2.3 Flux C — Traitement événement SSE¶

Événement reçu
  │
  ├─ seal_id ≠ actif ? → ignorer + log telemetry
  │
  ├─ event_id déjà vu (cache FIFO 100) ? → ignorer silencieusement
  │
  ├─ Validation Zod payload ?
  │   └─ échec → ignorer + toast erreur contrôlée 5s + telemetry
  │
  ├─ sequence_number gap ?
  │   ├─ attente fenêtre grâce 200ms
  │   └─ gap persistant → GET /seals/{id}/status resync
  │
  ├─ Transition autorisée (C2) ?
  │   └─ non → ignorer + toast erreur contrôlée 5s + telemetry
  │
  └─ OK → update store → render UI
       ├─ badge dégradation (si degradation_flag)
       ├─ artefacts expert (si état suffisant)
       └─ notification (si état terminal)

2.4 Flux D — Évaluation bouton urgent¶

GET détail document (données serveur)
  │
  ├─ account_type = minor → bouton ABSENT (INV-284-02)
  │
  └─ account_type ≠ minor → bouton VISIBLE (INV-284-01)
       │
       ├─ urgent_quota_remaining = 0 → DISABLED + tooltip "Quota épuisé ce mois"
       │
       ├─ has_active_urgent_seal = true → DISABLED + tooltip "Scellement urgent déjà en cours"
       │   (Réserve R-03 : valeur par défaut false + telemetry si champ absent —
       │    acceptable car PD-80 est idempotent sur POST /seals/urgent)
       │
       └─ sinon → ENABLED

2bis. Diagrammes Mermaid¶

Graphe de dépendances des composants¶

graph TD
    C1["C1: seal-types<br/><code>src/types/seal.ts</code>"]

    C2["C2: seal-state-machine<br/><code>src/seal/state-machine.ts</code>"]
    C3["C3: seal-sse-client<br/><code>src/seal/sse-client.ts</code>"]
    C4["C4: seal-event-processor<br/><code>src/seal/event-processor.ts</code>"]
    C5["C5: seal-store<br/><code>src/store/useSealStore.ts</code>"]
    C6["C6: seal-api<br/><code>src/seal/api-client.ts</code>"]
    C7["C7: seal-orchestrator<br/><code>src/seal/orchestrator.ts</code>"]
    C8["C8: urgent-button<br/><code>src/components/seal/UrgentSealButton.tsx</code>"]
    C9["C9: seal-progress-card<br/><code>src/components/seal/SealProgressCard.tsx</code>"]
    C10["C10: expert-panel<br/><code>src/components/seal/ExpertPanel.tsx</code>"]
    C11["C11: seal-notifications<br/><code>src/seal/notifications.ts</code>"]
    C12["C12: seal-secure-storage<br/><code>src/seal/secure-storage.ts</code>"]
    C13["C13: seal-telemetry<br/><code>src/seal/telemetry.ts</code>"]
    C14["C14: seal-detail-screen<br/><code>src/screens/vault/SealDetailScreen.tsx</code>"]
    C15["C15: seal-navigation<br/><code>src/navigation/seal-linking.ts</code>"]

    C2 --> C1
    C3 --> C1
    C4 --> C1
    C4 --> C2
    C5 --> C1
    C5 --> C2
    C5 --> C4
    C6 --> C1
    C7 --> C3
    C7 --> C4
    C7 --> C5
    C7 --> C6
    C8 --> C5
    C8 --> C6
    C9 --> C5
    C10 --> C1
    C10 --> C5
    C11 --> C1
    C12 --> C1
    C13 --> C1
    C14 --> C5
    C14 --> C8
    C14 --> C9
    C14 --> C10
    C15 --> C14

Diagramme de sequence — Flux A (declenchement urgent : POST -> GET -> SSE)¶

sequenceDiagram
    participant UI as UI (C8: UrgentSealButton)
    participant Orch as C7: seal-orchestrator
    participant API as C6: seal-api
    participant Backend as PD-80 Backend
    participant Store as C5: seal-store
    participant SSE as C3: seal-sse-client
    participant Proc as C4: seal-event-processor

    UI->>Orch: onPress (debounce 2s)
    Orch->>API: POST /seals/urgent
    API->>Backend: HTTP POST
    Backend-->>API: 201 { seal_id }
    API-->>Orch: seal_id

    Orch->>API: GET /seals/{seal_id}/status
    API->>Backend: HTTP GET
    alt GET reussit
        Backend-->>API: 200 { state, artefacts... }
        API-->>Orch: etat canonique
        Orch->>Store: init(state)
    else GET echoue (R-02)
        Backend-->>API: 5xx / timeout
        API-->>Orch: erreur
        Orch->>Store: init(RECEIVED)
        Note over Orch: Toast erreur 5s + telemetry
    end

    Orch->>SSE: open(seal_id)
    SSE->>Backend: EventSource /seals/{seal_id}/events

    loop Evenements SSE
        Backend-->>SSE: event { event_id, sequence_number, state, ... }
        SSE->>Proc: onEvent(event)
        Proc->>Proc: dedup event_id (cache FIFO 100)
        Proc->>Proc: check sequence_number gaps
        Proc->>Store: transition(new_state)
        Store-->>UI: re-render (C9: SealProgressCard)
    end

Diagramme de sequence — Failover SSE -> Polling (Flux B)¶

sequenceDiagram
    participant SSE as C3: seal-sse-client
    participant Backend as PD-80 Backend
    participant Proc as C4: seal-event-processor
    participant Store as C5: seal-store
    participant Telem as C13: seal-telemetry

    SSE->>Backend: EventSource (connexion SSE)
    Backend--xSSE: connexion perdue

    SSE->>SSE: retry #1 (delay 1s)
    SSE->>Backend: reconnexion SSE
    Backend--xSSE: echec

    SSE->>SSE: retry #2 (delay 2s)
    SSE->>Backend: reconnexion SSE
    Backend--xSSE: echec

    SSE->>SSE: retry #3 (delay 4s)
    SSE->>Backend: reconnexion SSE
    Backend--xSSE: echec

    SSE->>Telem: sse_failover_polling
    Note over SSE: Basculement en mode polling

    loop Polling 5s + tentative SSE parallele
        SSE->>Backend: GET /seals/{seal_id}/status
        Backend-->>SSE: 200 { state }
        SSE->>Proc: onPollResult(state)
        Proc->>Store: update(state)
        SSE->>Backend: tentative SSE parallele
        alt SSE reconnecte
            Backend-->>SSE: EventSource OK
            SSE->>Telem: sse_restored
            Note over SSE: Arret polling, retour SSE
        else SSE echoue encore
            Note over SSE: Continue polling
        end
    end

3. Mapping invariants → mécanismes¶

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

Définition « erreur contrôlée » : toast non bloquant auto-dismiss 5 secondes + émission telemetry structurée ({ event_type, seal_id, timestamp, details }). Pas d'interruption du flux UI. Pas d'état dans la machine d'états.

7. Impacts sécurité¶

8. Hypothèses techniques¶

9. Points de vigilance (risques, dette, pièges)¶

Réserves Gate 3 intégrées¶

Risques techniques¶

1. SSE sur React Native : Pas de lib SSE standard dans Expo SDK 54. L'implémentation custom via fetch + ReadableStream doit gérer le parsing text/event-stream manuellement. Risque de bugs subtils sur le parsing multi-ligne. Prévoir des tests unitaires exhaustifs du parser SSE.

2. Performance rendu P95 <= 100ms (CA-284-14) : Critique. Nécessite des sélecteurs Zustand granulaires (un sélecteur par champ affiché) et React.memo sur les sous-composants. Le test de performance est un test d'instrumentation sur device réel (iPhone 12+), pas simulable en CI.

3. Cache FIFO 100 event_id : Attention au type — event_id est un entier, pas un string. Le cache doit être un tableau circulaire (ring buffer) pour l'éviction FIFO (pas de LRUCache, pas de Set avec delete aléatoire).

4. Fenêtre de grâce 200ms : setTimeout en React Native peut dériver. Utiliser performance.now() pour mesurer la fenêtre, pas Date.now().

5. Debounce bouton : Le disabled optimistic après premier tap évite le spam. Mais attention a remettre enabled si le POST échoue (sinon bouton bloqué définitivement).

Dette technique connue¶

• Mode expert : La préférence mode_expert n'existe pas encore dans le store settings. Tâche explicite : ajouter mode_expert: boolean (défaut false) dans useSettingsStore existant ou à créer si absent. Fichier : src/store/useSettingsStore.ts. Persistance AsyncStorage. Cette tâche est rattachée au composant C10 (ExpertPanel) qui en dépend.
• Notifications deep-link : Le service de notifications existant supporte déjà les deep-links. L'ajout de la route seal/:id dans la config Expo linking est minimal.

10. Hors périmètre¶

11. Contraintes techniques¶

12. Mécanismes cross-module (anciennement §11)¶

Aucune modification d'autres modules. PD-284 est une story front-only qui consomme les API définies par PD-80. Les endpoints utilisés (POST /seals/urgent, GET /seals/{id}/status, SSE stream) sont exposés par le backend PD-80, pas créés par PD-284.

12. Périmètre de test¶

Tous les niveaux unitaire et intégration sont couverts. Les exclusions E2E et Perf sont justifiées par l'indisponibilité d'infrastructure et de device physique en CI.