bryan_garcia
8f044567c0
- Módulo HITL (/cases): 6 patrones de formularios dinámicos para 53 tipos de caso con validación Zod - Módulo Monitor (/monitor): streaming token-a-token en tiempo real, auto-scroll y notas internas vía WebSocket - Arquitectura híbrida: REST (canal autoritativo) + WebSocket (difusión/streaming) - MSW para desarrollo sin backend, hooks de notificaciones/sonido/título preservados - Backend legacy movido a legacy/, archivos residuales eliminados de raíz
123 lines
4.9 KiB
Markdown
123 lines
4.9 KiB
Markdown
# 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.
|