================================================================================
                    DOCUMENTACIÓN COMPLETA
                  WhatsApp Bot Manager
================================================================================

Versión: 1.2.0
PHP: 8.2+
Estado: Producción

Sistema completo de gestión de conversaciones de WhatsApp Business
Desarrollado por U-Site.app

================================================================================
ÍNDICE
================================================================================

1. Introducción
2. Manual de Usuario
3. Documentación Técnica
4. API REST Completa
5. Guía de Implementación
6. Casos de Uso
7. Entregables del Proyecto
8. Mantenimiento y Soporte

================================================================================
1. INTRODUCCIÓN
================================================================================

¿Qué es WhatsApp Bot Manager?
-------------------------------

WhatsApp Bot Manager es una plataforma web completa para gestionar 
comunicaciones de WhatsApp Business. Permite a empresas automatizar 
respuestas, gestionar conversaciones en tiempo real, enviar mensajes 
masivos y mantener un control total sobre las interacciones con clientes.


Características Principales
-----------------------------

GESTIÓN DE CONVERSACIONES
- Interfaz tipo WhatsApp Web responsive
- Notificaciones en tiempo real con SSE (Server-Sent Events)
- Soporte completo para multimedia (imágenes, videos, audio, documentos)
- Búsqueda y filtrado de conversaciones
- Indicadores de estado de mensajes (enviado, entregado, leído)

AUTOMATIZACIÓN INTELIGENTE
- Bot con respuestas automáticas configurables
- Plantillas de mensaje aprobadas por WhatsApp
- Menús interactivos con botones
- Mensajes masivos con segmentación
- Quick replies para respuestas rápidas

SEGURIDAD Y CONTROL
- Autenticación basada en base de datos
- Protección contra ataques de fuerza bruta
- Registro completo de actividades (logs)
- Sistema de sesiones seguras
- Configuración granular de permisos

ANÁLISIS Y REPORTES
- Dashboard con estadísticas en tiempo real
- Gráficos de mensajes por día/hora
- Estado de conversaciones (activas, resueltas, pendientes)
- Exportación de datos a CSV
- Métricas de rendimiento del bot


Tecnologías Utilizadas
------------------------

Tecnología        Versión    Uso
------------------------------------------------------------------------
PHP               8.2+       Backend y lógica de negocio
MariaDB           10.11+     Base de datos principal
Redis             7.0+       Cache y gestión de colas
JavaScript        ES6+       Frontend interactivo
Bootstrap         5.3.0      UI/UX responsive
Docker            24.0+      Contenedorización
Nginx             1.25+      Servidor web
WhatsApp API      v22.0      Integración con WhatsApp


================================================================================
2. MANUAL DE USUARIO
================================================================================

2.1. Acceso al Sistema
------------------------

