# AdminReportsPage - UI Specification

**Componente**: AdminReportsPage
**Ruta**: `/admin/reports`
**Fecha**: 2025-11-24
**Estado**: Implementado

---

## Layout General

```
┌─────────────────────────────────────────────────────────────────────────┐
│ AdminLayout (Header + Sidebar)                                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Generación de Reportes                                            │  │
│  │ Genera y gestiona reportes del sistema en diferentes formatos    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ ⚠️  BETA: Almacenamiento en Memoria                              │  │
│  │                                                                   │  │
│  │ IMPORTANTE: Los reportes se generan en memoria temporal y        │  │
│  │ no persisten al reiniciar el servidor backend.                   │  │
│  │                                                                   │  │
│  │ • Los reportes se perderán cuando el servidor se reinicie        │  │
│  │ • Esta es una implementación MVP para demostración               │  │
│  │ • Persistencia en BD será implementada en fase posterior    [X] │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌─────────────────────────┬────────────────────────────────────────┐  │
│  │ Generar Nuevo Reporte   │ Reportes Generados (5)     [Actualizar]│  │
│  │                         │                                         │  │
│  │ Tipo de Reporte *       │ ┌──────────────────────────────────────┐│  │
│  │ [Reporte de Usuarios▼]  │ │Tipo│Formato│Estado│Fecha │Acciones  ││  │
│  │ Información de usuarios │ ├────┼───────┼──────┼──────┼──────────┤│  │
│  │                         │ │Usr │[CSV]  │[COM] │Nov24 │[↓] [🗑️] ││  │
│  │ Formato *               │ │Prg │[XLSX] │[GEN] │Nov24 │[⏳] [🗑️]││  │
│  │ [Excel (XLSX)       ▼]  │ │Gam │[PDF]  │[PEN] │Nov24 │[⏳] [🗑️]││  │
│  │                         │ │Sys │[CSV]  │[COM] │Nov23 │[↓] [🗑️] ││  │
│  │ Fecha Inicio (Opcional) │ │Ins │[XLSX] │[FAI] │Nov23 │[❌] [🗑️]││  │
│  │ [2025-01-01        ]    │ └──────────────────────────────────────┘│  │
│  │                         │                                         │  │
│  │ Fecha Fin (Opcional)    │ COM = Completado (verde)                │  │
│  │ [2025-12-31        ]    │ GEN = Generando (azul)                  │  │
│  │                         │ PEN = Pendiente (amarillo)              │  │
│  │ ID de Aula (Opcional)   │ FAI = Fallido (rojo)                    │  │
│  │ [UUID del aula...  ]    │                                         │  │
│  │                         │ Mostrando 5 de 5 reportes               │  │
│  │ [Generar Reporte]       │                                         │  │
│  └─────────────────────────┴────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Legend:
[▼]    = Dropdown
[COM]  = Badge (colored)
[↓]    = Download button
[🗑️]   = Delete button
[⏳]   = Loading spinner
[❌]   = Disabled button
[X]    = Dismiss button
```

---

## Componentes Individuales

### 1. BetaBanner

```
┌──────────────────────────────────────────────────────────────────┐
│ ⚠️  BETA: Almacenamiento en Memoria                         [X] │
│                                                                  │
│ IMPORTANTE: Los reportes se generan en memoria temporal y       │
│ no persisten al reiniciar el servidor backend.                  │
│                                                                  │
│ • Los reportes generados se perderán cuando el servidor se      │
│   reinicie                                                       │
│ • Esta es una implementación MVP para demostración              │
│ • La persistencia en base de datos será implementada en una     │
│   fase posterior                                                │
└──────────────────────────────────────────────────────────────────┘

Color Scheme:
- Background: Amber-50 (light) / Amber-900/20 (dark)
- Border: Amber-400 (left border 4px)
- Icon: Amber-400
- Text: Amber-800 (light) / Amber-300 (dark)
```

### 2. ReportGenerationForm

```
┌─────────────────────────────────────┐
│ Generar Nuevo Reporte               │
│                                     │
│ Tipo de Reporte *                   │
│ ┌─────────────────────────────────┐ │
│ │ Reporte de Usuarios          ▼ │ │
│ └─────────────────────────────────┘ │
│ Información de usuarios registrados │
│ y actividad                         │
│                                     │
│ Formato *                           │
│ ┌─────────────────────────────────┐ │
│ │ Excel (XLSX)                 ▼ │ │
│ └─────────────────────────────────┘ │
│                                     │
│ Fecha Inicio (Opcional)             │
│ ┌─────────────────────────────────┐ │
│ │ 2025-01-01                     │ │
│ └─────────────────────────────────┘ │
│                                     │
│ Fecha Fin (Opcional)                │
│ ┌─────────────────────────────────┐ │
│ │ 2025-12-31                     │ │
│ └─────────────────────────────────┘ │
│                                     │
│ ID de Aula (Opcional)               │
│ ┌─────────────────────────────────┐ │
│ │ UUID del aula                  │ │
│ └─────────────────────────────────┘ │
│                                     │
│ ┌─────────────────────────────────┐ │
│ │     Generar Reporte             │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘

States:
- Normal: Teal button, all fields enabled
- Generating:
  Button: [⏳ Generando...]
  All fields: disabled
```

