PD-284 — UX de scellement urgent et suivi temps réel (v3 corrigée)¶

1. Objectif¶

Spécifier le comportement contractuel de l’interface client ProbatioVault pour :

• déclencher un scellement urgent lorsque l’utilisateur est éligible ;
• afficher la progression du scellement en temps réel ;
• exposer des états de dégradation lisibles et actionnables ;
• notifier l’utilisateur à la clôture (succès/échec) ;
• afficher, en mode expert, les artefacts probatoires disponibles selon l’état.

La présente spécification couvre le front mobile ProbatioVault-app et dépend de PD-80 pour les états backend, SLA et événements temps réel.

2. Périmètre / Hors périmètre¶

Inclus¶

• Bouton Scellement urgent conditionné par éligibilité, quota et scellement urgent déjà actif.
• Carte de progression à 5 étapes alignée sur la machine d’états PD-80.
• Abonnement temps réel via SSE avec reprise et fallback polling.
• Affichage des badges de dégradation dérivés des indicateurs serveur.
• Panneau Mode expert conditionnel aux préférences utilisateur.
• Notifications mobile de fin de traitement avec deep-link de retour.

Exclu¶

• Pipeline backend de scellement (orchestration, BullMQ, TSA, Merkle, ancrage).
• Facturation.
• Monitoring opérationnel interne.
• Android/Web.
• API d’administration (retry/resubmit manuels).
• Toute migration DDL (Aucune modification de schéma en front).

3. Définitions¶

• Scellement urgent : traitement prioritaire d’un document selon PD-80.
• SSE : flux unidirectionnel d’événements serveur vers client.
• Fallback polling : interrogation périodique d’un endpoint d’état lorsque SSE est indisponible.
• Mode expert : vue avancée affichant les détails probatoires.
• État terminal : état sans transition sortante autorisée (SEALED, FAILED_TIMEOUT).
• Dégradation : état UX indiquant un retard ou une situation critique signalée par le backend.
• Erreur contrôlée : toast non bloquant affiché 5 secondes (auto-dismiss), journalisation telemetry obligatoire avec event_type et seal_id, sans blocage de l’UI ni interruption du flux utilisateur.

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Flux A — Déclenchement d’un scellement urgent¶

1. L’utilisateur ouvre le détail document.
2. Le client évalue les conditions d’affichage du bouton urgent selon données serveur (account_type, urgent_quota_remaining, has_active_urgent_seal).
3. Si activable, l’action envoie POST /seals/urgent avec payload { document_id } (contrat exact — payload de réponse, codes d’erreur métier — défini par PD-80, hypothèse H-284-01).
4. Le client affiche un feedback immédiat (chargement) et reçoit seal_id.
5. Nouvelle étape obligatoire : le client appelle GET /seals/{seal_id}/status pour récupérer l’état initial canonique.
6. Le client affiche la carte de progression associée au seal_id avec l’état initial issu du GET.
7. Le client ouvre ensuite le flux SSE pour ce seal_id ; SSE prend le relais du suivi.

5.2 Flux B — Suivi temps réel de progression (SSE + reprise)¶

