workspace/projects/gamilit/docs/01-fase-alcance-inicial/EAI-001-fundamentos/historias-usuario/US-FUND-003-dashboard-principal-estudiante.md

US-FUND-003: Dashboard principal estudiante

Épica: EAI-001 - Fundamentos Sprint: Mes 1, Semana 2 Story Points: 8 SP Presupuesto: $2,900 MXN Prioridad: Alta (Alcance Inicial) Estado: ✅ Completada (Mes 1)

---

Descripción

Como estudiante, quiero ver un dashboard gamificado con mi progreso actual para mantenerme motivado y visualizar mis logros y actividades pendientes.

Contexto del Alcance Inicial: El dashboard del MVP muestra información gamificada básica: nivel, XP, monedas, módulos disponibles y actividades pendientes. Los datos están hardcodeados en la base de datos como seed data. No incluye gráficas avanzadas, estadísticas comparativas ni personalización, que se agregarán en extensiones futuras.

---

Criterios de Aceptación

• CA-01: El dashboard muestra el nivel actual del estudiante (rango Maya)
• CA-02: Se visualiza la experiencia (XP) actual y progreso hacia el siguiente nivel
• CA-03: Se muestran las monedas lectoras (ML Coins) disponibles
• CA-04: Se listan los módulos educativos disponibles (hardcodeados)
• CA-05: Cada módulo muestra: título, descripción breve, progreso (%), icono
• CA-06: Se destacan las actividades pendientes del día
• CA-07: Se muestra un mensaje motivacional relacionado con el progreso
• CA-08: El dashboard es responsive (mobile, tablet, desktop)
• CA-09: Se actualiza en tiempo real al completar actividades
• CA-10: Incluye navegación rápida a módulos y perfil

---

Especificaciones Técnicas

Backend (NestJS)

Endpoints:

GET /api/dashboard/student
- Headers: Authorization: Bearer {token}
- Response: {
    student: {
      id, firstName, lastName, photoUrl,
      level: number,
      rankName: string,
      currentXP: number,
      xpToNextLevel: number,
      coins: number
    },
    modules: [
      {
        id, title, description, iconUrl,
        totalActivities: number,
        completedActivities: number,
        progress: number, // percentage
        isLocked: boolean
      }
    ],
    pendingActivities: [
      {
        id, moduleId, moduleName, title, type,
        estimatedTime: number, // minutes
        dueDate?: Date
      }
    ],
    motivationalMessage: string,
    recentAchievements: [
      { badgeId, badgeName, earnedAt }
    ]
  }

Servicios:

• DashboardService: Lógica de agregación de datos
• StudentProgressService: Cálculo de progreso y estadísticas
• ModulesService: Obtención de módulos y actividades
• GamificationService: Nivel, XP, monedas, rangos

Consultas Optimizadas:

• Join de múltiples tablas (students, modules, activities, progress)
• Caching para datos que no cambian frecuentemente (módulos)
• Agregaciones SQL para conteos y promedios

Frontend (React + Vite)

Componentes:

- StudentDashboard.tsx: Contenedor principal
- ProgressCard.tsx: Card con nivel, XP, monedas
  - LevelDisplay.tsx: Visualización de rango Maya
  - XPProgressBar.tsx: Barra de progreso XP
  - CoinsDisplay.tsx: Contador de monedas
- ModulesGrid.tsx: Grid de módulos disponibles
  - ModuleCard.tsx: Card individual de módulo
- PendingActivitiesList.tsx: Lista de pendientes
  - ActivityItem.tsx: Item individual
- MotivationalBanner.tsx: Banner con mensaje
- RecentAchievements.tsx: Últimas insignias

Rutas:

• /dashboard - Dashboard principal (redireccionado desde /)

Estado (Zustand):

interface DashboardStore {
  dashboardData: DashboardData | null
  loading: boolean
  error: string | null
  fetchDashboard: () => Promise<void>
  refreshDashboard: () => Promise<void>
}

UI/UX:

• Layout en grid responsive (CSS Grid / Flexbox)
• Cards con sombras sutiles y hover effects
• Colores del tema Maya (verdes, terracotas, dorados)
• Iconos de Heroicons o similar
• Skeleton loaders mientras carga
• Animaciones suaves con Framer Motion

Diseño Visual

Layout Desktop:

