📄 SPÉCIFICATION CANONIQUE CONTRACTUELLE¶

PD-176 — Onboarding interactif en 5 étapes (Application mobile iOS)

📌 EPIC
➡️ PD-195 — MOBILE-IOS

📌 Artefact produit
➡️ PD-176-spec.md

1. Objectif¶

Définir de manière formelle, exhaustive et testable les exigences relatives à la mise en place d’un onboarding utilisateur interactif composé de cinq étapes, destiné à l’application mobile iOS.

L’onboarding a pour objectif de guider un utilisateur lors de sa première utilisation de l’application, en structurant un parcours initial contrôlé, déterministe et traçable.

Cette spécification constitue une référence contractuelle. Toute implémentation doit s’y conformer strictement.

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

2.1 Périmètre¶

La présente spécification couvre exclusivement :

• l’existence d’un parcours d’onboarding composé de cinq étapes distinctes et ordonnées ;
• le caractère interactif de chaque étape, nécessitant une action explicite de l’utilisateur ;
• les règles de navigation et de progression entre les étapes ;
• la persistance de l’état d’avancement de l’onboarding ;
• les conditions de complétion ou de non-complétion de l’onboarding ;
• la traçabilité des transitions entre étapes.

2.2 Hors périmètre¶

Les éléments suivants sont explicitement hors périmètre :

• le contenu précis des étapes (textes, visuels, animations) ;
• le design graphique, l’ergonomie détaillée et les animations ;
• les choix techniques d’implémentation iOS ;
• la personnalisation du parcours selon le profil utilisateur ;
• la traduction, la localisation et la gestion multilingue ;
• toute logique marketing, analytique avancée ou A/B testing.

Toute règle non testable relevant de ces éléments est considérée hors périmètre.

3. Définitions¶

4. Invariants (non négociables)¶

Les règles suivantes sont non négociables :

1. L’onboarding comporte exactement cinq étapes.
2. Les étapes sont parcourues dans un ordre strictement séquentiel.
3. Le passage à une étape suivante nécessite une action explicite et volontaire de l’utilisateur.
4. Un utilisateur ne peut être considéré comme ayant terminé l’onboarding que si les cinq étapes ont été validées.
5. L’état d’avancement de l’onboarding est persisté en base PostgreSQL.
6. Un utilisateur ayant complété l’onboarding n’est plus soumis à ce parcours par défaut, y compris après réinstallation ou changement d’appareil.
7. Toute validation ou transition d’étape est traçable.

Chaque invariant doit être vérifiable par test ou audit.

5. Flux nominaux¶

5.1 Démarrage de l’onboarding¶

1. L’utilisateur accède à l’application.
2. Le système détecte que l’onboarding n’est pas complété.
3. La première étape de l’onboarding est affichée.

5.2 Progression entre les étapes¶

1. L’utilisateur interagit avec l’étape courante.
2. L’utilisateur déclenche explicitement la validation de l’étape.
3. Le système enregistre la validation de l’étape.
4. L’étape suivante est affichée.

5.3 Finalisation de l’onboarding¶

1. L’utilisateur valide la cinquième étape.
2. Le système enregistre la complétion de l’onboarding.
3. L’utilisateur accède au fonctionnement normal de l’application.

5bis. Diagrammes Mermaid¶

5bis.1 Diagramme d’états — Progression de l’onboarding¶

Réf. invariants : INV-1 (exactement 5 étapes), INV-2 (ordre séquentiel), INV-4 (complétion = 5 étapes validées), INV-5 (persistance PostgreSQL), INV-6 (complétion définitive)

stateDiagram-v2
    [*] --> NOT_STARTED : Première ouverture app

    NOT_STARTED --> STEP_1 : Onboarding non complété détecté

    STEP_1 --> STEP_2 : Action explicite utilisateur (INV-3)
    STEP_2 --> STEP_3 : Action explicite utilisateur (INV-3)
    STEP_3 --> STEP_4 : Action explicite utilisateur (INV-3)
    STEP_4 --> STEP_5 : Action explicite utilisateur (INV-3)
    STEP_5 --> COMPLETED : Validation étape 5 (INV-4)

    COMPLETED --> [*] : Accès app normal (INV-6)

    STEP_1 --> STEP_1 : Interruption + reprise (INV-5)
    STEP_2 --> STEP_2 : Interruption + reprise (INV-5)
    STEP_3 --> STEP_3 : Interruption + reprise (INV-5)
    STEP_4 --> STEP_4 : Interruption + reprise (INV-5)
    STEP_5 --> STEP_5 : Interruption + reprise (INV-5)

    note right of COMPLETED
        État persisté en PostgreSQL.
        Irréversible : aucune transition
        retour vers STEP_N (INV-6).
    end note

