AIAnalytics - Parte 5: Configuracion avanzada, Cron automatico y personalizacion de la IA

Configuracion avanzada, RGPD y arquitectura

⚙️ Panel de configuracion

Accede a la configuracion pulsando el icono de engranaje en la cabecera del dashboard. Se abre un modal con las secciones de configuracion.

🔧 Configuracion General

Parametros basicos del analisis:

📈 Umbral de morosidad (%)

Por defecto: 15%
Qué hace: Cuando el porcentaje de facturacion vencida supera este umbral, se genera una alerta de morosidad.
Ejemplo: Si tienes 100.000 EUR facturados y 18.000 EUR vencidos (18%), y el umbral es 15%, se generara una alerta.

⏳ Dias de inactividad del cliente

Por defecto: 90 dias
Qué hace: Un cliente que no ha comprado en mas dias que este valor se considera "inactivo" en el modulo de Clientes.
Recomendacion: Ajusta segun tu ciclo de venta. Si vendes productos de compra recurrente mensual, baja a 45-60 dias. Si es venta puntual, sube a 180.

✉️ Email de alertas criticas

Por defecto: Vacio (desactivado)
Qué hace: Si se configura, las alertas de severidad critica pueden notificarse por email.

🗄️ Retencion de informes (dias)

Por defecto: 180 dias
Qué hace: Los informes con estado "resuelto" mas antiguos que este numero de dias se eliminan automaticamente por el Cron.
Nota: Solo se eliminan informes ya resueltos. Los pendientes se conservan siempre.

🖥️ Configuracion IA Local (Ollama)

🔛 Activar IA

Desactivado (solo reglas): El plugin funciona con analisis estadistico puro
Activado: Se conecta al backend configurado (Ollama, Groq o auto)

🌐 URL de Ollama

Por defecto: http://127.0.0.1:11434
Qué hace: Direccion del servidor Ollama. Si ejecutas Ollama en otro servidor de tu red local, cambia la IP.
Ejemplo red local: http://192.168.1.100:11434

🤖 Modelo Ollama

Selecciona el modelo de IA a utilizar: Qwen 2.5 3B (recomendado), Qwen 2.5 7B, Llama 3.2 3B, Llama 3.1 8B, Mistral 7B, Gemma 2 9B, Phi-3 3.8B.

🧩 Botones de instalacion rapida (Linux)

Instalar Ollama: Ejecuta el script de instalacion oficial en el servidor
Descargar Modelo: Descarga el modelo seleccionado
Probar Conexion: Verifica que Ollama esta corriendo y muestra los modelos disponibles

☁️ Configuracion Groq (IA en la nube)

🔑 API Key de Groq

Por defecto: Vacio
Qué hace: Clave de API para conectar con Groq. Obtenla gratis en console.groq.com
Formato: Empieza por gsk_...

🧠 Modelo Groq

Por defecto: llama-3.3-70b-versatile
Alternativas: llama-3.1-8b-instant, gemma2-9b-it
Fallback automatico: Si el modelo principal agota su cuota diaria, el plugin prueba automaticamente los modelos de fallback

⚙️ Backend IA

Por defecto: auto
Opciones: auto (Ollama primero, Groq fallback), ollama (solo local), groq (solo nube), off (sin IA)

🔎 Probar Groq

Boton que verifica la conexion con la API de Groq y muestra el modelo configurado.

🧭 Personalidad IA

📝 Prompt de sistema personalizado

Por defecto: Vacio (usa la personalidad predeterminada)
Qué hace: Reemplaza completamente la personalidad del consultor IA

La personalidad predeterminada es un "Director de Inteligencia Empresarial" con 7 roles expertos (CEO, CFO, Director Comercial, COO, RRHH, Controller, Auditor).

🕰️ Cuando personalizar

Personaliza el prompt si quieres que la IA:

Se especialice en tu sector (ej: "Eres un asesor financiero del sector retail")
Use terminologia especifica de tu industria
Se enfoque en ciertos aspectos del negocio
Tenga un tono diferente (mas formal, mas directo, etc.)

💬 Ejemplo de prompt personalizado

Eres un asesor financiero especializado en el sector alimentario.
Tu prioridad es el control de margenes y la rotacion de stock perecedero.
Siempre menciona si un producto tiene riesgo de caducidad basandote en
la falta de movimiento. Responde en espanol, se directo y usa cifras.

⚖️ Cumplimiento RGPD y AI Act

📚 Marco legal

AIAnalytics cumple con:

