# Plan de desarrollo: Sistema OLT multimarca (autorización de ONUs) integrado a facturación y control

## 1. Objetivo

Construir un módulo que permita **autorizar y registrar clientes (ONUs/ONTs) en OLTs de distintas marcas** desde una sola interfaz, y que esté **integrado con el sistema de facturación y control** (clientes, planes de internet, pagos, tickets, almacén, SRI Ecuador).

Resultados esperados:

- Autorizar una ONU nueva en segundos, sin entrar por CLI/WebUI de cada OLT.
- Que el plan contratado en facturación se refleje automáticamente en la OLT (velocidad, VLAN, perfil).
- Suspender / reactivar el servicio automáticamente según el estado de pago.
- Visibilidad del estado de cada ONU (online/offline, potencia óptica) dentro del panel del cliente y de soporte técnico.

---

## 2. Alcance funcional

### 2.1 Gestión de OLTs
- Alta/edición/baja de OLTs: nombre, marca, modelo, IP de gestión, puerto, protocolo, credenciales (cifradas), zona/nodo, empresa (multiempresa).
- Prueba de conexión y estado de la OLT (en línea, CPU, temperatura, uptime).
- Inventario de tarjetas PON y puertos (slot/puerto), capacidad y ocupación.

### 2.2 Descubrimiento y autorización de ONUs
- Detectar **ONUs no autorizadas** (pendientes) por OLT/puerto PON, con serial (SN/GPON-SN) o MAC.
- Autorizar la ONU asignándola a un cliente existente del sistema.
- Seleccionar: OLT, puerto PON, perfil/plan de velocidad, VLAN, tipo de servicio (PPPoE, IPoE/DHCP, bridge, IPTV opcional).
- Registrar ONU con ID asignado, nombre/descripción (cliente + cédula/ID).
- Desautorizar / eliminar / reiniciar / reemplazar ONU (cambio de equipo manteniendo el cliente).

### 2.3 Provisión de servicio
- Plantillas de servicio por plan de internet (velocidad up/down, VLAN, perfiles de línea y servicio).
- Configuración opcional del WiFi/WAN de la ONU (TR-069/OMCI según soporte).
- Aplicación de cambios de plan (upgrade/downgrade) desde facturación.

### 2.4 Integración con facturación y control
- **Alta de cliente / instalación** → genera orden de instalación → técnico autoriza la ONU → se activa el servicio y se inicia el ciclo de facturación.
- **Pago pendiente / vencido** → suspensión automática (cortar servicio sin eliminar la ONU).
- **Pago recibido / promesa de pago** → reactivación automática.
- **Cambio de plan** → actualiza el perfil de velocidad en la OLT.
- **Retiro del cliente** → desautoriza ONU y libera el equipo en almacén.
- Vinculación con **ALMACÉN**: la ONU autorizada descuenta del stock (serial, MAC, modelo) y queda asignada al cliente.
- Vinculación con **SOPORTE TÉCNICO**: desde un ticket ver estado, potencia óptica, historial y ejecutar reinicio.

### 2.5 Monitoreo
- Estado por ONU: online/offline, potencia Rx/Tx, distancia, última caída, motivo de desconexión.
- Alertas: ONU offline masiva en un puerto PON (posible corte de fibra), potencia fuera de rango.
- Dashboard: ONUs totales / online / offline / pendientes por OLT y por zona.

### 2.6 Auditoría y seguridad
- Bitácora de cada acción (quién autorizó, qué, cuándo, resultado).
- Roles y permisos (STAFF): técnico (autorizar), supervisor (suspender/eliminar), administrador (gestionar OLTs).
- Credenciales de OLT cifradas; aislamiento por empresa.

---

## 3. Arquitectura propuesta

