📋 INFORME COMPLETO – BITÁCORA DEL PROYECTO RINO CONCIERGE IA

1. VISIÓN GENERAL DEL PRODUCTO

Rino Concierge IA es un asistente virtual inteligente multicanal diseñado para:

• Atender clientes 24/7 a través de chat web (WordPress), WhatsApp Business y próximamente más canales

• Calificar leads automáticamente según su intención (venta/soporte/queja)

• Gestionar agentes humanos con asignación automática por departamento

• Agendar citas con recordatorios por WhatsApp

• Conectar con tiendas WooCommerce para consultar productos en tiempo real

• Ofrecer auditoría web y recomendaciones SEO

• Proporcionar métricas avanzadas con gráficos y exportación a Excel

• Soportar múltiples idiomas (español, portugués, inglés) y zonas horarias

Arquitectura: Sistema SaaS multi-tenant donde cada cliente (tenant) tiene su propio espacio aislado, dominios permitidos según su plan (Core=1, Quantum=3, Nexus=10), y límites de conversaciones mensuales.

2. ESTRUCTURA DE BASE DE DATOS

Nombre de la base de datos: rinopixel2_rino_saas_v2

Usuario de la base de datos: rinopixel2_utf8mb4_unicode_ci

Tablas creadas (12 tablas):

Relaciones clave:

• rino_leads.tenant_id → rino_tenants.id (ON DELETE CASCADE)

• rino_conversaciones.lead_id → rino_leads.id (ON DELETE CASCADE)

• rino_mensajes.conversacion_id → rino_conversaciones.id (ON DELETE CASCADE)

• rino_agentes.tenant_id → rino_tenants.id (ON DELETE CASCADE)

• rino_dominios.tenant_id → rino_tenants.id (ON DELETE CASCADE)

3. ESTRUCTURA DE DIRECTORIOS Y ARCHIVOS

Ruta raíz del proyecto: /home/rinopixel2/app.rinopixel.com

app.rinopixel.com/
│
├── .env                           # Variables de entorno (API keys, DB credentials)
├── .htaccess                      # Reglas de redirección y seguridad
├── index.php                      # Redirige a public/login.php o api/chat.php
├── logo-saas.png                  # Logo de la aplicación
│
├── /config/                       # Configuración central
│   ├── database.php               # Conexión PDO a MySQL
│   └── constants.php              # Constantes globales (planes, estados, idiomas)
│
├── /core/                         # Núcleo del sistema
│   ├── Database.php               # Query builder seguro (PDO wrapper)
│   ├── Auth.php                   # Autenticación, sesiones, sanitización
│   ├── LanguageDetector.php       # Detección de idioma y zona horaria
│   └── Lang.php                   # Diccionario central de textos multilingüe
│
├── /models/                       # Modelos de datos (CRUD por entidad)
│   ├── Tenant.php                 # Cliente SaaS
│   ├── Lead.php                   # Lead/prospecto
│   ├── Conversation.php           # Hilo de conversación
│   ├── Message.php                # Mensaje individual
│   ├── Product.php                # Catálogo de productos
│   ├── Agent.php                  # Agente humano
│   ├── Metric.php                 # Métricas diarias
│   └── Training.php               # Entrenamiento de IA
│
├── /services/                     # Servicios y lógica de negocio
│   ├── GeminiService.php          # Conexión con API de Google Gemini
│   ├── AppointmentService.php     # Gestión de citas y horarios
│   ├── WebScraperService.php      # Escáner de sitios web
│   ├── MetricsService.php         # Cálculo de métricas avanzadas
│   ├── WooCommerceService.php     # Conexión con API de WooCommerce
│   └── WhatsAppService.php        # Conexión con Meta Cloud API y Twilio
│
├── /api/                          # Endpoints públicos (AJAX, webhooks)
│   ├── chat.php                   # Endpoint principal del chat (IA + Gemini)
│   ├── webhook_whatsapp.php       # Webhook para recibir mensajes de WhatsApp
│   ├── webhook_whmcs.php          # Webhook para sincronizar con WHMCS
│   ├── ghost_login.php            # Login como cliente desde admin
│   └── run_scraping.php           # Ejecutar scraping manualmente
│
├── /admin/                        # Panel de Super Administrador
│   ├── index.php                  # Login de admin
│   ├── dashboard.php              # Dashboard con estadísticas globales
│   ├── logout.php                 # Cierre de sesión
│   ├── create_tenant.php          # Crear nuevo cliente SaaS
│   └── tenant_edit.php            # Editar cliente SaaS
│
├── /client/                       # Panel del Cliente (tenant)
│   ├── dashboard.php              # Dashboard con métricas y chat IA
│   ├── leads.php                  # Listado de leads (con filtros y exportación)
│   ├── lead_detail.php            # Ficha detallada del lead (historial, edición)
│   ├── training.php               # Entrenamiento de IA (FAQ, ejemplos)
│   ├── agents.php                 # Gestión de agentes humanos
│   ├── auditoria.php              # Auditoría web y recomendaciones SEO
│   ├── appointments.php           # Agendamiento de citas
│   ├── woocommerce.php            # Conexión con WooCommerce
│   ├── metrics.php                # Métricas avanzadas con gráficos (Chart.js)
│   ├── channels.php               # Configuración de canales (WhatsApp)
│   ├── settings.php               # Configuración general (idioma, zona horaria, dominios)
│   ├── logout.php                 # Cierre de sesión
│   └── agent_login.php            # Login para agentes
│   └── agent_dashboard.php        # Dashboard limitado para agentes
│   └── agent_logout.php           # Cierre de sesión para agentes
│
├── /public/                       # Frontend público
│   ├── login.php                  # Página de login de clientes
│   └── index.php                  # Landing page (redirige a login)
│
├── /cron/                         # Scripts para tareas programadas
│   ├── clean_logs.php             # Limpiar logs cada 15 días
│   └── reset_counters.php         # Resetear contadores mensuales
│
├── /logs/                         # Archivos de logs
│   └── whmcs_webhook.log          # Log de webhook de WHMCS
│
└── /tmp/                          # Archivos temporales