Inicio de Sesión
----------------
1. Accede a la URL de tu instalación (ej: https://tudominio.com)
2. Haz clic en "Iniciar Sesión"
3. Ingresa tus credenciales:
   - Usuario: admin (por defecto)
   - Contraseña: password123 (cámbiala tras el primer acceso)

Recuperación de Contraseña
---------------------------
1. Haz clic en "¿Olvidaste tu contraseña?"
2. Ingresa tu correo electrónico registrado
3. Recibirás un enlace para restablecer tu contraseña
4. Crea una nueva contraseña segura (mínimo 8 caracteres)


2.2. Panel Principal (Dashboard)
---------------------------------

Vista General
-------------
Al iniciar sesión verás el dashboard con:

ESTADÍSTICAS GENERALES
- Total de usuarios
- Mensajes recibidos (24h)
- Mensajes enviados (24h)
- Conversaciones activas

GRÁFICO DE MENSAJES
- Visualización por hora/día
- Comparativa entrada vs salida
- Tendencias de uso

MENSAJES RECIENTES
- Últimas 10 conversaciones
- Vista previa del mensaje
- Timestamp relativo


2.3. Gestión de Conversaciones
--------------------------------

Interfaz de Chat
----------------
La interfaz principal replica WhatsApp Web con:

PANEL IZQUIERDO (Lista de Conversaciones)
- Buscar: Campo de búsqueda por nombre o número
- Filtros:
  * Todos los mensajes
  * Solo no leídos
- Lista ordenada por mensaje más reciente
- Indicadores:
  * Punto azul = conversación no leída
  * Timestamp del último mensaje
  * Vista previa del contenido

PANEL PRINCIPAL (Área de Chat)
- Cabecera:
  * Avatar y nombre del usuario
  * Número de teléfono
  * Botones de acción (editar, eliminar)
- Área de mensajes:
  * Mensajes propios (derecha, fondo verde claro)
  * Mensajes recibidos (izquierda, fondo blanco)
  * Timestamps en cada mensaje
  * Estados: checkmark enviado, doble checkmark entregado/leído
- Barra de entrada:
  * Campo de texto para escribir
  * Botón de adjuntar archivos
  * Botón de respuestas rápidas
  * Botón de enviar

Enviar Mensajes de Texto
-------------------------
1. Selecciona una conversación de la lista
2. Escribe tu mensaje en el campo inferior
3. Presiona Enter o haz clic en Enviar
4. El mensaje aparecerá inmediatamente en el chat

Características de texto:
- Soporte para emojis
- Formato WhatsApp:
  * *texto* = negrita
  * _texto_ = cursiva
  * ~texto~ = tachado
  * `código` = monoespaciado
- Saltos de línea con Shift + Enter
- Envío con Enter


Enviar Archivos Multimedia
---------------------------

IMÁGENES
1. Haz clic en el botón Adjuntar
2. Selecciona "Imagen"
3. Elige una imagen desde tu dispositivo
4. Opcionalmente agrega un caption (texto)
5. Haz clic en "Enviar"

Formatos soportados: JPG, PNG, GIF, WebP
Tamaño máximo: 5 MB

VIDEOS
1. Clic en Adjuntar > "Video"
2. Selecciona un video (máx 16MB)
3. Agrega caption opcional
4. Envía

Formatos soportados: MP4, AVI, MOV, 3GP
Tamaño máximo: 16 MB

AUDIO
Opción A - Grabar nota de voz:
- Mantén presionado el botón del micrófono
- Habla al micrófono
- Suelta para enviar automáticamente
- Desliza para cancelar

Opción B - Subir archivo de audio:
- Clic en Adjuntar > "Audio"
- Selecciona archivo MP3, WAV, AAC, OGG
- Envía directamente

Tamaño máximo audio: 16 MB

DOCUMENTOS
1. Clic en Adjuntar > "Documento"
2. Selecciona archivo (PDF, DOC, XLS, etc.)
3. El sistema detecta el tipo automáticamente
4. Envía

Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP
Tamaño máximo: 100 MB


Respuestas Rápidas (Quick Replies)
-----------------------------------
Las respuestas rápidas te permiten enviar mensajes predefinidos con un 
solo clic:

1. Haz clic en el botón Respuestas Rápidas
2. Se desplegará un panel con dos pestañas:
   - Texto: Respuestas automáticas simples
   - Plantillas: Templates aprobados de WhatsApp
3. Selecciona la respuesta deseada
4. Se enviará automáticamente

Editar respuestas rápidas:
1. Ve a Configuración > Respuestas Automáticas
2. Haz clic en "Nueva Respuesta"
3. Ingresa:
   - Palabra clave (trigger)
   - Mensaje de respuesta
   - Activa/Desactiva
4. Guarda los cambios


Plantillas de WhatsApp
-----------------------
Las plantillas son mensajes pre-aprobados por Meta que puedes usar:

ENVIAR UNA PLANTILLA
1. En el chat, despliega Respuestas Rápidas
2. Ve a la pestaña "Plantillas"
3. Selecciona una plantilla aprobada
4. Si la plantilla tiene variables, se rellenarán automáticamente
5. La plantilla se envía instantáneamente

GESTIONAR PLANTILLAS
1. Ve a Configuración > Plantillas de Mensaje
2. Verás una lista con:
   - Nombre de la plantilla
   - Estado: Aprobada | Pendiente | Rechazada
   - Idioma
   - Fecha de creación
3. Crear nueva plantilla:
   - Clic en "Nueva Plantilla"
   - Completa el formulario:
     * Nombre: identificador único (sin espacios)
     * Categoría: MARKETING, UTILITY, AUTHENTICATION
     * Idioma: es (Español)
     * Encabezado: Título opcional
     * Cuerpo: Mensaje principal (puede incluir variables {{1}}, {{2}})
     * Pie: Texto al final opcional
     * Botones: Opcionales (CALL_TO_ACTION, QUICK_REPLY)
   - Enviar para aprobación
   - Meta revisará la plantilla (puede tardar 24-48h)

IMPORTANTE: Solo puedes enviar plantillas APROBADAS por WhatsApp.


Notificaciones en Tiempo Real
-------------------------------
El sistema usa SSE (Server-Sent Events) para actualizaciones en tiempo real:

- Nuevos mensajes: Aparecen automáticamente sin recargar
- Notificaciones de escritura: "Usuario está escribiendo..."
- Estados de mensaje: Cambios en tiempo real (entregado -> leído)
- Toasts informativos: Alertas visuales en la esquina superior derecha

Estados de conexión:
- Verde: Conectado
- Amarillo: Reconectando
- Rojo: Desconectado

Si pierdes conexión, el sistema intentará reconectar automáticamente 
cada 5 segundos.


2.4. Gestión de Usuarios
--------------------------

Listar Usuarios
---------------
1. Ve a "Usuarios" en el menú principal
2. Verás una tabla con:
   - ID del usuario
   - Nombre
   - Número de teléfono
   - Estado (in_service, on_hold, completed)
   - Última interacción
   - Acciones (editar, eliminar, ver chat)

Crear/Editar Usuario
---------------------
1. Haz clic en "Nuevo Usuario"
2. Completa el formulario:
   - Nombre: Nombre completo o identificador
   - Teléfono: Número con código de país (ej: 573001234567)
   - Email: Opcional
   - Notas: Información adicional
3. Guarda

Editar: Haz clic en el icono de edición en la fila del usuario.

Eliminar Usuario
----------------
1. Haz clic en el icono de eliminar
2. Confirma la acción
3. ADVERTENCIA: Esto eliminará también todo el historial de conversaciones

Exportar Usuarios
-----------------
1. Haz clic en "Exportar CSV"
2. Se descargará un archivo con todos los usuarios y sus datos


2.5. Mensajes Masivos (Broadcast)
-----------------------------------

Enviar Mensaje Masivo
----------------------
1. Ve a "Envío Masivo" en el menú
2. Configura el mensaje:
   - Tipo: Texto o Plantilla
   - Contenido: Escribe el mensaje o selecciona plantilla
   - Filtro de destinatarios:
     * Todos los usuarios
     * Solo usuarios activos (últimas 24h)
     * Lista personalizada (importar CSV)
3. Vista previa: Revisa cómo se verá el mensaje
4. Haz clic en "Enviar a todos"
5. El sistema procesará los envíos en segundo plano

Limitaciones de WhatsApp:
- Solo puedes enviar plantillas aprobadas a usuarios que no te han 
  escrito en 24h
- Respeta la ventana de 24 horas para mensajes libres
- El sistema controlará automáticamente estos límites

Seguimiento de Envíos
----------------------
En la sección "Historial de Envíos" puedes ver:
- Fecha y hora del envío
- Total de destinatarios
- Enviados exitosos
- Fallidos (con motivo)
- Estado general


2.6. Bot Automatizado
----------------------

Configurar el Bot
-----------------
1. Ve a Configuración > Bot Automático
2. Activa/Desactiva el bot con el interruptor
3. Configura:
   - Mensaje de bienvenida: Primer mensaje al nuevo usuario
   - Mensaje de ausencia: Respuesta fuera de horario
   - Horario de atención: Define días y horas
   - Palabras clave: Triggers que activan respuestas

Respuestas Automáticas
-----------------------

CREAR RESPUESTA AUTOMÁTICA
1. Ve a Configuración > Respuestas Automáticas
2. Clic en "Nueva Respuesta"
3. Configura:
   - Trigger: Palabra o frase que activa la respuesta
   - Mensaje: Respuesta automática
   - Activo: On/Off
   - Prioridad: Orden de evaluación (1 = más alta)
4. Guarda

Ejemplos de uso:
- Trigger: hola, buenos días, buenas tardes
  Respuesta: ¡Hola! Bienvenido a [Empresa]. ¿En qué puedo ayudarte?

- Trigger: horario, horarios, cuando abren
  Respuesta: Nuestro horario de atención es: Lunes a Viernes 9am-6pm

- Trigger: precio, cuanto cuesta, costo
  Respuesta: Para información sobre precios, por favor visita [URL]

TIPS PARA RESPUESTAS AUTOMÁTICAS EFECTIVAS
- Usa múltiples triggers: hola,buenos días,buenas tardes,hey
- Sé claro y conciso: Respuestas cortas son más efectivas
- Incluye opciones: "Responde 1 para ventas, 2 para soporte"
- Usa emojis: Hacen la conversación más amigable
- Escalamiento: Indica cuándo un humano tomará la conversación


Menús Interactivos
------------------
Los menús interactivos permiten crear flujos de conversación estructurados:

CREAR MENÚ
1. Ve a Configuración > Menús Interactivos
2. Clic en "Nuevo Menú"
3. Configura:
   - Nombre del menú: Identificador interno
   - Mensaje principal: Texto que verá el usuario
   - Opciones (hasta 10):
     * ID: Número o letra
     * Texto: Descripción de la opción
     * Acción: Respuesta o submenu
4. Guarda

Ejemplo de menú principal:
---------------------------
Bienvenido a [Empresa]

Por favor selecciona una opción:

1. Ventas
2. Soporte técnico
3. Información general
4. Hablar con un asesor

Responde con el número de tu opción.


2.7. Configuración del Sistema
--------------------------------

Configuración de WhatsApp
--------------------------
1. Ve a Configuración > WhatsApp API
2. Completa los campos:

   Datos de Meta Business:
   - App ID: ID de tu aplicación de Facebook
   - App Secret: Secreto de la aplicación
   - Business Account ID: ID de tu cuenta de negocio
   - Phone Number ID: ID del número de teléfono de WhatsApp
   - Access Token: Token de acceso permanente
   - Webhook Verify Token: Token para verificar el webhook

   URLs:
   - API URL: https://graph.facebook.com/v22.0/
   - Webhook URL: https://tudominio.com/api/webhook.php

3. Haz clic en "Verificar Configuración"
4. Si todo está correcto, verás checkmarks en todos los checks
5. Guarda los cambios

Configuración General
---------------------
1. Ve a Configuración > General
2. Ajusta:
   - Nombre de la empresa: Aparece en mensajes automáticos
   - Zona horaria: América/Bogota (por defecto)
   - Idioma: Español (es)
   - Límite de mensajes por minuto: Control de rate limiting
   - Retención de logs: Días que se guardan los registros
   - Activar notificaciones sonoras: Sonido al recibir mensaje
3. Guarda

Gestión de Administradores
---------------------------
1. Ve a Configuración > Administradores
2. Lista de usuarios admin actuales
3. Crear nuevo admin:
   - Clic en "Nuevo Administrador"
   - Ingresa:
     * Nombre de usuario
     * Email
     * Contraseña (mínimo 8 caracteres)
     * Permisos:
       - Admin completo: Acceso total
       - Operador: Solo gestión de conversaciones
       - Visualizador: Solo lectura
   - Guarda
4. Eliminar admin: Clic en icono eliminar junto al usuario


2.8. Logs y Auditoría
----------------------

Ver Logs del Sistema
--------------------
1. Ve a Logs en el menú principal
2. Filtros disponibles:
   - Nivel: Error, Warning, Info, Debug
   - Fecha: Rango de fechas
   - Módulo: API, Bot, Webhook, Sistema
3. Tabla de logs muestra:
   - Timestamp
   - Nivel de severidad
   - Mensaje
   - Contexto (datos adicionales)

Logs de Webhook
----------------
Los logs de webhook muestran cada interacción con WhatsApp:

1. Ve a Logs > Webhook
2. Cada entrada muestra:
   - Timestamp de recepción
   - Tipo de evento (message, status, etc.)
   - Datos del mensaje (JSON)
   - Respuesta del sistema
   - Tiempo de procesamiento

Útil para:
- Depurar problemas de recepción de mensajes
- Ver mensajes duplicados
- Auditar interacciones

Exportar Logs
-------------
1. Selecciona los filtros deseados
2. Clic en "Exportar"
3. Descarga archivo CSV con los logs

Limpiar Logs
------------
Para liberar espacio:
1. Ve a Logs > Limpieza
2. Selecciona:
   - Logs más antiguos de X días
   - Tipo específico
3. Confirma la eliminación


================================================================================
3. DOCUMENTACIÓN TÉCNICA
================================================================================

3.1. Arquitectura del Sistema
-------------------------------

DIAGRAMA DE COMPONENTES
------------------------

                         FRONTEND
  +----------+  +-------------+  +----------------+
  |conversations| chat_window |   inicio.html   |
  |   .php   |  |    .php     |   (landing)     |
  +----------+  +-------------+  +----------------+
                        |
                        v
                  API REST (42 Endpoints)
  +-------------+ +-------------+ +----------------+
  |send_message | |get_messages | | upload_media   |
  |send_template| | get_users   | | webhook        |
  |send_broadcast| | get_stats   | | sse_events     |
  +-------------+ +-------------+ +----------------+
                        |
                        v
                 CAPA DE SERVICIOS
  +-----------------+          +-------------------+
  | WhatsAppService |          |   BotService      |
  | (comunicación   |          | (automatización)  |
  |  con WhatsApp)  |          |                   |
  +-----------------+          +-------------------+
                        |
                        v
                   CAPA DE DATOS
  +------------+  +------------+  +---------------+
  |  Database  |  |   Redis    |  |  Filesystem   |
  |  (MariaDB) |  |  (cache)   |  |  (uploads/)   |
  +------------+  +------------+  +---------------+
                        |
                        v
              INTEGRACIONES EXTERNAS
  +------------------------------------------------------+
  |    WhatsApp Business API (Meta Graph API)          |
  |        https://graph.facebook.com/v22.0/           |
  +------------------------------------------------------+


FLUJO DE MENSAJES
-----------------

Mensaje Entrante (Incoming):
1. Usuario envía mensaje por WhatsApp
2. WhatsApp envía webhook POST a /api/webhook.php
3. Webhook valida firma de Meta
4. Procesa evento (message, status, etc.)
5. Guarda mensaje en BD (tabla: conversations)
6. BotService evalúa si debe responder automáticamente
7. Si hay respuesta automática -> Envía por WhatsAppService
8. SSE notifica a frontend conectado
9. Frontend actualiza UI en tiempo real

Mensaje Saliente (Outgoing):
1. Usuario escribe mensaje en interfaz web
2. Frontend llama a /api/send_message.php (POST)
3. API valida sesión y datos
4. WhatsAppService envía mensaje a Graph API
5. Graph API retorna ID del mensaje
6. Se guarda mensaje en BD con estado 'sent'
7. Respuesta JSON al frontend
8. Frontend muestra mensaje instantáneamente
9. Webhook recibe confirmación de entrega/lectura
10. Actualiza estado en BD y notifica por SSE


3.2. Estructura de Archivos
-----------------------------

whatsapp/
|-- api/                          (API REST Endpoints)
|   |-- webhook.php               (Recibe eventos de WhatsApp)
|   |-- send_message.php          (Enviar mensaje individual)
|   |-- send_media_message.php    (Enviar multimedia)
|   |-- send_template.php         (Enviar plantilla)
|   |-- send_broadcast.php        (Envío masivo)
|   |-- get_conversations.php     (Listar conversaciones)
|   |-- get_user_messages.php     (Mensajes de un usuario)
|   |-- get_users.php             (Listar usuarios)
|   |-- update_user.php           (Actualizar usuario)
|   |-- delete_user.php           (Eliminar usuario)
|   |-- upload_media.php          (Subir archivos)
|   |-- get_media.php             (Obtener URL temporal de media)
|   |-- get_templates.php         (Listar plantillas)
|   |-- save_template.php         (Guardar plantilla)
|   |-- get_autoresponses.php     (Respuestas automáticas)
|   |-- save_autoresponse.php     (Guardar respuesta automática)
|   |-- get_stats.php             (Estadísticas dashboard)
|   |-- sse_events.php            (Server-Sent Events)
|   +-- ... (42 endpoints totales)
|
|-- assets/                       (Recursos estáticos)
|   |-- css/
|   |   +-- main.css
|   |-- js/
|   |   |-- chat-common.js       (Funciones compartidas de chat)
|   |   |-- dashboard.js         (Dashboard stats)
|   |   +-- admin.js
|   +-- images/
|
|-- classes/                      (Clases PHP)
|   +-- Database.php             (Clase singleton de DB)
|
|-- config/                       (Configuración)
|   |-- config.php               (Configuración principal)
|   +-- .env.example             (Plantilla variables de entorno)
|
|-- database/                     (Scripts SQL)
|   |-- migrations/
|   |   |-- 001_initial_schema.sql
|   |   |-- 002_add_media_fields.sql
|   |   +-- ...
|   +-- backups/                 (Backups automáticos)
|
|-- docker/                       (Configuración Docker)
|   |-- nginx/
|   |   +-- default.conf
|   |-- php/
|   |   +-- Dockerfile
|   +-- supervisor/
|       +-- supervisord.conf
|
|-- services/                     (Servicios)
|   |-- WhatsAppService.php      (Cliente WhatsApp Business API)
|   |-- BotService.php           (Lógica del bot automático)
|   +-- MediaService.php         (Gestión multimedia)
|
|-- uploads/                      (Archivos subidos)
|   |-- images/
|   |-- videos/
|   |-- audio/
|   +-- documents/
|
|-- logs/                         (Logs del sistema)
|   |-- app.log
|   |-- webhook.log
|   +-- error.log
|
|-- tests/                        (Tests)
|   |-- ApiTest.php
|   |-- WhatsAppServiceTest.php
|   +-- ...
|
|-- conversations.php             (Interfaz principal de chat)
|-- chat_window.php              (Ventana de chat)
|-- inicio.html                  (Landing page)
|-- index.php                    (Dashboard / Redirect)
|-- login.php                    (Login)
|-- logout.php                   (Logout)
|-- worker.php                   (Worker de colas)
|-- composer.json                (Dependencias PHP)
|-- docker-compose.yml           (Orquestación containers)
|-- .env                         (Variables de entorno)
+-- README.md                    (Documentación básica)


3.3. Base de Datos
-------------------

TABLA: users
Almacena información de usuarios/contactos de WhatsApp.

Campo                  Tipo              Descripción
------------------------------------------------------------------------
id                    INT               ID único autoincremental
phone_number          VARCHAR(50)       Número con código de país
name                  VARCHAR(255)      Nombre del contacto
email                 VARCHAR(255)      Email (opcional)
profile_pic_url       TEXT              URL foto de perfil
in_service            TINYINT(1)        1 si está en conversación activa
advisor_requested     TINYINT(1)        1 si solicitó asesor humano
on_hold               TINYINT(1)        1 si está en espera
attended_by           INT               ID del admin que atiende
last_message_at       TIMESTAMP         Timestamp último mensaje
created_at            TIMESTAMP         Fecha de registro
updated_at            TIMESTAMP         Última actualización

Índices:
- idx_phone (phone_number)
- idx_last_message (last_message_at)
- idx_in_service (in_service)


TABLA: conversations
Almacena todos los mensajes (entrantes y salientes).

Campo                    Tipo              Descripción
------------------------------------------------------------------------
id                      INT               ID único autoincremental
user_id                 INT               ID del usuario
message_id              VARCHAR(255)      ID único de WhatsApp
content                 TEXT              Contenido del mensaje
direction               ENUM              'incoming' o 'outgoing'
message_type            VARCHAR(50)       text, image, video, audio, etc.
status                  VARCHAR(50)       sent, delivered, read, failed
media_url               TEXT              URL original de WhatsApp
whatsapp_media_id       VARCHAR(255)      ID del media en WhatsApp
local_file              VARCHAR(500)      Ruta local del archivo
local_thumb             VARCHAR(500)      Ruta de thumbnail
filename                VARCHAR(255)      Nombre del archivo
mime_type               VARCHAR(100)      Tipo MIME
media_url_external      TEXT              URL proxy persistente
reply_to_message_id     VARCHAR(255)      ID mensaje al que responde
reaction_emoji          VARCHAR(10)       Emoji de reacción
reaction_to_message_id  VARCHAR(255)      ID mensaje al que reacciona
created_at              TIMESTAMP         Fecha de creación

Índices:
- idx_user_id (user_id)
- idx_message_id (message_id)
- idx_direction (direction)
- idx_created_at (created_at)
- idx_user_created (user_id, created_at)


TABLA: message_templates
Plantillas de WhatsApp aprobadas por Meta.

Campo              Tipo              Descripción
------------------------------------------------------------------------
id                INT               ID único autoincremental
template_name     VARCHAR(255)      Nombre de la plantilla
language_code     VARCHAR(10)       Código de idioma (es, en)
category          VARCHAR(50)       MARKETING, UTILITY, AUTHENTICATION
header_text       TEXT              Texto del encabezado
body_text         TEXT              Texto del cuerpo
footer_text       TEXT              Texto del pie
buttons           TEXT              Botones (JSON)
status            VARCHAR(50)       pending, approved, rejected
created_at        TIMESTAMP         Fecha de creación
updated_at        TIMESTAMP         Última actualización

Índices:
- idx_status (status)


TABLA: autoresponses
Respuestas automáticas del bot.

Campo                Tipo              Descripción
------------------------------------------------------------------------
id                  INT               ID único autoincremental
trigger_keywords    TEXT              Palabras clave (separadas por comas)
response_message    TEXT              Mensaje de respuesta
is_active           TINYINT(1)        1 si está activa
priority            INT               Orden de evaluación
created_at          TIMESTAMP         Fecha de creación
updated_at          TIMESTAMP         Última actualización

Índices:
- idx_active (is_active)


TABLA: system_config
Configuración dinámica del sistema.

Campo           Tipo              Descripción
------------------------------------------------------------------------
id             INT               ID único autoincremental
config_key     VARCHAR(255)      Clave de configuración
config_value   TEXT              Valor
config_type    VARCHAR(50)       string, int, boolean, json
description    TEXT              Descripción
created_at     TIMESTAMP         Fecha de creación
updated_at     TIMESTAMP         Última actualización

Índices:
- idx_key (config_key)


TABLA: admin_users
Usuarios administradores del panel.

Campo         Tipo              Descripción
------------------------------------------------------------------------
id           INT               ID único autoincremental
username     VARCHAR(100)      Nombre de usuario
password     VARCHAR(255)      Contraseña hash
email        VARCHAR(255)      Email
role         VARCHAR(50)       super_admin, admin, operator, viewer
is_active    TINYINT(1)        1 si está activo
last_login   TIMESTAMP         Último inicio de sesión
created_at   TIMESTAMP         Fecha de creación
updated_at   TIMESTAMP         Última actualización

Índices:
- idx_username (username)


TABLA: webhook_logs
Auditoría de webhooks recibidos.

Campo                Tipo              Descripción
------------------------------------------------------------------------
id                  INT               ID único autoincremental
event_type          VARCHAR(100)      Tipo de evento
payload             TEXT              Datos del evento (JSON)
processed           TINYINT(1)        1 si fue procesado
processing_time_ms  INT               Tiempo de procesamiento
error_message       TEXT              Mensaje de error (si aplica)
created_at          TIMESTAMP         Fecha de recepción

Índices:
- idx_event_type (event_type)
- idx_processed (processed)
- idx_created_at (created_at)


3.4. Servicios Principales
----------------------------

WhatsAppService.php
Clase que encapsula toda la comunicación con WhatsApp Business API.

MÉTODOS PRINCIPALES:

1. sendTextMessage($to, $message)
   Envía un mensaje de texto simple.
   
   Parámetros:
   - $to: Número de destino con código de país
   - $message: Contenido del mensaje (máx 4096 caracteres)
   
   Retorna:
   [
       'success' => true|false,
       'message_id' => 'wamid.XXX...',
       'error' => null|string
   ]

2. sendTemplateMessage($to, $templateName, $language, $bodyParameters)
   Envía una plantilla de mensaje aprobada.
   
   Parámetros:
   - $to: Número destino
   - $templateName: Nombre de la plantilla
   - $language: Código de idioma (es)
   - $bodyParameters: Array de variables

3. sendImageMessage($to, $imageUrl, $caption, $isLocalFile)
   Envía una imagen.
   
   Formatos soportados: JPG, JPEG, PNG
   Tamaño máximo: 5 MB

4. sendVideoMessage($to, $videoUrl, $caption, $isLocalFile)
   Envía un video.
   
   Formatos soportados: MP4, 3GPP
   Tamaño máximo: 16 MB

5. sendAudioMessage($to, $audioUrl, $isLocalFile)
   Envía audio.
   
   Formatos soportados: AAC, MP3, AMR, OGG
   Tamaño máximo: 16 MB

6. sendDocumentMessage($to, $documentUrl, $filename, $caption, $isLocalFile)
   Envía un documento.
   
   Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP
   Tamaño máximo: 100 MB

7. uploadMedia($filePath, $mimeType)
   Sube un archivo a los servidores de WhatsApp.
   
   Retorna: media_id para usar en envíos

8. downloadMedia($mediaId)
   Descarga un archivo multimedia de WhatsApp.
   
   Retorna: ruta local del archivo descargado

9. sendInteractiveMessage($to, $bodyText, $buttons, $header, $footer)
   Envía un mensaje con botones interactivos (hasta 3 botones).

10. sendListMessage($to, $bodyText, $buttonText, $sections)
    Envía un mensaje con lista interactiva (hasta 10 opciones).


BotService.php
Servicio de automatización de respuestas.

MÉTODOS PRINCIPALES:

1. processIncomingMessage($userId, $message)
   Procesa un mensaje entrante y decide si el bot debe responder.
   
   Lógica:
   - Verifica si el bot está activado
   - Comprueba si el usuario está siendo atendido por humano
   - Busca respuesta automática que coincida
   - Ejecuta lógica de menús si aplica
   - Envía respuesta si corresponde

2. findAutoResponse($message)
   Busca una respuesta automática que coincida con el mensaje.
   
   Retorna: Objeto con response_message o null

3. sendWelcomeMessage($userId)
   Envía el mensaje de bienvenida configurado.

4. isBusinessHours()
   Verifica si está dentro del horario de atención.
   
   Retorna: true si está en horario, false fuera de horario


MediaService.php
Servicio para gestión de archivos multimedia.

MÉTODOS PRINCIPALES:

1. downloadAndSaveMedia($mediaId, $userId)
   Descarga un media de WhatsApp y lo guarda localmente.
   
   Proceso:
   - Obtiene URL temporal del media
   - Descarga el contenido
   - Detecta tipo MIME
   - Genera nombre único
   - Guarda en carpeta correspondiente
   - Genera thumbnail para imágenes/videos
   - Actualiza registro en BD

2. generateThumbnail($imagePath, $maxWidth, $maxHeight)
   Genera un thumbnail para imágenes.

3. getMediaProxy($messageId)
   Obtiene URL proxy persistente para un media.


3.5. Server-Sent Events (SSE)
-------------------------------

El sistema usa SSE para notificaciones en tiempo real sin WebSockets.

FLUJO SSE:
1. Frontend se conecta a /api/sse_events.php
2. El backend mantiene la conexión HTTP abierta
3. Cuando hay un nuevo evento:
   a. Se guarda en Redis (canal: sse_notifications)
   b. worker.php o webhook.php publica evento en canal
4. sse_events.php lee de Redis y envía al cliente
5. Frontend recibe evento y actualiza UI
6. Conexión se mantiene viva con heartbeat cada 15s

TIPOS DE EVENTOS SSE:

1. new_message
   Nuevo mensaje recibido.
   
   Datos:
   {
     "type": "new_message",
     "user_id": 123,
     "message_id": "wamid.XXX",
     "content": "Hola",
     "direction": "incoming",
     "created_at": "2024-01-27 14:30:45"
   }

2. message_status
   Cambio de estado de mensaje.
   
   Datos:
   {
     "type": "message_status",
     "message_id": "wamid.XXX",
     "status": "read",
     "timestamp": "2024-01-27 14:31:00"
   }

3. conversation_update
   Actualización de conversación en lista.
   
   Datos:
   {
     "type": "conversation_update",
     "user_id": 123,
     "last_message": "Hola",
     "unread_count": 1
   }

4. notification
   Notificación general.
   
   Datos:
   {
     "type": "notification",
     "title": "Nuevo mensaje",
     "message": "Juan te ha enviado un mensaje",
     "severity": "info"
   }


================================================================================
4. API REST COMPLETA
================================================================================

AUTENTICACIÓN
-------------
Todos los endpoints (excepto webhook) requieren autenticación mediante 
sesión PHP.

Headers requeridos:
Cookie: PHPSESSID=abc123...

Respuesta de error de autenticación:
{
  "error": "Acceso denegado. Inicia sesión.",
  "code": 401
}


ENDPOINTS DE MENSAJERÍA
------------------------

POST /api/send_message.php
Envía un mensaje de texto individual.

Request Body:
{
  "recipient": "573001234567",
  "message": "Hola, este es un mensaje de prueba",
  "reply_to": "wamid.XXX"  // Opcional
}

Response Success:
{
  "success": true,
  "message_id": "wamid.HBgNNTczMDA...",
  "timestamp": "2024-01-27 14:35:20"
}

Response Error:
{
  "success": false,
  "error": "Recipient not on WhatsApp"
}


POST /api/send_template.php
Envía una plantilla de mensaje.

Request Body:
{
  "recipient": "573001234567",
  "template_name": "welcome_message",
  "language": "es",
  "parameters": {
    "body": ["Juan Pérez", "2024-01-27"],
    "header": []
  }
}

Response:
{
  "success": true,
  "message_id": "wamid.XXX..."
}


POST /api/send_media_message.php
Envía un mensaje multimedia.

Request Body:
{
  "recipient": "573001234567",
  "media_type": "image",
  "media_url": "https://ejemplo.com/imagen.jpg",
  "caption": "Mira esta imagen",
  "filename": "imagen.jpg"  // Requerido para documentos
}

Tipos de media: image, video, audio, document

Response:
{
  "success": true,
  "message_id": "wamid.XXX...",
  "media_id": "123456789"
}


POST /api/send_broadcast.php
Envía mensaje masivo.

Request Body:
{
  "message": "Hola a todos, este es un anuncio importante",
  "filter": "active",
  "template_name": null
}

Filtros disponibles:
- all: Todos los usuarios
- active: Usuarios activos (< 24h)
- inactive: Usuarios inactivos
- custom: Lista personalizada (requiere user_ids array)

Response:
{
  "success": true,
  "total_sent": 150,
  "failed": 2,
  "details": [
    {"phone": "573001234567", "status": "sent"},
    {"phone": "573009876543", "status": "failed", "error": "Not on WhatsApp"}
  ]
}


ENDPOINTS DE CONVERSACIONES
----------------------------

GET /api/get_conversations.php
Lista todas las conversaciones.

Query Params:
- page (int): Número de página (default: 1)
- limit (int): Conversaciones por página (default: 50, max: 100)
- filter (string): all | unread | active

Ejemplo:
GET /api/get_conversations.php?page=1&limit=20&filter=unread

Response:
{
  "success": true,
  "data": [
    {
      "user_id": 123,
      "name": "Juan Pérez",
      "phone_number": "573001234567",
      "last_message": "Hola, necesito ayuda",
      "last_message_time": "2024-01-27 14:30:45",
      "last_message_direction": "incoming",
      "unread_count": 2,
      "in_service": 1,
      "attended_by": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 98,
    "per_page": 20
  }
}


GET /api/get_user_messages.php
Obtiene mensajes de un usuario específico.

Query Params:
- user_id (int): ID del usuario (requerido)
- limit (int): Número de mensajes (default: 50)
- before (timestamp): Cargar mensajes anteriores (scroll infinito)

Ejemplo:
GET /api/get_user_messages.php?user_id=123&limit=50

Response:
{
  "success": true,
  "data": [
    {
      "id": 456,
      "message_id": "wamid.XXX",
      "user_id": 123,
      "content": "Hola, necesito ayuda",
      "direction": "incoming",
      "message_type": "text",
      "status": "read",
      "media_url": null,
      "local_file": null,
      "reply_to_message_id": null,
      "reaction_emoji": null,
      "created_at": "2024-01-27 14:30:45"
    }
  ],
  "has_more": true
}


POST /api/mark_conversation_read.php
Marca una conversación como leída.

Request Body:
{
  "user_id": 123
}

Response:
{
  "success": true,
  "message": "Conversación marcada como leída"
}


ENDPOINTS DE USUARIOS
----------------------

GET /api/get_users.php
Lista todos los usuarios.

Query Params:
- page (int): Número de página
- limit (int): Usuarios por página
- search (string): Buscar por nombre o teléfono

Response:
{
  "success": true,
  "data": [
    {
      "id": 123,
      "phone_number": "573001234567",
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "in_service": 1,
      "advisor_requested": 0,
      "last_message_at": "2024-01-27 14:30:45",
      "created_at": "2024-01-20 10:00:00"
    }
  ],
  "pagination": {...}
}


POST /api/update_user.php
Actualiza información de un usuario.

Request Body:
{
  "user_id": 123,
  "name": "Juan Pérez García",
  "email": "juan.perez@example.com"
}

Response:
{
  "success": true,
  "message": "Usuario actualizado correctamente"
}


DELETE /api/delete_user.php
Elimina un usuario y todo su historial.

Request Body:
{
  "user_id": 123
}

Response:
{
  "success": true,
  "message": "Usuario eliminado correctamente"
}


GET /api/export_users.php
Exporta usuarios a CSV.

Response: Archivo CSV descargable


ENDPOINTS DE MULTIMEDIA
------------------------

POST /api/upload_media.php
Sube un archivo multimedia.

Request: multipart/form-data
- file (file): Archivo a subir

Response:
{
  "success": true,
  "media_id": "123456789",
  "media_url": "https://graph.facebook.com/v22.0/123456789",
  "local_file": "uploads/images/20240127_143520_abc123.jpg",
  "mime_type": "image/jpeg",
  "file_size": 245678
}


GET /api/get_media.php
Obtiene URL temporal de un media de WhatsApp.

Query Params:
- id (string): Media ID de WhatsApp

Response:
{
  "success": true,
  "url": "https://lookaside.fbsbx.com/whatsapp_business/...",
  "mime_type": "image/jpeg",
  "file_size": 245678,
  "sha256": "abc123...",
  "expires_at": "2024-01-27 15:30:00"
}


ENDPOINTS DE PLANTILLAS
------------------------

GET /api/get_templates.php
Lista plantillas de mensaje.

Query Params:
- approved_only (0|1): Solo plantillas aprobadas
- limit (int): Límite de resultados

Response:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "template_name": "welcome_message",
      "language_code": "es",
      "category": "MARKETING",
      "body_text": "Hola {{1}}, bienvenido...",
      "status": "approved",
      "created_at": "2024-01-20 10:00:00"
    }
  ]
}