1. Le client ouvre un flux SSE sur le scellement.
2. À chaque événement valide, l’UI met à jour :
3. étape visuelle (Capture, TSA, Merkle, Blockchain, Scellé),
4. badge de dégradation (si fourni),
5. disponibilité des détails expert.
6. Le client maintient un cache local FIFO des N=100 derniers event_id (politique d'éviction : les event_id les plus anciens sont éjectés en premier — FIFO, pas LRU).
7. si event_id déjà vu : événement ignoré silencieusement (déduplication, pas de toast, trace telemetry uniquement en mode debug).
8. Chaque événement contient aussi sequence_number (entier croissant).
9. en cas de réception désordonnée, le client attend une fenêtre de grâce de 200 ms pour recevoir le(s) sequence_number manquant(s) avant réordonnancement et rendu ;
10. en cas de gap persistant après la fenêtre de grâce (current_sequence - previous_sequence > 1 après 200 ms), le client déclenche GET /seals/{seal_id}/status pour resynchroniser.
11. En cas de coupure SSE, le client tente une reconnexion avec backoff exponentiel :
12. tentative 1 : 1s,
13. tentative 2 : 2s,
14. tentative 3 : 4s.
15. Après 3 échecs consécutifs SSE, le client bascule en polling toutes les 5 s.
16. Badge Hors ligne :
17. oui si perte réseau détectée (navigator.onLine=false ou équivalent RN),
18. non si simple échec SSE sans perte réseau (bascule polling silencieuse).
19. Re-tentative SSE depuis mode polling : à chaque cycle de polling (toutes les polling_interval_after_sse_failover secondes), le client tente en parallèle une connexion SSE. Si la connexion SSE réussit, le client revient en mode SSE et arrête le polling. Si elle échoue, le polling continue sans interruption.

5.3 Flux C — Gestion des dégradations¶

Le champ degradation_flag (optionnel dans les événements SSE, cf. §5.12) prend les valeurs suivantes :

• Échec timeout : état terminal FAILED_TIMEOUT (transition d’état, pas un degradation_flag) avec message de contact support.

Le client n’effectue aucun calcul local de seuil ; il applique les indicateurs reçus. Toute valeur de degradation_flag non listée ci-dessus est traitée comme none + trace telemetry.

5.4 Flux D — Mode expert¶

• Le panneau expert est visible uniquement si la préférence utilisateur mode_expert=true.
• Disponibilité conditionnelle des champs :
• hash_document : dès RECEIVED.
• tsa_token_ref : dès TSA_SEALED.
• merkle_root, merkle_proof[] : dès ANCHOR_PENDING.
• blockchain_tx_hash, proof_package_url : à SEALED.

5.5 Flux E — Notifications de clôture¶

• À SEALED : notification succès + deep-link détail.
• À FAILED_TIMEOUT : notification échec + deep-link détail.
• Si push indisponible : fallback email (conformément à PD-80).

5.6 Modèle de données contractuel (formats)¶

5.7 Machine d’états d’affichage et transitions inverses¶

États couverts : RECEIVED, QUEUED_PRIORITY, TSA_PENDING, TSA_SEALED, ANCHOR_PENDING, SEALED, FAILED_TIMEOUT.

• RECEIVED
• Autorisées : RECEIVED → QUEUED_PRIORITY, RECEIVED → FAILED_TIMEOUT
• Interdites : RECEIVED → SEALED direct.
• QUEUED_PRIORITY
• Autorisées : QUEUED_PRIORITY → TSA_PENDING, QUEUED_PRIORITY → FAILED_TIMEOUT
• Transition retour QUEUED_PRIORITY → RECEIVED : INTERDITE.
• TSA_PENDING
• Autorisées : TSA_PENDING → TSA_SEALED, TSA_PENDING → FAILED_TIMEOUT
• Transition retour TSA_PENDING → QUEUED_PRIORITY : INTERDITE.
• TSA_SEALED
• Autorisées : TSA_SEALED → ANCHOR_PENDING, TSA_SEALED → FAILED_TIMEOUT
• Transition retour TSA_SEALED → TSA_PENDING : INTERDITE.
• ANCHOR_PENDING
• Autorisées : ANCHOR_PENDING → SEALED, ANCHOR_PENDING → FAILED_TIMEOUT
• Transition retour ANCHOR_PENDING → TSA_SEALED : INTERDITE.
• SEALED
• SEALED → * : INTERDITE (état terminal, résolution manuelle uniquement).
• FAILED_TIMEOUT
• FAILED_TIMEOUT → * : INTERDITE (état terminal, résolution manuelle uniquement).

Aucune transition retour applicable dans ce flux (modèle monotone vers terminal).

5.8 Paramètres numériques contractuels¶

Backoff attendu avec paramètres par défaut : 1s, 2s, 4s puis failover polling. Si le délai cumulé de backoff dépasse sse_reconnect_max_cumulative_delay (défaut 30s) avant d'atteindre max_attempts, le client bascule immédiatement en polling sans attendre les tentatives restantes.

5.9 SLA temporels (checklist)¶

5.10 Clauses structurelles obligatoires¶

• Migration DDL : non applicable (aucune colonne backend modifiée par cette story).
• Atomicité multi-composant DB+queue : non applicable côté client (dépend de PD-80).
• Protection distribuée (locks/idempotence/réconciliation/rate-limit/clearing) : non applicable au module UI ; gérée contractuellement par PD-80 côté backend.
• Contraintes inter-modules : aucune contrainte inter-module backend supplémentaire introduite.

5.11 Classification des artefacts¶

Règle explicite : le cache mémoire React (state/context) n’est pas une persistance durable.

Politique de purge des artefacts sensibles : tous les artefacts sensibles persistés en iOS Keychain / Expo SecureStore DOIVENT être purgés lors de la déconnexion utilisateur (logout) et lors de la suppression de compte (deleteAccount). Les clés de session SSE sont purgées à la fermeture de la session SSE. La restauration iCloud Keychain ne doit pas restaurer ces artefacts (attribut kSecAttrAccessible = kSecAttrAccessibleWhenUnlockedThisDeviceOnly ou équivalent Expo).

5.12 Contenu événement SSE par état¶

Champs communs à tous les états SSE :

• event_id (séquentiel croissant),
• sequence_number (entier croissant),
• seal_id,
• status,
• timestamp,
• degradation_flag? (optionnel),
• document_id.

5.13 Diagrammes¶

5.13.1 Machine d’états d’affichage (statechart)¶

Transitions autorisées conformes à §5.7. Les états terminaux SEALED et FAILED_TIMEOUT n’ont aucune transition sortante (INV-284-08). Toute transition retour est interdite — modèle monotone (INV-284-06, INV-284-07).

stateDiagram-v2
    [*] --> RECEIVED

    RECEIVED --> QUEUED_PRIORITY
    RECEIVED --> FAILED_TIMEOUT

    QUEUED_PRIORITY --> TSA_PENDING
    QUEUED_PRIORITY --> FAILED_TIMEOUT

    TSA_PENDING --> TSA_SEALED
    TSA_PENDING --> FAILED_TIMEOUT

    TSA_SEALED --> ANCHOR_PENDING
    TSA_SEALED --> FAILED_TIMEOUT

    ANCHOR_PENDING --> SEALED
    ANCHOR_PENDING --> FAILED_TIMEOUT

    SEALED --> [*]
    FAILED_TIMEOUT --> [*]

    note right of SEALED : Terminal — INV-284-08
    note right of FAILED_TIMEOUT : Terminal — INV-284-08

5.13.2 Flux de déclenchement et suivi temps réel (séquence)¶

Couvre le flux A (§5.1) et le flux B (§5.2). L’état initial est récupéré par GET canonique avant ouverture SSE (INV-284-06). Les artefacts sensibles (tsa_token_ref, clés SSE) transitent uniquement vers le stockage sécurisé (INV-284-10). Les artefacts publics (hash_document, merkle_root, blockchain_tx_hash) sont affichés en mode expert (INV-284-11).

sequenceDiagram
    participant U as Utilisateur
    participant App as ProbatioVault-app
    participant API as Backend PD-80
    participant SSE as Flux SSE
    participant KS as iOS Keychain

    U->>App: Appui bouton urgent
    Note over App: Vérifie INV-284-01/02/03<br/>account_type, quota, active_seal

    App->>API: POST /seals/urgent {document_id}
    API-->>App: 201 {seal_id}

    App->>API: GET /seals/{seal_id}/status
    API-->>App: État initial (RECEIVED)
    App->>App: Affiche carte progression

    App->>SSE: Ouvre connexion SSE (seal_id)

    loop Événements temps réel
        SSE-->>App: event {event_id, sequence_number, status, ...}
        App->>App: Déduplication event_id (cache FIFO N=100)
        App->>App: Ordonnancement sequence_number (grâce 200ms)
        alt Gap séquence détecté
            App->>API: GET /seals/{seal_id}/status (resync)
        end
        App->>App: Transition état (INV-284-06/07)
        alt Artefact sensible reçu (tsa_token_ref)
            App->>KS: Stockage sécurisé (INV-284-10)
        end
    end

    alt SEALED
        App->>U: Notification succès + deep-link (INV-284-12)
    else FAILED_TIMEOUT
        App->>U: Notification échec + deep-link (INV-284-12)
    end

5.13.3 Résilience SSE : reconnexion et fallback polling (séquence)¶

Couvre la stratégie de reprise §5.2 étapes 5-8. Le badge Hors ligne est conditionné à la perte réseau réelle (INV-284-09), pas à un simple échec SSE.

sequenceDiagram
    participant App as ProbatioVault-app
    participant SSE as Flux SSE
    participant API as Backend PD-80
    participant Net as Réseau (navigator.onLine)

    Note over App,SSE: Connexion SSE active
    SSE--xApp: Coupure SSE

    App->>Net: Vérifier connectivité
    alt Perte réseau (onLine=false)
        App->>App: Badge "Hors ligne" (INV-284-09)
        App->>App: Conserver dernier état connu
    else Réseau OK
        App->>SSE: Reconnexion tentative 1 (délai 1s)
        SSE--xApp: Échec
        App->>SSE: Reconnexion tentative 2 (délai 2s)
        SSE--xApp: Échec
        App->>SSE: Reconnexion tentative 3 (délai 4s)
        SSE--xApp: Échec

        Note over App: 3 échecs — failover polling<br/>Pas de badge Hors ligne (INV-284-09)

        loop Polling toutes les 5s
            App->>API: GET /seals/{seal_id}/status
            API-->>App: État courant
            App->>SSE: Tentative SSE parallèle
            alt SSE rétabli
                App->>App: Retour mode SSE, arrêt polling
            end
        end
    end

6. Cas d’erreur¶

• Éligibilité refusée minor : bouton absent.
• Quota nul (urgent_quota_remaining=0) : bouton visible mais disabled + tooltip Quota épuisé ce mois.
• Urgent déjà actif (has_active_urgent_seal=true) : bouton visible mais disabled + tooltip Scellement urgent déjà en cours.
• POST urgent rejeté (4xx/5xx) : message d’échec, aucun passage en progression active.
• Événement SSE invalide (format, état inconnu, seal_id incohérent) : événement ignoré, erreur contrôlée, continuité UI.
• Événement SSE dupliqué (event_id déjà vu) : ignoré silencieusement.
• Réception SSE désordonnée : tri par sequence_number.
• Gap de séquence (>1) : GET /seals/{id}/status de resynchronisation.
• Perte réseau : badge Hors ligne, dernier état conservé, reprise auto.
• Échec reconnection SSE sans perte réseau : pas de badge Hors ligne, passage en polling après 3 tentatives.
• Timeout terminal : affichage état terminal + call-to-action support.
• Donnée expert invalide : section concernée masquée sans casser la carte globale.
• Push impossible : fallback email.

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

1. Éligibilité standard avec quota disponible
2. Given un utilisateur standard, urgent_quota_remaining > 0, has_active_urgent_seal=false
3. When il ouvre le détail document

4. Then le bouton urgent est visible, actif, et le quota est affiché

5. Compte minor

6. Given un utilisateur minor
7. When il ouvre le détail document

8. Then le bouton urgent est absent

9. Quota épuisé

10. Given un utilisateur standard avec urgent_quota_remaining=0
11. When il ouvre le détail document

12. Then le bouton urgent est visible mais disabled avec tooltip Quota épuisé ce mois

13. Déjà en urgent

14. Given un utilisateur standard avec has_active_urgent_seal=true
15. When il ouvre le détail document

16. Then le bouton urgent est visible mais disabled avec tooltip Scellement urgent déjà en cours

17. Déclenchement urgent réussi

18. Given bouton urgent actif
19. When l’utilisateur déclenche l’action et la réponse POST est succès

20. Then le client appelle GET /seals/{id}/status, initialise la carte avec cet état, puis démarre SSE

21. Échec SSE sans perte réseau

22. Given une carte active, réseau disponible
23. When la connexion SSE échoue 3 fois (1s, 2s, 4s)

24. Then le client bascule en polling 5s sans badge Hors ligne

25. Perte réseau

26. Given une carte active
27. When le device passe offline (navigator.onLine=false ou équivalent RN)

28. Then le badge Hors ligne s’affiche immédiatement et le dernier état connu est conservé

29. Déduplication événement

30. Given un événement event_id=42 déjà traité
31. When le même event_id=42 est reçu à nouveau

32. Then l’événement est ignoré silencieusement sans impact UI

33. Désordre / gap de séquence

34. Given événements SSE avec sequence_number 10 puis 12
35. When le client détecte un gap de 2

36. Then le client lance GET /seals/{id}/status pour resynchronisation

37. Dégradation retard

38. Given un scellement en cours
39. When le backend envoie un flag retard

40. Then l’UI affiche le badge En retard sans calcul local de seuil

41. État terminal succès

42. Given un scellement en ANCHOR_PENDING
43. When un événement SEALED est reçu

44. Then la carte passe en terminal succès et la notification succès est émise

45. État terminal échec

46. Given un scellement en cours
47. When un événement FAILED_TIMEOUT est reçu

48. Then la carte passe en terminal échec et la notification échec est émise

49. Mode expert progressif

50. Given mode_expert=true
51. When les états progressent
52. Then les champs expert apparaissent uniquement selon les jalons contractuels

8.1 Cas nominaux de non-régression (TC-NOM)¶

9. Hypothèses explicites¶

10. Points à clarifier (restants)¶

Références¶

• Epic : à compléter
• JIRA : PD-284
• Repos concernés : ProbatioVault-app (React Native + Expo SDK 54 + TypeScript), ProbatioVault-backend (dépendance PD-80)
• Documents associés : PD-80 (machine d’états/SLA/flags), expression de besoin PD-284, learnings PD-81/PD-264/PD-80.