Plan de arranque de IPSmart Z
Aprobado el 17 de septiembre de 2026. Este es el plan con el que nació el módulo; se conserva tal como se aprobó, y lo que cambie después se anota al final, no se reescribe.
1. Objetivo
Una persona entra al radio de una Zona WiFi, se conecta al SSID abierto, ve la plantilla de esa zona, se identifica y navega. Si es cliente verificado contra el API de IPSmart, navega 2 horas. Si no lo es, navega 30 minutos y al segundo siguiente ya existe como prospecto en el IPSmartCRM, con su zona, su hora y su dispositivo.
Se da por cerrado cuando, en una zona piloto real y con el equipo real, se cumplen las cinco condiciones a la vez:
- Un Android y un iPhone abren el portal solos, sin teclear ninguna dirección.
- El corte ocurre a los 30:00 y a las 2:00:00 con menos de 30 s de desviación, y el aviso de «te quedan 5 minutos» llega antes.
- Una cédula de cliente da 2 h; una inventada da 30 min; y con el API de IPSmart caído, el módulo sigue repartiendo con el padrón en caché.
- El prospecto aparece en el CRM en menos de 10 s, sin duplicarse cuando esa persona vuelve mañana.
- Los manuales permiten que un técnico que no participó en esto monte la zona siguiente sin preguntar nada.
2. Decisiones tomadas el 17-sep-2026
| Decisión | Elegido | Consecuencia |
|---|---|---|
| Fabricantes a soportar | MikroTik, UniFi, Omada y Ruijie | Cuatro conectores; Ruijie es el de mayor incertidumbre y exige equipo real antes de prometer fecha |
| Cómo se verifica al cliente | API de IPSmart en vivo, con padrón en caché de respaldo | La zona sigue viva aunque el núcleo esté caído |
| Verificación del visitante | Sin OTP ahora, cableado para encenderlo por zona | Más conversión hoy; el interruptor existe desde el primer día |
| Dónde se aplica el corte | API del controlador ahora, RADIUS después | Fase 1 sin hierro en sitio; Fase 2 para grado operador |
3. Arquitectura
Un solo artefacto, dos modos, con un interruptor de configuración (Z_MODO), no dos compilaciones:
| Pieza | Suelto | Integrado |
|---|---|---|
| Entrada al panel | Login propio | Pase SSO del escritorio; el login propio se apaga |
| Quién es cliente | Padrón importado | API de IPSmart en vivo, con padrón de respaldo |
| A dónde va el lead | CRM propio o webhook del cliente | IPSmartCRM, con su empresa y su vendedor |
| Zonas y sedes | Maestro local | Espejo de tenancy.site; no se duplican maestros |
Pila: Next.js 15 + TypeScript + Prisma + PostgreSQL, en Railway, con dominio zonaw.ipsmart.app. El portal que ve el visitante pesa menos de 120 KB porque se carga con señal mala y sin internet todavía.
Los conectores son adaptadores con un contrato único (autorizar / cortar / probar): añadir un fabricante no toca el portal ni el CRM.
Por qué el RADIUS va aparte y en sitio: RADIUS habla UDP (1812/1813, y 3799 para el corte en caliente) y Railway no expone UDP. Vive como contenedor propio junto al NAS del ISP y se comunica con zonaw por HTTPS.
4. EDT y esfuerzo
| Fase | Paquete | Entregable verificable | Días |
|---|---|---|---|
| F0 | Fundaciones | Repo, esqueleto, servicio en Railway, dominio con TLS | 1 |
| F1 | Núcleo del portal | Zonas, sesiones, dispositivos, consentimientos, reloj, cuotas | 3 |
| F2 | Conector MikroTik | Zona de laboratorio: conecta, navega y se corta en el minuto exacto | 2 |
| F3 | Las tres plantillas | Z-1, Z-2 y Z-3 vivas con editor de marca por zona | 3 |
| F4 | Identidad y CRM | Cédula contra IPSmart con caché; prospecto sin duplicados | 2 |
| F5 | Panel de operación | Zonas, sesiones vivas, embudo, y qué pasó con cada lead | 3 |
| F6 | UniFi · Omada · Ruijie | Los tres conectores certificados contra equipo real | 3 |
| F7 | Suelto e integrado | Registro de 9 puntos, pase SSO, arranque sin IPSmart | 2 |
| F8 | Manuales y piloto | Los 11 manuales y una zona montada siguiéndolos | 3 |
| F9 | RADIUS en sitio (Fase 2, se aprueba aparte) | Contenedor, contabilidad y corte en caliente | 4 |
22 días·hombre hasta F8. Camino crítico: F1 → F2 → F4 → F8.
5. Riesgos
| Riesgo | Prob. | Impacto | Mitigación |
|---|---|---|---|
| El HTTPS impide el redirigir al portal | Alta | Alto | No se depende del redirigir: detección del propio sistema operativo y jardín vallado del DNS, probado con iPhone y Android desde F2 |
| MAC aleatoria: la identidad del dispositivo deja de ser fiable | Alta | Medio | La identidad fuerte es el teléfono; la MAC sólo como conveniencia de reconexión |
| Ruijie: el portal externo cambia entre firmwares | Media | Medio | Se certifica con el equipo real antes de comprometer fecha; si no, esa marca entra por RADIUS |
| Sin OTP, entre 30 % y 50 % de teléfonos falsos | Alta | Medio | Formato validado, puntuación del lead, interruptor de OTP por zona listo |
| El formulario público del CRM acepta 10/min | Media | Alto | Cola propia con reintentos y, en F4, punto de ingesta dedicado con credencial por empresa |
| Datos personales sin consentimiento demostrable | Media | Alto | Consentimiento con sello de tiempo, IP y texto exacto; cifrado; retención de 12 meses (Manual 10) |
| Saturación de radio en plazas | Alta | Alto | Es diseño, no software: canales, RSSI mínimo, límites por cliente, retorno dimensionado (Manuales 01 y 06) |
| Rotación de MAC para renovar los 30 min | Alta | Bajo | La cuota se cuenta por teléfono y zona, no por MAC |
El token de GitHub de jermsoft2026 vence el 20-sep |
Alta | Medio | El repo se crea en F0, dentro de los tres días |
6. Calidad (ISO/IEC 25010)
| Característica | Qué se mueve | Cómo se mide |
|---|---|---|
| Adecuación funcional | El reloj corta cuando debe | Desviación < 30 s en 20 sesiones por conector |
| Fiabilidad | La zona vive aunque IPSmart caiga | Prueba de caos: se apaga el API y las conexiones se resuelven con el padrón |
| Eficiencia | El portal abre con señal mala | < 120 KB y primera pintura < 1,5 s simulando 3G |
| Seguridad | Una empresa no ve lo de otra | Prueba de aislamiento con dos empresas y un rol sin privilegios |
| Usabilidad | Conectarse no requiere pensar | Tres toques y < 20 s |
| Mantenibilidad | Añadir un fabricante no toca el portal | Pruebas de contrato del adaptador |
| Portabilidad | Se vende solo | Arranque en limpio con Z_MODO=suelto |
7. Lo que NO se hace sin pedirlo
- Vender el acceso: nada de cobrar por hora, vouchers ni pasarela. La zona es gratis y su negocio es el lead.
- Encender el OTP: queda cableado y apagado.
- RADIUS en Fase 1: es Fase 2 y se aprueba aparte.
- Tocar equipos en producción: todo se certifica primero en banco de pruebas.
- Datos inventados: ni una pantalla con datos de mentira; lo que se muestre se siembra en la base.
- Inventario de red: IPSmart Z no es dueño de los equipos ni de la planta — eso es de FibraMap y del módulo Red.
Anotaciones posteriores
17-sep-2026 · misma sesión. Se construyó F0 a F5 y F8 completos, y los conectores de F6 escritos a falta de certificarlos contra equipo real. Dos hallazgos durante las pruebas, ya corregidos:
- La normalización de teléfonos partía a una persona en dos. «0414-1234500» y «+584141234500» producían identidades distintas, y con ellas dos prospectos para el mismo teléfono. La causa era confundir la longitud del número nacional con la del número marcado con el 0 troncal. Corregido y cubierto con una prueba automática que compara las ocho formas de escribir el mismo número.
- La cuota diaria no cortaba, precisamente porque la identidad estaba partida. Con el teléfono bien normalizado, la tercera conexión del día se rechaza como debe.