POST /api/save_template.php
Crea o actualiza una plantilla.

Request Body:
{
  "template_name": "new_template",
  "language_code": "es",
  "category": "MARKETING",
  "header_text": "Oferta Especial",
  "body_text": "Hola {{1}}, tenemos una oferta...",
  "footer_text": "Válido hasta fin de mes",
  "buttons": [
    {"type": "QUICK_REPLY", "text": "Me interesa"}
  ]
}

Response:
{
  "success": true,
  "template_id": 5,
  "message": "Plantilla creada. Pendiente de aprobación."
}


ENDPOINTS DE RESPUESTAS AUTOMÁTICAS
-------------------------------------

GET /api/get_autoresponses.php
Lista respuestas automáticas.

Response:
{
  "success": true,
  "data": [
    {
      "id": 1,
      "trigger_keywords": "hola,buenos días,hey",
      "response_message": "¡Hola! Bienvenido...",
      "is_active": 1,
      "priority": 1
    }
  ]
}


POST /api/save_autoresponse.php
Crea o actualiza respuesta automática.

Request Body:
{
  "id": null,
  "trigger_keywords": "precio,costo,cuanto cuesta",
  "response_message": "Nuestros precios varían...",
  "is_active": 1,
  "priority": 5
}

Response:
{
  "success": true,
  "id": 3,
  "message": "Respuesta automática guardada"
}