### 3. ReportsList

```
┌────────────────────────────────────────────────────────────────┐
│ Reportes Generados (5)      ⟳ Auto-refresh activo [Actualizar]│
│                                                                │
│ ┌────┬───────┬──────┬──────────────────────┬──────────────┐  │
│ │Tipo│Formato│Estado│Fecha                 │Acciones      │  │
│ ├────┼───────┼──────┼──────────────────────┼──────────────┤  │
│ │Usr │ CSV   │ COM  │Nov 24, 2025, 10:30 AM│ [↓]  [🗑️]   │  │
│ │Prg │ Excel │ GEN  │Nov 24, 2025, 10:25 AM│ [⏳] [🗑️]   │  │
│ │Gam │ PDF   │ PEN  │Nov 24, 2025, 10:20 AM│ [⏳] [🗑️]   │  │
│ │Sys │ CSV   │ COM  │Nov 23, 2025, 03:15 PM│ [↓]  [🗑️]   │  │
│ │Ins │ Excel │ FAI  │Nov 23, 2025, 02:00 PM│ [❌] [🗑️]   │  │
│ └────┴───────┴──────┴──────────────────────┴──────────────┘  │
│                                                                │
│ Mostrando 5 de 5 reportes                                     │
└────────────────────────────────────────────────────────────────┘

Empty State:
┌────────────────────────────────────────────────────────────────┐
│ Reportes Generados (0)                          [Actualizar]  │
│                                                                │
│                        📄                                      │
│                                                                │
│              No hay reportes generados                        │
│     Genera tu primer reporte usando el formulario de arriba   │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Loading State:
┌────────────────────────────────────────────────────────────────┐
│ Reportes Generados (-)                          [⏳]          │
│                                                                │
│                        ⏳                                      │
│                                                                │
│                   Cargando reportes...                        │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

### 4. Toast Notifications

```
Success:
┌────────────────────────────────────────────────────────┐
│ ✓ Reporte generado exitosamente. Se está procesando...│ [X]
└────────────────────────────────────────────────────────┘
Color: Green-50 / Green-900/20

Error:
┌────────────────────────────────────────────────────────┐
│ ✗ Error al generar reporte                            │ [X]
└────────────────────────────────────────────────────────┘
Color: Red-50 / Red-900/20

Position: Top of content area, below banner
Duration: 5 seconds (auto-dismiss)
Dismissible: Yes
```

---

## Estados y Transiciones

### Generación de Reporte

```
Estado Inicial
    │
    │ [User clicks "Generar Reporte"]
    ▼
Generando (Loading)
    │
    │ [Backend responds]
    ▼
┌─────────┴─────────┐
│                   │
▼                   ▼
Éxito             Error
│                   │
│                   │
▼                   ▼
Toast Verde      Toast Rojo
│
│ [5 segundos]
▼
Toast desaparece
```

### Auto-refresh de Reportes

```
Lista Inicial
    │
    │ [hasPendingReports = true]
    ▼
Inicia Timer (5s)
    │
    │ [Timer tick]
    ▼
Fetch Reports
    │
    │ [Backend responds]
    ▼
Actualiza Lista
    │
    │ [hasPendingReports?]
    ▼
┌─────────┴─────────┐
│                   │
▼                   ▼
Sí              No
│                   │
Continuar         Detener
Timer             Timer
```

### Descarga de Reporte

```
Estado Inicial
    │
    │ [User clicks Download]
    ▼
Verificar Status
    │
    │ [status === 'completed'?]
    ▼
┌─────────┴─────────┐
│                   │
▼                   ▼
Sí              No
│                   │
│                   └─> Error: "Reporte no disponible"
│
│ [Fetch Blob]
▼
Descargando
    │
    │ [Blob received]
    ▼
Browser Download
    │
    │ [File saved]
    ▼
Toast Verde
```

### Eliminación de Reporte

```
Estado Inicial
    │
    │ [User clicks Delete]
    ▼
Confirmación
    │
    │ [User confirms?]
    ▼
┌─────────┴─────────┐
│                   │
▼                   ▼
Sí              No
│                   │
│                   └─> Cancelar
│
│ [DELETE request]
▼
Eliminando
    │
    │ [Backend responds]
    ▼
