# ANÁLISIS DEL SISTEMA ACTUAL — Recarga.do / PagoExpress

**Fecha del análisis:** 2026-08-12
**Código auditado:** `/var/www/html/recargas/` (READ ONLY — no se modificó ningún archivo)
**Base de datos:** `recargas_2` en 104.197.163.89 (MySQL 5.6.51-google-log)

---

## 1. QUÉ ES RECARGA.DO

Plataforma dominicana de **recargas electrónicas y pago de servicios**, operando para República Dominicana y Haití. El motor interno se identifica como *PagoExpress* y actúa como capa intermedia entre los comercios afiliados y el agregador **MidasRed API 5.1** (`api5-prod06.midasred.com`), que es quien ejecuta las recargas reales contra las telcos y las empresas de servicios.

El modelo de negocio es **prepago multi-tenant**: cada comercio (`empresa`) mantiene un saldo depositado y lo consume al vender recargas. Recarga.do gana por comisión sobre cada operación.

Volumen actual verificado en producción:

| Métrica | Valor |
|---|---|
| Transacciones completadas | 43,123 (RD$ 5,527,395.94) |
| Transacciones fallidas | 4,839 |
| Transacciones anuladas | 467 |
| Empresas registradas | 368 (355 con API habilitada) |
| Clientes registrados | 265 |
| Servicios activos | 59 en 10 categorías |
| Tokens de API emitidos | 360 |

---

## 2. ARQUITECTURA ACTUAL

PHP plano sin framework, con una organización *MVC-like* incompleta.

```
Portal cliente (recarga.do/cliente)
        │  login_jwt.php?action=login  (api_key + api_secret)
        ▼
   JWT de 5 minutos
        │  <iframe src="index.php?token=JWT">
        ▼
/var/www/html/recargas/index.php   ← "el motor", 82 KB, valida el token inline
        │  $_SESSION['empresa_id']
        ▼
  api/*.php  (19 endpoints AJAX)
        │
        ├── models/     Transaction, Service, Package, Project
        ├── classes/    Database (Singleton PDO), MidasRedAPI, Logger, LimitValidator…
        ▼
   MidasRed API 5.1 (proveedor real, producción)
        ▼
   Telcos / distribuidoras eléctricas / acueductos
```

> **Aclaración para integradores.** El `<iframe>` del diagrama es cómo el **portal interno del
> sistema legado** monta su propia pantalla; **no** es el mecanismo de integración de terceros.
> La API v1 (`api.recarga.do`) se consume por **consulta directa REST**, sin iframe, sin
> redirección y sin SDK. Ver [GUIA-INTEGRACION.md](GUIA-INTEGRACION.md) y [API.md](API.md).

**Observación estructural:** `controllers/` y `views/` existen pero están **vacíos**. Las vistas están embebidas en archivos monolíticos (`index.php` 82 KB, `debug.php` 117 KB, `historial.php` 60 KB, `formulario.php` 50 KB) y los controladores son en realidad los scripts de `api/`.

---

## 3. STACK TECNOLÓGICO

| Componente | Detalle | Nota |
|---|---|---|
| Lenguaje | PHP (sin framework, sin Composer) | Autoload manual vía `spl_autoload_register` |
| Base de datos | MySQL **5.6.51** (Google Cloud SQL) | Sin CTE, sin funciones de ventana, sin tipo JSON nativo |
| Acceso a datos | PDO con patrón Singleton (`classes/Database.php`) | Sentencias preparadas — correcto |
| Frontend | HTML5 + CSS3 + jQuery | Sin build |
| Servidor | Apache 2 + mod_rewrite, PHP-FPM 8.4 | |
| Proveedor | MidasRed API 5.1 Producción v06 | Único proveedor |
| Autenticación | JWT propio, validado inline | Ver §7 |

**Restricción heredada importante:** MySQL 5.6 condiciona el diseño de la API nueva —no hay `JSON`, el límite de índice es 767 bytes con `utf8mb4`, y no existen CTEs para los reportes.

---

## 4. ESTRUCTURA DE CARPETAS

```
/var/www/html/recargas/            293 archivos (160 PHP, 52 MD, 19 JS)
├── api/          19 endpoints AJAX — la capa "controlador" real
├── classes/      10 clases núcleo (Database, MidasRedAPI, Logger, 5× JWT*, validadores)
├── models/       4 modelos (Transaction, Service, Package, Project)
├── helpers/      TokenHelper
├── config/       config.php (secretos), config.example.php, cors.php
├── database/     6 archivos .sql (schema + migraciones sueltas)
├── templates/    formularios por servicio
├── controllers/  VACÍO
├── views/        VACÍO
├── logs/ cache/ uploads/  (777)
└── ~40 archivos test_*.php / debug*.php / check_*.php en la raíz
```

