# 📱 MANUAL DE INTEGRACIÓN Y ARQUITECTURA: BOT DE WHATSAPP CON IA - POSCLOUD V12

> **Módulo 100% Independiente:**  
> Ubicado en `app/WhatsAppBot/`, `config/whatsapp.php` y `routes/whatsapp.php`.  
> Diseñado para vender de forma autónoma por WhatsApp con comportamiento humano, audios y fotos de recetas médicas.

---

## 🏗️ 1. ESTRUCTURA INDEPENDIENTE DEL MÓDULO

```text
c:\xampp\htdocs\Admin_PosCloud_V12\
├── app/
│   ├── WhatsAppBot/
│   │   ├── Controllers/
│   │   │   └── WhatsAppWebhookController.php   # Recibe mensajes, audios y fotos de WhatsApp 24/7
│   │   └── Services/
│   │       ├── WhatsAppAIService.php           # Cerebro IA: Function Calling + Cotizaciones
│   │       ├── WhatsAppAudioService.php        # Transcripción de notas de voz con OpenAI Whisper
│   │       ├── WhatsAppVisionService.php       # Lectura de recetas médicas con Gemini/GPT-4o
│   │       └── WhatsAppSenderService.php       # Envío y simulación humana de "Escribiendo..."
│   └── Http/Controllers/
│       └── WhatsAppApiController.php           # Endpoints REST de catálogo, cliente y cotización
├── config/
│   └── whatsapp.php                            # Configuración de Evolution API, tokens e IA
└── routes/
    └── whatsapp.php                            # Rutas dedicadas e independientes de WhatsApp
```

---

## 🧭 2. FLUJO DE ATENCIÓN MULTIMODAL (TEXTO, AUDIO Y FOTOS)

```mermaid
sequenceDiagram
    autonumber
    actor Cliente as 👤 Cliente (WhatsApp)
    participant Evo as 📲 Evolution API / WhatsApp
    participant Webhook as ⚡ WhatsAppWebhookController
    participant Audio as 🎙️ WhatsAppAudioService (Whisper)
    participant Vision as 📷 WhatsAppVisionService (Gemini Vision)
    participant IA as 🧠 WhatsAppAIService + PosCloud Tools
    participant POS as 🏢 Cotizaciones del POS

    alt Cliente envía Nota de Voz (Audio)
        Cliente->>Evo: Envía nota de voz (.ogg)
        Evo->>Webhook: Dispara Webhook con audio
        Webhook->>Audio: Transcribe audio con Whisper
        Audio-->>Webhook: "Me manda 2 cajas de acetaminofén a la calle 45"
    else Cliente envía Foto de Receta / Empaque
        Cliente->>Evo: Envía foto de la fórmula médica
        Evo->>Webhook: Dispara Webhook con imagen
        Webhook->>Vision: Analiza receta con Gemini Vision
        Vision-->>Webhook: "Medicamentos: Amoxicilina 500mg"
    else Cliente envía Texto Normal
        Cliente->>Evo: "Hola, ¿a cómo está el Dolex?"
        Evo->>Webhook: Dispara Webhook con texto
    end

    Webhook->>IA: Procesa mensaje con herramientas del POS
    IA->>POS: Consulta inventario y precios reales (Caja y Fracción)
    IA->>POS: Guarda el pedido en la tabla 'cotizacion' (WA-...)
    IA-->>Webhook: Genera respuesta empática con el No. Cotización
    Webhook->>Evo: Simula "Escribiendo..." (2 seg) y despacha mensaje
    Evo-->>Cliente: "¡Hola Mariana! Con gusto, tu pedido WA-260827201500 ya quedó registrado por $ 30.000 COP."
```

---

## ⚡ 3. CONFIGURACIÓN DEL WEBHOOK EN EVOLUTION API

En el panel de Evolution API, en tu instancia de WhatsApp:

1. **URL del Webhook:**  
   `https://tu-dominio-poscloud.com/api/whatsapp/webhook?token=TU_TOKEN_PRIVADO`
2. **Eventos a habilitar:**  
   ✅ `MESSAGES_UPSERT` (Recepción de mensajes entrantes)
3. **Autenticación Multi-Tienda:**  
   Puedes usar una instancia por cada tienda/sucursal (`pasto_jhoana`, `drogas_mas_salud`), y el sistema conectará dinámicamente a la base de datos de esa sucursal según `config/whatsapp.php`.

---

## 📋 4. ENDPOINTS REST DISPONIBLES EN `routes/whatsapp.php`

| Método | Endpoint | ¿Para qué sirve? |
| :---: | :--- | :--- |
| `GET` / `POST` | `/api/whatsapp/webhook` | **Webhook en Vivo**: Recibe textos, audios y fotos de clientes. |
| `GET` | `/api/whatsapp/productos` | **Catálogo Ligero**: Precios al público, fracción, stock y promociones. |
| `GET` | `/api/whatsapp/cliente` | **Identificar Cliente**: Busca por celular o cédula. |
| `POST` | `/api/whatsapp/cliente` | **Guardar Cliente**: Registra o actualiza dirección de entrega. |
| `POST` | `/api/whatsapp/pedido` | **Crear Pedido**: Asienta la venta en la tabla `cotizacion` con código `WA-...`. |
| `GET` | `/api/whatsapp/pedido/{numero}` | **Consultar Estado**: Revisa detalle y total de una cotización. |