# Agente de Seguimiento Comercial — Track Mar (PHP 7.0)

Reescritura en PHP 7.0 de la version original en Python (`../agente_seguimiento/`),
a pedido de Osvaldo el 2026-09-08, para correr en el mismo stack que el
sistema propio de Track Mar ("Utopia"). La version Python queda como
referencia de todo lo ya validado contra datos reales — la logica de
negocio es la misma en los dos lados, portada 1 a 1.

Diseño completo, decisiones y justificación de cada regla en
`Agente_Seguimiento_Comercial_TrackMar.docx` y en los comentarios de cada
archivo (especialmente `config.php` sección 2 y `db.php`).

## Regla de oro

**Este código nunca escribe en la base de Utopia.** Todas las consultas en
`db.php` son `SELECT`. El resultado de las respuestas de los clientes queda
en el registro propio del agente (`registro.php`, CSV), no en
`AGENDA_COTIZACIONES` — el vendedor lo carga a mano como hace hoy. Si en
algún momento se decide que el agente sí escriba en Utopia, es una decisión
aparte a confirmar explícitamente antes de tocar `db.php`.

## Compatibilidad PHP 7.0

Escrito deliberadamente sin sintaxis de PHP 7.1+: nada de `?tipo` nullable,
`void` como tipo de retorno, `list()` con claves, `catch (A | B $e)`,
propiedades tipadas, etc. Sin dependencias externas (no requiere Composer):
usa `PDO` (mysql), `curl`, y un cliente SMTP mínimo escrito a mano
(`fsockopen` + `STARTTLS` + `AUTH LOGIN`) en `reportes.php`.

Extensiones de PHP necesarias: `pdo_mysql`, `curl`, `openssl` (para el
STARTTLS del SMTP), `json` (viene por defecto).

**No se probó localmente** (no hay PHP en esta máquina) — revisar antes de
correr en producción. Para un chequeo rápido de sintaxis en cualquier
entorno con PHP:

```bash
for f in *.php; do php -l "$f"; done
```

## Archivos

| Archivo | Qué hace |
|---|---|
| `config.php` | Conexión a la base, umbrales, WhatsApp, SMTP, piloto, destinatarios, botones de respuesta rápida |
| `db.php` | Consultas de solo lectura a Utopia (PDO) |
| `reglas.php` | Reglas de negocio puras |
| `whatsapp.php` | Envío de plantillas y de texto libre interno vía WhatsApp Business API (Meta Cloud API), con modo dry-run |
| `reportes.php` | Arma y manda la alerta diaria y el resumen semanal por email |
| `registro.php` | Trazabilidad de acciones (CSV), anti-duplicados, y relación mensaje-enviado ↔ cotización |
| `main.php` | Orquestador batch: `--modo diario` / `--modo semanal` (cron / Task Scheduler) |
| `webhook.php` | Receptor de respuestas del cliente por WhatsApp — necesita correr detrás de un servidor web real, no por CLI (ver más abajo) |

## Uso — `main.php` (batch diario/semanal)

```bash
cp .env.example .env   # completar con los datos reales

# Modo de prueba (no manda nada real, solo registra en registro_acciones.csv)
php main.php --modo diario --dry-run

# Producción, una vez validado el modo de prueba
php main.php --modo diario
php main.php --modo semanal
```

Programar `--modo diario` todos los días hábiles y `--modo semanal` una vez
por semana (cron o Task Scheduler).

## Uso — `webhook.php` (respuestas de clientes en tiempo real)

A diferencia de `main.php`, este archivo necesita un **servidor web
siempre encendido** con una URL pública HTTPS — Meta (o el BSP elegido) le
manda un POST cada vez que un cliente responde. No se ejecuta por CLI ni
por tarea programada.

Para probarlo local sin instalar Apache/Nginx, el servidor embebido de PHP
alcanza:

```bash
php -S localhost:8080
# la URL del webhook seria http://localhost:8080/webhook.php
# (para que Meta la pueda llamar de verdad hace falta HTTPS publico -
# tunel tipo ngrok para pruebas, o el servidor real para produccion)
```

Configurar en Meta Business Manager (o en la consola del BSP):
- **Callback URL**: `https://.../webhook.php`
- **Verify token**: el mismo valor que `WHATSAPP_VERIFY_TOKEN` en `.env`

### Flujo de respuesta del cliente (confirmado con Osvaldo 2026-09-08)

Las 3 plantillas de Eje 1 llevan botones de respuesta rápida fijos
(`config::botones_cotizacion()`): *"Quiero avanzar"* / *"Necesito ajustar
algo"* / *"Ya no me interesa"*. El agente **no conversa con IA** — solo
rutea:

- Botón tocado → aviso al **encargado de la sucursal** por WhatsApp interno,
  con urgencia distinta según el botón.
- Texto libre (el cliente no tocó ningún botón) → se reenvía tal cual al
  encargado, sin interpretarlo.
- Nada de esto se escribe en Utopia — solo en el registro propio del agente.

### ⚠️ Pendiente de confirmar con Osvaldo

**A quién avisar cuando la sucursal no tiene ningún encargado.** El
encargado se identifica como el empleado de `EMPLEADOS` con `CARGO` que
contiene "ENCARGAD" (cubre ENCARGADO/ENCARGADA), activo, de esa sucursal —
pero relevado el 2026-09-08 contra la base de prueba, **solo 10 de ~17
sucursales reales tienen alguien con ese cargo**. Faltan: Córdoba,
Comodoro, Buenos Aires, Charata, San Juan, Olavarría, Venta Telefónica,
Jujuy, Santiago del Estero, Bahía Blanca, La Pampa, Mar del Plata (algunas,
como Charata u Olavarría, en realidad SÍ tienen encargado pero cubriendo
varias sucursales — el título del cargo lo dice, pero `EMPLEADOS.SUCURSAL`
solo apunta a una).

Mientras se define, `webhook.php` usa un **default de seguridad temporal**:
si no hay encargado con celular cargado, avisa por **email** a
`SUCURSALES.EMAIL_ALERTA` (el mismo canal que ya usa la alerta diaria) en
vez de perder la respuesta del cliente. Si no hay ni encargado ni email
válido, queda registrado como `sin_encargado_ni_email` en el CSV para
poder auditar los casos que se cayeron. **Esto no reemplaza la decisión
real** — ver `_rutear_al_encargado()` en `webhook.php`.

## Antes de correrlo con datos reales

Falta lo mismo que en la versión Python (ver sección 9 del documento
`.docx`, checklist de prerrequisitos), más lo específico de esta iteración:

1. Elegir proveedor de WhatsApp Business API (Meta directo vs BSP) —
   pendiente.
2. Enviar las 3 plantillas de Eje 1 a aprobación de Meta (texto ya
   definido con Osvaldo, ver `config.php` — falta decidir tono final).
3. Resolver la pregunta abierta de arriba (encargado sin cargo asignado).
4. Completar `.env` con credenciales reales de WhatsApp y SMTP.
5. Desplegar `webhook.php` detrás de un servidor con HTTPS público.
6. Completar `DESTINATARIOS_GERENCIALES` en `config.php` (Diego Starosta,
   Sebastián).