**Deuda técnica visible:** ~40 scripts de prueba y diagnóstico conviven con el código de producción en la raíz servida por HTTP, y hay 52 documentos Markdown de cambios acumulados sin índice.

---

## 5. MÓDULOS Y FUNCIONALIDADES DESCUBIERTOS

| Módulo | Endpoint actual | Tablas | Estado |
|---|---|---|---|
| Recargas de balance | `api/process-recharge.php` | `transacciones`, `empresa_balances`, `servicios` | Núcleo del negocio |
| Paquetes de datos | `api/packages.php` + process-recharge | `paquetes`, `servicios` | 4 operadoras |
| Pago de facturas | `api/pay-invoice.php`, `get-invoices.php` | `transacciones` | Electricidad, agua |
| Reverso de facturas | `api/reverse-invoice.php` | `transacciones` | |
| Anulación de recargas | `api/reverse-transaction.php` | `transacciones` | 467 anuladas |
| Consulta de contrato | `api/check-contract.php` | — (pasa a proveedor) | Electricidad |
| Catálogo de servicios | `api/services.php` | `servicios`, `categorias` | 59 servicios |
| Historial | `api/get-transactions.php` | `transacciones` | |
| Recibos | `api/print-receipt.php` | `transacciones` | HTML imprimible |
| Estado de recarga | `api/check-recharge-status.php` | `transacciones` | |
| Límites y saldo | `api/check-limits.php` + `LimitValidator` | `empresa_balances` | |
| Conciliación | `api/conciliacion-volored.php`, `conciliacion.php` | `transacciones` | |
| Seguros vehiculares | `MidasRedAPI` (sin endpoint) | — | **Bloqueado**: lanza excepción |
| Autenticación | `login_jwt.php`, `index.php` | `jwt_tokens`, `api_tokens` | Ver §7 |
| WhatsApp | tablas `wa_*` (13 tablas) | `wa_mensajes`, `wa_config`… | Subsistema aparte |
| Proyectos / webhooks | `models/Project.php` | `proyectos`, `proyecto_webhook_logs` | 38,417 logs |

**Categorías de servicio reales:** Otros Servicios (19), Electricidad (10), Telefonía (7), Agua (5), Entretenimiento (5), Servicios Financieros (4), Paquetes de Datos (4), Internet & TV (3), Servicios Gubernamentales (1), Seguros (1).

> Existe una categoría corrupta `Telefon&iacute;a` (entidad HTML sin decodificar) con 0 servicios, duplicando a `Telefonía`.

---

## 6. BASE DE DATOS

83 tablas y 6 vistas. Detalle completo en [`database/schema.md`](database/schema.md).

**Tablas centrales:**

| Tabla | Filas | Función |
|---|---|---|
| `transacciones` | 48,151 | Registro maestro de operaciones |
| `empresas` | 368 | Comercios afiliados (tenants) |
| `empresa_balances` | 195 | Saldo, límites, tipo de crédito |
| `movimientos_balance` | 932 | Libro mayor — **incompleto**, ver auditoría M-02 |
| `api_tokens` | 360 | Credenciales de API por empresa |
| `jwt_tokens` | 2,555 | Sesiones del motor |
| `servicios` / `productos` / `paquetes` | 49 / 37 / 27 | Catálogo |
| `empresa_comisiones` | 2,759 | Comisiones por empresa |
| `empresa_producto_comision` | 2,174 | Comisiones por empresa+producto |
| `proyecto_webhook_logs` | 38,417 | Notificaciones salientes |
| `oauth_states` | 55,386 | Estados OAuth — **la tabla más grande, sin purga aparente** |

**Anomalías estructurales confirmadas:**
- `transacciones` es `utf8mb4`; `empresas`, `empresa_balances` y `movimientos_balance` son `utf8_unicode_ci` → los JOIN entre ellas convierten colación y descartan índices.
- El saldo vive duplicado en `empresas.saldo_actual` y `empresa_balances.saldo_actual`; **96 empresas ya divergen**.
- `transacciones` no tiene clave foránea hacia `empresas`; hay 166 filas con `empresa_id` NULL.
- La vista `v_transacciones_super_master` está rota (referencia objetos inexistentes).
- Hay 13 tablas completamente vacías (`api_credentials`, `refresh_tokens`, `jwt_blacklist`, `comisiones_calculadas`, `empresa_usuarios`…), residuo de funcionalidades planificadas y no implementadas.

