# 🔍 DIAGNÓSTICO COMPLETO: AgendaPro → Siigo
## Análisis Arquitectónico de Integración

---

## 📊 ESTADO ACTUAL (Revisión del Código)

### ✅ LO QUE ESTÁ IMPLEMENTADO

1. **Arquitectura correcta**:
   - ✅ Sistema de webhooks (recepción de eventos)
   - ✅ Cola de trabajos con reintentos exponenciales
   - ✅ Idempotencia (evita duplicados)
   - ✅ HTTP logging completo
   - ✅ Mapeo de clientes AgendaPro ↔ Siigo
   - ✅ Sincronización de clientes
   - ✅ Sincronización de pagos
   - ✅ Creación de facturas
   - ✅ Creación de recibos de caja

2. **APIs correctamente implementadas**:
   - ✅ AgendaPro API v1 con Basic Auth
   - ✅ Siigo API v1 con POST /auth
   - ✅ Partner-Id header configurado
   - ✅ Idempotency-Key para reintentos

3. **Base de datos bien diseñada**:
   - ✅ `clients_map` - mapeo AgendaPro ↔ Siigo
   - ✅ `queue_jobs` - cola de trabajos
   - ✅ `idempotency_keys` - prevención duplicados
   - ✅ `http_logs` - trazabilidad completa
   - ✅ `agendapro_events` - eventos recibidos

---

## ❌ PROBLEMA REAL IDENTIFICADO

### **LA INTEGRACIÓN NO ESTÁ EJECUTÁNDOSE**

Analizando el dump SQL (`u418271893_kanelaspa.sql`):

```sql
-- Tabla: agendapro_events - 0 registros ❌
-- Tabla: queue_jobs - 0 registros ❌
-- Tabla: http_logs - 0 registros ❌
-- Tabla: clients_map - 0 registros ❌
```

**CONCLUSIÓN**: El middleware **NUNCA HA PROCESADO EVENTOS**.

---

## 🔴 CAUSAS RAÍZ DEL PROBLEMA

### 1. **Webhook NO configurado en AgendaPro**

El webhook debe configurarse en AgendaPro apuntando a:
```
https://knelaspa.mch.com.co/index.php?route=webhook/agendapro
```

**Cómo verificar**:
- Panel AgendaPro → Integraciones → Webhooks
- Debe haber una URL configurada apuntando a tu servidor
- Debe estar **activo**

### 2. **Worker Cron NO está ejecutándose**

El worker (`src/queue/Worker.php`) procesa los jobs encolados, pero necesita:

```bash
# DEBE ejecutarse cada minuto
* * * * * curl -s "https://knelaspa.mch.com.co/index.php?route=cron/worker&secret=TU_SECRET" > /dev/null
```

**Sin esto**, los eventos quedan en la cola SIN PROCESAR.

### 3. **Falta de validación inicial**

No hay pruebas manuales que confirmen:
- ¿Las credenciales de AgendaPro funcionan?
- ¿Las credenciales de Siigo funcionan?
- ¿Se puede crear un cliente en Siigo manualmente?

---

## 🏗️ ARQUITECTURA CORRECTA (Tu código ya la tiene)

```
┌─────────────────────────────────────────────────────────────────┐
│                        FLUJO COMPLETO                           │
└─────────────────────────────────────────────────────────────────┘

1️⃣ EVENTO EN AGENDAPRO
   ↓
   Cliente creado → Webhook dispara POST a tu middleware

2️⃣ RECEPCIÓN (index.php?route=webhook/agendapro)
   ↓
   - Guarda evento en agendapro_events
   - Encola job en queue_jobs
   - Responde 200 OK inmediatamente

3️⃣ PROCESAMIENTO ASÍNCRONO (Worker - cron cada 1min)
   ↓
   - Toma job de la cola
   - Ejecuta SyncClients::syncByAgendaProClientId()
   - Consulta cliente en AgendaPro API
   - Verifica si existe en clients_map
   - Si NO existe → crea en Siigo
   - Guarda mapeo en clients_map
   - Marca job como "done"

4️⃣ RESULTADO
   ↓
   Cliente existe en Siigo con mismo ID mapeado
```

**Para pagos/abonos**:

