workspace/projects/gamilit/docs/01-fase-alcance-inicial/EAI-004-analytics/historias-usuario/US-ANA-001-dashboard-clase-basico.md

US-ANA-001: Dashboard de Clase Básico

Épica: EAI-004 (Analytics Básico) Sprint: Mes 1, Semana 3 Story Points: 8 SP Presupuesto: $4,000 MXN Prioridad: Alta (Alcance Inicial) Estado: ✅ Completada (Mes 1)

---

Descripción

Como profesor, quiero visualizar un dashboard básico de mi clase para obtener un resumen rápido del estado general de mis estudiantes sin tener que revisar cada uno individualmente.

Contexto del Alcance Inicial:

Este dashboard proporciona las métricas fundamentales que un profesor necesita en su día a día: número de estudiantes, progreso promedio de la clase, y las últimas actividades registradas. Se enfoca en visualizaciones simples y directas, sin análisis avanzados, predicciones ML, o configurabilidad de métricas (eso va a EXT-005 Reportes Avanzados).

---

Criterios de Aceptación

CA-01: Métricas Generales de la Clase

• El dashboard muestra el número total de estudiantes en la clase
• Muestra el porcentaje de completitud promedio de la clase
• Muestra el nivel promedio de los estudiantes
• Muestra el XP total acumulado de la clase

CA-02: Visualizaciones Básicas

• Gráfica de barras: distribución de estudiantes por nivel
• Gráfica de pie chart: porcentaje de módulos completados vs pendientes
• Gráfica de barras: progreso por módulo educativo
• Todas las gráficas se renderizan correctamente en desktop y mobile

CA-03: Actividades Recientes

• Muestra las últimas 10 actividades de la clase
• Cada actividad muestra: estudiante, módulo, actividad, fecha/hora
• Las actividades están ordenadas de más reciente a más antigua
• Se actualiza automáticamente cada 5 minutos

CA-04: Navegación Rápida

• Botón "Ver Todos los Estudiantes" que lleva a US-ANA-002
• Botón "Ver Reportes" que lleva a US-ANA-004
• Selector de clase (si el profesor tiene múltiples clases)

CA-05: Performance y UX

• El dashboard carga en menos de 2 segundos
• Muestra skeleton loaders mientras carga los datos
• Maneja correctamente el caso de clase sin estudiantes
• Muestra mensajes amigables si no hay datos

---

Especificaciones Técnicas

Backend

Endpoint Principal:

GET /api/teacher/classroom/{classroomId}/dashboard

Response:

{
  "classroomId": "uuid",
  "classroomName": "Matemáticas 6A",
  "metrics": {
    "totalStudents": 25,
    "averageProgress": 65.5,
    "averageLevel": 3,
    "totalXP": 12500
  },
  "levelDistribution": [
    {"level": 1, "count": 5},
    {"level": 2, "count": 8},
    {"level": 3, "count": 10},
    {"level": 4, "count": 2}
  ],
  "moduleCompletion": {
    "completed": 60,
    "inProgress": 30,
    "notStarted": 10
  },
  "moduleProgress": [
    {"moduleName": "Fracciones", "averageProgress": 75},
    {"moduleName": "Geometría", "averageProgress": 55},
    {"moduleName": "Álgebra", "averageProgress": 45}
  ],
  "recentActivities": [
    {
      "studentName": "Juan Pérez",
      "moduleName": "Fracciones",
      "activityName": "Suma de fracciones",
      "timestamp": "2025-11-02T10:30:00Z",
      "type": "completed"
    }
  ]
}

Controller:

// TeacherAnalyticsController.ts
@Get('classroom/:classroomId/dashboard')
async getClassroomDashboard(
  @Param('classroomId') classroomId: string,
  @CurrentUser() teacher: User
) {
  return this.analyticsService.getClassroomDashboard(classroomId, teacher.id);
}

Service:

