Feature #1262
openOnboarding premier utilisateur : wizard d'amorçage + profilage progressif + visite guidée
0%
## Onboarding premier utilisateur — Spec
Parcours de premier lancement par espace (multi-tenant) : wizard 3 étapes (2 bloquantes) sautable → écran de fin → tableau de bord (checklist « Premiers pas » + proposition de visite guidée ~6 étapes) → profilage progressif en contexte. Déclencheur : onboardingState.completed === false pour l'espace courant ; jamais re-déclenché après complétion (sauf nouvel espace).
### Décisions techniques (post-audit code)
- **Persistance** : nouvelle entité base44 `OnboardingState.jsonc` (par utilisateur+espace, rls self-scope, workspace-scoped automatiquement), schema:generate. Exposée via la couture par une PAIRE de fonctions `functions.invoke('getOnboardingState')` / `invoke('updateOnboardingState', patch)` (mode register par défaut = scope X-Workspace-Id imposé) — pas d'élargissement de l'interface AppClient.
- **Montage UI** : wizard + provider de tour dans `Layout.jsx` (post-auth, post-workspace garantis). Checklist = widget dashboard (`WidgetCatalog`). Visite = ancres `data-tour` stables sur la sidebar (`Layout.jsx` navigation). Menu d'aide « ? » à ajouter dans l'en-tête (absent aujourd'hui).
- **Invitations (étape 3)** : réutilise `inviteUserWithPermissions` (rôles admin/member/volunteer).
- **§4 « Profil structure »** : les champs légaux existent dans `Production.jsonc` (= partie tierce). Pour la PROPRE structure → nouvelle entité workspace-scoped calquée sur Production (résolu dans #1267).
### Découpage (6 sous-tâches, ordre de dépendance)
1. #1263 Backend OnboardingState + GET/PATCH + couture AppClient (fondation, bloque le reste)
2. #1264 WelcomeWizard 3 étapes + écran de fin
3. #1265 Checklist « Premiers pas » (deep-links + auto-complétion par événements métier + réordonnancement par rôle)
4. #1266 ProductTour ~6 étapes (data-tour + réactivation menu d'aide)
5. #1267 Profilage progressif (ProgressiveFieldPrompt + déclencheurs §4 + résolution Profil structure)
6. #1268 Télémétrie §10 (wrapper léger landé tôt)
DoD = §11 du cahier. Copy FR définitive intégrée mot pour mot dans chaque sous-tâche.
Description
Concevoir l'expérience de premier lancement (par espace/workspace) après création de compte / entrée dans un nouvel espace. Source : cahier de développement `scobby-onboarding-cahier-developpement.md` (copy FR définitive). Couvre la visite guidée *haut niveau* (les coachmarks page par page sont hors périmètre, doc séparé).
**Principe directeur :** minimum bloquant à l'entrée, profilage progressif (champs lourds réclamés au moment où ils deviennent nécessaires), tout sautable/réactivable, guider par l'action.
**Périmètre :**
1. **Wizard d'amorçage** (modale plein écran, barre 1/3→3/3, « Passer » partout) — Étape 1 *Bienvenue & vous* (prénom, nom, rôle — bloquant), Étape 2 *Votre structure* (nom + type — bloquant léger ; nb d'événements/an facultatif), Étape 3 *Invitez votre équipe* (facultatif, réutilise les rôles existants). Écran de fin → visite guidée ou checklist. Le rôle réordonne visite + checklist.
2. **Checklist « Premiers pas »** — widget tableau de bord persistant, 7 items deep-link, progression X/7, mise à jour aussi par **événements métier** (créer un événement coche l'item), réductible/masquable.
3. **Profilage progressif** — encart contextuel `ProgressiveFieldPrompt` réclamant adresse/SIRET/APE, forme juridique, licence spectacle, IBAN/BIC + signataire, salles & jauges, modèles de deals, fournisseurs, hôtels — chacun à son déclencheur, mémorisé (one-time). NB : confirmer la table de destination du « Profil structure » (infos légales du lieu en tant que partie au contrat).
4. **Visite guidée haut niveau** — spotlight ~6 étapes sur la sidebar via attributs `data-tour` stables, 1 phrase/étape, sautable, réactivable depuis le menu d'aide.
5. **Persistance serveur par espace** — `OnboardingState` (cf. §8), endpoints `GET/PATCH /onboarding/:workspaceId` ; jamais re-déclenché après complétion (sauf nouvel espace).
6. **Télémétrie** des étapes (ouverture, complétion/abandon par étape, skip, items checklist, visite, encarts progressifs).
7. **A11y** : focus piégé, Échap = passer, `aria-current`, contraste AA, infobulles annoncées.
**Design :** réutilise le design system landing (dégradé orange #F59E0B→#EA580C, slate-900, `rounded-xl`/`rounded-full`).
**Definition of Done :** voir §11 du cahier (wizard 3 étapes/2 bloquantes ; aucun champ lourd à l'inscription ; profilage progressif au bon déclencheur ; checklist 7 items + maj par événements métier ; visite ~6 étapes data-tour réactivable ; état persisté par espace ; réordonnancement par rôle ; copy FR mot pour mot ; a11y ; télémétrie).
Stack Scobby : frontend React 18 + Vite (seam `src/api/client/` / `base44` AppClient) ; backend self-hosté `server/` NestJS + Prisma (hexagonal), schéma Prisma généré depuis `base44/entities/*.jsonc`.