```
┌────────────────────┐     ┌───────────────────────┐
│  Panel web         │     │ Sistema facturación   │
│  (Clientes, Tickets│◄───►│ y control (existente) │
│  Almacén, Finanzas)│     └──────────┬────────────┘
└─────────┬──────────┘                │ eventos (pago, plan, alta, baja)
          │ API REST                  ▼
          ▼                 ┌───────────────────────┐
┌────────────────────┐      │ Cola de trabajos      │
│  API del módulo OLT│◄────►│ (Redis + workers)     │
│  (backend)         │      └──────────┬────────────┘
└─────────┬──────────┘                 │
          ▼                            ▼
┌──────────────────────────────────────────────────┐
│        Capa de drivers (adaptadores por marca)    │
│  Huawei │ ZTE │ VSOL │ Fiberhome │ BDCOM │ ...    │
└─────────┬───────────┬──────────┬─────────────────┘
          ▼           ▼          ▼
        OLT 1       OLT 2      OLT N   (SSH/Telnet · SNMP · API/NETCONF)
```

### Decisión clave: patrón **Adapter / Driver por marca**
Una interfaz común que todas las marcas implementan, para que el resto del sistema no sepa qué marca es la OLT:

```
interface OltDriver {
  testConnection()
  getSystemInfo()
  listPonPorts()
  listUnauthorizedOnus()
  authorizeOnu({ sn, ponPort, profile, vlan, serviceType, description })
  deauthorizeOnu(onuId)
  suspendOnu(onuId)
  resumeOnu(onuId)
  rebootOnu(onuId)
  changeProfile(onuId, profile)
  getOnuStatus(onuId)        // estado, potencia, distancia
  listOnus()
}
```

Cada marca = un driver nuevo, sin tocar el núcleo. Esto es lo que hace el sistema **multimarca**.

### Protocolos de comunicación por OLT
| Método | Uso | Notas |
|---|---|---|
| **SSH / Telnet (CLI)** | Autorizar, configurar, suspender | El más universal; requiere parseo de texto y control de sesiones |
| **SNMP** | Lectura: estado, potencias, contadores | Ligero para monitoreo masivo |
| **API REST / NETCONF / gestor (U2000, ZXAN, etc.)** | Si la marca o el gestor la ofrece | Más estable que CLI cuando está disponible |
| **TR-069 (ACS)** | Configurar WiFi/WAN de la ONU | Opcional, fase posterior |

Estrategia recomendada: **CLI para escritura + SNMP para lectura**, y API del fabricante donde exista.

---

## 4. Marcas a soportar (priorización sugerida)

Empezar por las que realmente tienes desplegadas o planeas desplegar. Orden típico de mercado en ISPs pequeños/medianos de Latinoamérica:

1. **Huawei** (MA5600T / MA5800 / MA5608T)
2. **ZTE** (C300 / C320 / C600)
3. **VSOL** (económicas, muy comunes en ISPs pequeños)
4. **Fiberhome** (AN5516 / AN5506)
5. **BDCOM / Hioso / otras genéricas**

> Acción previa: confirmar cuáles marcas/modelos/firmware usas realmente, ya que los comandos CLI varían entre modelos y versiones.

---

## 5. Modelo de datos (MySQL)

Tablas principales (todas con `empresa_id` por ser multiempresa):

| Tabla | Campos clave |
|---|---|
| `olts` | id, empresa_id, nombre, marca, modelo, ip, puerto, protocolo, usuario, password_cifrado, snmp_comunidad, zona_id, estado, ultimo_chequeo |
| `olt_puertos_pon` | id, olt_id, slot, puerto, tecnologia (GPON/EPON), capacidad, ocupadas |
| `olt_perfiles` | id, olt_id, nombre, vel_bajada, vel_subida, vlan, tipo_servicio, plan_internet_id |
| `onus` | id, empresa_id, olt_id, puerto_pon_id, onu_id_olt, serial/mac, modelo, cliente_id, servicio_id, estado_admin (activa/suspendida), estado_red (online/offline), potencia_rx, potencia_tx, distancia, fecha_autorizacion, dispositivo_almacen_id |
| `onus_pendientes` | id, olt_id, puerto_pon, serial, detectada_en |
| `olt_acciones` (auditoría) | id, usuario_id, olt_id, onu_id, accion, parametros, resultado, error, fecha |
| `olt_trabajos` | id, tipo, payload, estado, intentos, ultimo_error |

