1-5-onboarding-guide-fr2.md 9.8 KB

Story 1.5: Onboarding guidé (FR2)

Status: done

Story

En tant que Transformateur, je veux suivre une checklist guidée (configurer contexte → soumettre 1ère idée → inviter contributeurs → attendre 48h), afin de démarrer rapidement sans me perdre.

Acceptance Criteria

  1. Given je viens de créer mon workspace When je vois la checklist d'onboarding (configurer contexte → soumettre 1ère idée → inviter contributeurs → attendre 48h) Then chaque étape complétée est cochée visuellement

  2. And les étapes sont skipables sauf la configuration de base (configurer secteur et taille)

  3. And l'ordre des étapes peut être adapté : "inviter des contributeurs" peut précéder "soumettre une 1ère idée" si le Transformateur le souhaite

  4. And les étapes dont la fonctionnalité sous-jacente n'existe pas encore (Epic 2) affichent un état "À venir" avec un libellé explicatif — la checklist reste utilisable et l'étape "configurer contexte" est fonctionnelle immédiatement

Tasks / Subtasks

  • [x] Task 1 : Composant OnboardingChecklist (AC: #1, #2, #3, #4)

    • Subtask 1.1 : Créer OnboardingChecklist.tsx dans components/workspace/
    • Subtask 1.2 : Définir les 4 étapes : configurer contexte, soumettre 1ère idée, inviter contributeurs, attendre 48h
    • Subtask 1.3 : État visuel par étape : done (checkmark), pending (lien actif), à venir (badge + libellé)
    • Subtask 1.4 : Étape "configurer contexte" → lien vers /workspace/[id]/settings, marquée done si workspace.sector OU workspace.companySize renseigné
    • Subtask 1.5 : Étapes "soumettre 1ère idée" et "inviter contributeurs" → état "À venir" (Epic 2) avec message court
    • Subtask 1.6 : Étape "attendre 48h" → état informatif, message rassurant sur le délai attendu
    • Subtask 1.7 : Bouton "Passer" (skip) sur étapes skipables — sauf configurer contexte
    • Subtask 1.8 : Permettre réordonnancement des étapes 2 et 3 (soumettre / inviter) — drag & drop ou boutons monter/descendre
  • [x] Task 2 : Intégration dashboard workspace (AC: #1)

    • Subtask 2.1 : Intégrer OnboardingChecklist dans workspace/[workspaceId]/page.tsx
    • Subtask 2.2 : Afficher la checklist en priorité si au moins une étape non complétée
    • Subtask 2.3 : Optionnel : masquer ou réduire la checklist une fois toutes les étapes complétées (ou garder visible pour rappel)
  • [x] Task 3 : Persistance préférence ordre (AC: #3)

    • Subtask 3.1 : Stocker l'ordre préféré des étapes (ex. champ onboardingStepOrder JSON sur Workspace, ou localStorage côté client pour MVP)
    • Subtask 3.2 : Si persistance Workspace : ajouter migration Prisma si nouveau champ ; sinon documenter choix localStorage
  • [x] Task 4 : Tests et UX (AC: #1, #2, #3)

    • Subtask 4.1 : Tests unitaires composant — états done/pending/à venir, skip, ordre
    • Subtask 4.2 : Vérifier accessibilité (WCAG 2.1 AA) — focus, labels, structure sémantique
    • Subtask 4.3 : Design tokens Livinia Chaleureux, cohérence avec dashboard existant

Dev Notes

Contexte technique

  • Story 1.4 : Page settings /workspace/[workspaceId]/settings existe avec WorkspaceSettingsForm. L'étape "configurer contexte" pointe vers cette page.
  • Workspace : sector et companySize (Prisma) — si l'un des deux est renseigné, l'étape config est considérée complétée.
  • Epic 2 : Formulaire soumission (Story 2.2) et invitation contributeurs (Story 2.1) n'existent pas encore. Les étapes correspondantes affichent "À venir — disponible prochainement" ou équivalent.
  • Architecture : components/workspace/OnboardingChecklist prévu dans architecture.md. Point d'entrée : workspace/[workspaceId]/page.tsx.

Définition des étapes

# Étape Critère "done" État MVP
1 Configurer le contexte entreprise workspace.sector OU workspace.companySize non null Fonctionnel — lien settings
2 Soumettre une 1ère idée ≥ 1 idée dans le workspace (Epic 3) À venir
3 Inviter des contributeurs ≥ 1 invitation envoyée (Epic 2) À venir
4 Attendre les premières soumissions (48h) Informative — message rassurant Toujours "en attente" jusqu'à Epic 2/3

Ordre flexible (AC #3)

  • Étapes 2 et 3 sont interchangeables : le Transformateur peut inviter avant de soumettre sa 1ère idée.
  • Implémentation : liste ordonnée avec possibilité de swap 2↔3. Pour MVP, deux ordres prédéfinis au clic ("Inviter d'abord" / "Soumettre d'abord") suffisent si drag & drop complexifie.
  • Persistance : localStorage onboarding_preferred_order ou champ Workspace. Documenter le choix.

Patterns à respecter

  • shadcn/ui : Checkbox (done), Badge (à venir), Button (skip), éventuellement @dnd-kit/core si drag & drop
  • tRPC : Pas de nouveau router pour cette story. La page [workspaceId]/page.tsx est un Server Component qui charge le workspace via db.workspace.findFirst. OnboardingChecklist reçoit workspace en props — pas de hook tRPC côté client pour cette donnée.
  • Design tokens : Livinia Chaleureux (#fefdfb, #7c3aed, #e7e5e4)
  • Empty state : Message rassurant pour "attendre 48h" — "Vos premières idées apparaîtront ici dans 48h à 3 jours" (UX spec)

Architecture Compliance

  • Multi-tenant : OnboardingChecklist reçoit workspaceId et workspace en props. Jamais de requête sans vérification owner.
  • Structure : src/components/workspace/OnboardingChecklist.tsx, src/app/(dashboard)/workspace/[workspaceId]/page.tsx
  • Pas de Route Handler : tout côté client + tRPC/React Query pour données workspace

Library / Framework Requirements

  • shadcn/ui : Checkbox, Badge, Button, Card (pour conteneur checklist), Progress (optionnel pour barre de progression)
  • React : État local pour ordre des étapes si pas de persistance serveur
  • Server Component : La page parent passe workspace (sector, companySize) en props à OnboardingChecklist. Pas de tRPC pour la lecture initiale.

File Structure Requirements

Fichier Action
src/components/workspace/OnboardingChecklist.tsx Créer
src/app/(dashboard)/workspace/[workspaceId]/page.tsx Modifier — intégrer OnboardingChecklist
prisma/schema.prisma Modifier uniquement si persistance ordre sur Workspace (champ optionnel onboardingStepOrder)

Testing Requirements

  • Unit : OnboardingChecklist — étape config done quand sector/companySize, étapes 2–3 en "À venir", skip désactivé sur config
  • Composant : Rendu des 4 étapes, états visuels corrects, lien settings fonctionnel
  • E2E (optionnel) : Parcours complet config → checklist mise à jour

Previous Story Intelligence (1.4)

  • Workspace router : update et list existent. Pas de getById — la page dashboard utilise db.workspace.findFirst directement (Server Component). OnboardingChecklist reçoit workspace en props.
  • Dashboard : [workspaceId]/page.tsx affiche name, slug, contactEmail, sector, companySize, lien settings. needsConfig déjà calculé.
  • WorkspaceSettingsForm : Client component avec Select sector, Input companySize. Invalidation après mutation.
  • createWorkspaceProcedure : Utiliser pour toute opération workspace. workspace.getMine retourne le workspace unique de l'utilisateur (1 user = 1 workspace).
  • getSectorLabel : Utilisé pour affichage secteur. Réutiliser si besoin dans checklist.

Project Context Reference

  • Pas de project-context.md trouvé. Suivre conventions architecture.md et patterns Story 1.3, 1.4.

Références

  • [Source: epics.md#Story 1.5]
  • [Source: architecture.md#User Journey to Structure Mapping — Onboarding CDO]
  • [Source: ux-design-specification.md#J1 — Onboarding CDO (Marc)]
  • [Source: implementation-readiness-report-2026-02-27.md#Story 1.5 forward reference]
  • [Source: prd.md#FR2]

Change Log

  • 2026-02-27 : Implémentation complète — OnboardingChecklist, intégration dashboard, persistance localStorage, tests Vitest
  • 2026-02-27 : Code review — fixes : lien Soumettre→/submit/slug, suppression badge "À venir" sur submit_first_idea, index map O(1), slug passé en prop depuis page.tsx

Dev Agent Record

Agent Model Used

{{agent_model_name_version}}

Debug Log References

Completion Notes List

  • Composant OnboardingChecklist créé avec 4 étapes : config, soumettre 1ère idée, inviter contributeurs, attendre 48h
  • États visuels : done (checkmark), pending (lien Configurer), à venir (Badge)
  • Bouton "Passer" sur étapes skipables (sauf config)
  • Toggle "Inviter d'abord" / "Soumettre d'abord" pour réordonnancement étapes 2 et 3
  • Persistance localStorage : onboarding_preferredorder{workspaceId}, onboarding_skippedsteps{workspaceId}
  • Intégration dans workspace/[workspaceId]/page.tsx
  • Tests unitaires : 7 tests (rendu, config done/pending, À venir, Passer, skip désactivé sur config)
  • shadcn : Checkbox, Badge, Card ajoutés ; @testing-library/react, jest-dom, jsdom pour tests

File List

  • aimpact-hub/src/components/workspace/OnboardingChecklist.tsx (créé)
  • aimpact-hub/src/components/workspace/OnboardingChecklist.test.tsx (créé)
  • aimpact-hub/src/app/(dashboard)/workspace/[workspaceId]/page.tsx (modifié)
  • aimpact-hub/src/components/ui/checkbox.tsx (ajouté via shadcn)
  • aimpact-hub/src/components/ui/badge.tsx (ajouté via shadcn)
  • aimpact-hub/src/components/ui/card.tsx (ajouté via shadcn)
  • aimpact-hub/vitest.config.ts (modifié — jsdom, setupFiles)
  • aimpact-hub/vitest.setup.ts (créé)
  • aimpact-hub/package.json (modifié — @testing-library/react, jest-dom, jsdom)