# 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:

```mermaid
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](file:///c:/Users/pepit/Desktop/doc/NODE/autonomus/Claro%20Cases/db.js).

```sql
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**:
  ```json
  {
    "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**:
  ```json
  {
    "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](file:///c:/Users/pepit/Desktop/doc/NODE/autonomus/Claro%20Cases/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:
   ```cmd
   npm install
   ```
2. Ejecutar servidor en modo desarrollo (con recarga automática vía nodemon):
   ```cmd
   npm run dev
   ```
   El servidor levantará en http://localhost:3000.