5bis.2 Diagramme de séquence — Validation d’une étape et persistance¶

Réf. invariants : INV-3 (action explicite), INV-5 (persistance PostgreSQL), INV-7 (traçabilité)

sequenceDiagram
    actor U as Utilisateur
    participant App as App iOS
    participant API as Backend API
    participant DB as PostgreSQL

    U->>App: Interaction étape N
    U->>App: Valide étape N (action explicite — INV-3)

    App->>API: POST /onboarding/steps/{N}/validate
    API->>DB: UPDATE onboarding SET current_step = N+1, updated_at = now()
    Note over DB: Persistance état (INV-5)
    API->>DB: INSERT audit_log (user_id, step_N, validated_at)
    Note over DB: Traçabilité (INV-7)
    DB-->>API: OK
    API-->>App: 200 {current_step: N+1, completed: false}
    App->>U: Affiche étape N+1

    Note over U,DB: Si N = 5 (dernière étape)

    U->>App: Valide étape 5 (action explicite — INV-3)
    App->>API: POST /onboarding/steps/5/validate
    API->>DB: UPDATE onboarding SET current_step = 5, completed = true
    Note over DB: Complétion irréversible (INV-4, INV-6)
    API->>DB: INSERT audit_log (user_id, step_5, completed_at)
    DB-->>API: OK
    API-->>App: 200 {current_step: 5, completed: true}
    App->>U: Accès fonctionnement normal

5bis.3 Diagramme de séquence — Reprise après interruption¶

Réf. invariants : INV-2 (ordre séquentiel), INV-5 (persistance PostgreSQL)

sequenceDiagram
    actor U as Utilisateur
    participant App as App iOS
    participant API as Backend API
    participant DB as PostgreSQL

    U->>App: Ouvre l’application
    App->>API: GET /onboarding/status
    API->>DB: SELECT current_step, completed FROM onboarding WHERE user_id = ?
    DB-->>API: {current_step: 3, completed: false}
    API-->>App: 200 {current_step: 3, completed: false}

    alt Onboarding complété
        App->>U: Accès direct app (INV-6)
    else Onboarding en cours
        App->>U: Affiche étape 3 (INV-2 — reprise séquentielle)
    end

6. Cas d’erreur¶

Les situations suivantes doivent être explicitement gérées :

• interruption du parcours avant validation de la cinquième étape ;
• tentative d’accès à une étape hors séquence ;
• état d’avancement manquant, corrompu ou incohérent ;
• échec de persistance de l’état d’onboarding.

Chaque cas d’erreur doit produire un comportement déterministe, contrôlé et traçable.

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

• L’onboarding comporte exactement cinq étapes.
• Il est impossible de terminer l’onboarding sans valider les cinq étapes.
• L’ordre des étapes est strictement respecté.
• L’état d’avancement est conservé entre deux sessions utilisateur.
• Un utilisateur ayant terminé l’onboarding n’y est plus confronté.
• Chaque validation d’étape est traçable.

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

Scénario 1 — Parcours complet nominal¶

Given un utilisateur n’ayant jamais complété l’onboarding
When il valide successivement les cinq étapes
Then l’onboarding est marqué comme complété

Scénario 2 — Interruption du parcours¶

Given un utilisateur ayant validé deux étapes
When l’application est quittée puis relancée
Then l’onboarding reprend à la troisième étape

Scénario 3 — Tentative de saut d’étape¶

Given un utilisateur à l’étape 2
When il tente d’accéder directement à l’étape 4
Then l’accès est refusé et l’étape courante est maintenue

9. Hypothèses explicites¶

• L’application est capable de persister un état utilisateur.
• L’utilisateur dispose d’une interface permettant l’interaction requise.
• Le système est capable de journaliser les événements de progression.

10. Points à clarifier¶

Les éléments suivants doivent être explicitement définis avant implémentation :

1. Nature exacte des interactions attendues à chaque étape.
2. Possibilité ou non d’abandon volontaire définitif de l’onboarding.
3. Comportement en cas de réinstallation de l’application.
4. Niveau exact de traçabilité attendu (local, serveur, audit).
5. Contraintes réglementaires éventuelles liées à l’onboarding.

Fin de la spécification canonique.