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

---
id: EPIC-MCH-033
type: Epic
title: "MCH-033: Onboarding Wizard"
code: MCH-033
status: Planificado
phase: 8
priority: P2
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "4.0.1"
dependencies:
  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

```typescript
// 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

```tsx
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:

```tsx
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