From 85aa6a38ba64eba459f21daf2aec069af984dd0c Mon Sep 17 00:00:00 2001 From: dmolinari Date: Thu, 30 Oct 2025 12:05:59 -0300 Subject: [PATCH] Add README.md --- README.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9a76103 --- /dev/null +++ b/README.md @@ -0,0 +1,182 @@ +--- + +# Titulares APP 📰 + +**Titulares APP** es una aplicación web de dashboard en tiempo real diseñada para extraer titulares de un sitio de noticias, gestionarlos y exportarlos automáticamente a un archivo CSV en una ubicación de red. + +El sistema se compone de un **backend RESTful API desarrollado en ASP.NET Core** que gestiona el scraping, la base de datos y la comunicación en tiempo real, y un **frontend interactivo de tipo SPA (Single Page Application) construido con React, TypeScript y Vite**. + +--- +## 🚀 Funcionalidades Principales + +El sistema está diseñado para la automatización, la gestión centralizada y la visualización en tiempo real de titulares de noticias. + +### 🤖 Motor de Scraping Automatizado +- **Worker en Segundo Plano:** Un proceso `BackgroundService` de .NET se ejecuta de forma continua en el servidor. +- **Scraping Periódico:** Extrae los últimos titulares del sitio de noticias (`eldia.com`) a intervalos configurables. +- **Sincronización Inteligente:** Compara los titulares extraídos con los existentes en la base de datos para evitar duplicados y mantener la lista actualizada, preservando el orden de los titulares manuales. +- **Limpieza de Datos:** Procesa el texto de los titulares para eliminar prefijos no deseados (ej: "VIDEO.-") y decodificar entidades HTML. + +### ⚡ Actualizaciones en Tiempo Real con SignalR +- **Notificación Instantánea:** Cualquier cambio en la lista de titulares (por scraping, creación manual, edición, reordenamiento o eliminación) es notificado instantáneamente a todos los clientes conectados. +- **Dashboard Sincronizado:** La tabla de titulares en la interfaz de todos los usuarios se actualiza en tiempo real sin necesidad de refrescar la página. +- **Gestión de Conexión:** El backend detecta cuándo hay clientes activos y puede pausar el proceso de scraping si no hay nadie conectado para ahorrar recursos. + +### 🖐️ Gestión Manual Completa +- **Creación de Titulares:** Permite añadir titulares manualmente, los cuales se insertan al principio de la lista. +- **Edición Rápida:** + - Edición del texto del titular directamente en la tabla. + - Edición de la viñeta (bullet point) a través de un modal dedicado. +- **Reordenamiento Drag & Drop:** Permite cambiar el orden visual de los titulares simplemente arrastrándolos y soltándolos en la tabla. +- **Eliminación Segura:** Borrado de titulares con un modal de confirmación para evitar acciones accidentales. + +### ⚙️ Panel de Configuración Dinámico +- **Gestión Centralizada:** Una sección en la UI permite configurar todos los parámetros clave del sistema. +- **Parámetros Configurables:** + - **Ruta del archivo CSV:** Ubicación de red donde se guardará el archivo. + - **Intervalo de Scraping:** Frecuencia en minutos para la extracción de nuevos titulares. + - **Cantidad de Titulares:** Número máximo de titulares a mantener en la lista. + - **Viñeta por Defecto:** Símbolo a usar cuando un titular no tiene una viñeta específica. +- **Auto-Guardado Inteligente:** Los cambios en la configuración se guardan automáticamente en la base de datos después de una breve pausa (`debounce`), proporcionando una experiencia de usuario fluida. + +### 📄 Exportación a CSV Robusta +- **Generación Automática:** Después de cada ciclo de scraping exitoso, el sistema regenera automáticamente el archivo `titulares.csv` en la ruta de red configurada. +- **Generación Manual:** Un botón en la UI permite forzar la regeneración del archivo CSV en cualquier momento. +- **Codificación Específica:** El archivo CSV se genera con codificación `UTF-16 Big Endian con BOM` para máxima compatibilidad con sistemas específicos que puedan consumir el archivo. + +### 🎨 Interfaz de Usuario Moderna +- **Diseño Oscuro y Profesional:** Construido con Material-UI, ofreciendo una experiencia visual agradable y consistente. +- **Feedback al Usuario:** Notificaciones instantáneas para operaciones de éxito o error. +- **Indicadores de Estado:** Muestra el estado de la conexión con el servidor (Conectado, Reconectando, Desconectado) y el estado del proceso de scraping (ON/OFF). + +--- + +## 🛠️ Stack Tecnológico + +### Backend (`backend/`) +- **Framework:** ASP.NET Core 9 +- **Lenguaje:** C# +- **Acceso a Datos:** Dapper (Micro ORM) +- **Base de Datos:** Microsoft SQL Server +- **Scraping:** HtmlAgilityPack +- **Comunicación Real-Time:** SignalR +- **Generación CSV:** CsvHelper + +### Frontend (`frontend/`) +- **Librería:** React 19 +- **Lenguaje:** TypeScript +- **Componentes UI:** Material-UI (MUI) +- **Drag & Drop:** dnd-kit +- **Comunicación Real-Time:** Cliente de SignalR (`@microsoft/signalr`) +- **Build Tool:** Vite + +### Entorno de Producción +- **Contenerización:** Docker & Docker Compose +- **Proxy Inverso y Servidor Web:** Nginx (configurado para servir React y actuar como proxy para la API y SignalR/WebSockets) + +--- + +## 🚀 Puesta en Marcha (Getting Started) + +Siga estos pasos para configurar y ejecutar el proyecto. + +### 1. Entorno de Desarrollo Local + +#### Prerrequisitos +- **.NET SDK 9.0** o superior. +- **Node.js** v20.x o superior. +- **Microsoft SQL Server** y una herramienta de gestión como SSMS. + +#### Configuración +1. **Clonar el Repositorio:** + ```bash + git clone + cd TitularesApp # O el nombre de tu carpeta + ``` +2. **Base de Datos:** + - Cree una base de datos en su instancia de SQL Server (ej: `TitularesDB`). + - Ejecute los scripts necesarios para crear las tablas `Titulares` y `Configuracion` según los modelos en el proyecto (`Titular.cs`, `ConfiguracionApp.cs`). +3. **Backend (`backend/src/Titulares.Api`):** + - Renombre o copie `appsettings.Development.json` si es necesario. + - **Modifique la `ConnectionString`** en `appsettings.json` para apuntar a su base de datos. + - Ejecute desde el directorio `backend/src/Titulares.Api`: + ```bash + dotnet restore + dotnet run + ``` + - La API estará escuchando en `http://localhost:5174`. +4. **Frontend (`frontend/`):** + - Verifique que `frontend/.env.development` contiene `VITE_API_BASE_URL=http://localhost:5174`. + - Ejecute desde el directorio `frontend/`: + ```bash + npm install + npm run dev + ``` + - La aplicación estará disponible en `http://localhost:5173`. + +--- + +### 2. Entorno de Producción con Docker + +Esta es la forma recomendada de desplegar la aplicación. + +#### Prerrequisitos +- **Docker** y **Docker Compose** instalados en el servidor anfitrión (ej: `192.168.5.128`). +- Una **carpeta compartida en la red** accesible desde el servidor Docker, donde se guardará el archivo CSV. + +#### Configuración del Servidor Anfitrión (Host de Docker) +Para asegurar que el contenedor pueda escribir en la carpeta de red de forma persistente y resiliente a reinicios, se recomienda configurar un montaje bajo demanda con `autofs`. + +1. **Instalar dependencias:** `sudo apt-get install -y autofs cifs-utils`. +2. **Configurar el mapa maestro `auto.master`:** Añadir la línea `/mnt /etc/auto.cifs --timeout=60`. +3. **Crear el mapa `auto.cifs`** con los detalles de la carpeta compartida, apuntando a un archivo de credenciales seguro. + ``` + # /etc/auto.cifs + nombre_montaje -fstype=cifs,credentials=/ruta/segura/credenciales.txt,uid=1000,gid=1000,vers=3.0 ://IP_PC_USUARIO/CARPETA_COMPARTIDA + ``` +4. **Reiniciar el servicio:** `sudo systemctl restart autofs`. + +#### Despliegue +1. **Clonar el repositorio** en el servidor Docker. +2. **Configurar la red externa de Docker** si es necesario (para la base de datos). + ```bash + docker network create shared-net + ``` +3. **Ejecutar Docker Compose** desde la raíz del proyecto. + ```bash + docker-compose up --build -d + ``` +4. **Acceder a la Aplicación:** La aplicación estará disponible en la IP del servidor Docker y el puerto configurado en `docker-compose.yml`. + - **URL:** `http://192.168.5.128:8905` + +--- +## 📂 Estructura del Proyecto + +``` +. +├── backend/ +│ └── src/ +│ └── Titulares.Api/ # Proyecto principal de ASP.NET Core +│ ├── Controllers/ # Controladores de la API +│ ├── Data/ # Repositorios (Dapper) para acceso a datos +│ ├── Hubs/ # Hubs de SignalR +│ ├── Models/ # Clases de modelo y DTOs +│ ├── Services/ # Lógica de negocio (Scraping, CSV, Estado) +│ ├── Workers/ # Servicios en segundo plano +│ ├── Dockerfile # Instrucciones para construir la imagen del backend +│ └── ... +├── frontend/ +│ ├── src/ +│ │ ├── components/ # Componentes de React +│ │ ├── contexts/ # Proveedores de Contexto (Notificaciones) +│ │ ├── hooks/ # Hooks personalizados (useSignalR, useDebounce) +│ │ ├── services/ # Lógica de llamadas a la API (axios) +│ │ ├── App.tsx # Componente principal de la aplicación +│ │ └── main.tsx # Punto de entrada de React +│ ├── .env.development # Variables de entorno para desarrollo +│ ├── .env.production # Variables de entorno para producción +│ └── Dockerfile # Instrucciones para construir la imagen del frontend +├── nginx/ +│ └── nginx.conf # Configuración de Nginx como proxy inverso +└── docker-compose.yml # Orquestación de los contenedores +``` \ No newline at end of file