# PLUGIN_INDEX.md — Índice Maestro
> Plugin: **siip-whatsapp-notifications** | Versión actual: ver `manifest.json`
> Este archivo es el punto de entrada para cualquier agente IA que trabaje en este plugin.

---

## 🧭 Guía rápida: ¿Qué índice leer?

| Tarea | Índices a leer | Tokens est. |
|---|---|---|
| Modificar lógica de hooks UCRM | `INDEX_plugin.md` + `INDEX_deps.md` | ~4,500 |
| Agregar/modificar endpoint en el portal web | `INDEX_public.md` | ~3,000 |
| Modificar módulo Stripe del portal | `INDEX_public.md` + leer `views/stripe.php` directamente | ~3,500 |
| Modificar módulo OXXO del portal | `INDEX_public.md` + leer `views/oxxo.php` directamente | ~3,500 |
| Nueva feature que usa API UCRM | `INDEX_api_used.md` + `INDEX_api_ucrm.md` | ~3,500 |
| Nueva feature que usa API UNMS | `INDEX_api_used.md` + `INDEX_api_unms.md` | ~5,000 |
| Bug en llamada API existente | `INDEX_api_used.md` solo | ~1,500 |
| Modificar notificaciones WhatsApp | `INDEX_deps.md` (sección Facades) | ~2,000 |
| Cambiar flujo de pago OXXO/Stripe | `INDEX_plugin.md` + `INDEX_deps.md` | ~4,500 |

> ⚡ **Tip:** Después de leer el índice correspondiente, usa `StartLine/EndLine` para leer solo el fragmento del archivo fuente que necesitas modificar, en lugar de leer el archivo completo.

---

## 📁 Estructura del Plugin

```
siip-whatsapp-notifications/
│
├── 📄 public.php          (2978 líneas) — Portal web + endpoint HTTP público
├── 📄 src/Plugin.php      (672 líneas)  — Entry point de hooks UCRM
│
├── src/
│   ├── Facade/
│   │   ├── AbstractMessageNotifierFacade.php  — Base notificaciones WhatsApp
│   │   ├── AbstractStripeOperationsFacade.php — Lógica Stripe + registro pagos UCRM
│   │   ├── AbstractOxxoOperationsFacade.php   — Lógica OXXO Pay + vouchers
│   │   ├── PluginNotifierFacade.php           — Facade principal (extiende Stripe)
│   │   ├── PluginOxxoNotifierFacade.php       — Facade OXXO
│   │   ├── TwilioNotifierFacade.php           — Legacy Twilio
│   │   └── ClientCallBellAPI.php              — Cliente Callbell (81KB)
│   │
│   ├── Service/
│   │   ├── PaymentIntentService.php   — Stripe SDK: PIs, historial, balance
│   │   ├── SmsNumberProvider.php      — Extrae teléfonos WhatsApp de contactos UCRM
│   │   ├── Logger.php                 — PSR-3 logger
│   │   ├── OptionsManager.php         — Carga config → PluginData
│   │   ├── MinioStorageService.php    — Sube vouchers a MinIO
│   │   ├── CurlExecutor.php           — Wrapper cURL
│   │   └── PluginDataValidator.php    — Valida configuración
│   │
│   ├── Data/
│   │   ├── PluginData.php             — DTO config del plugin
│   │   ├── NotificationData.php       — DTO payload webhook UCRM
│   │   └── UcrmData.php               — Base DTO
│   │
│   └── Factory/
│       ├── NotificationDataFactory.php — Construye NotificationData desde JSON
│       └── MessageTextFactory.php      — Genera textos de mensajes WhatsApp
│
├── views/
│   ├── stripe.php   (17KB) — HTML+JS del módulo Stripe del portal
│   └── oxxo.php     (12KB) — HTML+JS del módulo OXXO del portal
│
├── scripts-uisp/    — Scripts auxiliares UNMS (audit_client_passwords.php, etc.)
├── data/            — config.json, logs, ordenes OXXO
├── vendor/          — Dependencias Composer
├── img/             — Imágenes del portal (logos, íconos)
└── vouchers_oxxo/   — Vouchers OXXO generados
```

---

## 📚 Archivos de Índice