```
1️⃣ Pago registrado en AgendaPro
   ↓
2️⃣ Webhook → queue_jobs (type: sync_payment)
   ↓
3️⃣ Worker ejecuta SyncPayments::processPaymentPayload()
   ↓
4️⃣ Verifica cliente existe (si no, lo crea)
   ↓
5️⃣ Crea Recibo de Caja en Siigo con:
   - Cliente asociado
   - Valor del abono
   - Medio de pago (cash/card/transfer)
   - Fecha
   ↓
6️⃣ Resultado: Recibo visible en Siigo
```

---

## 🔧 SOLUCIÓN PASO A PASO

### FASE 1: VALIDAR CREDENCIALES

Ejecuta el script de prueba que crearé: `test_integracion.php`

Este validará:
- ✅ Conexión a AgendaPro API
- ✅ Conexión a Siigo API
- ✅ Listar clientes de AgendaPro
- ✅ Crear cliente de prueba en Siigo

### FASE 2: CONFIGURAR WEBHOOK

1. **En AgendaPro**:
   - Ve a: Panel → Configuración → Integraciones → Webhooks
   - URL: `https://knelaspa.mch.com.co/index.php?route=webhook/agendapro`
   - Eventos: `client.created`, `payment.created`, `booking.created`
   - Basic Auth (opcional):
     - User: `mediacodehouse_webhook`
     - Pass: `generar_password_seguro_aqui`
   - Guardar y **activar**

2. **Actualizar .env** si usas Basic Auth:
   ```env
   AGENDAPRO_WEBHOOK_USER=mediacodehouse_webhook
   AGENDAPRO_WEBHOOK_PASS=tu_password_aqui
   ```

### FASE 3: CONFIGURAR CRON

1. **En Hostinger cPanel**:
   - Cron Jobs → Crear nuevo
   - Frecuencia: `* * * * *` (cada minuto)
   - Comando:
   ```bash
   /usr/bin/php /home/u418271893/public_html/index.php route=cron/worker secret=TU_SECRET_AQUI
   ```
   
2. **Actualizar .env**:
   ```env
   CRON_SECRET=generar_password_largo_aqui
   ```

### FASE 4: PROBAR FLUJO COMPLETO

1. **Trigger manual**:
   - Ejecuta: `php test_flujo_completo.php` (lo crearé)
   - Esto simula un evento de AgendaPro
   - Verifica que se encola el job
   - Ejecuta el worker manualmente
   - Verifica creación en Siigo

2. **Trigger real**:
   - Crea un cliente en AgendaPro
   - Espera 1 minuto (cron)
   - Verifica en monitor.php que:
     - Aparece evento en `agendapro_events`
     - Aparece job en `queue_jobs`
     - Job cambia a status `done`
     - Cliente aparece en `clients_map`
     - HTTP log muestra request a Siigo

---

## 🔍 PUNTOS DE VALIDACIÓN

### Checkpoint 1: Webhook recibe eventos
```sql
SELECT * FROM agendapro_events ORDER BY id DESC LIMIT 10;
```
**Debe haber registros** después de crear algo en AgendaPro.

### Checkpoint 2: Jobs se encolan
```sql
SELECT * FROM queue_jobs ORDER BY id DESC LIMIT 10;
```
**Debe haber jobs** con status `pending`.

### Checkpoint 3: Worker procesa
```sql
SELECT * FROM queue_jobs WHERE status='done' ORDER BY id DESC LIMIT 10;
```
**Debe haber jobs** con status `done`.

### Checkpoint 4: HTTP requests a Siigo
```sql
SELECT * FROM http_logs WHERE target='siigo' ORDER BY id DESC LIMIT 10;
```
**Debe haber requests** con status_code 200/201.

### Checkpoint 5: Clientes mapeados
```sql
SELECT * FROM clients_map ORDER BY last_sync DESC LIMIT 10;
```
**Debe haber mapeos** con IDs de ambos sistemas.

---

## 🚨 ERRORES COMUNES Y SOLUCIONES

### Error 1: "Token Siigo expirado"
**Causa**: Token guardado en `settings` está vencido.
**Solución**: Borrar token de BD, se renovará automáticamente:
```sql
DELETE FROM settings WHERE k = 'SIIGO_ACCESS_TOKEN';
```

### Error 2: "Cliente sin documento de identidad"
**Causa**: Siigo requiere `identification` obligatorio.
**Solución**: En AgendaPro, asegurar que clientes tengan RUT/CC/NIT.

