Initial

2026-07-21 16:53:38 -05:00
commit 69cc215954
12 changed files with 3478 additions and 0 deletions
@@ -0,0 +1,122 @@
+# 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.