4. PLUGIN DE WORDPRESS

Nombre del plugin: Rino Concierge IA

Ubicación: /wp-content/plugins/rino-concierge-ia/

Estructura del plugin:

rino-concierge-ia/
├── rino-concierge-ia.php           # Archivo principal (activación, menú, widget)
├── /includes/
│   ├── widget.php                  # Widget flotante del chat (CSS + JS)
│   ├── ajax-handlers.php           # Manejadores AJAX para enviar mensajes
│   ├── user-recognition.php        # Reconocimiento de usuario por email/IP
│   └── rating.php                  # Sistema de valoración con deditos
└── /assets/
    ├── icon.svg                    # Icono redondo del chat
    ├── css/widget.css              # Estilos del widget
    └── js/widget.js                # JavaScript del widget

Funcionalidades del plugin:

• Widget flotante con efecto de latido neón

• Burbuja de bienvenida a los 3 segundos

• Sonido pop sutil (opcional)

• Formulario de captura de datos (nombre, email, WhatsApp, empresa, departamento)

• Reconocimiento de usuario por cookie (email) y IP

• Envío de mensajes a la API central (api/chat.php)

• Valoración al final del chat (satisfecho, no resolvió, transferir a agente)

• Configuración desde WordPress (Token API, color, nombre de la IA)

5. PANEL DE ADMINISTRACIÓN (SUPER ADMIN)

6. PANEL DEL CLIENTE (TENANT)

7. API ENDPOINTS

8. SERVICIOS (SERVICES)

9. LÓGICA DE NEGOCIO IMPLEMENTADA

Calificación automática de leads (api/chat.php):

• Detecta intención del mensaje: venta (+20 puntos), soporte (-5 puntos), queja (-10 puntos), info (neutro)

• Score máximo: 100 (Caliente), mínimo: 0 (Frío)

• Estados: Nuevo (0-39), Templado (40-69), Caliente (70-100), Soporte (fijo), Atendido, Cliente

Asignación automática de agente:

• Según intención detectada: venta → departamento ventas, soporte/queja → departamento soporte

• Busca agente activo del departamento correspondiente

• Envía notificación WhatsApp al agente con resumen del caso

Límites por plan:

Web Scraper:

• Se ejecuta manualmente desde client/auditoria.php

• Escanea: home, productos, servicios, contacto, blog, nosotros, FAQ

• Extrae: título, meta descripción, H1, contenido, productos, precios, emails, teléfonos, redes sociales

• Genera recomendaciones SEO (alta/media/baja prioridad)

Citas:

• Horarios configurables por día en tabla rino_business_hours

• Intervalo de 30 minutos por defecto

• Validación de disponibilidad antes de agendar

• Recordatorio por WhatsApp (pendiente de activar)

Métricas:

• Gráficos con Chart.js (líneas para leads/conversaciones, dona para satisfacción)

• Exportación a CSV: métricas generales, leads, conversaciones, agentes

• Períodos: Hoy, Última semana, Último mes

10. CARACTERÍSTICAS DEL PRODUCTO

11. CREDENCIALES Y CONFIGURACIÓN

Archivo .env (variables de entorno):

APP_NAME="Rino Concierge IA"
APP_ENV=production
APP_DEBUG=false
APP_TIMEZONE="America/La_Paz"

