231 lines
12 KiB
Markdown
Executable File
231 lines
12 KiB
Markdown
Executable File
# INDEX_deps.md — Facades y Services
|
||
> Firmas y propósito de todas las dependencias usadas por `public.php` y `Plugin.php`
|
||
|
||
---
|
||
|
||
## src/Facade/
|
||
|
||
### AbstractMessageNotifierFacade (abstract) — L.1–537
|
||
`src/Facade/AbstractMessageNotifierFacade.php`
|
||
Base de todas las facades. Maneja lógica de notificación via Callbell/WhatsApp.
|
||
|
||
**Constantes:**
|
||
- `SUBJECT_OF_INSTALLER_CHANGE[]` — textos para notificar cambio/desasignación de técnico
|
||
- `ADDITIONAL_CHANGE_DATA[]` — datos adicionales del cambio de técnico
|
||
|
||
**Constructor:** `(Logger, MessageTextFactory, SmsNumberProvider)` + carga `$ucrmApi` desde config
|
||
|
||
**Métodos públicos:**
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `verifyPaymentActionToDo(NotificationData): void` | Itera teléfonos por tipo (whatsapp/whatsnotifica/whatsactualiza) y llama notify/update |
|
||
| `verifyClientActionToDo(NotificationData): void` | Solo `onlyUpdate()` para tipos whatsapp/whatsactualiza |
|
||
| `verifyServiceActionToDo(NotificationData): void` | `onlyUpdateService()` para tipos whatsapp/whatsactualiza |
|
||
| `verifyJobActionToDo($jsonData, $reprog, $changeInstaller): void` | Notifica instalador anterior, cliente y técnico nuevo; gestiona título del job |
|
||
| `verifyInvoiceActionToDo(NotificationData): void` | `onlyUpdate()` sin mostrar balance |
|
||
| `notify(NotificationData, $phone): void` | Envía notificación de pago vía Callbell (texto o plantilla) |
|
||
| `notifyAndUpdate(NotificationData, $phone): void` | Notifica + hace PATCH en Callbell |
|
||
| `notifyOverDue(NotificationData): void` | Notifica factura vencida/por vencer |
|
||
| `onlyUpdate(NotificationData, $phone): void` | Solo actualiza contacto en Callbell (sin enviar mensaje) |
|
||
| `onlyUpdateService(NotificationData, $phone): void` | Actualiza status de servicio en Callbell |
|
||
|
||
**Métodos protegidos:**
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `getVaultCredentialsByClientId($clientId): string` | Obtiene pass de antena desde UNMS vault; sincroniza en CRM. Usa `GET /nms/api/v2.1/devices?siteId=` y `GET /nms/api/v2.1/vault/{deviceId}/credentials` |
|
||
| `syncPasswordWithCrm(int $clientId, string $pass): void` | PATCH atributo `passwordAntenaCliente` en CRM si difiere |
|
||
| `generateStrongPassword(int $length=16): string` | Genera contraseña segura (lower+upper+digits+@#) |
|
||
| `patchClientCustomAttribute(int $clientId, int $attributeId, string $value): bool` | PATCH `clients/{id}` con atributo custom |
|
||
| `comparePasswords(?string $crm, ?string $vault): string` | Prioriza vault, luego crm, luego mensaje de advertencia |
|
||
| `validarNumeroTelefono($n): string` | Normaliza teléfono a formato internacional 521XXXXXXXXXX |
|
||
|
||
**Abstracto:** `sendWhatsApp(NotificationData, string $phone): void`
|
||
|
||
---
|
||
|
||
### PluginNotifierFacade extends AbstractStripeOperationsFacade
|
||
`src/Facade/PluginNotifierFacade.php` — L.1–152
|
||
|
||
**Herencia:** `PluginNotifierFacade → AbstractStripeOperationsFacade → AbstractOxxoOperationsFacade → AbstractMessageNotifierFacade`
|
||
|
||
**Constructor:** `(Logger, MessageTextFactory, SmsNumberProvider, OptionsManager)` — carga `$pluginData`
|
||
|
||
**Métodos propios:**
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `updatePasswordAntenaIfNeeded(int $clientId, array $jsonData): void` | Llama `getVaultCredentialsByClientId()` — sincroniza pass antena |
|
||
| `processClientPasswordAntenna(int $clientId, array $clientEntity): void` | Procesa tag "OBTENER PASSWORD ANTENA": incluye `scripts-uisp/audit_client_passwords.php`, llama `fixClientData()`, remueve tag |
|
||
| `sendWhatsApp(NotificationData, string $phone): void` | Implementación mock (solo log) |
|
||
|
||
**Métodos heredados de AbstractStripeOperationsFacade** (ver abajo):
|
||
- `createPaymentIntent()`, `registerPaymentFromWebhook()`, `registerPaymentFromIntent()`
|
||
- `ensureStripePaymentAttribute()`, `createStripeClient()`, `syncStripeCustomerData()`
|
||
- `createClabeForClient()`, `removeTagFromClient()`
|
||
|
||
---
|
||
|
||
### AbstractStripeOperationsFacade (abstract)
|
||
`src/Facade/AbstractStripeOperationsFacade.php` — ~45KB
|
||
|
||
Hereda de `AbstractOxxoOperationsFacade`. Maneja toda la integración con Stripe y registro de pagos en UCRM.
|
||
|
||
**Métodos clave** (firmas aproximadas):
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `createPaymentIntent(array $jsonData): void` | Crea PaymentIntent en Stripe desde webhook `customer_cash_balance_transaction.funded` |
|
||
| `registerPaymentFromWebhook(array $jsonData): void` | Registra pago en UCRM desde webhook `applied_to_payment` |
|
||
| `registerPaymentFromIntent(array $piData): void` | Registra pago en UCRM desde `payment_intent.succeeded` |
|
||
| `ensureStripePaymentAttribute(NotificationData $n): void` | Determina si el pago Stripe es OXXO, Transferencia o Tarjeta revisando metadata |
|
||
| `createStripeClient(NotificationData $n, string $tag, bool $createClabe): void` | Crea cliente en Stripe + opcionalmente genera CLABE |
|
||
| `syncStripeCustomerData(int $clientId, string $name, ?string $email): void` | Actualiza nombre/email del customer en Stripe |
|
||
| `removeTagFromClient(int $clientId, string $tagName): void` | Elimina tag del cliente en UCRM |
|
||
|
||
---
|
||
|
||
### AbstractOxxoOperationsFacade (abstract)
|
||
`src/Facade/AbstractOxxoOperationsFacade.php` — ~31KB
|
||
|
||
Maneja la integración OXXO Pay con Stripe y generación de vouchers.
|
||
|
||
**Métodos clave:**
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `createStripeReference(array $jsonData, ?float $amount): array` | Crea PaymentIntent OXXO en Stripe. Retorna `{hasError, data:{oxxo_reference, url, clientID, clientFullName, amount}}` |
|
||
| `createOxxoOrder(array $oxxoData): array` | Guarda orden OXXO en storage local. Retorna `{order_id, oxxo_reference, url, ...}` |
|
||
| `generateOxxoVoucher(array $responseOxxo, bool $background): void` | Llama a Puppeteer para generar imagen del voucher y subirla a MinIO |
|
||
| `getOxxoOrderStatus(string $orderId): array` | Retorna estado actual de la orden OXXO |
|
||
| `createOxxoPaymentIntent(array $clientData, float $amount, bool $notify): array` | Flujo completo: crea PI Stripe OXXO + orden + voucher |
|
||
|
||
---
|
||
|
||
### PluginOxxoNotifierFacade extends AbstractOxxoOperationsFacade
|
||
`src/Facade/PluginOxxoNotifierFacade.php` — pequeño
|
||
|
||
Solo implementa los métodos abstractos. No agrega lógica propia relevante.
|
||
|
||
---
|
||
|
||
### TwilioNotifierFacade extends AbstractMessageNotifierFacade
|
||
`src/Facade/TwilioNotifierFacade.php` — ~2KB
|
||
|
||
Implementa `sendWhatsApp()` usando Twilio (legacy, en desuso). Métodos notificación estándar delegados a la clase base.
|
||
|
||
---
|
||
|
||
### ClientCallBellAPI
|
||
`src/Facade/ClientCallBellAPI.php` — ~81KB
|
||
|
||
Cliente completo de la API de Callbell. Usado internamente por las facades vía `new ClientCallBellAPI($apitoken, $ipserver, $tokencallbell)`.
|
||
|
||
**Métodos clave relevantes para el plugin:**
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `sendPaymentNotificationWhatsApp($phone, NotificationData): bool` | Envía plantilla de pago con template de Callbell |
|
||
| `sendTextPaymentNotificationWhatsApp($phone, NotificationData): bool` | Envía texto plano de pago |
|
||
| `sendOverdueNotificationWhatsApp($phone, NotificationData): bool` | Notificación de factura vencida |
|
||
| `sendJobNotificationWhatsAppToClient($phone, array $data, $reprog, $changeInst): bool` | Notificación de job al cliente |
|
||
| `sendJobNotificationWhatsAppToInstaller($phone, array $data, $reprog, $changeInst): void` | Notificación de job al técnico |
|
||
| `getContactWhatsapp($phone): string` | GET contacto en Callbell por teléfono → JSON |
|
||
| `patchWhatsapp(array $contact, NotificationData): void` | PATCH datos del contacto en Callbell |
|
||
| `patchServiceStatusWhatsApp(array $contact, NotificationData): void` | PATCH status de servicio en Callbell |
|
||
|
||
---
|
||
|
||
## src/Service/
|
||
|
||
### PaymentIntentService
|
||
`src/Service/PaymentIntentService.php` — 282 líneas
|
||
|
||
Usado directamente en `public.php` (no via DI). Constructor: `($ucrmApi, $stripeApiKey, $logger=null)`
|
||
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `searchClients($query): array` | UCRM `GET clients?query=q&limit=5` — retorna array simplificado |
|
||
| `getClientDetails($clientId): array` | UCRM `GET clients/{id}` — retorna datos + stripeCustomerId + clabeInterbancaria |
|
||
| `createPaymentIntent($clientId, $amount, $stripeCustomerId, $adminId): array` | Crea PI Stripe tipo `customer_balance/bank_transfer/mx_bank_transfer` |
|
||
| `getLastPayments($stripeCustomerId, $limit=10): array` | Stripe `paymentIntents.all` filtrado a bank_transfer — últimos N |
|
||
| `getLastOxxoPayments($stripeCustomerId, $limit=5): array` | Stripe `paymentIntents.all` filtrado a OXXO — últimos N |
|
||
| `getCustomerCashBalance($stripeCustomerId): float` | Stripe `customers.retrieveCashBalance` → MXN |
|
||
|
||
---
|
||
|
||
### SmsNumberProvider
|
||
`src/Service/SmsNumberProvider.php` — 160 líneas
|
||
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `getUcrmClientNumber(NotificationData): ?string` | Primer contacto con tipo aplicable al evento |
|
||
| `getUcrmClientNumbers(NotificationData?, array?): array` | Retorna `['whatsapp'=>[phones], 'whatsnotifica'=>[phones], 'whatsactualiza'=>[phones]]` |
|
||
| `getAllUcrmClientNumbers(array): array` | Todos los teléfonos del cliente sin filtrar por tipo |
|
||
|
||
**Tipos de contacto reconocidos:**
|
||
- `whatsapp` — recibe notificación + actualización en Callbell
|
||
- `whatsnotifica` — solo recibe notificación (no actualiza Callbell)
|
||
- `whatsactualiza` — solo actualiza Callbell (no notifica)
|
||
|
||
---
|
||
|
||
### Logger (`src/Service/Logger.php`)
|
||
Wrapper de PSR-3. Métodos: `debug()`, `info()`, `warning()`, `error()`. Nivel controlado por config `logging_level` / `debugMode`.
|
||
|
||
### OptionsManager (`src/Service/OptionsManager.php`)
|
||
Carga config del plugin. Método: `load(): PluginData`
|
||
|
||
### PluginDataValidator (`src/Service/PluginDataValidator.php`)
|
||
Valida que la configuración esté completa. Método: `validate(): bool`
|
||
|
||
### MinioStorageService (`src/Service/MinioStorageService.php`)
|
||
Sube vouchers OXXO a MinIO. Usado por `AbstractOxxoOperationsFacade`.
|
||
|
||
### CurlExecutor (`src/Service/CurlExecutor.php`)
|
||
Wrapper de cURL para la `UcrmApi` interna del plugin.
|
||
|
||
---
|
||
|
||
## src/Data/
|
||
|
||
### PluginData (extends UcrmData)
|
||
`src/Data/PluginData.php` — Propiedades de configuración del plugin:
|
||
|
||
| Propiedad | 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 del microservicio Puppeteer |
|
||
| `$portPuppeteer` | string | Puerto del microservicio Puppeteer |
|
||
| `$idPaymentAdminCRM` | string | ID admin para registrar pagos |
|
||
| `$cashPaymentMethodId` | bool | Habilitar notif. efectivo |
|
||
| `$courtesyPaymentMethodId` | bool | Habilitar notif. cortesía |
|
||
| `$bankTransferPaymentMethodId` | bool | Habilitar notif. transferencia |
|
||
| `$oxxoPayPaymentMethodId` | bool | Habilitar notif. OXXO |
|
||
| `$creditCardStripePaymentMethodId` | bool | Habilitar notif. tarjeta Stripe |
|
||
| `$stripeSubscriptionCreditCardPaymentMethodId` | bool | Habilitar notif. suscripción Stripe |
|
||
| `$notificationTypeText` | bool | true=texto plano, false=plantilla Callbell |
|
||
| `$installersDataWhatsApp` | string | JSON de instaladores |
|
||
| `$debugMode` | bool | Activa logging DEBUG |
|
||
| `$logging_level` | bool | Nivel verbose de log |
|
||
| `$twilioAccountSid` | string\|null | Legacy Twilio |
|
||
| `$twilioAuthToken` | string\|null | Legacy Twilio |
|
||
| `$twilioSmsNumber` | string\|null | Legacy Twilio |
|
||
|
||
### NotificationData
|
||
`src/Data/NotificationData.php`
|
||
DTO con propiedades: `$uuid`, `$changeType`, `$entity`, `$entityId`, `$eventName`, `$clientId`, `$clientData[]`, `$paymentData[]`, `$invoiceData[]`
|
||
|
||
---
|
||
|
||
## src/Factory/
|
||
|
||
### NotificationDataFactory
|
||
`src/Factory/NotificationDataFactory.php` — 5.8KB
|
||
| Método | Descripción |
|
||
|---|---|
|
||
| `getObject(array $jsonData): NotificationData` | Construye `NotificationData` desde el payload del webhook UCRM, cargando datos adicionales de la API |
|
||
|
||
### MessageTextFactory
|
||
`src/Factory/MessageTextFactory.php` — 3.7KB
|
||
Genera textos de mensajes WhatsApp. Usado por las facades para construir el contenido de notificaciones.
|