ENDPOINTS DE ESTADÍSTICAS
---------------------------

GET /api/get_stats.php
Obtiene estadísticas del dashboard.

Response:
{
  "success": true,
  "data": {
    "total_users": 1250,
    "messages_received_24h": 340,
    "messages_sent_24h": 285,
    "active_conversations": 45,
    "messages_by_hour": [
      {"hour": "00:00", "incoming": 5, "outgoing": 2},
      ...
    ],
    "messages_by_day": [
      {"date": "2024-01-21", "incoming": 120, "outgoing": 95},
      ...
    ],
    "top_users": [
      {"user_id": 123, "name": "Juan Pérez", "message_count": 45}
    ]
  }
}


ENDPOINT DE WEBHOOK
-------------------

POST /api/webhook.php
Recibe eventos de WhatsApp Business API.

Verificación (GET):
GET /api/webhook.php?hub.mode=subscribe&hub.challenge=123456&hub.verify_token=token

Response: 123456 (echo del challenge)

Eventos recibidos (POST):

Nuevo mensaje:
{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "messages": [{
          "from": "573001234567",
          "id": "wamid.XXX",
          "timestamp": "1706367000",
          "type": "text",
          "text": {
            "body": "Hola, necesito ayuda"
          }
        }]
      }
    }]
  }]
}

