Manual Instructivo de Uso — CHUCHYISP
Bienvenido a la documentación interactiva oficial de CHUCHYISP. Este manual explica paso a paso cómo operar los 4 portales integrados del sistema: desde el aprovisionamiento de routers MikroTik, OLTs GPON y Cajas NAP, hasta la facturación fiscal DGII (NCF/e-CF), el corte automático de morosos y el trabajo en campo sin señal con la aplicación móvil para técnicos.
Visión General del Ecosistema y los 4 Portales
Cómo interactúan las áreas de Red, Finanzas, Cuadrillas de Campo y Suscriptores en tiempo real.
La plataforma centraliza toda la operación técnica y administrativa de un proveedor de Internet (ISP / WISP) en una única base de datos relacional MySQL 8.0 de 18 tablas conectada por sockets en vivo con los equipos de borde.
Panel Central NOC & ERP
- Control de Routers MikroTik, OLTs GPON/EPON, Redes IPv4 y Cajas NAP georreferenciadas.
- Facturación recurrente, Punto de Venta (POS), promesas de pago y reportes fiscales DGII (606/607/e-CF).
- Inventario de almacén (ONUs, carretes de fibra Drop, conectores) y Mesa de Ayuda (Tickets).
App Móvil de Técnicos (PWA)
- Diseñada para teléfonos Android/iOS de cuadrillas instaladoras.
- Captura de coordenadas GPS + sugerencia automática de la Caja NAP más cercana por fórmula Haversine.
- Subida de fotos de potencia óptica, número de serie de ONU, firma digital en pantalla y cola de sincronización Offline.
Autogestión y Corte Automático
- Cuando una factura vence, el motor automático añade la IP del cliente al address-list
MOROSOSen MikroTik. - El navegador del cliente es redirigido automáticamente a
/suspendidomostrando su saldo pendiente. - Al registrar el pago o activar una Promesa de Pago, el servicio se reconecta en menos de 3 segundos.
Roles de Usuario y Credenciales de Demostración
Control de Acceso Basado en Roles (RBAC) con protección JWT y Segundo Factor (2FA TOTP).
El sistema filtra automáticamente el menú lateral y los permisos de API según el rol del operador que inicia sesión. Para realizar demostraciones o pruebas inmediatas, puedes utilizar las cuentas preconfiguradas:
| Rol Operativo | Correo / Usuario | Contraseña Demo | Alcance y Permisos en la Plataforma |
|---|---|---|---|
| Super Administrador | admin@chuchyisp.net |
Karlos031516 |
Acceso total al NOC, Routers, Finanzas, Backups, Seguridad 2FA y Configuración general. |
| Técnico de Campo | tecnico1@chuchyisp.net |
tec123 |
Acceso directo a Órdenes de Instalación (OT), App PWA Móvil (/tecnico.html), Tickets y Cajas NAP. |
| Portal de Cliente (Cliente) | Cédula / ID (ej. CLI-001) |
Teléfono o PIN asignado | Acceso a /portal.html para consultar facturas, descargar recibos PDF, pagar en línea y abrir tickets. |
Dashboard Principal y Monitoreo NOC en Tiempo Real
Supervisión de tráfico, estado de nodos, ingresos del mes y alertas por WebSocket.
Visualiza al instante el total de Clientes Activos vs. Suspendidos, los Ingresos Recaudados del mes, el ancho de banda agregado (Download / Upload en Mbps) y la disponibilidad de Routers y OLTs.
Escribe cualquier nombre de cliente, dirección IP, dirección MAC, serial de ONU GPON o número de ticket en el buscador superior para abrir su ficha técnica sin cambiar de módulo.
El botón Sincronizar en la barra superior ejecuta una sincronización masiva de colas Simple Queue y listas de corte con todos los routers MikroTik activos.
Gestión de Red: Routers MikroTik, OLTs GPON y Cajas NAP
Cómo conectar tus equipos de borde, medir latencia real y gestionar la red de fibra óptica FTTH.
4.1. Administración de Routers MikroTik (Gestión de Red → Routers)
CHUCHYISP se comunica directamente con la API nativa de RouterOS (puerto TCP 8728). En la vista de Routers dispones de herramientas completas de aprovisionamiento:
Sincronización Socket en Vivo
- Haz clic en el icono Sincronizar Router en la fila del MikroTik.
- El sistema se conecta por socket TCP y actualiza automáticamente las
/queue/simple(límites de velocidad de cada cliente) y la lista/ip/firewall/address-list(MOROSOS).
Generador Walled Garden & VPN
- Botón Walled Garden (Corte): Genera el script
.rsclisto para pegar en WinBox que bloquea a los morosos y redirige su navegador al aviso de suspensión. - Botón Túnel VPN (Local ↔ VPS): Genera el script WireGuard para enlazar tu MikroTik con un VPS en la nube aunque tu proveedor upstream tenga CGNAT.
4.2. Cabeceras OLT GPON y Cajas NAP (Gestión de Red → OLT / Cajas NAP)
Administra tus OLTs (Huawei, ZTE, VSOL, TP-Link) consultando la potencia óptica RX/TX por SNMP (por ejemplo -18.5 dBm) y organiza tu planta externa FTTH mediante Cajas NAP con control de puertos ocupados vs. disponibles (8, 16 o 32 puertos).
4.3. Monitoreo de Latencia Dual ICMP + TCP (Gestión de Red → Monitoreo)
Ejecuta pruebas de ping en vivo hacia cualquier Router, OLT o CPE de cliente. Si el servidor corre en un VPS donde el proveedor bloquea paquetes ICMP, el motor conmuta automáticamente a TCP Ping midiendo el tiempo exacto de respuesta del socket.
Catálogo de Planes de Internet, Voz IP y Servicios
Configuración de velocidades simétricas/asimétricas, precios e impuestos.
Desde el menú Servicios → Internet / Voz / Personalizado defines los planes comerciales que se asignan a los clientes:
Define el nombre comercial (ej. Fibra Hogar 100 Mbps), velocidad de Subida y Bajada, tarifa mensual en pesos/dólares y el perfil de cola para MikroTik.
Al cambiar el plan de un cliente o editar la velocidad de un plan existente, la próxima sincronización con MikroTik ajustará el max-limit de su Simple Queue de forma transparente.
Gestión de Clientes, Mapa Geográfico FTTH y Contratos
Altas de suscriptores, geolocalización de ONUs/NAPs, órdenes de instalación y contratos digitales.
Padrón de Usuarios
- Registra datos personales, cédula/RNC, teléfono WhatsApp, dirección IP, router asignado y plan contratado.
- Botones de acción rápida para Suspender / Reactivar el servicio en 1 clic, ver historial de facturas o abrir el expediente técnico.
- Importación y exportación masiva en formato Excel (.xlsx).
Mapa Interactivo de Clientes
- En Clientes → Mapa clientes visualizas en un mapa satelital/callejero todos los clientes (verdes = activos, rojos = suspendidos) junto con las Cajas NAP y el trazado de acometidas Drop.
Instalaciones y Contratos
- En Clientes → Instalaciones creas Órdenes de Trabajo (OT) y las asignas a un técnico de campo.
- En Clientes → Contratos generas contratos listos para imprimir con la firma digital capturada en el domicilio del cliente.
Finanzas, Caja POS, Facturación Fiscal (e-CF / DGII) y Corte
Ciclo completo de facturación, cobro en ventanilla o pasarela web y reconexión automática.
El motor Cron genera las facturas del ciclo automáticamente o puedes emitirlas desde Finanzas → Nueva Factura con numeración fiscal NCF / e-CF (B01 Crédito Fiscal, B02 Consumidor Final, E31/E32).
Al cobrar una factura en efectivo, transferencia o tarjeta, el sistema cambia la factura a Pagada, genera el recibo térmico/PDF y, si el cliente estaba cortado, reactiva su servicio en el MikroTik automáticamente.
Si un cliente solicita prórroga, puedes otorgarle una Promesa de Pago indicando la fecha límite. El sistema le restablece el Internet inmediatamente y lo volverá a suspender si no paga antes del vencimiento acordado.
Descarga los reportes tributarios listos para la DGII y concilia transferencias bancarias desde las pestañas superiores del módulo de Finanzas.
Fichas Hotspot, Almacén, Tickets de Soporte y Mensajería
Módulos complementarios para operación comercial y atención al cliente.
Fichas Hotspot (Vouchers)
- Genera lotes de pines/fichas prepago por horas, días o semanas para redes Wi-Fi públicas.
- Impresión de plantillas de tickets con código QR de conexión rápida.
Almacén e Inventario
- Control de stock de ONUs, Routers Wi-Fi, bobinas de fibra óptica, splitters y rosetas.
- Alertas visuales cuando un insumo baja del stock mínimo configurado.
Tickets SLA y Mensajería
- Gestión de averías reportadas por clientes con prioridad (Alta, Media, Baja) y técnico asignado.
- Módulo de Mensajería con plantillas de aviso de factura próxima a vencer, confirmación de pago y mantenimiento programado por WhatsApp/Correo.
Uso de la App Móvil PWA para Técnicos (/tecnico.html)
Guía paso a paso para cuadrillas de instalación y soporte en la calle (con o sin cobertura de Internet).
Los técnicos de campo ingresan desde su celular a http://TU_SERVIDOR:4002/tecnico.html (pueden instalarla en la pantalla de inicio como App nativa gracias a su Service Worker).
El técnico visualiza sus órdenes asignadas, toca la orden del cliente y presiona "En Ruta" al salir hacia el domicilio y "En Sitio" al llegar.
Al pulsar "Fijar GPS", la app captura la ubicación satelital del domicilio y ordena automáticamente el selector de Cajas NAP mostrando primero la más cercana en metros, junto con un botón para abrir la ruta en Google Maps. Si opera en una red local HTTP sin SSL, permite heredar con 1 toque las coordenadas de la Caja NAP.
Ingresa la potencia medida con el Power Meter (ej. -18.9 dBm), el número de serie de la ONU, los metros de cable Drop utilizados y toma fotografías desde la cámara del teléfono (se comprimen automáticamente para ahorrar datos).
El cliente firma con el dedo sobre la pantalla del celular. Al presionar "Finalizar Orden y Activar Servicio", el cliente pasa a estado Activo en el NOC en tiempo real.
Offline (X en cola) y, apenas el teléfono recupere conexión Wi-Fi o datos móviles, sincronizará todos los cambios automáticamente con el servidor central.
Portal del Cliente (/portal.html) y Aviso de Corte (/suspendido)
Experiencia de autogestión para el cliente final.
Portal de Autogestión (/portal.html)
- El cliente ingresa con su código de cliente o cédula.
- Consulta su plan actual, velocidad contratada, estado de cuenta e historial de facturas.
- Puede reportar averías creando un Ticket de Soporte directamente hacia el NOC.
Portal Cautivo de Suspensión (/suspendido)
- Se muestra automáticamente cuando el cliente intenta navegar estando en la lista
MOROSOSdel MikroTik. - Detecta automáticamente al cliente por su IP (tanto en LAN local como en VPS mediante redirección WebProxy) y le permite pagar en línea o solicitar reactivación.
Guía de Despliegue Híbrido: Servidor Local ↔ Cloud VPS
Cómo operar el sistema en un servidor físico local, en un VPS en la nube o migrar entre ambos en 1 clic.
11.1. Migrar Datos entre Servidor Local y VPS (Backup & Restore 1-Click)
Si trabajas en un servidor local y deseas llevar toda tu operación a un VPS (o descargar un respaldo del VPS a tu servidor local de contingencia):
En el servidor de origen, ve a Ajustes → Copias de Seguridad (Backups), haz clic en "Crear Backup Ahora" y descarga el archivo .json generado.
En el servidor destino, abre Ajustes → Copias de Seguridad, pulsa "Importar / Migrar (.JSON)" y selecciona el archivo descargado. El sistema restaurará clientes, facturas, routers, OLTs, cajas NAP, órdenes e inventario en una única transacción segura.
11.2. Comandos Rápidos de Ejecución
# Opción A: Ejecución con Docker Compose (Local o VPS)
docker compose up -d --build
# Opción B: Ejecución directa con Node.js / PM2
npm install
node server.js
# o en producción con PM2:
pm2 start ecosystem.config.cjs10.200.0.2) para administrarlo de forma cifrada y segura.