Arquitectura del Módulo Perfex AI

**Módulo:** perfex_ai | **Versión:** 2.0.0 | **Framework:** CodeIgniter 3 (Perfex CRM)

---

```
modules/perfex_ai/
├── perfex_ai.php # Punto de entrada: define constantes, registra hooks de activación
├── install.php # Instalación: crea 35 tablas, settings iniciales, permisos
├── core/
│ ├── ai_hooks.php # Todos los hooks registrados (admin_init, cron, login, etc.)
│ └── ai_menu.php # Menú lateral en el admin
├── controllers/ # 13 controladores
│ ├── Perfex_ai.php # Controlador principal del módulo
│ ├── Chat.php # Interfaz de chat, streaming, mensajes
│ ├── Dashboard.php # Dashboard con estadísticas y estado
│ ├── Settings.php # Configuración del módulo
│ ├── Knowledge_base.php # Gestión de la base de conocimiento
│ ├── Glass_tariffs.php # Tarifas de vidrio: productos, proveedores, fabricantes
│ ├── Telegram.php # Configuración del bot Telegram
│ ├── Telegram_webhook.php # Handler del webhook de Telegram
│ ├── Visitors.php # Gestión de visitantes de oficina

│ ├── Quick_auth.php # Acceso rápido admin (IP oficina)
│ ├── Client_quick_auth.php # Acceso rápido clientes (IP oficina)
│ ├── Whatsapp.php # Configuración WhatsApp
│ └── Wiki_ai.php # Consultas IA para la Wiki
├── models/ # 7 modelos
│ ├── Conversations_model.php # CRUD conversaciones, exportar a MD
│ ├── Messages_model.php # CRUD mensajes de chat
│ ├── Knowledge_base_model.php # KB: categorías, documentos, chunks, búsqueda FULLTEXT
│ ├── File_operations_model.php # Auditoría de operaciones de archivo
│ ├── Shared_prompt_model.php # Prompts compartidos por contexto
│ ├── Visitors_model.php # Tracking de visitantes
│ └── Wiki_ai_model.php # Consultas IA wiki
├── libraries/ # 24 librerías
│ ├── AI_factory.php # Factory para crear clientes Gemini/Claude
│ ├── AI_client.php # Interfaz abstracta del cliente IA
│ ├── Gemini_client.php # Integración API Gemini

│ ├── Claude_client.php # Integración API Claude
│ ├── Gemini_streaming.php # Streaming SSE con Gemini
│ ├── Gemini_tools.php # Function calling (tools) de Gemini
│ ├── Gemini_cache.php # Caché específica de Gemini
│ ├── Context_manager.php # Gestión del contexto de conversación
│ ├── Chat_session.php # Sesiones de chat
│ ├── Cache_manager.php # Sistema de caché de respuestas
│ ├── Crm_action_tools.php # Tools CRM: crear presupuesto, factura, etc.
│ ├── Crm_query_tools.php # Tools CRM: buscar clientes, productos, etc.
│ ├── File_manager.php # Operaciones de archivo con aprobación
│ ├── Document_extractor.php # Extraer texto de documentos
│ ├── Embedding_service.php # Embeddings para KB semántica
│ ├── Glass_pricing_engine.php # Motor de cálculo de precios de vidrio
│ ├── Pdf_tariff_parser.php # Parsear PDFs de tarifas con Gemini Vision
│ ├── Pdf_exporter.php # Exportar datos a PDF

│ ├── Kb_processor.php # Procesamiento de documentos KB
│ ├── Google_drive.php # Integración Google Drive
│ ├── Insight_extractor.php # Extraer insights de conversaciones
│ ├── Module_analyzer.php # Analizar módulos Perfex
│ ├── Predictive_analytics.php # Analítica predictiva
│ └── Wiki_knowledge_saver.php # Guardar contenido wiki en KB
├── helpers/
│ └── ai_helper.php # Funciones helper: ai_get_setting(), ai_log(), etc.
├── views/ # Vistas organizadas por sección
│ ├── chat/ # Chat UI, lista conversaciones
│ ├── glass_tariffs/ # 10 vistas de tarifas
│ ├── knowledge_base/ # Gestión KB
│ ├── settings/ # Configuración
│ ├── telegram/ # Config Telegram
│ ├── visitors/ # Visitantes
│ ├── whatsapp/ # Config WhatsApp
│ ├── wiki_ai/ # Consultas wiki
│ ├── dashboard.php # Dashboard principal
│ └── floating_chat.php # Widget chat flotante

├── assets/
│ ├── css/ # ai.css, floating_chat.css
│ ├── js/ # chat.js, floating_chat.js, ai.js, visitor_device_collect.js
│ └── images/providers/ # Logos de proveedores IA
├── language/ # i18n: english, spanish, catalan
├── uploads/ # Archivos subidos: attachments, knowledge_base
├── kb_docs/ # Documentación interna del módulo (este directorio)
├── backups/ # Backups automáticos
├── locks/ # Archivos de bloqueo para procesos concurrentes
└── tests/ # Tests unitarios
```

El módulo usa **35 tablas** con prefijo `tblperfex_ai_`. Principales:

| Tabla | Propósito |
|-------|-----------|
| `conversations` | Conversaciones de chat |
| `messages` | Mensajes dentro de conversaciones |
| `kb_categories` | Categorías de la base de conocimiento |
| `kb_documents` | Documentos indexados en la KB |
| `kb_chunks` | Fragmentos de texto con FULLTEXT index |
| `glass_products` | Catálogo de productos de vidrio |
| `glass_suppliers` | Proveedores de vidrio |
| `settings` | Configuración del módulo (key-value) |
| `rate_limits` | Control de frecuencia de peticiones |
| `webhook_logs` | Logs de webhooks (Telegram) |

- **MVC estricto**: Controladores → Modelos → Vistas
- **Factory Pattern**: `AI_factory` crea el cliente correcto (Gemini/Claude)
- **Hook System**: Toda la integración con Perfex CRM vía hooks en `ai_hooks.php`
- **Prefijo DB**: Siempre `db_prefix()`, nunca hardcodeado
- **Helpers globales**: `ai_get_setting()`, `ai_set_setting()`, `ai_log()`, `ai_is_api_configured()`

- [Conversaciones](modulo_conversaciones.md) - Sistema de chat
- [Knowledge Base](modulo_knowledge_base.md) - Base de conocimiento
- [Telegram Bot](modulo_telegram_bot.md) - Bot Telegram
- [Tarifas Vidrio](modulo_tarifas_vidrio.md) - Sistema de tarifas
- [Configuración](modulo_configuracion.md) - Settings
- [Cron Jobs](modulo_cron_jobs.md) - Tareas automáticas