Add README.md
This commit is contained in:
182
README.md
Normal file
182
README.md
Normal file
@@ -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 <URL_DEL_REPOSITORIO_GITEA>
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user