| Archivo | Describe | Tamaño |
|---|---|---|
| [`INDEX_plugin.md`](INDEX_plugin.md) | `src/Plugin.php`: flujos, eventos UCRM, UUIDs de métodos de pago | ~5KB |
| [`INDEX_public.md`](INDEX_public.md) | `public.php`: todos los endpoints, acciones JS, módulos UI | ~6KB |
| [`INDEX_deps.md`](INDEX_deps.md) | Facades y Services: firmas de métodos y propósito | ~7KB |
| [`INDEX_api_used.md`](INDEX_api_used.md) | Todas las llamadas API reales que hace el plugin | ~4KB |
| [`INDEX_api_ucrm.md`](INDEX_api_ucrm.md) | Catálogo de 162 endpoints UCRM CRM v1.0 | ~10KB |
| [`INDEX_api_unms.md`](INDEX_api_unms.md) | Catálogo de 560 endpoints UNMS NMS v2.1 | ~74KB |

---

## 🔧 Scripts de utilidad

| Script | Uso |
|---|---|
| `.agent/scripts/gen_index_unms_swagger.php` | `php gen_index_unms_swagger.php` — regenera `INDEX_api_unms.md` desde `unms-swagger.json` |
| `.agent/scripts/gen_index_ucrm_apib.php` | `php gen_index_ucrm_apib.php` — regenera `INDEX_api_ucrm.md` desde `unmscrm.apib` |

---

## ⚙️ Configuración del Plugin (claves en `data/config.json`)

| Clave | Tipo | Descripción |
|---|---|---|
| `ipserver` | string | IP/hostname del servidor UISP |
| `apitoken` | string | Token API UCRM |
| `unmsApiToken` | string | Token API UNMS/NMS |
| `tokencallbell` | string | Token API Callbell |
| `tokenstripe` | string | API Key Stripe |
| `ipPuppeteer` | string | IP microservicio Puppeteer para vouchers |
| `portPuppeteer` | string | Puerto microservicio Puppeteer |
| `idPaymentAdminCRM` | string | ID admin UCRM para registrar pagos |
| `installersDataWhatsApp` | JSON string | `{"instaladores":[{id, nombre, whatsapp}]}` |
| `notificationTypeText` | bool | `true`=texto plano, `false`=plantilla Callbell |
| `debugMode` | bool | Activa logging DEBUG |
| `cashPaymentMethodId` | bool | Habilitar notif. efectivo |
| `bankTransferPaymentMethodId` | bool | Habilitar notif. transferencia bancaria |
| `oxxoPayPaymentMethodId` | bool | Habilitar notif. OXXO |
| `creditCardStripePaymentMethodId` | bool | Habilitar notif. tarjeta Stripe |
| *(más métodos de pago)* | bool | Ver `PluginData.php` para lista completa |

---

## 🔄 Flujos principales resumidos

### Flujo: Pago registrado en UCRM
```
UCRM → POST public.php (uuid presente) → Plugin::run() → processHttpRequest()
→ NotificationDataFactory::getObject() → event: payment.add
→ switch(methodId) → notifierFacade::verifyPaymentActionToDo()
→ SmsNumberProvider::getUcrmClientNumbers() → ClientCallBellAPI::sendPaymentNotificationWhatsApp()
```

### Flujo: Transferencia bancaria Stripe (SPEI)
```
Stripe → POST public.php (type: customer_cash_balance_transaction.created → funded)
→ Plugin::run() → pluginNotifierFacade::createPaymentIntent()
→ AbstractStripeOperationsFacade: crea PI en Stripe + registra pago en UCRM
```

### Flujo: Solicitud OXXO Pay
```
Bot/Cliente → POST public.php (type: oxxo.request)
→ Plugin::run() → pluginOxxoNotifierFacade::createStripeReference()
→ createOxxoOrder() → responde inmediatamente → fastcgi_finish_request()
→ [background] generateOxxoVoucher() → Puppeteer → MinIO
```

### Flujo: Tarea de Instalador
```
UCRM → POST public.php (uuid, event: job.edit, status 0→1)
→ notifierFacade::verifyJobActionToDo()
→ ClientCallBellAPI: notifica cliente + técnico vía WhatsApp
→ PATCH job title en UCRM (remueve/actualiza prefijo [NOTIFICACION-PENDIENTE])
```

### Flujo: Obtener Password Antena
```
UCRM client.edit + tag "OBTENER PASSWORD ANTENA" agregado
→ Plugin::processHttpRequest() → pluginNotifierFacade::processClientPasswordAntenna()
→ AbstractMessageNotifierFacade::getVaultCredentialsByClientId()
→ UNMS GET devices?siteId → GET vault/{id}/credentials
→ UCRM PATCH clients/{id} (atributo passwordAntenaCliente)
→ removeTagFromClient("OBTENER PASSWORD ANTENA")
```