Estado de mensaje:
{
  "entry": [{
    "changes": [{
      "value": {
        "statuses": [{
          "id": "wamid.XXX",
          "status": "read",
          "timestamp": "1706367100",
          "recipient_id": "573001234567"
        }]
      }
    }]
  }]
}

Tipos de status:
- sent: Enviado
- delivered: Entregado
- read: Leído
- failed: Fallido


ENDPOINTS SSE
-------------

GET /api/sse_events.php
Conexión de Server-Sent Events para notificaciones en tiempo real.

Headers:
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Eventos enviados:
event: message
data: {"type":"new_message","user_id":123,"content":"Hola"}

event: heartbeat
data: {"timestamp":"2024-01-27 14:35:00"}


CÓDIGOS DE ESTADO HTTP
-----------------------

Código    Significado
------------------------------------------------------------------------
200       Éxito
201       Creado
400       Petición inválida
401       No autenticado
403       Sin permisos
404       No encontrado
405       Método no permitido
429       Demasiadas peticiones (rate limit)
500       Error del servidor
503       Servicio no disponible


================================================================================
5. GUÍA DE IMPLEMENTACIÓN
================================================================================

5.1. Instalación desde Cero
-----------------------------

REQUISITOS DEL SERVIDOR
------------------------

Mínimos:
- CPU: 2 cores
- RAM: 4 GB
- Disco: 20 GB SSD
- SO: Ubuntu 22.04 LTS, Debian 11+, CentOS 8+