RGPD (Reglamento General de Proteccion de Datos): Art. 6, 13, 17, 25, 28
AI Act (Ley de IA de la UE): Art. 6, 12, 14, 26, 50

🧾 Clasificacion de riesgo

El plugin se clasifica como riesgo minimo segun el AI Act porque:

Es un sistema de analisis interno de datos empresariales
No toma decisiones automatizadas vinculantes sobre personas fisicas
Todas las alertas requieren revision y accion manual del usuario (supervision humana)

⚖️ Base juridica del tratamiento

Analisis interno: RGPD Art. 6(1)(f) — Interes legitimo del responsable del tratamiento
Datos de empleados: RGPD Art. 6(1)(b) — Ejecucion de contrato laboral
Chat consultor: RGPD Art. 6(1)(f) — Interes legitimo

🛡️ Privacidad por diseno (Art. 25)

Cuando se usa Groq (API externa):

Los analizadores generan narrativas agregadas sin PII (nombres, emails, identificadores personales)
Los datos de clientes se envian por posicion, no por nombre
Las metricas son agregadas (totales, porcentajes, conteos)
La IA recibe solo lo necesario para analizar, no la base de datos completa

Cuando se usa Ollama:

Todos los datos se procesan en el propio servidor, sin transferencia externa

🔒 Zero Data Retention (Art. 28)

Groq aplica politica de Zero Data Retention a nivel de cuenta. Los datos enviados para analisis no se almacenan en los servidores de Groq tras generar la respuesta.

🧾 Consentimiento y transparencia (Art. 13)

El plugin incluye un sistema de consentimiento informado:

Aviso de privacidad: Texto completo con finalidades, bases juridicas, destinatarios, derechos y clasificacion AI Act
Aceptar: Registra el nick del usuario, la fecha y la version del aviso
Revocar: Fuerza el backend a solo Ollama (local), bloqueando el envio a Groq
Versionado: Si cambia la politica (version 2.0, 3.0...), se requiere nueva aceptacion

🧑‍⚖️ Derechos del interesado

El aviso de transparencia informa sobre los derechos RGPD:

Acceso (Art. 15), Rectificacion (Art. 16), Supresion (Art. 17)
Portabilidad (Art. 20), Oposicion (Art. 21)
Autoridad de control: AEPD (www.aepd.es)

✅ Panel de cumplimiento

Desde configuracion se accede al estado de cumplimiento que verifica 6 puntos:

| Verificacion | Norma | |--------------|-------| | Aviso de privacidad aceptado | RGPD Art. 13 | | Privacidad por diseno (narrativas sin PII) | RGPD Art. 25 | | Zero Data Retention en Groq | RGPD Art. 28 | | Log de auditoria activo | AI Act Art. 12 y 26 | | Supervision humana de alertas | AI Act Art. 14 | | Clasificacion de riesgo minimo | AI Act Art. 6 |

Se muestra un score de cumplimiento en porcentaje y nivel (conforme/parcial/no conforme).

📋 Log de auditoria (AI Act Art. 12)

Cada uso de IA queda registrado en la tabla ai_audit_log:

Evento: tipo de operacion (analisis, chat, ask)
Backend: ollama o groq
Resultado: ok o error
Metadatos: tokens aproximados, tiempo en ms, anonimizacion aplicada, ZDR, base juridica, finalidad
Fecha: timestamp del evento

La auditoria se activa por defecto (auditoria_activa = 1) y tiene retencion minima de 180 dias (AI Act Art. 26). El sistema crea la tabla automaticamente la primera vez que se necesita.

Desde el panel se pueden consultar:

Los ultimos 50 registros de auditoria
Estadisticas: total de usos en 30 dias, errores, usos anonimizados, desglose por backend

🔐 Parametros de privacidad

| Clave | Por defecto | Descripcion | |-------|-------------|-------------| | anonimizacion_groq | 1 | Privacidad por diseno para Groq (RGPD Art. 25) | | groq_zdr | 1 | Zero Data Retention en Groq (RGPD Art. 28) | | auditoria_activa | 1 | Log de auditoria de uso IA (AI Act Art. 12) |

⏰ Analisis automatico con Cron

⚙️ Que es el Cron de AIAnalytics

El plugin incluye un trabajo programado que se ejecuta automaticamente cada 24 horas. Realiza:

Analisis completo de los 9 modulos (igual que pulsar "Analisis Completo")
Limpieza de informes antiguos resueltos segun la retencion configurada

🔔 Activar el Cron

El Cron viene activado por defecto (cron_activo = 1). Para desactivarlo, cambia el parametro en la configuracion.

🕓 Hora de ejecucion