Relaciones con tablas existentes: `clientes`, `planes_internet`, `zonas`, `instalaciones`, `tickets`, `dispositivos_almacen`, `facturas`, `pagos`.

---

## 6. Flujos principales

### 6.1 Autorizar ONU nueva (instalación)
1. Se crea/selecciona el **cliente** y su **plan de internet** (módulo Clientes → Instalaciones).
2. El técnico conecta la ONU en campo.
3. El sistema consulta la OLT y muestra **ONUs pendientes** (por serial).
4. El técnico elige la ONU, confirma cliente, puerto PON y perfil (se propone según el plan).
5. El sistema encola el trabajo → el driver de la marca ejecuta la autorización.
6. Se verifica que la ONU quede online y se guarda potencia/estado.
7. Se marca la instalación como completada, se descuenta el equipo del almacén y se activa la facturación del cliente.

### 6.2 Suspensión por falta de pago
1. Un proceso programado (cron) revisa facturas vencidas según las reglas de la empresa.
2. Para cada cliente moteado, encola `suspendOnu`.
3. Se registra en auditoría y se notifica al cliente (opcional).
4. Al registrar el pago (o una **promesa de pago**), se encola `resumeOnu`.

### 6.3 Cambio de plan
1. Finanzas/Clientes cambia el plan.
2. Evento → cola → `changeProfile` en la OLT con el perfil equivalente.
3. Se confirma y se guarda el resultado.

### 6.4 Reemplazo de ONU
1. Técnico selecciona la ONU dañada y registra el nuevo serial.
2. Sistema desautoriza la anterior, autoriza la nueva con la misma configuración y actualiza almacén.

---

## 7. Fases de desarrollo

### Fase 0 — Descubrimiento y preparación (1 semana)
- Inventario real: marcas, modelos, versiones de firmware, topología, cantidad de ONUs.
- Acceso de laboratorio/pruebas a al menos una OLT por marca (o un horario de pruebas controlado).
- Definir perfiles/VLAN/plantillas estándar por plan.
- Documentar comandos CLI y OIDs SNMP por marca.

### Fase 1 — Núcleo y primer driver (2–3 semanas)
- Modelo de datos y migraciones.
- CRUD de OLTs, puertos y perfiles.
- Capa de drivers + **driver de la primera marca** (la más usada por ti).
- Cola de trabajos, reintentos, logs y manejo de errores/timeouts.
- Gestión segura de credenciales.

### Fase 2 — Autorización de ONUs (2 semanas)
- Listado de ONUs pendientes.
- Pantalla de autorización con selección de cliente, PON y perfil.
- Desautorizar, reiniciar, reemplazar.
- Auditoría completa.

### Fase 3 — Integración con facturación y control (2–3 semanas)
- Integración con Clientes/Instalaciones/Planes.
- Suspensión y reactivación automática por pagos y promesas de pago.
- Cambio de plan sincronizado.
- Integración con Almacén (serial/MAC de la ONU) y Soporte (ver estado desde ticket).

### Fase 4 — Monitoreo (2 semanas)
- Lectura periódica SNMP/CLI: estado y potencias.
- Dashboard de OLTs/ONUs.
- Alertas por caídas masivas y potencia fuera de rango.

### Fase 5 — Drivers adicionales (1–2 semanas por marca)
- ZTE, VSOL, Fiberhome, etc., uno por uno con su batería de pruebas.

### Fase 6 — Pruebas, piloto y despliegue (2 semanas)
- Pruebas con OLT real y clientes piloto (un nodo/zona).
- Pruebas de carga y de fallos (OLT caída, timeout, comando rechazado).
- Capacitación al personal técnico, documentación y puesta en producción gradual.

**Estimación total:** ~10–14 semanas para núcleo + 2 marcas + integración completa + monitoreo (varía con la cantidad de marcas y el equipo).

---