Recomendados para producción:
- CPU: 4+ cores
- RAM: 8+ GB
- Disco: 50+ GB SSD
- SO: Ubuntu 22.04 LTS


OPCIÓN 1: Docker (Recomendado)
-------------------------------

1. Instalar Docker y Docker Compose

Ubuntu/Debian:
sudo apt update
sudo apt install -y docker.io docker-compose

Verificar instalación:
docker --version
docker-compose --version

2. Clonar Repositorio

git clone https://github.com/tu-usuario/whatsapp.git
cd whatsapp

3. Configurar Variables de Entorno

cp .env.example .env
nano .env

Editar .env:
# Base de datos
DB_HOST=db
DB_PORT=3306
DB_NAME=whatsapp_bot
DB_USER=whatsapp_user
DB_PASS=tu_password_seguro

# WhatsApp Business API
WHATSAPP_TOKEN=tu_access_token
WHATSAPP_PHONE_ID=tu_phone_id
WHATSAPP_BUSINESS_ACCOUNT_ID=tu_business_account_id
WHATSAPP_APP_ID=tu_app_id
WHATSAPP_APP_SECRET=tu_app_secret

# Webhook
WEBHOOK_VERIFY_TOKEN=tu_token_verificacion_webhook

# Sistema
APP_ENV=production
APP_DEBUG=false
APP_TIMEZONE=America/Bogota

4. Levantar Contenedores

Desarrollo:
docker-compose -f docker-compose.dev.yml up -d

Producción:
docker-compose -f docker-compose.prod.yml up -d

5. Verificar Estado

docker-compose ps

Deberías ver:
NAME                    STATUS
whatsapp-app            Up
whatsapp-db             Up
whatsapp-redis          Up
whatsapp-worker         Up
whatsapp-nginx          Up

6. Acceder a la Aplicación

App: http://tu-servidor:8080 (dev) o http://tu-dominio (prod)
phpMyAdmin: http://tu-servidor:8084 (dev)

7. Configurar en el Panel

1. Accede con las credenciales por defecto:
   Usuario: admin
   Password: password123
2. Cambia la contraseña inmediatamente
3. Ve a Configuración > WhatsApp API y completa los datos
4. Verifica la configuración


