# INTERLINK WhatsApp v2.8 — instalación controlada

Fecha del release: **1 de agosto de 2026**  
Base revisada: ZIP exacto de producción `whatsapp_v2(2).zip` + dump `interlink_crm (50).sql`.

## 1. Alcance de esta versión

La actualización corrige el comportamiento repetitivo o confuso sin reemplazar la integración existente con Meta Cloud API ni la estructura general del CRM.

Cambios principales:

- normalización UTF-8 defensiva antes de aplicar expresiones regulares;
- ampliación de expresiones coloquiales basada en mensajes reales del dump;
- continuidad de contexto para instalación, cobertura, pagos y traslados;
- interpretación contextual de nombres, DNI, domicilios, ubicaciones, selecciones y respuestas breves;
- selección explícita cuando un WhatsApp pertenece a más de una cuenta o servicio;
- soporte técnico por pasos, sin repetir pruebas ya realizadas;
- creación o reutilización de un ticket real antes de informar un número al cliente;
- respuestas operativas deterministas: la IA no reescribe saldos, pagos, incidentes, tickets, visitas ni pasos de soporte;
- imágenes y documentos solo se registran como comprobantes cuando el filtro valida que corresponden a una cuenta destino de INTERLINK;
- reacciones, stickers y contactos no generan respuestas innecesarias;
- logs del webhook sin payloads, mensajes, respuestas, teléfonos completos, query strings de verificación ni tokens;
- compatibilidad temporal de lectura para la API key heredada, pero bloqueo de nuevas escrituras en Base64;
- soporte para `OPENAI_API_KEY`, cifrado AES-256-GCM mediante `WA2_APP_KEY` y validación opcional de firma Meta mediante `WA2_META_APP_SECRET`.

La migración **no borra** conversaciones, mensajes, clientes, servicios, facturas, pagos, comprobantes, tickets ni conocimiento.

## 2. Paquetes

- `interlink_whatsapp_v28_produccion_patch_2026-08-01.zip`: actualización para aplicar sobre la versión exacta enviada.
- `interlink_whatsapp_v28_rollback_archivos_2026-08-01.zip`: restaura exactamente los archivos existentes que fueron reemplazados y elimina únicamente los archivos nuevos de v2.8.
- `INTERLINK_WA2_V28_MIGRACION_2026-08-01.sql`: copia externa de la migración incluida también dentro del módulo.
- `INTERLINK_WA2_V28_VERIFICAR_SOLO_LECTURA_2026-08-01.sql`: controles posteriores sin modificar datos.
- `INTERLINK_WA2_V28_ROLLBACK_SQL_2026-08-01.sql`: retira el marcador de migración, pero por seguridad mantiene desactivada la reescritura operativa por IA.

No aplicar el ZIP de actualización y el ZIP de rollback al mismo tiempo.

## 3. Identificar la carpeta correcta

El ZIP contiene la carpeta superior `whatsapp_v2/`. Debe extraerse en la carpeta **padre** del módulo real.

Ejemplos:

- módulo real `/var/www/html/_inc/whatsapp_v2` → extraer en `/var/www/html/_inc`;
- módulo real `/var/www/html/interlink_crm/whatsapp_v2` → extraer en `/var/www/html/interlink_crm`.

En los comandos siguientes, reemplazar `/RUTA/PADRE` por esa carpeta padre y `/RUTA/RELEASE` por el lugar donde se copiaron los archivos del release.

## 4. Copia de seguridad obligatoria

```bash
export WA2_PARENT=/RUTA/PADRE
export RELEASE_DIR=/RUTA/RELEASE
cd "$WA2_PARENT"

sudo cp -a whatsapp_v2 "whatsapp_v2_backup_2026-08-01_$(date +%H%M%S)"
mysqldump -u USUARIO_DB -p --single-transaction --routines --triggers interlink_crm \
  > "$HOME/interlink_crm_backup_2026-08-01.sql"
```

Comprobar que ambos respaldos existen antes de continuar.

## 5. Verificar integridad del release

Desde la carpeta del release:

```bash
cd "$RELEASE_DIR"
sha256sum -c SHA256SUMS_INTERLINK_WA2_V28_2026-08-01.txt
unzip -t interlink_whatsapp_v28_produccion_patch_2026-08-01.zip
unzip -t interlink_whatsapp_v28_rollback_archivos_2026-08-01.zip
```

Todos los controles deben indicar `OK`.

## 6. Aplicar la migración

```bash
mysql -u USUARIO_DB -p interlink_crm \
  < "$RELEASE_DIR/INTERLINK_WA2_V28_MIGRACION_2026-08-01.sql"
```

La migración es idempotente: puede ejecutarse nuevamente si la primera ejecución terminó de forma incierta.

## 7. Aplicar los archivos

```bash
cd "$WA2_PARENT"
sudo unzip -o "$RELEASE_DIR/interlink_whatsapp_v28_produccion_patch_2026-08-01.zip"
```

No copiar desde otra instalación los archivos `config/db.local.php`, `.env`, logs, comprobantes, uploads, media ni credenciales. El ZIP no contiene esos archivos.

## 8. Propietario y permisos