┌─────────────────────────────────────────┐
│ Header (Navbar)                         │
├─────────────────┬───────────────────────┤
│ Progress Card   │ Motivational Banner   │
│ (Nivel/XP/Coins)│                       │
├─────────────────┴───────────────────────┤
│ Módulos Disponibles (Grid 3x2)         │
│ [Card] [Card] [Card]                    │
│ [Card] [Card] [Card]                    │
├─────────────────────────────────────────┤
│ Actividades Pendientes (List)           │
│ - Actividad 1                           │
│ - Actividad 2                           │
└─────────────────────────────────────────┘

Layout Mobile:

• Stacked vertical
• Progress card en top
• Módulos en grid 1 columna
• Actividades al final

---

Dependencias

Antes:

• US-FUND-001 (Autenticación)
• US-FUND-002 (Perfil - usa foto)
• US-GAM-001 (Sistema de rangos)
• US-GAM-002 (Sistema XP)
• US-GAM-003 (Monedas)

Después:

• Punto de entrada principal para navegación a actividades
• Base para dashboard de profesor (diferente vista)

---

Definición de Hecho (DoD)

• Endpoint de dashboard implementado
• Optimización de queries (máx 3 queries)
• Componentes de frontend implementados
• Responsive design probado (mobile, tablet, desktop)
• Loading states y error handling
• Tests unitarios (>80% coverage)
• Tests E2E para dashboard load
• Performance: dashboard carga en <2 segundos
• Documentación de componentes

---

Notas del Alcance Inicial

• ✅ Datos hardcodeados: módulos pre-cargados en BD
• ✅ Sin gráficas avanzadas (barras, líneas, comparativas)
• ✅ Sin filtros de tiempo (última semana, mes, etc.)
• ✅ Sin leaderboard en dashboard (existe separado en US-GAM-007)
• ✅ Mensajes motivacionales fijos (no personalizados por IA)
• ✅ Sin notificaciones push
• ⚠️ Extensión futura: EXT-005-Analytics (gráficas, estadísticas avanzadas)
• ⚠️ Extensión futura: EXT-006-Personalization (dashboard personalizable)
• ⚠️ Extensión futura: EXT-007-Social (actividad de amigos en dashboard)

---

Tareas de Implementación

Backend (Estimado: 16h, Real: 17.5h)

Total Backend: 17.5h (~4.4 SP)

• Tarea B.1: Servicios de datos y agregación - Estimado: 6h, Real: 7h

  • Subtarea B.1.1: DashboardService con lógica de agregación - 2h
  • Subtarea B.1.2: StudentProgressService para cálculo de progreso - 2h
  • Subtarea B.1.3: GamificationService para nivel, XP, monedas - 1.5h
  • Subtarea B.1.4: ModulesService para obtener módulos y actividades - 1.5h

• Tarea B.2: Endpoint GET /dashboard/student - Estimado: 5h, Real: 5.5h

  • Subtarea B.2.1: Estructura de response con todos los campos - 1.5h
  • Subtarea B.2.2: Queries SQL optimizadas con joins - 2h
  • Subtarea B.2.3: Cálculo de progreso por módulo - 1h
  • Subtarea B.2.4: Filtrado de actividades pendientes - 1h

• Tarea B.3: Seed data de módulos - Estimado: 3h, Real: 3h

  • Subtarea B.3.1: Script de seed con módulos educativos Maya - 1.5h
  • Subtarea B.3.2: Actividades hardcodeadas por módulo (5-10 cada uno) - 1h
  • Subtarea B.3.3: Mensajes motivacionales en base de datos - 0.5h

• Tarea B.4: Optimización y caching - Estimado: 2h, Real: 2h

  • Subtarea B.4.1: Optimización de queries (máximo 3 queries) - 1h
  • Subtarea B.4.2: Índices en base de datos - 0.5h
  • Subtarea B.4.3: Documentación Swagger del endpoint - 0.5h

Frontend (Estimado: 10h, Real: 10h)

Total Frontend: 10h (~2.5 SP)

• Tarea F.1: Componentes de dashboard - Estimado: 6h, Real: 6h

  • Subtarea F.1.1: StudentDashboard (contenedor principal) - 1h
  • Subtarea F.1.2: ProgressCard con nivel/XP/monedas - 1.5h
  • Subtarea F.1.3: ModulesGrid y ModuleCard - 1.5h
  • Subtarea F.1.4: PendingActivitiesList - 1h
  • Subtarea F.1.5: MotivationalBanner y RecentAchievements - 1h

• Tarea F.2: Estado y layout - Estimado: 4h, Real: 4h

  • Subtarea F.2.1: DashboardStore en Zustand - 1h
  • Subtarea F.2.2: Layout responsive con CSS Grid - 1.5h
  • Subtarea F.2.3: Skeleton loaders mientras carga - 1h
  • Subtarea F.2.4: Página /dashboard con rutas - 0.5h

