161 lines
7.5 KiB
Markdown
Executable File
161 lines
7.5 KiB
Markdown
Executable File
# 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")
|
|
```
|