Por defecto: 04:00 (madrugada, cuando hay menos actividad)
Parametro: cron_hora
El Cron de FacturaScripts debe estar configurado para que se ejecute periodicamente

🛠️ Requisito: Cron de FacturaScripts

Para que el analisis automatico funcione, el cron del sistema operativo debe ejecutar el cron de FacturaScripts. Ejemplo para Linux:

*/10 * * * * php /var/www/facturascripts/vendor/bin/cron.php

Esto ejecuta el cron cada 10 minutos. AIAnalytics solo realizara el analisis una vez cada 24 horas gracias a isTimeForJob('ai-analysis', '24 hours').

🧹 Limpieza automatica

El Cron tambien ejecuta la limpieza que:

Busca informes con estado resuelto
Cuya fecha de creacion sea anterior a los dias de retencion configurados
Los elimina automaticamente

📋 Tabla completa de parametros de configuracion

| Clave | Valor por defecto | Descripcion | |-------|-------------------|-------------| | ollama_url | http://127.0.0.1:11434 | URL del servidor Ollama local | | ollama_model | qwen2.5:3b | Modelo IA local a utilizar | | usar_ia | 0 | Legacy: 1=Usar IA, 0=Solo reglas | | backend_ia | auto | Selector de backend: auto, ollama, groq, off | | groq_api_key | (vacio) | API Key de Groq | | groq_model | llama-3.3-70b-versatile | Modelo de Groq a utilizar | | cron_activo | 1 | Analisis automatico diario | | cron_hora | 04:00 | Hora del analisis automatico | | dias_retencion | 180 | Dias que se guardan los informes resueltos | | email_alertas | (vacio) | Email para alertas criticas | | umbral_morosidad_pct | 15 | Porcentaje de morosidad para alerta | | umbral_inactividad_dias | 90 | Dias sin comprar = cliente inactivo | | system_prompt | (vacio) | Prompt personalizado (vacio = predeterminado) | | anonimizacion_groq | 1 | Privacidad por diseno para Groq | | groq_zdr | 1 | Zero Data Retention en Groq | | auditoria_activa | 1 | Log de auditoria de uso de IA |

🏗️ Arquitectura tecnica

🗂️ Estructura de archivos del plugin

AIAnalytics/
  Init.php                    — Inicializacion, seed de 13 parametros + 3 RGPD
  Cron.php                    — Analisis diario automatico (9 modulos)
  facturascripts.ini          — Metadatos del plugin
  Controller/
    AIAnalytics.php           — Dashboard + 25+ acciones AJAX
    ListAIReport.php          — Listado de informes con filtros
  Lib/
    AIClient.php              — Factory: selector de backend (auto/ollama/groq/off)
    AnalysisEngine.php        — Motor: orquesta 9 modulos + chat + ask + healthScore
    OllamaClient.php          — Cliente HTTP para Ollama API (local)
    GroqClient.php            — Cliente HTTP para Groq API (nube) con fallback
    Config.php                — Sistema de configuracion con cache
    ExpertPrompts.php         — Prompts expertos por departamento (7 roles)
    DataCollector.php         — Consultas SQL (MySQL + PostgreSQL)
    ReportExporter.php        — Exportacion PDF + envio email
    Analyzers/
      Base.php                — Clase abstracta + enriquecimiento IA + narrativa
      Facturacion.php         — Analisis de facturacion
      Finanzas.php            — Analisis financiero
      Clientes.php            — Analisis de cartera
      Stock.php               — Analisis de inventario
      Procesos.php            — Analisis de embudo comercial
      Anomalias.php           — Deteccion de irregularidades
      Horarios.php            — Patrones y plazos
      RRHH.php                — Equipo: empleados, fichajes, imputaciones, proyectos
      Prevision.php           — Regresion lineal y proyeccion a 3 meses
    Privacy/
      AuditLogger.php         — Log de auditoria (AI Act Art. 12)
      ConsentManager.php      — Consentimiento y transparencia (RGPD Art. 13)
  Model/
    AIConfig.php              — Tabla ai_config (clave-valor)
    AIReport.php              — Tabla ai_reports (informes)
    AIChat.php                — Tabla ai_chat (historial chat)
    AIMetric.php              — Tabla ai_metrics (metricas)
  View/
    AIAnalytics.html.twig     — Vista completa (dashboard + chat + config)
  XMLView/
    ListAIReport.xml          — Definicion de la vista listado
  Table/
    ai_config.xml             — Definicion tabla configuracion
    ai_reports.xml            — Definicion tabla informes
    ai_chat.xml               — Definicion tabla chat
    ai_metrics.xml            — Definicion tabla metricas
  Translation/
    es_ES.json                — Traducciones al espanol