---

## 7. AUTENTICACIÓN Y SESIONES

Coexisten **tres** mecanismos, lo que constituye la mayor fuente de confusión del sistema:

1. **JWT de portal** — `login_jwt.php` emite un JWT HMAC-SHA256 de 5 minutos a partir de `api_key`/`api_secret`. `index.php` lo canjea por una fila en `jwt_tokens` con vigencia de 7 días, deslizante en cada uso.
2. **Sesión PHP** — tras validar el token, `index.php` puebla `$_SESSION['empresa_id']`, que es lo que consultan los endpoints de `api/`.
3. **`api_tokens` (`api_key`/`api_secret`)** — 360 credenciales emitidas por empresa con tablas satélite de permisos, IPs y logs. **Es la infraestructura pensada para clientes externos y está infrautilizada**: solo existen 4 filas de permisos, todas con el valor `autenticacion`.

Las clases `classes/JWTValidator*.php` (5 variantes) **no las usa `index.php`**, que valida en línea. Son código muerto que aparenta seguridad.

`empresa_id` es la identidad efectiva de todo el sistema: determina saldo, catálogo, comisiones y permisos. **El token es la identidad; equivale a una credencial de pago.**

Ver los defectos asociados en [`SECURITY_AUDIT.md`](SECURITY_AUDIT.md) §C-01 y §A-04.

---

## 8. INTEGRACIÓN CON EL PROVEEDOR

**MidasRed API 5.1 Producción v06** — único proveedor, implementado en `classes/MidasRedAPI.php` (~1,140 líneas).

| Aspecto | Valor actual | Observación |
|---|---|---|
| URL | `https://api5-prod06.midasred.com` | Producción |
| Autenticación | usuario + contraseña + API key → token de 30 min | Renovación automática |
| Verificación TLS | **desactivada** (`CURLOPT_SSL_VERIFYPEER = false`) | Ver auditoría A-03 |
| Timeout de petición | **180 s** | Excesivo; induce reintentos |
| Timeout de conexión | 60 s | Excesivo |
| Reintentos | `makeRequest($…, $retryCount)` | Sin control de idempotencia |
| Código de éxito | `cod === '00'` | |

**Operaciones expuestas por el cliente:** recarga de balance, paquetes de datos, consulta de contrato, consulta y pago de facturas, reverso de factura, reverso de transacción, consulta de estado por `xid`, historial, catálogo de proveedores, y un bloque de seguros vehiculares (`getVehicleTypes`, `sellInsurance`, `reverseInsurance`…) que el flujo de recarga **rechaza explícitamente** por falta de interfaz.

---

## 9. FLUJO REAL DE UNA RECARGA

Reconstruido desde `api/process-recharge.php`:

```
 1. Leer parámetros (JSON o form-data)
 2. auth_guard  →  MODO OBSERVE: registra, NO bloquea          ⚠ C-01
 3. Tomar empresa_id y usuario_id DEL CUERPO de la petición    ⚠ C-01
 4. Validar servicio y rango de monto
 5. Validación de horario                                       ⚠ COMENTADA (M-03)
 6. LimitValidator: saldo disponible + límites diario/semanal/mensual (fail-closed)
 7. INSERT transacción en estado 'pendiente'
 8. Llamar a MidasRed (hasta 180 s)                             ⚠ sin idempotencia (C-03)
 9. Si cod == '00' → UPDATE estado 'completada'
10. DESPUÉS: updateEmpresaBalance(débito)                       ⚠ sin transacción (C-02)
11. Si el débito falla → solo advertencia en log, éxito igual   ⚠ C-05
12. usleep(500 ms) esperando el webhook                         ⚠ M-04
13. Devolver la transacción
```

**El paso 6 valida el saldo, pero el paso 10 lo debita.** Entre ambos hay una llamada de red de hasta 3 minutos sin ninguna reserva del importe: ahí caben todas las condiciones de carrera.

Ver el flujo corregido en [`BUSINESS_RULES.md`](BUSINESS_RULES.md).

---

## 10. ESTADOS TRANSACCIONALES

ENUM real de `transacciones.estado`:

```
pendiente · procesando · completada · fallida · anulada
```

Distribución: 43,123 completadas · 4,839 fallidas · 467 anuladas · **367 pendientes**.