┌─────────┴─────────┐
│                   │
▼                   ▼
Éxito             Error
│                   │
│                   │
▼                   ▼
Actualiza Lista  Toast Rojo
+
Toast Verde
```

---

## Responsive Design

### Desktop (≥ 1024px)
- Layout: 3 columnas (1 formulario + 2 lista)
- Tabla: Todas las columnas visibles
- Banner: Full width

### Tablet (768px - 1023px)
- Layout: Stacked (formulario arriba, lista abajo)
- Tabla: Scroll horizontal si necesario
- Banner: Full width

### Mobile (< 768px)
- Layout: Stacked (formulario arriba, lista abajo)
- Tabla: Cards en lugar de tabla
- Banner: Full width, texto condensado

---

## Color Palette

### Status Badges

| Status      | Background               | Text                   | Border   |
|-------------|--------------------------|------------------------|----------|
| PENDING     | yellow-100 / yellow-900  | yellow-800 / yellow-300| -        |
| GENERATING  | blue-100 / blue-900      | blue-800 / blue-300    | -        |
| COMPLETED   | green-100 / green-900    | green-800 / green-300  | -        |
| FAILED      | red-100 / red-900        | red-800 / red-300      | -        |

### Format Badges

| Format  | Background               | Text                   |
|---------|--------------------------|------------------------|
| PDF     | gray-100 / gray-700      | gray-800 / gray-300    |
| CSV     | gray-100 / gray-700      | gray-800 / gray-300    |
| Excel   | gray-100 / gray-700      | gray-800 / gray-300    |

### Type Badges

| Type      | Display Text              | Color               |
|-----------|---------------------------|---------------------|
| users     | Usuarios                  | -                   |
| progress  | Progreso                  | -                   |
| gamification| Gamificación            | -                   |
| system    | Sistema                   | -                   |
| student_insights| Insights Estudiantes | -                   |
| classroom_summary| Resumen Aulas        | -                   |
| risk_analysis| Análisis Riesgo         | -                   |

---

## Accessibility (A11y)

### Keyboard Navigation
- Tab order: Formulario → Lista → Acciones
- Enter: Activar botones
- Esc: Cerrar toasts, cancelar confirmaciones

### Screen Reader Support
- ARIA labels en botones de iconos
- ARIA live regions para toasts
- ARIA describedby para estados de loading
- Alt text en iconos

### Focus Management
- Visible focus indicators (ring-2)
- Focus trap en modales de confirmación
- Auto-focus en campos importantes

---

## Performance

### Optimizations
- Memo de componentes estáticos
- useCallback para handlers
- Cleanup de timers y listeners
- Lazy loading de lista (future)

### Loading States
- Skeleton loaders (future)
- Shimmer effects (future)
- Progressive loading (future)

---

## Testing Checklist

### Functional Tests
- [ ] Generar reporte (cada tipo)
- [ ] Generar reporte (cada formato)
- [ ] Generar con filtros opcionales
- [ ] Generar sin filtros opcionales
- [ ] Lista muestra reportes correctamente
- [ ] Auto-refresh funciona
- [ ] Descargar reporte COMPLETED
- [ ] Botón download deshabilitado para no-COMPLETED
- [ ] Eliminar reporte con confirmación
- [ ] Cancelar eliminación
- [ ] Banner dismissible
- [ ] Banner re-aparece después de limpiar localStorage
- [ ] Toast auto-dismiss
- [ ] Toast manual dismiss

### UI/UX Tests
- [ ] Responsive en mobile
- [ ] Responsive en tablet
- [ ] Dark mode
- [ ] Loading states visibles
- [ ] Error states informativos
- [ ] Empty state amigable
- [ ] Badges coloreados correctamente
- [ ] Fechas formateadas correctamente

### Edge Cases
- [ ] Error de red
- [ ] Error 401 (unauthorized)
- [ ] Error 500 (server error)
- [ ] Lista vacía
- [ ] > 20 reportes (paginación)
- [ ] Múltiples reportes PENDING
- [ ] Reporte FAILED
- [ ] Download mientras está GENERATING

---

## Future Enhancements

### Phase 2
- [ ] Filtros avanzados (dropdown de tipos, status)
- [ ] Búsqueda por nombre/ID
- [ ] Ordenamiento de columnas
- [ ] Paginación completa con controles
- [ ] Vista previa de reporte

### Phase 3
- [ ] Programación de reportes (schedule)
- [ ] Reportes recurrentes
- [ ] Notificaciones push cuando listo
- [ ] Compartir reporte por email
- [ ] Export múltiple (ZIP)

### Phase 4
- [ ] Dashboard de reportes
- [ ] Gráficos de uso
- [ ] Historial de descargas
- [ ] Favoritos
- [ ] Templates de reportes

---

**Document Version**: 1.0
**Last Updated**: 2025-11-24
**Status**: Implemented & Documented