OPCIÓN 2: Instalación Manual
------------------------------

1. Instalar Stack LAMP

Ubuntu 22.04:
sudo apt update
sudo apt install -y apache2 mariadb-server php8.2 php8.2-mysql \
  php8.2-curl php8.2-mbstring php8.2-xml php8.2-gd php8.2-zip \
  php8.2-redis redis-server

Verificar PHP:
php -v

2. Configurar MariaDB

sudo mysql_secure_installation

Crear base de datos:
sudo mysql -u root -p

SQL:
CREATE DATABASE whatsapp_bot CHARACTER SET utf8mb4 
  COLLATE utf8mb4_unicode_ci;
CREATE USER 'whatsapp_user'@'localhost' 
  IDENTIFIED BY 'tu_password_seguro';
GRANT ALL PRIVILEGES ON whatsapp_bot.* 
  TO 'whatsapp_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

3. Clonar y Configurar Aplicación

cd /var/www/html
sudo git clone https://github.com/tu-usuario/whatsapp.git
cd whatsapp

Permisos:
sudo chown -R www-data:www-data /var/www/html/whatsapp
sudo chmod -R 755 /var/www/html/whatsapp
sudo chmod -R 777 /var/www/html/whatsapp/uploads
sudo chmod -R 777 /var/www/html/whatsapp/logs

Configurar .env:
cp .env.example .env
sudo nano .env

4. Importar Base de Datos

mysql -u whatsapp_user -p whatsapp_bot < \
  database/migrations/001_initial_schema.sql
mysql -u whatsapp_user -p whatsapp_bot < \
  database/migrations/002_add_media_fields.sql

5. Configurar Apache

sudo nano /etc/apache2/sites-available/whatsapp.conf

Contenido:
<VirtualHost *:80>
    ServerName tudominio.com
    DocumentRoot /var/www/html/whatsapp

    <Directory /var/www/html/whatsapp>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/whatsapp_error.log
    CustomLog ${APACHE_LOG_DIR}/whatsapp_access.log combined
</VirtualHost>

Habilitar sitio:
sudo a2ensite whatsapp.conf
sudo a2enmod rewrite
sudo systemctl restart apache2

6. Configurar SSL con Let's Encrypt

sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d tudominio.com

7. Configurar Worker (Supervisor)

sudo apt install -y supervisor
sudo cp supervisor-whatsapp-worker.conf \
  /etc/supervisor/conf.d/whatsapp-worker.conf
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start whatsapp-worker:*

8. Configurar Cron Jobs

sudo crontab -e

Agregar:
# Limpiar logs antiguos (diario a las 3am)
0 3 * * * cd /var/www/html/whatsapp && \
  php scripts/clean_old_logs.php

# Backup de base de datos (diario a las 2am)
0 2 * * * /usr/bin/mysqldump -u whatsapp_user \
  -p'tu_password' whatsapp_bot > \
  /var/www/html/whatsapp/database/backups/backup_$(date +\%Y\%m\%d_\%H\%M\%S).sql

# Limpiar backups antiguos (mantener últimos 7 días)
0 4 * * * find /var/www/html/whatsapp/database/backups \
  -name "backup_*.sql" -mtime +7 -delete


5.2. Configuración de Producción
----------------------------------

OPTIMIZACIÓN DE PHP
-------------------

Editar /etc/php/8.2/apache2/php.ini:

memory_limit = 256M
post_max_size = 100M
upload_max_filesize = 100M
max_execution_time = 300
max_input_time = 300

; Para SSE (Server-Sent Events)
output_buffering = Off
implicit_flush = On

; Seguridad
expose_php = Off
display_errors = Off
log_errors = On
error_log = /var/log/php/error.log

; Zona horaria
date.timezone = America/Bogota


OPTIMIZACIÓN DE MariaDB
------------------------

Editar /etc/mysql/mariadb.conf.d/50-server.cnf:

[mysqld]
# Memoria
innodb_buffer_pool_size = 2G
innodb_log_file_size = 256M

# Conexiones
max_connections = 200

# Charset
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

# Logs
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow-query.log
long_query_time = 2

# Índices
innodb_flush_log_at_trx_commit = 2
innodb_flush_method = O_DIRECT

Reiniciar:
sudo systemctl restart mariadb


FIREWALL
--------

UFW (Ubuntu):
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status


MONITOREO
---------

Instalar Monit:
sudo apt install -y monit
sudo nano /etc/monit/monitrc

Configurar:
set daemon 60
set logfile /var/log/monit.log

check process apache2 with pidfile /var/run/apache2/apache2.pid
    start program = "/usr/sbin/service apache2 start"
    stop program = "/usr/sbin/service apache2 stop"
    if failed host localhost port 80 protocol http then restart
    if 5 restarts within 5 cycles then timeout

check process mysql with pidfile /var/run/mysqld/mysqld.pid
    start program = "/usr/sbin/service mysql start"
    stop program = "/usr/sbin/service mysql stop"
    if failed host localhost port 3306 protocol mysql then restart
    if 5 restarts within 5 cycles then timeout

check process redis with pidfile /var/run/redis/redis-server.pid
    start program = "/usr/sbin/service redis-server start"
    stop program = "/usr/sbin/service redis-server stop"
    if failed host localhost port 6379 protocol redis then restart

Iniciar:
sudo systemctl enable monit
sudo systemctl start monit


5.3. Actualización del Sistema
--------------------------------

PROCESO DE ACTUALIZACIÓN
-------------------------

1. Backup completo
./scripts/backup_all.sh

2. Modo mantenimiento
touch maintenance.lock

3. Actualizar código
git pull origin main

4. Ejecutar migraciones
php scripts/run_migrations.php

5. Limpiar cache
php scripts/clear_cache.php

6. Reiniciar servicios
sudo systemctl restart apache2
sudo supervisorctl restart whatsapp-worker:*

7. Verificar funcionamiento
php scripts/check_health.php

8. Desactivar modo mantenimiento
rm maintenance.lock


================================================================================
6. CASOS DE USO
================================================================================

CASO 1: Atención al Cliente Automatizada
------------------------------------------

Escenario: Una empresa de e-commerce quiere automatizar respuestas a 
preguntas frecuentes.

Implementación:
1. Configurar respuestas automáticas con triggers específicos
2. Crear menú interactivo de opciones principales
3. Configurar horario de atención para transferencia a humano
4. Resultado: Reducción de 70% en consultas repetitivas


CASO 2: Campañas de Marketing
-------------------------------

Escenario: Lanzamiento de nueva colección, enviar anuncio a clientes activos.

Implementación:
1. Crear plantilla en Meta con variables dinámicas
2. Enviar broadcast con filtro de usuarios activos
3. Seguimiento de métricas (enviados, leídos, interacciones)
4. Resultado: 300% ROI, 36% tasa de apertura, 9% conversión


CASO 3: Soporte Técnico con Tickets
-------------------------------------

Escenario: Empresa de software que recibe consultas técnicas.

Implementación:
1. Crear sistema de tickets automático
2. Escalamiento automático según palabras clave
3. Vinculación de respuestas a tickets
4. Sistema de calificación de servicio
5. Resultado: Tiempo de respuesta 15 minutos, satisfacción 4.5/5


CASO 4: Reservas y Citas
--------------------------

Escenario: Clínica médica permite agendar citas por WhatsApp.

Implementación:
1. Menú de especialidades
2. Sistema de calendario con disponibilidad
3. Confirmación automática de citas
4. Recordatorios 24h antes
5. Resultado: 80% de citas agendadas fuera de horario


CASO 5: Encuestas y Feedback
------------------------------

Escenario: Recopilar feedback post-compra.

