# INTERLINK WhatsApp v2.8.1 — hotfix de comprobantes

## Problema confirmado

La versión v2.8 convirtió la validación automática de imágenes en una condición bloqueante. Aunque la conversación estuviera en `payment_waiting_receipt` y el asistente acabara de pedir el comprobante, una falla de Meta/OpenAI, una confianza baja o un falso negativo en la cuenta destino producía `media_received_not_receipt` y no creaba el registro pendiente.

Eso no demostraba que al comprobante le faltaran datos. Solo demostraba que la validación automática no había alcanzado el criterio estricto en ese intento.

## Comportamiento corregido

- Cuando la conversación está explícitamente esperando un comprobante, toda imagen o documento recibido se registra en `wa2_payment_receipts` con estado `pending_review`.
- El archivo **no se acredita, no se imputa y no modifica el saldo**. Siempre queda sujeto a conciliación administrativa.
- La validación por Meta/OpenAI continúa como ayuda. Si extrae importe, fecha, referencia o confianza, esos valores quedan guardados como sugerencias para revisión.
- Si la validación automática falla, no coincide o lanza una excepción, el archivo igualmente queda pendiente cuando fue solicitado dentro del flujo de pago.
- Fuera de un flujo de pago, una imagen de soporte, instalación u otra consulta no se convierte automáticamente en comprobante.
- La coincidencia de cuenta destino ya no depende únicamente del booleano devuelto por la IA: también se comparan de forma determinística alias, CBU/CVU, CUIT y componentes del nombre del titular.

## Instalación

Este hotfix parte de la v2.8 ya instalada y no requiere migración SQL.

1. Hacer una copia de los archivos actuales:

```bash
cd /var/www/html/_inc
sudo cp -a whatsapp_v2 whatsapp_v2_backup_antes_v281
```

2. Extraer el ZIP del hotfix en la carpeta padre de `whatsapp_v2`:

```bash
cd /var/www/html/_inc
sudo unzip -o /ruta/interlink_whatsapp_v281_hotfix_comprobantes_2026-08-02.zip
```

3. Ajustar propietario y permisos según la instalación. Ejemplo con `www-data`:

```bash
sudo chown -R www-data:www-data /var/www/html/_inc/whatsapp_v2
sudo find /var/www/html/_inc/whatsapp_v2 -type d -exec chmod 755 {} \;
sudo find /var/www/html/_inc/whatsapp_v2 -type f -exec chmod 644 {} \;
```

4. Limpiar OPcache o reiniciar el servicio PHP/Apache que use el VPS. Ejemplos posibles:

```bash
sudo systemctl reload apache2
# o, si usa PHP-FPM, reiniciar la versión instalada:
# sudo systemctl restart php8.3-fpm
```

5. Ejecutar validaciones:

```bash
cd /var/www/html/_inc/whatsapp_v2
php -l app/ReceiptGuardService.php
php -l app/ConversationEngine.php
php tests/run_pure_tests.php .
python3 tests/run_static_checks.py .
```

6. Probar desde un número controlado:

- identificar una cuenta;
- escribir que se enviará un comprobante;
- confirmar que el estado sea `payment_waiting_receipt`;
- enviar una imagen válida;
- verificar que la respuesta sea `Comprobante recibido`;
- confirmar que se creó un registro `pending_review` en el panel **Comprobantes**.

7. Ejecutar, opcionalmente, `sql/wa2_v281_verify_receipts_read_only.sql`.

## Resultado esperado

La decisión debe ser `payment_receipt_received`, no `media_received_not_receipt`. En `decision_json` y `analysis_json` quedarán los campos:

- `receipt_guard_verified` o `guard_verified`;
- `receipt_guard_reason` o `guard_reason`;
- `queued_by_expected_payment_flow`;
- `requires_manual_review`.

`queued_by_expected_payment_flow = true` significa que la validación automática no fue concluyente, pero el comprobante se conservó porque el cliente estaba exactamente en el paso solicitado. No significa que el pago esté acreditado.

## Imagen rechazada antes de instalar el hotfix

El mensaje de la captura ya fue procesado como `media_received_not_receipt`; el hotfix no modifica retroactivamente decisiones existentes. Después de instalarlo, reenviar ese comprobante desde el número de prueba para generar el pendiente correcto.