PD-284 — Expression de besoin¶

1. Contexte¶

Story UX companion de PD-80 (scellement instantané backend < 1h). PD-80 contractualise le pipeline backend (fast-track, BullMQ prioritaire, TSA, Merkle, ancrage blockchain, proof package). PD-284 couvre les composants visuels côté client pour piloter et suivre ce pipeline en temps réel.

Dépendance bloquante : PD-80 (API backend scellement prioritaire — machine d'états, SSE, quotas).

2. User Story¶

En tant qu' utilisateur ProbatioVault (mineur auto ou standard/premium/enterprise éligible), Je veux déclencher un scellement urgent et suivre sa progression en temps réel via une carte de progression visuelle avec états de dégradation clairs, Afin de comprendre où en est ma preuve, être rassuré sur le processus, et être alerté immédiatement en cas de retard ou d'échec.

3. Décisions PO¶

4. Périmètre fonctionnel¶

4.1 Bouton "Scellement urgent"¶

• Visible uniquement pour les utilisateurs non-mineurs éligibles (standard/premium/enterprise avec quota > 0).
• Pour les comptes mineurs (account_type=minor), le fast-track est automatique — pas de bouton.
• Affiche le quota restant : "{N}/{max} scellements urgents restants ce mois".
• Désactivé (grisé + tooltip explicatif) quand : quota épuisé OU rate-limit atteint OU document déjà en scellement urgent.
• Déclenche POST /seals/urgent avec document_id.
• Feedback immédiat : spinner + transition vers la carte de progression.

4.2 Carte de progression temps réel¶

• 5 étapes visuelles reflétant la machine d'états PD-80 :
• Capture (RECEIVED → QUEUED_PRIORITY) — icône document + coche
• Horodatage TSA (QUEUED_PRIORITY → TSA_PENDING → TSA_SEALED) — icône horloge certifiée
• Ancrage Merkle (TSA_SEALED → ANCHOR_PENDING) — icône arbre Merkle
• Blockchain (ANCHOR_PENDING → SEALED) — icône chaîne
• Scellé (SEALED) — icône bouclier vert + animation succès
• Chaîne complète : RECEIVED → QUEUED_PRIORITY → TSA_PENDING → TSA_SEALED → ANCHOR_PENDING → SEALED

• État terminal d'échec : FAILED_TIMEOUT (accessible depuis tout état intermédiaire si délai > 120 min)

• Mise à jour temps réel via SSE : connexion GET /seals/{id}/events (endpoint PD-80).

• Reconnexion automatique : si SSE coupé, reconnexion avec Last-Event-ID, fallback polling 5s après 3 échecs SSE.
• Barre de progression : animation fluide entre étapes, pourcentage estimé basé sur SLA cibles PD-80.

4.3 États de dégradation UX¶

Basés sur les SLA temporels contractualisés dans PD-80 (§5.2, §5.3) :

• Le calcul d'état de dégradation est dérivé des flags serveur (learning PD-81 : flags-as-source-of-truth).
• Chaque seuil est configurable côté serveur — le front consomme les flags, ne calcule pas les seuils.

4.4 Détails techniques avancés (mode expert)¶

• Panneau dépliable visible uniquement si toggle "Mode expert" activé dans les préférences utilisateur.
• Contenu affiché une fois le scellement terminé (SEALED) :
• Hash SHA-256 du document (hash_document)
• Token TSA (résumé + date horodatage)
• Preuve Merkle (chemin de vérification, racine)
• Transaction blockchain (hash tx + lien vers explorateur L2)
• Lien de téléchargement du proof package complet
• Contenu intermédiaire (pendant progression) :
• Hash document (dès RECEIVED)
• Token TSA (dès TSA_SEALED)
• Merkle root + proof (dès ANCHOR_PENDING résolu)

4.5 Notification push mobile (iOS)¶

• Succès (SEALED) : "Votre document est scellé ✓ — Preuve probatoire disponible" + deep-link vers carte de détails.
• Échec (FAILED_TIMEOUT) : "Échec du scellement urgent — Contactez le support" + deep-link vers détails.
• Format : titre court (< 50 chars) + body (< 100 chars) + action deep-link.
• Canaux : Push APNs (iOS natif), email en fallback si pas de device push enregistré (INV-80-08).

5. Hors périmètre¶

• Pipeline backend de scellement (PD-80).
• Facturation / paiement Stripe.
• Dashboard opérationnel (monitoring interne).
• Version Android et Web (stories dédiées ultérieures).
• API admin (resubmit, retry manuels).

6. Contraintes techniques¶

• Plateforme : iOS (Swift + React Native bridge si applicable).
• Temps réel : SSE avec reconnexion automatique + fallback polling.
• Accessibilité : VoiceOver compatible, annonces dynamiques sur changement d'étape.
• Performance : carte de progression < 100ms de rendu après réception événement SSE.
• Offline : si perte réseau, afficher dernier état connu + badge "Hors ligne" + reconnexion automatique.

7. Learnings injectés¶

• PD-81 : chaque transition d'état temporelle DOIT avoir SLA min/max/default → les seuils de dégradation UX sont dérivés des SLA backend, pas codés en dur.
• PD-264 : protocole statistique temps constant → les badges de dégradation utilisent les seuils serveur (flags), pas de calcul local de percentiles.