Implementación:
1. Envío automático de encuesta 24h después de compra
2. Procesamiento inteligente de respuestas
3. Escalamiento de casos negativos
4. Dashboard de resultados y análisis
5. Resultado: 350 respuestas en 1 semana, NPS de 72


================================================================================
7. ENTREGABLES DEL PROYECTO
================================================================================

1. CÓDIGO FUENTE COMPLETO
   - Código PHP backend (42 APIs, servicios, clases)
   - Frontend (HTML, CSS, JavaScript)
   - Configuración Docker (dev y prod)
   - Scripts SQL (esquema, migraciones)
   - Tests automatizados

2. DOCUMENTACIÓN COMPLETA
   - README.md
   - DOCUMENTACION_COMPLETA.md (este documento)
   - REPORTE_SISTEMA_COMPLETO.md
   - DEPLOYMENT_GUIDE.md
   - DOCKER_README.md
   - SSE_REALTIME_DOCS.md
   - API_REFERENCE.md

3. BASE DE DATOS
   - Esquema completo (schema_complete.sql)
   - Migraciones ordenadas
   - Scripts de mantenimiento

4. CONFIGURACIÓN DE SERVIDOR
   - Nginx configuration
   - Apache vhost configuration
   - Supervisor configuration
   - Cron jobs

5. SCRIPTS DE UTILIDAD
   - install.php (Instalador interactivo)
   - run_migrations.php
   - clean_old_logs.php
   - backup_database.sh
   - restore_backup.sh
   - check_health.php
   - test_whatsapp_connection.php
   - generate_report.php

6. TESTS AUTOMATIZADOS
   - Tests unitarios
   - Tests de integración
   - Coverage reports

7. DOCKER COMPOSE
   - docker-compose.dev.yml (Desarrollo)
   - docker-compose.prod.yml (Producción)

8. MANUALES DE USUARIO
   - Manual de usuario final (PDF)
   - Manual de administrador (PDF)

9. VIDEO TUTORIALES
   - Instalación y configuración inicial (15 min)
   - Configurar WhatsApp Business API (10 min)
   - Gestión de conversaciones (8 min)
   - Crear respuestas automáticas (7 min)
   - Enviar mensajes masivos (6 min)
   - Crear plantillas de WhatsApp (12 min)
   - Administración de usuarios (5 min)
   - Interpretar estadísticas (8 min)
   - Solución de problemas comunes (10 min)
   - Actualización del sistema (7 min)

10. LICENCIA Y GARANTÍA
    - 30 días de soporte post-entrega
    - Corrección de bugs sin costo
    - Actualizaciones de seguridad durante 1 año
    - Consultoría técnica (10 horas incluidas)

11. ACCESOS Y CREDENCIALES
    - Credenciales de admin por defecto
    - Accesos a servidor (SSH)
    - Credenciales de base de datos
    - Tokens de WhatsApp Business API

12. CHECKLIST DE ENTREGA
    - Pre-Entrega
    - Entrega
    - Post-Entrega


================================================================================
8. MANTENIMIENTO Y SOPORTE
================================================================================

8.1. Tareas de Mantenimiento
------------------------------

DIARIO (Automatizado)
----------------------
1. Backup de base de datos (2:00 AM, retención 7 días)
2. Limpieza de logs (3:00 AM, retención 30 días)
3. Verificación de salud (cada hora)

SEMANAL
-------
1. Optimización de base de datos
2. Revisión de logs de error
3. Actualización de dependencias

MENSUAL
-------
1. Auditoría de seguridad
2. Análisis de uso y optimización
3. Backup completo


8.2. Monitoreo
---------------

MÉTRICAS CLAVE
--------------
Métrica              Umbral    Acción
------------------------------------------------------------------------
CPU > 80%            5 min     Escalar recursos
RAM > 90%            5 min     Revisar memory leaks
Disco > 85%          -         Limpiar archivos antiguos
Respuesta API > 2s   -         Optimizar queries
Errores > 10/min     -         Investigar logs


8.3. Solución de Problemas Comunes
------------------------------------

1. MENSAJES NO SE ENVÍAN
Síntomas: API retorna error 401 o 403
Solución:
- Verificar token de acceso
- Regenerar token si expiró
- Verificar permisos del token en Meta

2. WEBHOOK NO RECIBE EVENTOS
Síntomas: No llegan mensajes nuevos
Solución:
- Verificar URL del webhook en Meta
- Revisar logs de webhook
- Verificar suscripción a eventos
- Probar manualmente con curl

3. SSE NO FUNCIONA
Síntomas: No hay notificaciones en tiempo real
Solución:
- Verificar que Redis esté corriendo
- Revisar configuración PHP (output_buffering=Off)
- Verificar soporte SSE en navegador
- Revisar logs del navegador

4. MULTIMEDIA NO SE DESCARGA
Síntomas: Imágenes/videos no se muestran
Solución:
- Verificar permisos de carpeta uploads/
- Verificar espacio en disco
- Revisar logs de descarga
- Verificar permisos del token

5. ALTO USO DE CPU/RAM
Síntomas: Sistema lento, timeouts
Solución:
- Identificar procesos pesados con top
- Optimizar consultas lentas
- Aumentar recursos del servidor
- Activar cache (Redis/Memcached)
- Optimizar tablas de base de datos


8.4. Contacto de Soporte
--------------------------

Desarrollado por: U-Site.app

Canales de soporte:
- Email: soporte@u-site.app
- WhatsApp: +57 XXX XXX XXXX
- Portal: https://u-site.app/soporte
- Telegram: @usiteapp_soporte

Horario de soporte:
- Lunes a Viernes: 9:00 AM - 6:00 PM (GMT-5)
- Emergencias críticas: 24/7 (solo clientes premium)

Niveles de soporte:
- Básico (incluido): Email, respuesta en 24-48h
- Estándar: Email + WhatsApp, respuesta en 12h
- Premium: Email + WhatsApp + Teléfono, respuesta en 2h, atención 24/7


================================================================================
LICENCIA
================================================================================

© 2024-2026 U-Site.app. Todos los derechos reservados.

Este software es propiedad de U-Site.app y está protegido por las leyes 
de derechos de autor.

Permisos:
- Uso en producción para el cliente que adquirió la licencia
- Modificaciones para uso interno
- Despliegue en múltiples instancias del mismo cliente

Prohibido:
- Redistribución del código fuente
- Reventa o sublicencia
- Uso en proyectos de terceros sin autorización

Para consultas sobre licenciamiento, contacta: licencias@u-site.app


================================================================================
CONCLUSIÓN
================================================================================

Este sistema de WhatsApp Bot Manager representa una solución completa y 
profesional para gestión de comunicaciones empresariales vía WhatsApp Business.

CARACTERÍSTICAS DESTACADAS:
- 42 endpoints API REST documentados
- Interfaz moderna y responsive
- Tiempo real con SSE
- Bot inteligente y configurable
- Soporte multimedia completo
- Seguridad robusta
- Docker ready
- Escalable y mantenible

CASOS DE USO VALIDADOS:
- Atención al cliente automatizada
- Campañas de marketing masivas
- Soporte técnico con tickets
- Reservas y citas
- Encuestas y feedback

PRÓXIMOS PASOS SUGERIDOS:
1. Revisar la documentación completa
2. Seguir la guía de instalación
3. Configurar WhatsApp Business API
4. Personalizar respuestas automáticas
5. Capacitar al equipo
6. Lanzar en producción
7. Monitorear y optimizar

¿Necesitas ayuda? Contacta al equipo de U-Site.app:

Website: u-site.app
Email: contacto@u-site.app
WhatsApp: +57 XXX XXX XXXX


================================================================================
Desarrollado con amor por U-Site.app
Simplificando la comunicación empresarial
================================================================================