## 8. Stack tecnológico sugerido

Alineado con tu sistema (base de datos **MySQL**):

- **Backend:** el mismo del sistema actual (Node.js/NestJS, Laravel o el que uses) como módulo/servicio dedicado.
- **Cola de trabajos:** Redis + BullMQ (Node) o Laravel Queues.
- **Conexión a OLTs:** librería SSH/Telnet (p. ej. `ssh2` / `node-ssh`, `netmiko`/`paramiko` si usas Python) y cliente SNMP (`net-snmp` / `pysnmp`).
- **Seguridad:** cifrado de credenciales (AES-256 con clave en variables de entorno/secret manager), HTTPS, JWT/roles.
- **Tareas programadas:** cron/scheduler para suspensiones y sondeo de estado.
- **Frontend:** el mismo panel actual, con nuevas secciones dentro de CLIENTES, SISTEMA, SOPORTE TÉCNICO y ALMACÉN.

> Opción a evaluar: un **microservicio “olt-gateway”** (por ejemplo en Python por su ecosistema de red) que exponga una API interna y sea el único que habla con las OLTs. El sistema principal solo le envía órdenes. Reduce riesgo y facilita agregar marcas.

---

## 9. Ubicación en el menú del sistema

- **SISTEMA** → OLTs (lista, puertos PON, perfiles) · Zonas
- **CLIENTES → Instalaciones** → botón “Autorizar ONU”
- **SOPORTE TÉCNICO** → en cada ticket: estado ONU, potencia, reiniciar
- **ALMACÉN** → ONUs/equipos con serial, asignación a cliente
- **FINANZAS** → reglas de suspensión/reactivación automática
- **AJUSTES** → parámetros de corte (días de gracia, horarios, notificaciones)
- **DASHBOARD** → tarjetas: ONUs online/offline/pendientes

---

## 10. Riesgos y mitigaciones

| Riesgo | Mitigación |
|---|---|
| Comandos CLI cambian según modelo/firmware | Driver por modelo/versión; pruebas con equipo real; plantillas de comandos configurables |
| Sesiones CLI limitadas o bloqueadas en la OLT | Pool de conexiones con límite por OLT, cola serializada por equipo |
| Suspensión masiva por error | Modo “simulación”, límites por lote, confirmación para acciones masivas, bitácora |
| Credenciales de OLT expuestas | Cifrado, acceso restringido por rol, rotación |
| Pérdida de sincronía sistema ↔ OLT | Proceso de **conciliación** periódico (comparar ONUs en OLT vs. base de datos) |
| OLT inaccesible durante una acción | Reintentos con backoff, estado “pendiente”, alerta al administrador |
| Multiempresa: una empresa ve OLTs de otra | `empresa_id` obligatorio en consultas y permisos por tenant |

---

## 11. Criterios de aceptación

- Autorizar una ONU pendiente desde el panel en menos de 1 minuto y verla online.
- Suspender y reactivar un cliente automáticamente al cambiar el estado de pago.
- Cambio de plan reflejado en la OLT sin intervención manual.
- Al menos 2 marcas operativas con el mismo flujo desde la misma pantalla.
- Toda acción registrada en auditoría con usuario, fecha y resultado.
- Reporte de conciliación sin diferencias entre OLT y sistema en el piloto.

---

## 12. Datos que necesito confirmar para afinar el plan

1. ¿Qué **marcas y modelos** de OLT tienes (o piensas usar) y cuántas ONUs aproximadas?
2. ¿Tecnología **GPON, EPON** o ambas?
3. ¿Cómo entregas el servicio: **PPPoE (MikroTik)**, DHCP/IPoE o bridge? ¿Los routers ya están en tu módulo SISTEMA?
4. ¿Tu backend actual (lenguaje/framework) para alinear el stack?
5. ¿Tienes acceso a las OLTs desde el servidor (VPN/red de gestión) o van a requerir un agente local por cliente/empresa?
6. ¿La suspensión será en la OLT, en el router (MikroTik) o en ambos?