Stack Tecnológico

🛠 Stack Tecnológico

Frontend

Backend

Herramientas

---

📊 Informe de Carga Docente - Documentación Técnica

Índice

• Descripción General
• Arquitectura del Sistema
• Flujo de Generación del Informe
• Formato de Datos
• API Endpoints
• Implementación Frontend
• Configuración del Mock Server
• Manejo de Errores
• Ejemplos de Uso
• Troubleshooting

---

📋 Descripción General

El Informe de Carga Docente es una funcionalidad que permite visualizar información detallada sobre la distribución de materias y estudiantes asignados a cada docente del sistema ProfeSort.

Características principales:

• Visualización de estadísticas generales (totales y promedios)
• Tabla detallada por docente con información de carga
• Datos en tiempo real mediante API REST
• Manejo robusto de errores y estados de carga
• Interfaz responsive con Bootstrap

---

🏗️ Arquitectura del Sistema

graph TD
  A[Componente AdminDocente] --> B[AdminDocenteService]
  B --> C[HttpClient]
  C --> D[Mock API Server]
  D --> E[JSON Database]

  F[Usuario] --> G[Click 'Ver Informe']
  G --> H[toggleInformeCarga()]
  H --> I[cargarInformeCarga()]
  I --> J[getDocentesCarga()]
  J --> K[HTTP GET /carga]
  K --> L[Procesar Respuesta]
  L --> M[Actualizar UI]

Componentes involucrados:

• Frontend: Angular 17 con Reactive Forms
• Servicio: AdminDocenteService para comunicación HTTP
• Mock API: JSON Server para simular backend
• Base de datos: Archivo JSON con datos mock

---

🔄 Flujo de Generación del Informe

1. Activación del Informe

// Usuario hace clic en "Ver Informe de Carga"

toggleInformeCarga(): void {
  this.mostrarInformeCarga = !this.mostrarInformeCarga;
  if (this.mostrarInformeCarga && this.docentesCarga.length === 0) {
    this.cargarInformeCarga(); // Cargar datos si no existen
  }
}

2. Solicitud de Datos

// Llamada al servicio para obtener datos

cargarInformeCarga(): void {
  this.cargandoDatos = true;
  this.errorCarga = '';

  this.adminDocenteService.getDocentesCarga().subscribe({
    next: (data: DocenteCarga[]) => {
      this.docentesCarga = data;
      this.cargandoDatos = false;
    },
    error: (error) => {
      this.errorCarga = error.message;
      this.cargandoDatos = false;
    }
  });
}

3. Procesamiento de Datos

// Cálculo de estadísticas en tiempo real

obtenerEstadisticas() {
  const totalDocentes = this.docentesCarga.length;
  const docentesActivos = this.docentesCarga.filter(d => d.estado === 'Activo').length;
  const totalMaterias = this.docentesCarga.reduce((sum, d) => sum + d.cantidadMaterias, 0);
  const totalEstudiantes = this.docentesCarga.reduce((sum, d) => sum + d.cantidadEstudiantes, 0);
  return { totalDocentes, docentesActivos, totalMaterias, totalEstudiantes };
}

4. Renderización de la UI

• Estadísticas generales: Cards con totales
• Tabla detallada: Información por docente
• Estados visuales: Loading, error, datos vacíos

---

📄 Formato de Datos

Estructura de datos esperada (DocenteCarga):

interface DocenteCarga {
  id: number;                    // Identificador único del docente
  nombre: string;                // Nombre completo del docente
  email: string;                 // Correo electrónico
  legajo: string;                // Número de legajo institucional
  estado: 'Activo' | 'Inactivo'; // Estado del docente
  cantidadMaterias: number;      // Número de materias asignadas
  cantidadEstudiantes: number;   // Total de estudiantes a cargo
  materias: string[];            // Array con nombres de materias
  fechaIngreso?: string;         // Fecha de ingreso (opcional)
  departamento?: string;         // Departamento (opcional)
}

Ejemplo de datos JSON:

{
  "carga": [
    {
      "id": 1,
      "nombre": "Karina del Valle Quinteros",
      "email": "karinaq38@gmail.com",
      "legajo": "DOC001",
      "estado": "Activo",
      "cantidadMaterias": 3,
      "cantidadEstudiantes": 45,
      "materias": ["Matemática", "Física", "Química"],
      "fechaIngreso": "2020-03-15",
      "departamento": "Ciencias Exactas"
    },
    {
      "id": 2,
      "nombre": "Juan Pablo Sanchez Brandán",
      "email": "sanchezbrandan@gmail.com",
      "legajo": "DOC002",
      "estado": "Activo",
      "cantidadMaterias": 2,
      "cantidadEstudiantes": 38,
      "materias": ["Historia", "Geografía"],
      "fechaIngreso": "2019-08-10",
      "departamento": "Ciencias Sociales"
    }
  ]
}

---

🌐 API Endpoints

GET /carga
Descripción: Obtiene la lista completa de docentes con información de carga
URL: http://localhost:3001/carga
Método: GET
Headers: Content-Type: application/json