// TeacherAnalyticsService.ts
async getClassroomDashboard(classroomId: string, teacherId: string) {
  // Validar que el profesor tiene acceso a la clase
  await this.validateTeacherAccess(classroomId, teacherId);

  // Obtener métricas generales
  const metrics = await this.calculateClassMetrics(classroomId);

  // Obtener distribución por nivel
  const levelDistribution = await this.getLevelDistribution(classroomId);

  // Obtener completitud de módulos
  const moduleCompletion = await this.getModuleCompletion(classroomId);

  // Obtener progreso por módulo
  const moduleProgress = await this.getModuleProgress(classroomId);

  // Obtener actividades recientes (últimas 10)
  const recentActivities = await this.getRecentActivities(classroomId, 10);

  return {
    classroomId,
    metrics,
    levelDistribution,
    moduleCompletion,
    moduleProgress,
    recentActivities
  };
}

Frontend

Ruta:

/teacher/classroom/:classroomId/dashboard

Componente Principal:

// ClassroomDashboard.tsx
export const ClassroomDashboard = () => {
  const { classroomId } = useParams();
  const { dashboardData, isLoading } = useClassroomDashboard(classroomId);

  if (isLoading) return <DashboardSkeleton />;

  return (
    <div className="dashboard-container">
      <MetricsCards metrics={dashboardData.metrics} />
      <ChartSection>
        <LevelDistributionChart data={dashboardData.levelDistribution} />
        <ModuleCompletionPieChart data={dashboardData.moduleCompletion} />
        <ModuleProgressBarChart data={dashboardData.moduleProgress} />
      </ChartSection>
      <RecentActivitiesList activities={dashboardData.recentActivities} />
      <QuickActions classroomId={classroomId} />
    </div>
  );
};

Estado (Zustand):

// teacherAnalyticsStore.ts
interface TeacherAnalyticsStore {
  dashboardData: DashboardData | null;
  isLoading: boolean;
  error: string | null;
  fetchDashboard: (classroomId: string) => Promise<void>;
  refreshDashboard: () => void;
}

Librería de Gráficas:

• Recharts para visualizaciones básicas (barras, pie chart)
• Colores consistentes con el tema de gamificación

---

Diseño UI/UX

Layout Desktop

+-----------------------------------------------------------+
|  Matemáticas 6A                    [Cambiar Clase ▼]     |
+-----------------------------------------------------------+
|  [Card]         [Card]         [Card]         [Card]     |
|  25 Estudiantes | 65% Progreso | Nivel 3 Prom | 12,500 XP|
+-----------------------------------------------------------+
|  [Gráfica Barras]          |  [Pie Chart]                |
|  Distribución por Nivel    |  Módulos Completados        |
+----------------------------+------------------------------+
|  [Gráfica Barras Horizontal]                             |
|  Progreso por Módulo                                      |
+-----------------------------------------------------------+
|  Actividad Reciente                    [Ver Todas →]     |
|  • Juan Pérez completó "Suma de fracciones" hace 5 min   |
|  • María López inició "Geometría básica" hace 10 min     |
|  ...                                                       |
+-----------------------------------------------------------+
|  [Ver Todos los Estudiantes]  [Ver Reportes Completos]  |
+-----------------------------------------------------------+

Consideraciones Mobile

• Cards de métricas en grid 2x2
• Gráficas apiladas verticalmente
• Actividades recientes colapsables

---

Alcance Básico vs Extensiones

EAI-004 (Este alcance - Analytics Básico):