### Error 3: "Item no encontrado en Siigo"
**Causa**: El SKU del servicio no existe en Siigo.
**Solución**: Crear productos en Siigo o mapear en `package_map`:
```sql
INSERT INTO package_map (agendapro_plan_id, siigo_item_code, siigo_item_name) 
VALUES (123, 'SERV001', 'Servicio Spa Facial');
```

### Error 4: "Jobs quedan en status pending"
**Causa**: Worker no se ejecuta (cron no configurado).
**Solución**: Verificar cron en cPanel → Cron Jobs.

### Error 5: "Recibo sin cliente asociado"
**Causa**: Cliente no existe en Siigo antes de crear recibo.
**Solución**: El código ya lo maneja automáticamente (`SyncPayments::processPaymentPayload()` línea 61-70).

---

## 📈 MÉTRICAS DE ÉXITO

### KPIs a monitorear en `monitor.php`:

1. **Eventos recibidos**: `agendapro_events` → debe incrementar
2. **Jobs procesados**: `queue_jobs.status='done'` → debe crecer
3. **Errores**: `queue_jobs.status='failed'` → debe ser < 5%
4. **Dead letter**: `queue_jobs.status='dead'` → investigar y reencolar
5. **HTTP 2xx**: `http_logs.status_code=200-299` → debe ser > 95%

---

## 🛠️ HERRAMIENTAS DE DEBUG

### Ver últimos eventos
```sql
SELECT id, received_at, resource_type, `trigger`, auth_ok, processed 
FROM agendapro_events 
ORDER BY id DESC LIMIT 20;
```

### Ver últimos jobs
```sql
SELECT id, job_type, status, attempts, last_error, created_at 
FROM queue_jobs 
ORDER BY id DESC LIMIT 20;
```

### Ver últimos requests a Siigo
```sql
SELECT id, created_at, method, url, status_code, duration_ms, error 
FROM http_logs 
WHERE target='siigo' 
ORDER BY id DESC LIMIT 20;
```

### Reencolar job muerto
```sql
UPDATE queue_jobs 
SET status='pending', attempts=0, next_run_at=NOW(), locked_by=NULL 
WHERE id=123;
```

---

## ✅ CHECKLIST FINAL

- [ ] Credenciales AgendaPro funcionan (test_integracion.php)
- [ ] Credenciales Siigo funcionan (test_integracion.php)
- [ ] Webhook configurado en AgendaPro
- [ ] Webhook responde 200 OK (probar con Postman)
- [ ] Cron worker configurado en cPanel
- [ ] Cron ejecutándose cada minuto
- [ ] Crear cliente en AgendaPro
- [ ] Verificar evento en `agendapro_events`
- [ ] Verificar job en `queue_jobs`
- [ ] Verificar job status='done'
- [ ] Verificar cliente en Siigo panel
- [ ] Verificar mapeo en `clients_map`
- [ ] Crear pago en AgendaPro
- [ ] Verificar Recibo de Caja en Siigo

---

## 🎯 RESULTADO ESPERADO

Después de implementar todo:

1. **Crear cliente "Juan Pérez" en AgendaPro**
   - Nombre: Juan Pérez
   - Email: juan@ejemplo.com
   - CC: 1234567890
   
2. **Verificar en Siigo**:
   - Panel Siigo → Terceros → Buscar "Juan Pérez"
   - Debe aparecer con:
     - Nombre: Juan Pérez
     - Email: juan@ejemplo.com
     - Identificación: 1234567890
     - Tipo: Cliente

3. **Crear pago de $50.000 en AgendaPro**:
   - Cliente: Juan Pérez
   - Servicio: Masaje Relajante
   - Valor: $50.000
   - Método: Efectivo

4. **Verificar en Siigo**:
   - Panel Siigo → Recibos de Caja
   - Debe aparecer:
     - Cliente: Juan Pérez
     - Valor: $50.000
     - Medio de pago: Efectivo
     - Fecha: Hoy
     - Estado: Aplicado

---

## 🚀 SIGUIENTE: Ejecutar Scripts de Diagnóstico

Ahora crearé:
1. `test_integracion.php` - Validar credenciales APIs
2. `test_flujo_completo.php` - Simular evento completo
3. `test_webhook.php` - Probar recepción webhook

Luego podrás ejecutar y diagnosticar exactamente dónde está el problema.