Respuesta exitosa (200):

[
  {
    "id": 1,
    "nombre": "Karina del Valle Quinteros",
    "email": "karinaq38@gmail.com",
    "legajo": "DOC001",
    "estado": "Activo",
    "cantidadMaterias": 3,
    "cantidadEstudiantes": 45,
    "materias": ["Matemática", "Física", "Química"],
    "fechaIngreso": "2020-03-15",
    "departamento": "Ciencias Exactas"
  }
]

Códigos de error:

• 404: Recurso no encontrado
• 500: Error interno del servidor
• 0: Error de conexión

---

💻 Implementación Frontend

Servicio AdminDocenteService:

@Injectable({ providedIn: 'root' })
export class AdminDocenteService {
  private apiUrl = 'http://localhost:3001/carga';
  constructor(private http: HttpClient) {}

  getDocentesCarga(): Observable<DocenteCarga[]> {
    return this.http.get<DocenteCarga[]>(this.apiUrl)
      .pipe(
        retry(1),                  // Reintentar una vez
        catchError(this.handleError) // Manejo de errores
      );
  }

  private handleError(error: HttpErrorResponse) {
    // Lógica de manejo de errores...
  }
}

Componente AdminDocente

Propiedades principales:

• docentesCarga: DocenteCarga[] = [] // Array de datos de carga
• cargandoDatos = false // Estado de carga
• errorCarga = '' // Mensaje de error
• mostrarInformeCarga = false // Visibilidad del informe

Métodos principales:

• toggleInformeCarga(): Alternar visibilidad
• cargarInformeCarga(): Obtener datos del API
• obtenerEstadisticas(): Calcular estadísticas

---

🔧 Configuración del Mock Server

Instalación: npm install -g json-server

Estructura de archivos: ProfeSort/ ├── mock-api/ │ ├── db.json # Base de datos JSON │ ├── routes.json # Configuración de rutas (opcional) │ └── middleware.js # Middleware personalizado (opcional)

Ejecución:

Servidor básico

json-server --watch mock-api/db.json --port 3001
# Con configuración avanzada
json-server --watch mock-api/db.json --routes mock-api/routes.json --port 3001

Script en package.json:
{
  "scripts": {
    "mock-api": "json-server --watch mock-api/db.json --port 3001",
    "dev:with-mock": "concurrently \"npm run mock-api\" \"ng serve\""
  }
}

---

⚠️ Manejo de Errores

Tipos de errores manejados:

• Error de conexión (Status 0): "No se puede conectar al servidor. Verifique que el mock API esté ejecutándose en el puerto 3001."
• Recurso no encontrado (Status 404): "Recurso no encontrado."
• Error del servidor (Status 500): "Error interno del servidor."

Estrategia:

• Retry automático (1 reintento)
• Mensajes descriptivos
• Logging (console.error)
• Botón de reintento en UI

---

📖 Ejemplos de Uso

Ejemplo 1: Carga exitosa

1. Usuario hace clic en "Ver Informe de Carga"
2. toggleInformeCarga()
3. cargarInformeCarga()
4. GET http://localhost:3001/carga
5. Respuesta procesada → tabla + estadísticas

Ejemplo 2: Manejo de error

1. Mock server apagado
2. HTTP request falla con status 0
3. Mensaje: "No se puede conectar al servidor..."
4. Botón "Reintentar"
5. Nuevo intento con cargarInformeCarga()

Ejemplo 3: Datos vacíos

1. Mock responde []
2. Se ocultan estadísticas
3. Mensaje: "No hay datos disponibles"

---

🔍 Troubleshooting

Problema: "Error de conexión"
Solución:

• Verificar server en puerto 3001
• Comprobar db.json válido
• Revisar CORS
  curl http://localhost:3001/carga

Problema: "Property does not exist"
Solución:

• Revisar métodos implementados
• Comprobar imports
• Revisar interfaces

Problema: "JSON Server options not supported"
Solución:

• Instalar versión: npm install -g json-server@0.17.4
• Usar JSON simplificado

Problema: "Datos no se muestran"
Solución:

• Revisar estructura de db.json
• Comprobar URL del servicio
• Confirmar HttpClient en app.config.ts

---

📝 Notas Adicionales

Rendimiento

• Carga inicial solo al abrir el informe
• Estadísticas en tiempo real (cliente)
• Considerar caché para datasets grandes

Futuras mejoras

• Filtros: depto, estado, fechas
• Exportación: PDF, Excel, CSV
• Paginación
• Gráficos: Chart.js / D3
• Tiempo real: WebSockets

Seguridad

• En producción usar JWT
• Validar datos en backend
• Sanitización de inputs
• Rate limiting en API

---

📚 Referencias

• Angular HttpClient Documentation
• JSON Server Documentation
• RxJS Operators
• Bootstrap Documentation

---

Última actualización: Septiembre 2025
Versión: 1.0
Autor: Equipo de Desarrollo ProfeSort