🗃️ Tablas de base de datos

| Tabla | Uso | |-------|-----| | ai_config | Configuracion clave-valor del plugin (16+ parametros) | | ai_reports | Informes de analisis con severidad, estado y detalle JSON | | ai_chat | Historial de conversaciones del chat | | ai_metrics | Metricas historicas | | ai_audit_log | Log de auditoria de uso de IA (creada automaticamente) |

🔁 Flujo de comunicacion con Ollama

OllamaClient conecta via HTTP a http://127.0.0.1:11434/api/chat
Timeout de conexion: 5 segundos
Timeout de generacion: 180 segundos (3 minutos)
La respuesta se parsea como JSON
Si falla la conexion, AIClient cae automaticamente al siguiente backend disponible

🔐 Flujo de comunicacion con Groq

GroqClient conecta via HTTPS a https://api.groq.com/openai/v1/chat/completions
Verificacion SSL activa (certificados verificados)
Timeout de conexion: 8 segundos, timeout de respuesta: 60 segundos
Si hay error 429 TPM (tokens por minuto): espera el tiempo indicado y reintenta
Si hay error 429 TPD (tokens por dia): prueba con el siguiente modelo de fallback
Cadena de fallback: llama-3.3-70b-versatile → llama-3.1-8b-instant → gemma2-9b-it
Cada llamada se registra en el log de auditoria con tokens, tiempo y resultado

🔄 Flujo del AIClient (selector de backend)

Lee el parametro backend_ia de configuracion
Si es off: retorna null (sin IA)
Si es auto u ollama: intenta conectar con Ollama. Si esta online, lo usa.
Si es solo ollama y esta offline: retorna null
Si es auto o groq: verifica que groq_api_key esta configurada. Si si, usa Groq.
Cache por request: solo resuelve una vez, las llamadas siguientes usan la instancia cacheada
reset() limpia la cache (se llama tras guardar configuracion)

🔒 Seguridad y privacidad

Datos 100% locales con Ollama: Toda la informacion se procesa en tu servidor
Narrativas sin PII con Groq: Los datos enviados a Groq son agregados, sin nombres ni identificadores
Zero Data Retention: Groq no almacena tus datos tras generar la respuesta
Log de auditoria: Cada uso de IA queda registrado con metadatos de privacidad
Sin telemetria: El plugin no comunica con ningun servidor externo salvo Groq (si esta configurado)
Acceso protegido: Solo usuarios autenticados de FacturaScripts acceden al plugin
AJAX con token: Todas las peticiones AJAX incluyen el token multireqtoken de FacturaScripts
Supervision humana: Todas las alertas requieren revision manual antes de actuar

🛠️ Resolucion de problemas

🔍 Ollama no se detecta

Verifica que el servicio esta corriendo: systemctl status ollama
Prueba manualmente: curl http://127.0.0.1:11434/api/tags
Revisa que la URL en configuracion sea correcta
Si usas Docker, verifica que el puerto 11434 esta expuesto

🌐 Groq no conecta

Verifica que tienes API key configurada (empieza por gsk_...)
Prueba con el boton "Probar Groq" en configuracion
Si da error 429, puede ser limite de cuota — el fallback automatico deberia activarse
Verifica conexion a internet del servidor

⏳ El analisis tarda mucho

Con Ollama, un analisis completo puede tardar 1-3 minutos dependiendo del modelo y hardware
Con Groq, el analisis es rapido (segundos por modulo)
Sin IA, el analisis es casi instantaneo (solo SQL)
Modelos mas pequenos (3B) son mas rapidos que los grandes (7B, 9B)

⚠️ No se generan alertas

Ejecuta primero un "Analisis Completo" desde el dashboard
Verifica que tienes datos en FacturaScripts (facturas, clientes, productos)
Revisa los umbrales de configuracion (puede que sean demasiado permisivos)

💬 El chat no responde

Si ningun backend esta online, el chat muestra datos en formato texto
Verifica el estado con el badge de la cabecera
Prueba la conexion desde Configuracion (Ollama y/o Groq)
Si Groq da errores 429 repetidos, puede haberse agotado la cuota diaria

🧑‍💼 RRHH no muestra datos

El modulo RRHH necesita que esten instalados los plugins de RRHH de FacturaScripts
Usa la accion ajax-diag-rrhh para diagnosticar que tablas existen en tu base de datos
El modulo detecta automaticamente las tablas disponibles y adapta el analisis