michangarrito/docs/01-epicas/MCH-033-onboarding-wizard.md

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	dependencies
EPIC-MCH-033	Epic	MCH-033: Onboarding Wizard	MCH-033	Planificado	8	P2	2026-01-10	2026-01-10	4.0.1	blocks depends_on MCH-029

MCH-033: Onboarding Wizard

Metadata

• Codigo: MCH-033
• Fase: 8 - Mejoras UX
• Prioridad: P2
• Estado: Planificado
• Story Points: 3
• Sprint Objetivo: Sprint 9

Descripcion

Crear asistente interactivo de configuracion inicial que guie al usuario en los primeros pasos de setup de su negocio. Reduce friccion, aumenta activacion y mejora la experiencia de primer uso.

Objetivos

1. Guiar configuracion inicial de negocio
2. Facilitar carga de primeros productos
3. Configurar metodos de pago
4. Invitar al equipo
5. Mostrar tour interactivo de la app

Alcance

Incluido

• Wizard de 5 pasos con progreso
• Persistencia de progreso (continuar despues)
• Skip opcional por paso
• Productos sugeridos por giro de negocio
• Animacion de celebracion al completar

Excluido

• Migracion desde otros sistemas
• Importacion masiva de productos (otra feature)
• Video tutoriales (contenido futuro)

Arquitectura

                    ┌─────────────────────────────────────┐
                    │    MCH-033: Onboarding Wizard       │
                    └─────────────────────────────────────┘
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        ▼                             ▼                             ▼
  ┌──────────────┐           ┌──────────────┐           ┌──────────────┐
  │    Paso 1    │           │   Paso 2     │           │   Paso 3     │
  │  Mi Negocio  │   ───>    │  Productos   │   ───>    │    Pagos     │
  └──────────────┘           └──────────────┘           └──────────────┘
                                                               │
                                                               ▼
                             ┌──────────────┐           ┌──────────────┐
                             │   Paso 5     │   <───    │   Paso 4     │
                             │  Completar   │           │   Mi Equipo  │
                             └──────────────┘           └──────────────┘

                    ┌─────────────────────────────────────┐
                    │         Onboarding Progress         │
                    │   (tenant_settings.onboarding)      │
                    └─────────────────────────────────────┘

Entregables

Entregable	Estado	Sprint	Ubicacion
OnboardingWizard component	Planificado	9	apps/web/src/components/onboarding/
BusinessSetupStep	Planificado	9	apps/web/src/components/onboarding/steps/
ProductsStep	Planificado	9	apps/web/src/components/onboarding/steps/
PaymentsStep	Planificado	9	apps/web/src/components/onboarding/steps/
TeamStep	Planificado	9	apps/web/src/components/onboarding/steps/
CompletionStep	Planificado	9	apps/web/src/components/onboarding/steps/

Dependencias

Depende de

• MCH-029 (Infraestructura completa para guardar progreso)

Bloquea a

• Ninguna

---

Historias de Usuario

MCH-US-111: Wizard de Configuracion

Como usuario nuevo Quiero una guia paso a paso para configurar mi negocio Para empezar a usar la app rapidamente

Story Points: 3

Criterios de Aceptacion:

• [CA-111-1] Wizard de 5 pasos: Negocio, Productos, Pagos, Equipo, Completar
• [CA-111-2] Progreso guardado en backend (puede cerrar y continuar)
• [CA-111-3] Skip opcional por cada paso (excepto paso 1)
• [CA-111-4] Productos iniciales sugeridos segun giro seleccionado
• [CA-111-5] Animacion de confetti al completar

Tareas:

ID	Tarea	Tipo	SP
MCH-TT-111-01	OnboardingWizard container	Frontend	0.25
MCH-TT-111-02	Paso 1: Datos de negocio (nombre, giro, logo)	Frontend	0.5
MCH-TT-111-03	Paso 2: Productos iniciales (templates por giro)	Frontend	0.5
MCH-TT-111-04	Paso 3: Metodos de pago (conexion Stripe/MercadoPago)	Frontend	0.5
MCH-TT-111-05	Paso 4: Invitar equipo (emails de colaboradores)	Frontend	0.25
MCH-TT-111-06	Paso 5: Completar con confetti y tour	Frontend	0.25
MCH-TT-111-07	Persistencia de progreso en backend	Backend	0.25
MCH-TT-111-08	Tests	Test	0.25
MCH-TT-111-09	Documentacion	Docs	0.25

---

Resumen de Story Points

Historia	SP	Sprint
MCH-US-111: Wizard de Configuracion	3	9
TOTAL	3	9

---

Criterios de Aceptacion de Epica

• Wizard visible para nuevos usuarios
• Progreso persistido correctamente
• Productos sugeridos por giro funcionando
• Animacion de celebracion al completar
• Tests de flujo completo

Notas Tecnicas

Persistencia de Progreso

// tenant_settings.onboarding
{
  "current_step": 2,
  "completed_steps": [1],
  "skipped_steps": [],
  "started_at": "2026-01-10T10:00:00Z",
  "completed_at": null,
  "data": {
    "business_type": "abarrotes",
    "products_count": 15
  }
}

Giros y Productos Sugeridos

Giro	Productos Sugeridos
Abarrotes	Refrescos, Galletas, Pan, Leche, Huevos
Papeleria	Cuadernos, Lapices, Colores, Folders
Ferreteria	Tornillos, Pintura, Brochas, Herramientas
Farmacia	Medicamentos basicos, Vitaminas
Comida	Tacos, Tortas, Aguas, Refrescos

Componente OnboardingWizard

function OnboardingWizard() {
  const [step, setStep] = useState(1);
  const [progress, saveProgress] = useOnboardingProgress();

  const steps = [
    { id: 1, name: 'Mi Negocio', component: BusinessSetupStep },
    { id: 2, name: 'Productos', component: ProductsStep },
    { id: 3, name: 'Pagos', component: PaymentsStep },
    { id: 4, name: 'Mi Equipo', component: TeamStep },
    { id: 5, name: 'Completar', component: CompletionStep },
  ];

  const CurrentStep = steps[step - 1].component;

  return (
    <div className="onboarding-wizard">
      <ProgressBar steps={steps} current={step} />
      <CurrentStep
        onNext={() => setStep(s => s + 1)}
        onSkip={() => setStep(s => s + 1)}
        saveProgress={saveProgress}
      />
    </div>
  );
}

Animacion de Celebracion

Usar libreria canvas-confetti para el efecto de confetti al completar:

import confetti from 'canvas-confetti';

function CompletionStep() {
  useEffect(() => {
    confetti({
      particleCount: 100,
      spread: 70,
      origin: { y: 0.6 }
    });
  }, []);

  return (
    <div className="completion">
      <h1>Tu negocio esta listo</h1>
      <Button onClick={startTour}>Iniciar tour</Button>
    </div>
  );
}

---

Ultima actualizacion: 2026-01-10 Autor: Architecture Team