158 lines
5.5 KiB
Markdown
158 lines
5.5 KiB
Markdown
---
|
|
|
|
# 📄 Gestor de Facturas - Sistema Automatizado
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sistema integral para la automatización, organización y monitoreo de archivos de facturación electrónica. Este proyecto es la **migración y modernización** del sistema legacy (VB.NET), reimplementado con una arquitectura orientada a microservicios, contenerización y una interfaz web reactiva.
|
|
|
|
---
|
|
|
|
## 🚀 Características Principales
|
|
|
|
* **Procesamiento en Segundo Plano (Worker):** Servicio continuo que monitorea la base de datos del ERP y busca los archivos PDF correspondientes en la red.
|
|
* **Lógica de Reintentos Inteligente:** Sistema de reintentos ante fallos de I/O y notificaciones por correo con lógica "anti-spam" (evita alertar repetidamente sobre el mismo error).
|
|
* **Dashboard en Tiempo Real:** Interfaz web para visualizar el estado del servicio, próxima ejecución, logs de eventos y estadísticas diarias.
|
|
* **Configuración Dinámica:** Permite ajustar la periodicidad (minutos, días, meses), rutas y credenciales sin detener el contenedor.
|
|
* **Seguridad:** Autenticación mediante JWT, encriptación de credenciales sensibles en base de datos (AES-256) y protección de rutas.
|
|
* **Compatibilidad Legacy:** Replica exactamente la estructura de carpetas y nomenclatura de archivos del sistema anterior para asegurar la continuidad del negocio.
|
|
|
|
---
|
|
|
|
## 🛠️ Stack Tecnológico
|
|
|
|
### Backend (`/Backend`)
|
|
* **Framework:** .NET 10.0 (C#)
|
|
* **Tipo:** Web API + Hosted Service (Worker)
|
|
* **Base de Datos:** SQL Server (Entity Framework Core)
|
|
* **Logging:** Serilog (Salida a Consola para integración con Grafana/Loki)
|
|
|
|
### Frontend (`/frontend`)
|
|
* **Framework:** React 24 + TypeScript
|
|
* **Build Tool:** Vite
|
|
* **Estilos:** Tailwind CSS
|
|
* **Estado:** TanStack Query
|
|
|
|
### Infraestructura
|
|
* **Docker:** Orquestación con Docker Compose.
|
|
* **Nginx:** Servidor web y Proxy Inverso para la API.
|
|
|
|
---
|
|
|
|
## 📦 Instalación y Despliegue
|
|
|
|
### Prerrequisitos
|
|
* Docker y Docker Compose instalados en el servidor.
|
|
* Acceso a los volúmenes de red donde se alojan las facturas.
|
|
|
|
### 1. Clonar el Repositorio
|
|
```bash
|
|
git clone https://repo.eldiaservicios.com/dmolinari/GestorWebFacturas.git
|
|
cd GestorWebFacturas
|
|
```
|
|
|
|
### 2. Configuración de Entorno (.env)
|
|
Crea un archivo `.env` en la raíz del proyecto basándote en el siguiente ejemplo.
|
|
|
|
```ini
|
|
# --- BASE DE DATOS SQL SERVER (ERP) ---
|
|
DB_HOST=192.168.X.X,1433
|
|
DB_NAME=AdminFacturasApp
|
|
DB_USER=usuario_sql
|
|
DB_PASSWORD=tu_password_seguro
|
|
|
|
# --- SEGURIDAD (JWT & Encriptación) ---
|
|
# Generar claves seguras (mínimo 32 caracteres)
|
|
JWT_KEY=Clave_Secreta_Para_Firmar_Tokens_JWT_!
|
|
JWT_ISSUER=GestorFacturasAPI
|
|
JWT_AUDIENCE=GestorFacturasFrontend
|
|
ENCRYPTION_KEY=Clave_32_Bytes_Para_AES_DB_Config
|
|
|
|
# --- FRONTEND ---
|
|
API_PUBLIC_URL=/api
|
|
```
|
|
|
|
### 3. Ejecutar con Docker Compose
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
El sistema estará disponible en el puerto 80 del servidor (o el configurado en el `docker-compose.yml`).
|
|
|
|
---
|
|
|
|
## ⚙️ Configuración del Sistema
|
|
|
|
El sistema utiliza dos niveles de configuración:
|
|
|
|
### 1. `appsettings.json` (Backend)
|
|
Define mapeos estáticos de negocio.
|
|
* **EmpresasMapping:** Relaciona códigos de empresa (ej: "0001") con nombres de carpeta (ej: "ELDIA").
|
|
* **FacturaTiposMapping:** Define la traducción de tipos de comprobante (ej: "FSR" -> "A", "CAI" -> "NCA").
|
|
|
|
### 2. Base de Datos (Tabla `Configuraciones`)
|
|
Editable desde el **Frontend > Configuración**. Controla:
|
|
* Periodicidad de ejecución.
|
|
* Rutas de origen y destino (rutas internas del contenedor).
|
|
* Credenciales SMTP y de la base de datos externa (se guardan encriptadas).
|
|
|
|
---
|
|
|
|
## 📂 Estructura de Directorios y Volúmenes
|
|
|
|
Para que el sistema funcione, los volúmenes de Docker deben mapearse correctamente a las rutas de red del servidor host.
|
|
|
|
| Ruta en Contenedor | Descripción | Configuración en Panel Web |
|
|
| :--- | :--- | :--- |
|
|
| `/app/data/origen` | Carpeta donde el ERP deposita los PDFs originales | `/app/data/origen` |
|
|
| `/app/data/destino` | Carpeta donde el sistema organiza los PDFs procesados | `/app/data/destino` |
|
|
|
|
**Estructura de salida generada:**
|
|
```text
|
|
/destino
|
|
/NOMBRE_EMPRESA
|
|
/YYYY-MM (Año-Mes de la factura)
|
|
/CLIENTE-EMPRESA-SUCURSAL-TIPO_AJUSTADO-NUMERO (Carpeta)
|
|
/CLIENTE-EMPRESA-SUCURSAL-TIPO_ORIGINAL-NUMERO.pdf (Archivo)
|
|
```
|
|
|
|
---
|
|
|
|
## 🛡️ Notas de Migración (Legacy vs Moderno)
|
|
|
|
Se han respetado las siguientes reglas críticas para mantener compatibilidad:
|
|
|
|
1. **Nomenclatura:**
|
|
* **Carpeta:** Usa el "Tipo Ajustado" (ej: `NCA` para Notas de Crédito A).
|
|
* **Archivo:** Conserva el "Tipo Original" del ERP (ej: `CAI`).
|
|
2. **Alertas:**
|
|
* El sistema Legacy enviaba correos informativos en cada ejecución.
|
|
* El sistema Moderno opera por **Gestión de Excepción**: Solo envía correo si hay errores no reportados previamente (Lógica Anti-Spam / Anti-Fatiga).
|
|
3. **Logs:**
|
|
* Salida estándar (`stdout`) habilitada para recolección por Grafana/Portainer.
|
|
* Registro en base de datos para auditoría interna visible desde el Dashboard.
|
|
|
|
---
|
|
|
|
## 👨💻 Desarrollo Local
|
|
|
|
Para levantar el entorno de desarrollo fuera de Docker:
|
|
|
|
**Backend:**
|
|
```bash
|
|
cd Backend/GestorFacturas.API
|
|
dotnet restore
|
|
dotnet user-secrets init
|
|
# Configurar secretos locales (ver documentación interna)
|
|
dotnet run
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
``` |