Testing (Estimado: 4h, Real: 3.5h)

Total Testing: 3.5h (~0.9 SP)

• Tarea T.1: Tests unitarios backend - Estimado: 2h, Real: 1.5h

  • Subtarea T.1.1: Tests de DashboardService (agregación) - 0.5h
  • Subtarea T.1.2: Tests de StudentProgressService (cálculos) - 0.5h
  • Subtarea T.1.3: Tests de GamificationService - 0.5h

• Tarea T.2: Tests E2E - Estimado: 1h, Real: 1h

  • Subtarea T.2.1: Tests de endpoint GET /dashboard/student - 0.5h
  • Subtarea T.2.2: Tests de performance (carga < 2s) - 0.5h

• Tarea T.3: Tests frontend - Estimado: 1h, Real: 1h

  • Subtarea T.3.1: Tests de componentes de dashboard - 0.5h
  • Subtarea T.3.2: Tests de DashboardStore - 0.5h

Deployment (Estimado: 2h, Real: 1h)

Total Deployment: 1h (~0.25 SP)

• Tarea D.1: Seed data en producción - Estimado: 1h, Real: 0.5h

  • Subtarea D.1.1: Ejecutar seeds de módulos - 0.25h
  • Subtarea D.1.2: Verificar integridad de datos - 0.25h

• Tarea D.2: Deploy y validación - Estimado: 1h, Real: 0.5h

  • Subtarea D.2.1: Deploy a staging - 0.25h
  • Subtarea D.2.2: Smoke tests de dashboard - 0.25h

---

Resumen de Horas

Categoría	Estimado	Real	Variación
Backend	16h	17.5h	+9.4%
Frontend	10h	10h	0%
Testing	4h	3.5h	-12.5%
Deployment	2h	1h	-50%
TOTAL	32h	32h	0%

Validación: 8 SP × 4h/SP = 32 horas estimadas ✅

---

Cronograma Real

Sprint: Sprint 1-2 (05-16 Agosto 2024) Fecha Inicio Real: 09 Agosto 2024 Fecha Fin Real: 12 Agosto 2024 Estado: ✅ Completada Notas: La optimización de queries tomó más tiempo del estimado, pero el frontend avanzó más rápido gracias al sistema de diseño base. El dashboard quedó muy performante (<1.5s de carga) y visualmente atractivo con el tema Maya.

---

Testing

Tests Unitarios

describe('DashboardService', () => {
  it('should aggregate student data correctly')
  it('should calculate module progress')
  it('should fetch pending activities')
  it('should select appropriate motivational message')
})

describe('StudentProgressService', () => {
  it('should calculate XP to next level')
  it('should determine current rank')
})

Tests E2E

describe('Dashboard API', () => {
  it('GET /dashboard/student - returns complete data')
  it('GET /dashboard/student - handles no progress')
  it('GET /dashboard/student - unauthorized returns 401')
})

Tests Frontend

describe('StudentDashboard', () => {
  it('renders all dashboard sections')
  it('displays correct XP progress')
  it('shows modules with progress')
  it('lists pending activities')
  it('shows loading state')
  it('handles error state')
  it('navigates to module on click')
})

Tests de Performance

it('dashboard loads in under 2 seconds')
it('handles 20+ modules without lag')

---

Estimación

Desglose de Esfuerzo (8 SP = ~3 días):

• Backend: queries + aggregation: 1 día
• Frontend: layout + components: 1.5 días
• UI/UX: styling + responsive: 0.75 días
• Testing: 0.5 días
• Optimización: 0.25 días

Riesgos:

• Queries complejas pueden requerir optimización
• Responsive design puede tomar más tiempo del estimado
• Datos hardcodeados deben estar bien estructurados

---

Seed Data Requerido

Módulos Educativos (ejemplo):

INSERT INTO modules (title, description, icon_url, order) VALUES
('Números Mayas', 'Aprende el sistema numérico maya', '/icons/numeros.svg', 1),
('Calendario Haab', 'Descubre el calendario solar maya', '/icons/calendario.svg', 2),
('Astronomía Maya', 'Explora los conocimientos astronómicos', '/icons/astronomia.svg', 3),
...

Actividades (ejemplo):

• Cada módulo tiene 5-10 actividades hardcodeadas
• Tipos variados: multiple choice, drag & drop, etc.

---

Creado: 2025-11-02 Actualizado: 2025-11-02 Responsable: Equipo Fullstack