# SIIP - WhatsApp Notifications & Integrated Payment Portal

![Version](https://img.shields.io/badge/version-4.2.0-blue.svg?style=for-the-badge)
![UCRM Compatibility](https://img.shields.io/badge/UCRM-v2.1.0%2B-green.svg?style=for-the-badge)
![Status](https://img.shields.io/badge/status-PRODUCTION-success.svg?style=for-the-badge)
![Author](https://img.shields.io/badge/author-SIIP_INTERNET-orange.svg?style=for-the-badge)

Este plugin es una solución integral que transforma tu UCRM en un **Portal Administrativo de Última Generación**. No solo automatiza la comunicación por WhatsApp, sino que integra un Dashboard completo para la gestión de pagos online (Stripe/OXXO), visualización de comprobantes y coordinación de equipos técnicos.

## 🚀 Novedades v4.2.0 (Analytics & Sync)

-   **📊 Visualizador de Pagos Mensuales**: Nueva herramienta de análisis que permite seleccionar cualquier mes y visualizar gráficamente:
    -   Estadísticas de clientes activos vs clientes que pagaron
    -   Gráfica de dona interactiva con Chart.js
    -   Listado detallado de clientes pendientes con saldos
    -   Porcentajes de cobranza en tiempo real
-   **🔄 Sincronización Mejorada CallBell**: Fix crítico que garantiza la actualización automática del saldo y estado del cliente en CallBell cuando se agregan facturas o se modifican servicios.
-   **🎯 Categorización Inteligente de Pagos**: Nuevo microservicio con acceso directo a la base de datos para obtener metadata de Stripe (tipo de pago) y asignar correctamente los atributos incluso cuando la API de UCRM no tiene la información.
-   **⚙️ Configuración para Producción**: Sistema de `.env` implementado para gestión segura de credenciales de base de datos.

## 🚀 Novedades v4.1.0 (Performance & Storage)

-   **⚡ Microservicio PDF (`pdf-cropper`)**: Nuevo motor de renderizado externo (Python/FastAPI) que reemplaza librerías legacy, aumentando la velocidad y eliminando problemas de memoria en el servidor principal.
-   **📦 MinIO / S3 Storage**: Migración completa del almacenamiento de comprobantes. Adiós FTP, hola almacenamiento de objetos seguro y escalable con URLs firmadas y limpieza automática.
-   **🖼️ Smart Image Processing**: Generación de imágenes "Full Mode" (sin recortes) y capacidad de **Edición Dinámica de Texto** (Overlay) para personalizar métodos de pago en los comprobantes.

## 🚀 Novedades v4.0.0 (Portal Dashboard)

-   **🖥️ Dashboard de Pagos Integrado**: Nueva interfaz visual dentro de UCRM para gestionar cobros de Stripe y OXXO sin salir de la plataforma.
-   **🏪 OXXO Pay Híbrido & Visual**: Generación de fichas OXXO con dos modos inteligentes:
    -   **Inline (Admin)**: Visualización inmediata del voucher (local) para máxima velocidad.
    -   **FTP (Webhook)**: Carga automática a servidor externo para compartir links públicos.
-   **🌑 UI/UX Premium**: Interfaz rediseñada con Sidebar expandible, cabecera global "Sticky", Modo Oscuro automático y componentes responsivos.

---

## ⚡ Funcionalidades Principales

### 1. Gestión de Cobranza Avanzada
-   **Pagos SPEI**: Instrucciones inmediatas con CLABE personalizada.
-   **Vouchers OXXO**: Generación instantánea de códigos de barras con vista previa "Split-Screen" (Datos + Imagen).
-   **Historial en Tiempo Real**: Consulta los últimos 10 pagos de cualquier cliente al instante.

### 2. Automatización WhatsApp (CallBell)
-   **Notificaciones Dinámicas**: Envío automático de facturas, recordatorios de pago y avisos de corte.
-   **Re-envío Manual**: Herramienta para disparar notificaciones específicas desde el Dashboard si el proceso automático falla.
-   **Sincronización Total**: Mantiene los contactos de CallBell siempre actualizados con los datos del CRM.

### 3. Coordinación Técnica (Jobs/Tasks)
-   **Agenda Inteligente**: Notifica a instaladores sobre nuevas tareas y reprogramaciones.
-   **Datos para Técnicos**: Envía coordenadas GPS y contraseñas de equipos (formato impresora térmica) directamente al WhatsApp del técnico.

---

## 🏗️ Arquitectura del Sistema

El plugin utiliza una arquitectura modular basada en **Facades** y **Servicios** para garantizar estabilidad y escalabilidad.

### Componentes Clave

-   **Frontend (`public.php`)**: Una Single Page Application (SPA) ligera incrustada en UCRM, construida con Vanilla JS y CSS moderno (Variables, Flexbox/Grid).
-   **Despachador (`Plugin.php`)**: Router de eventos que delega acciones a los controladores específicos.
-   **Motor de Pagos (`PaymentIntentStripe`)**: Servicio robusto que se comunica con la API de Stripe para crear intenciones de pago y métodos.
-   **Generador OXXO (`AbstractOxxoOperationsFacade`)**: Orquesta el flujo complejo: Stripe -> Puppeteer (Screenshot) -> FTP/Local Storage -> Respuesta JSON.

---

## 🛠️ Requisitos e Integraciones

Para desbloquear todo el potencial, el plugin requiere:

1.  **UISP/UCRM**: Versión 2.1.0 o superior.
2.  **Stripe API**: Keys de producción/test para procesar pagos.
3.  **CallBell API**: Token para el envío de mensajes de WhatsApp.
4.  **Microservicio Puppeteer**: Contenedor Docker para renderizar los vouchers de OXXO a imagen.
5.  **Servidor FTP (Opcional)**: Requerido solo si se desea generar URLs públicas para compartir los vouchers externamente.

---

## 🏷️ Configuración Rápida

El plugin se configura directamente desde el panel de UCRM (`Ajustes -> Plugins -> siip-whatsapp-notifications`).

### Parámetros Críticos
-   `ipserver`: Tu dominio UCRM.
-   `tokenstripe`: Tu Secret Key de Stripe.
-   `tokencallbell`: Tu API Key de CallBell.
-   `hostServerFTP` / `user` / `pass`: Credenciales para el almacenamiento de vouchers remotos.

---

## 📝 Registro de Cambios

Para consultar la evolución detallada del proyecto, ver el archivo [CHANGELOG.md](./CHANGELOG.md).