DB_HOST=localhost
DB_NAME=rinopixel2_rino_saas_v2
DB_USER=rinopixel2_utf8mb4_unicode_ci
DB_PASS=[CONTRASEÑA]

GEMINI_API_KEY=AIzaSyBN7Qnxg7Yuc_etEVEvatuK1MN_l1juKgQ
GEMINI_MODEL=gemini-3.5-flash

WHMCS_SECRET_KEY=[CLAVE_SECRETA]

Accesos al sistema:

12. INTEGRACIÓN CON WHMCS

Estado actual:

• ✅ Archivo api/webhook_whmcs.php creado

• ✅ Credenciales de API generadas en WHMCS (Identifier + Secret)

• ✅ Archivo sync_to_rino.php creado (sincronización manual)

• ✅ Archivo rino_concierge_hook.php creado (hooks automáticos)

Eventos que maneja el webhook:

• AfterModuleCreate / CreateAccount → Crea tenant

• AfterModuleSuspend / SuspendAccount → Suspende tenant

• AfterModuleUnsuspend / UnsuspendAccount → Activa tenant

• AfterModuleTerminate / TerminateAccount → Cierra tenant

• InvoicePaid → Registra pago

Pendiente de WHMCS:

• ⚠️ Subir los archivos hook a la carpeta includes/hooks/ de WHMCS

• ⚠️ Configurar el cron job para sincronización automática

• ⚠️ Probar el flujo completo (compra → creación de cuenta)

13. INTEGRACIÓN CON WHATSAPP BUSINESS

Proveedores soportados:

• Meta Cloud API (oficial, requiere App de Facebook Developers)

• Twilio (oficial, requiere cuenta de Twilio)

Flujo de mensajes:

1. Cliente escribe al número de WhatsApp configurado

2. Meta/Twilio envía el mensaje a api/webhook_whatsapp.php

3. El sistema procesa el mensaje (igual que el chat web)

4. La IA responde y se envía de vuelta por WhatsApp

Configuración del cliente:

• Desde client/channels.php elige proveedor

• Pega sus credenciales (Access Token, Phone Number ID, etc.)

• Verifica la conexión

Pendiente de WhatsApp:

• ⚠️ Probar con un número real (requiere cuenta en Meta/Twilio)

• ⚠️ Configurar webhook en Meta Developers (apuntando a api/webhook_whatsapp.php)

14. PENDIENTES Y TAREAS FUTURAS

Prioridad Alta:

1. Configurar CRON en cPanel:

   text

   0 0 1 * * php /home/rinopixel2/app.rinopixel.com/cron/reset_counters.php

2. Probar el webhook de WHMCS:

   • Subir hooks a la carpeta de WHMCS

   • Crear un cliente de prueba en WHMCS

   • Verificar que se cree el tenant automáticamente

3. Probar WhatsApp Business:

   • Crear cuenta en Meta Developers o Twilio

   • Configurar webhook

   • Probar envío/recepción de mensajes

Prioridad Media:

4. Completar internacionalización:

   • Aplicar Lang::get() en todos los paneles (dashboard, leads, training, agents, auditoria, citas, woocommerce, channels, settings)

   • Traducir textos estáticos restantes

5. Mejorar rendimiento:

   • Optimizar consultas SQL (índices)

   • Implementar caché para datos frecuentes

Prioridad Baja:

6. Documentación para el cliente:

   • Manual de usuario (cómo usar el panel)

   • Guía de instalación del plugin

   • FAQ

7. Métricas adicionales:

   • Gráfico de satisfacción por agente

   • Exportación de métricas a PDF

15. OBSERVACIONES Y RECOMENDACIONES

Seguridad:

• El archivo .env está protegido por .htaccess, pero verificar que no sea accesible desde el navegador

• Las contraseñas de los usuarios están hasheadas con password_hash()

• Los tokens API son únicos por tenant

Escalabilidad:

• La arquitectura multi-tenant permite agregar más clientes sin afectar rendimiento

• Los límites por plan evitan abusos de recursos

• Recomendación: migrar a servidor VPS cuando el número de clientes supere los 50

Optimizaciones pendientes:

• Implementar caché para el catálogo de productos

• Usar colas para el web scraping (evitar timeouts)

• Comprimir archivos CSS/JS en producción

16. CONCLUSIÓN

El proyecto Rino Concierge IA está 90% completado. Las funcionalidades principales están implementadas y probadas. Quedan tareas de integración (WHMCS, WhatsApp) y configuración (CRON, webhooks) para el lanzamiento final.

El sistema es robusto, escalable y preparado para manejar múltiples clientes con diferentes planes y límites. La arquitectura está bien estructurada y documentada.

Fecha del informe: 31 de mayo de 2026
Versión del sistema: 3.5.0
Estado: En producción (pendiente lanzamiento oficial)