Las 367 pendientes son transacciones cuyo resultado real ante el proveedor **nunca se resolvió**. No existe proceso de barrido que las concilie contra MidasRed mediante `checkRechargeStatus($xid)`, pese a que el método existe. Representan RD$ 43,381.00 de estado desconocido.

---

## 11. PROCESOS AUTOMÁTICOS

No se encontró ningún cron job activo del sistema de recargas en el servidor. El `CLAUDE.md` del proyecto lista tres cron **recomendados** (limpieza de logs, sincronización de servicios, optimización de BD) redactados en modo sugerencia, no instalados.

**Consecuencia:** no hay purga de `oauth_states` (55,386 filas), ni de `proyecto_webhook_logs` (38,417), ni barrido de transacciones pendientes.

---

## 12. RIESGOS Y DEUDA TÉCNICA

**Riesgos financieros** (detalle en `SECURITY_AUDIT.md`):
1. Débito sin transacción ni bloqueo → doble gasto (C-02).
2. Recarga entregada aunque falle el cobro (C-05).
3. Sin idempotencia → duplicación por reintento (C-03).
4. Control de acceso desactivado → gasto del saldo ajeno (C-01).

**Deuda técnica:**
- Archivos monolíticos: `debug.php` 117 KB, `index.php` 82 KB, `historial.php` 60 KB.
- 5 clases JWT de las cuales ninguna se usa en el camino real.
- `controllers/` y `views/` vacíos: la estructura MVC es nominal.
- ~40 scripts de test/debug servibles por HTTP.
- 13 tablas vacías de funcionalidades abandonadas.
- Sin gestor de dependencias, sin pruebas automatizadas, sin control de versiones detectado en el árbol.
- Lógica de negocio duplicada entre `index.php`, `formulario.php` y `api/process-recharge.php`.

---

## 13. QUÉ SE REUTILIZA EN LA API NUEVA

| Componente existente | Decisión | Motivo |
|---|---|---|
| Base de datos `recargas_2` | **Reutilizar íntegra** | Fuente de verdad; no se altera producción |
| Tabla `api_tokens` + satélites | **Reutilizar** | Ya es el modelo de credenciales por empresa |
| `empresas.ambiente` | **Reutilizar** | Ya distingue production/development → sandbox |
| Catálogo `servicios`/`productos`/`paquetes` | **Reutilizar** | Sincronizado con el proveedor |
| Contrato de MidasRed | **Reimplementar** como adaptador | Corregir TLS, timeouts y trazabilidad |
| `LimitValidator` | **Reimplementar** | Debe operar bajo bloqueo transaccional |
| `updateEmpresaBalance` | **Descartar** | Patrón inseguro por diseño (C-02) |
| Clases `JWTValidator*` | **Descartar** | Código muerto |
| `auth_guard.php` | **Rediseñar** | Su modo OBSERVE es la causa de C-01 |

---

## 14. RECOMENDACIONES

1. **No extender el sistema actual.** La API nueva se construye al lado, comparte la base de datos y corrige el camino del dinero por diseño.
2. **Priorizar la integridad financiera** sobre cualquier funcionalidad: transacción de BD, débito atómico condicional e idempotencia antes que cualquier endpoint nuevo.
3. **Rotar todas las credenciales** expuestas (BD, MidasRed, y los 610 secretos de cliente en texto plano).
4. **Instalar el barrido de pendientes** contra `checkRechargeStatus` — hay RD$ 43,381 en estado indeterminado.
5. **Reconstruir el libro mayor**: todo movimiento de saldo debe generar su fila en `movimientos_balance` dentro de la misma transacción.
6. **Unificar la fuente de verdad del saldo** y conciliar las 96 empresas divergentes antes de que el número crezca.

---

## NOTA DE ALCANCE

- **HECHO CONFIRMADO:** estructura de archivos, esquema de base de datos, cifras de volumen y todas las referencias con archivo:línea.
- **INFERENCIA:** el modelo de negocio prepago con comisión se deduce del esquema (`empresa_balances.tipo_credito`, `empresa_comisiones`) y del flujo de débito; no se validó con documentación comercial.
- **REQUIERE VALIDACIÓN:** ausencia de cron jobs (se inspeccionó el servidor actual; podrían ejecutarse desde otro host), y el destino real de los webhooks de `proyectos`.
- **NO CONFIRMADO:** el propósito de las 13 tablas vacías y si el subsistema `wa_*` (WhatsApp) está en uso productivo.