• ✅ Métricas básicas hardcodeadas (# estudiantes, progreso %, nivel, XP)
• ✅ Gráficas simples estáticas (barras, pie chart)
• ✅ Últimas 10 actividades (lista simple)
• ✅ Vista única, sin personalización
• ✅ Actualización automática cada 5 minutos

EXT-005 (Extensión futura - Reportes Avanzados):

• ⏳ Dashboard configurable (elegir métricas a mostrar)
• ⏳ Gráficas interactivas con drill-down
• ⏳ Filtros avanzados (rango de fechas, comparativas)
• ⏳ Métricas de engagement (tiempo promedio, tasa de retención)
• ⏳ Exportación de dashboard a PDF/imagen
• ⏳ Comparativa entre clases
• ⏳ Tendencias y análisis predictivo con ML
• ⏳ Alertas configurables
• ⏳ Actualización en tiempo real (WebSockets)

---

Dependencias

Dependencias Técnicas:

• Backend: Sistema de autenticación de profesores (EAI-005)
• Backend: Modelo de datos de Classroom, Student, Module
• Backend: Sistema de tracking de actividades (EAI-002)
• Backend: Sistema de gamificación para XP y niveles (EAI-003)
• Frontend: Librería Recharts
• Frontend: teacherStore con autenticación

Dependencias de User Stories:

• Ninguna crítica (puede desarrollarse en paralelo con otras US de analytics)

---

Pruebas

Pruebas Unitarias:

• calculateClassMetrics retorna métricas correctas
• getLevelDistribution agrupa estudiantes correctamente
• getModuleCompletion calcula porcentajes correctos
• getRecentActivities retorna solo las últimas 10 actividades

Pruebas de Integración:

• Endpoint retorna 200 para profesor con acceso
• Endpoint retorna 403 para profesor sin acceso
• Endpoint retorna 404 para clase inexistente
• Dashboard se actualiza al cambiar de clase

Pruebas E2E:

• Profesor ve dashboard con datos correctos
• Gráficas se renderizan correctamente
• Navegación a otras vistas funciona
• Selector de clase cambia el dashboard

---

Notas de Implementación

1. Performance:

   • Cachear métricas por 5 minutos (Redis)
   • Query optimizado con joins limitados
   • Paginación en actividades recientes

2. Escalabilidad:

   • Cálculo de métricas puede moverse a background job si la clase es muy grande (>100 estudiantes)
   • Considerar pre-cálculo nocturno para clases grandes

3. UX:

   • Skeleton loaders para mejor percepción de velocidad
   • Error boundaries para manejar fallos de gráficas
   • Mensajes amigables para clases sin datos

4. Accesibilidad:

   • Gráficas con texto alternativo
   • Tablas de datos alternativas para lectores de pantalla
   • Contraste adecuado en colores de gráficas

---

Estimación de Esfuerzo

Backend: 3 SP

• Endpoints y lógica de cálculo de métricas
• Queries optimizados

Frontend: 4 SP

• Componentes de dashboard
• Integración de Recharts
• Layout responsive

Testing: 1 SP

• Pruebas unitarias, integración, E2E

Total: 8 SP = $4,000 MXN

---

Tareas de Implementación

Backend (14.4h - 45%)

1. Configuración de Módulo y Endpoints Base (2h)

• Crear módulo TeacherAnalyticsModule en NestJS
• Configurar guard TeacherGuard para validación de rol profesor
• Definir estructura de DTOs base para analytics
• Configurar importaciones de dependencias (TypeORM, JWT)

2. Modelo de Datos y Repositorios (3h)

• Validar entidad Classroom con relaciones (students, modules)
• Validar entidad Student con campos de gamificación (level, xp)
• Validar entidad Activity y Module para tracking
• Crear repositorio custom si es necesario para agregaciones
• Configurar índices en base de datos para queries frecuentes

3. Service de Cálculo de Métricas (4.5h)

• Implementar calculateClassMetrics(): totalStudents, averageProgress, averageLevel, totalXP
• Implementar getLevelDistribution(): contar estudiantes por nivel
• Implementar getModuleCompletion(): % de módulos completados/en progreso/no iniciados
• Implementar getModuleProgress(): progreso promedio por módulo
• Implementar getRecentActivities(): últimas 10 actividades ordenadas
• Optimizar queries con joins y agregaciones SQL

4. Controller y Endpoint Principal (2.4h)

• Implementar GET /api/teacher/classroom/{classroomId}/dashboard
• Implementar validación de parámetros (classroomId UUID)
• Implementar validateTeacherAccess(): verificar que profesor tiene acceso al aula
• Manejar errores 403 (sin acceso), 404 (aula no existe)
• Documentar endpoint con Swagger/OpenAPI

5. Caché y Optimización (1.6h)

• Implementar caché Redis con TTL de 5 minutos para métricas
• Configurar invalidación de caché al actualizar datos
• Implementar query pagination para actividades recientes
• Optimizar consultas con select específicos (evitar over-fetching)

6. Testing Backend (0.9h)

• Unit tests para calculateClassMetrics()
• Unit tests para getLevelDistribution()
• Integration tests para endpoint 200, 403, 404
• Test de performance para clases con >50 estudiantes

Frontend (11.2h - 35%)

1. Setup de Estado y API Client (2h)

• Crear teacherAnalyticsStore con Zustand (dashboardData, isLoading, error)
• Implementar teacherAnalyticsApi.getDashboard() con axios
• Configurar interceptores para autenticación (Bearer token)
• Implementar manejo de errores global

2. Componente Principal Dashboard (2.5h)

• Crear componente ClassroomDashboard.tsx
• Implementar hook useClassroomDashboard() con auto-fetch
• Implementar skeleton loader DashboardSkeleton
• Configurar layout responsive (desktop/mobile)
• Implementar breadcrumb y navegación

3. Componentes de Métricas (2h)

• Crear componente MetricsCards con 4 cards (estudiantes, progreso, nivel, XP)
• Implementar StatCard reutilizable con icono y valor
• Aplicar estilos Tailwind para grid responsive
• Implementar iconos (UsersIcon, ProgressIcon, LevelIcon, XPIcon)

4. Componentes de Gráficas (3h)

• Instalar y configurar librería Recharts
• Crear LevelDistributionChart (BarChart) con datos de niveles
• Crear ModuleCompletionPieChart con 3 segmentos (completado/progreso/no iniciado)
• Crear ModuleProgressBarChart (BarChart horizontal) con progreso por módulo
• Aplicar tema de colores consistente (verde/amarillo/rojo)
• Hacer gráficas responsive (ajuste de tamaño)

5. Componente de Actividades Recientes (1h)

• Crear RecentActivitiesList con scroll vertical
• Implementar ActivityItem con avatar, nombre, módulo, timestamp
• Formatear timestamp a relativo ("hace 5 min")
• Implementar empty state si no hay actividades

6. Auto-refresh y UX (0.7h)

• Implementar auto-refresh cada 5 minutos con setInterval
• Agregar indicador de última actualización
• Implementar botón manual de refresh
• Agregar transiciones suaves con Tailwind

Testing (4.8h - 15%)

1. Testing Unitario (2h)

• Tests de componentes aislados con React Testing Library
• Tests de custom hooks (useClassroomDashboard)
• Tests de formateo de datos (formatRelativeTime, etc.)
• Tests de edge cases (clase sin estudiantes, sin datos)

2. Testing de Integración (1.5h)

• Test E2E: Profesor ve dashboard con datos correctos
• Test E2E: Gráficas se renderizan correctamente
• Test E2E: Navegación a otras vistas funciona
• Test E2E: Auto-refresh actualiza datos

3. Testing de Performance (0.8h)

• Test de carga de dashboard <2s
• Test de renderizado de gráficas con datasets grandes
• Test de memory leaks en auto-refresh

4. Testing de Accesibilidad (0.5h)

• Tests de contraste de colores
• Tests de navegación por teclado
• Tests de screen reader (aria-labels)

Deployment (1.6h - 5%)

1. Preparación de Build (0.8h)

• Configurar variables de entorno (API_URL, CACHE_TTL)
• Build de producción (npm run build)
• Verificar bundle size (<500KB para dashboard)
• Configurar lazy loading de Recharts

2. Deploy y Smoke Tests (0.8h)

• Deploy a ambiente de staging
• Smoke test: dashboard carga correctamente
• Smoke test: métricas son correctas
• Verificar logs y errores
• Tag de versión en Git

---

Total Horas: 32h Distribución Real: Backend 45% | Frontend 35% | Testing 15% | Deploy 5%