Usar el usuario real de Apache/PHP-FPM. En una instalación con `www-data`:

```bash
sudo chown -R www-data:www-data "$WA2_PARENT/whatsapp_v2"
sudo find "$WA2_PARENT/whatsapp_v2" -type d -exec chmod 755 {} \;
sudo find "$WA2_PARENT/whatsapp_v2" -type f -exec chmod 644 {} \;
sudo chmod 755 "$WA2_PARENT/whatsapp_v2/tests/run_static_checks.py"
```

No cambiar permisos a `777`.

## 9. Pruebas locales en el VPS

Estas pruebas no envían WhatsApp, no llaman a OpenAI y no modifican la base:

```bash
cd "$WA2_PARENT"
find whatsapp_v2 -name '*.php' -not -path '*/logs/*' -print0 \
  | xargs -0 -n1 php -l

php whatsapp_v2/tests/run_pure_tests.php whatsapp_v2
php whatsapp_v2/tests/run_training_catalog_checks.php whatsapp_v2
python3 whatsapp_v2/tests/run_static_checks.py whatsapp_v2
```

Luego ejecutar la verificación SQL:

```bash
mysql -u USUARIO_DB -p interlink_crm \
  < "$RELEASE_DIR/INTERLINK_WA2_V28_VERIFICAR_SOLO_LECTURA_2026-08-01.sql"
```

Resultados esperados:

- existe el marcador `wa2_v28_conversation_memory_security`;
- `operational_ai_refine_enabled = 0`;
- la clave aparece solo como estado (`legacy_base64_rotar`, `cifrada_aes_gcm` o `sin_clave_en_base`), nunca en texto;
- no hay errores SQL ni PHP.

## 10. Seguridad de OpenAI y Meta

El dump enviado contiene una clave OpenAI en el formato Base64 heredado. Base64 no es cifrado. Esa clave debe considerarse expuesta y rotarse.

Orden recomendado:

1. crear una nueva clave OpenAI y revocar la anterior;
2. configurar la nueva en el entorno del proceso PHP como `OPENAI_API_KEY`;
3. comprobar en `WhatsApp v2 → Configuración IA` que la fuente indicada sea `OPENAI_API_KEY`;
4. recién entonces retirar la clave heredada de la base.

Alternativa: definir una frase secreta larga como `WA2_APP_KEY` y guardar la nueva API key desde el panel; v2.8 la cifra con AES-256-GCM. Si `WA2_APP_KEY` cambia o desaparece, una clave cifrada con ella no podrá abrirse.

Para validar que los POST provienen de Meta, configurar el App Secret como `WA2_META_APP_SECRET` en el entorno de Apache/PHP-FPM. Mientras no exista esa variable, el webhook conserva compatibilidad con el funcionamiento actual.

La forma exacta de declarar variables depende de si el VPS usa Apache `mod_php`, PHP-FPM, systemd o contenedores. Deben quedar disponibles para el proceso web, no solamente para la terminal SSH.

## 11. Prueba controlada desde WhatsApp

Usar un número controlado y revisar cada respuesta en la bandeja:

1. saludo más falla: `Buenas noches, no me da internet`;
2. frase histórica: `no me anda en Internet`;
3. instalación en varios mensajes: solicitud, nombre/DNI, domicilio y confirmación breve;
4. traslado con dos servicios: enviar nueva dirección, elegir servicio y confirmar que la dirección se conserva;
5. WhatsApp compartido por dos clientes: verificar que el bot pide elegir y no muestra saldo de otra cuenta;
6. soporte de un solo dispositivo: confirmar que no abre un ticket de caída total;
7. imagen que no es comprobante: confirmar que no crea pendiente;
8. comprobante completo dirigido a INTERLINK: confirmar que crea un único pendiente de conciliación;
9. reacción o sticker: confirmar que no responde;
10. ticket: confirmar en la tabla/panel que el ticket existe antes de que el bot informe su número.

No habilitar una prueba masiva hasta completar estos casos.

## 12. Reversión de archivos

```bash
cd "$WA2_PARENT"
sudo unzip -o "$RELEASE_DIR/interlink_whatsapp_v28_rollback_archivos_2026-08-01.zip"
sudo bash "$WA2_PARENT/whatsapp_v2/tools/rollback_v28_remove_new_files.sh"
```

Después, si se desea quitar el marcador SQL:

```bash
mysql -u USUARIO_DB -p interlink_crm \
  < "$RELEASE_DIR/INTERLINK_WA2_V28_ROLLBACK_SQL_2026-08-01.sql"
```

El rollback SQL mantiene `operational_ai_refine_enabled = 0` de manera intencional. No vuelve a activar el comportamiento que generaba respuestas operativas variables.

## 13. Límites de la validación realizada fuera del VPS

Se comprobó el código, el dump, la sintaxis PHP, los catálogos, la regresión histórica, la integridad de los ZIP y la reversión simulada. En este entorno no se conectó a MariaDB, Meta ni OpenAI reales, no se enviaron mensajes y no se crearon tickets o comprobantes en producción. La validación viva final debe hacerse en el VPS con el procedimiento anterior.