Claro Cases Tracking System - Manual Técnico

Este documento detalla el funcionamiento técnico, arquitectura y endpoints de la aplicación Claro Cases, un sistema en tiempo real para rastrear solicitudes de clientes, gestionar casos y registrar métricas de tiempo de atención.

---

🏗️ Arquitectura del Sistema

La aplicación sigue una arquitectura desacoplada monolítica simple basada en Node.js, Express y SQLite:

graph TD
    Client[Cliente Externo / API Client] -->|POST /api/requests| ExpressServer[Express Server Node.js]
    ExpressServer -->|Guarda Datos| SQLite[SQLite database.sqlite]
    ExpressServer -->|SSE Broadcast| Frontend[Frontend SPA HTML/JS]
    Frontend -->|Interacción de Operador| ExpressServer

1. Frontend (SPA - Single Page Application): Desarrollado con Vanilla HTML5, Javascript (ES6) y CSS3 adaptativo con soporte para temas Claro/Oscuro.
2. Backend: Servidor REST Express que provee persistencia y notificaciones en tiempo real a través de Server-Sent Events (SSE).
3. Persistencia: Base de datos ligera embebida SQLite gestionada eficientemente de manera síncrona por medio del driver better-sqlite3.

---

🗄️ Esquema de la Base de Datos

La tabla principal es requests. La inicialización del esquema y las migraciones automáticas de columnas se gestionan dinámicamente en el módulo db.js.

CREATE TABLE IF NOT EXISTS requests (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  description TEXT,
  status TEXT DEFAULT 'Pending',
  external_id TEXT,
  cedula TEXT,
  tipo_solicitud TEXT,
  payload TEXT,                           -- Objeto JSON guardado como String
  handling_time INTEGER DEFAULT 0,         -- Tiempo de gestión en segundos
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

---

🔌 API Endpoints (Backend)

1. Registrar Nuevo Caso

• Endpoint: POST /api/requests
• Content-Type: application/json
• Payload:

  {
    "title": "Título del Caso",
    "description": "Detalle descriptivo",
    "external_id": "EXT-12345",
    "cedula": "10203040",
    "tipo_solicitud": "validacion_usuario",
    "payload": {
      "nombre": "Juan Pérez",
      "telefono": "31000000"
    }
  }
  

• Comportamiento: Guarda la solicitud y transmite en tiempo real la información a todos los operadores conectados usando SSE.

2. Stream de Actualizaciones en Tiempo Real

• Endpoint: GET /api/sse
• Content-Type: text/event-stream
• Comportamiento: Registra el cliente para recibir eventos unidireccionales desde el servidor en tiempo real.

3. Obtener Solicitudes

• Endpoint: GET /api/requests
• Comportamiento: Devuelve todos los casos de la base de datos en orden descendente por fecha de creación.

4. Actualizar Estado / Finalizar Caso

• Endpoint: PUT /api/requests/:id
• Payload:

  {
    "status": "Finalizado",
    "handling_time": 125,
    "payload": {
      "valor_cierre": "Comentario de finalización"
    }
  }
  

5. Eliminar Solicitud

• Endpoint: DELETE /api/requests/:id

---

⚡ Lógica del Operador (Frontend)

El flujo interactivo se gestiona en public/app.js y se compone de:

• Sincronización en Tiempo Real (SSE): Permite la llegada instantánea de nuevos casos al panel de control del operador sin recargar la página. Al ingresar un caso nuevo:
  • Se reproduce una alerta de sonido usando la API nativa de Web Audio.
  • Se genera una Notificación de Escritorio HTML5 en el sistema operativo.
  • El título de la pestaña del navegador destella con la cantidad de casos pendientes.
• Filtros e Historial:
  • Buscador integrado que busca en tiempo real por título, ID de referencia, descripción, cédula y tipo de solicitud.
  • Pestañas rápidas para clasificar casos entre Todos, Pendientes y Finalizados.
• Flujos Especiales al Gestionar Casos:
  • Al dar clic en Gestionar Caso, se inicia un cronómetro individual para medir el tiempo que el operador tarda en resolver la solicitud.
  • Solicitud de Validación: Si el caso contiene la palabra "validacion" en su campo tipo_solicitud, la UI cambia dinámicamente y despliega los botones Sí y No integrados bajo la pregunta "¿El usuario es válido?". Al hacer clic en cualquiera de ellos, el caso se cierra.
  • Otras Solicitudes: Si es de cualquier otro tipo, la interfaz le exige al operador ingresar un valor de resolución en una entrada de texto antes de dar clic en Finalizar Caso. Este valor se inyecta en el objeto JSON de payload del caso.

---

🛠️ Ejecución Local

1. Instalar dependencias:

   npm install
   

2. Ejecutar servidor en modo desarrollo (con recarga automática vía nodemon):

   npm run dev
   

   El servidor levantará en http://localhost:3000.