Electrosystems — Mapa de red para triage asistido

Contexto

Captura del 2026-05-20 (Sergio). El objetivo final es documentar toda la estructura de red de Electrosystems (clientes, sitios, enlaces, equipos, dependencias y rutas de acceso) en una forma que yo (Claude) pueda leer y razonar sobre ella durante una llamada/sesión, para poder atender prompts como:

• “Revisa el enlace de Telcel de San Julián, me reportan consumo bajo.”
• “Mina Dolores me reporta que no tienen servicio, ayúdame a revisar.”
• “Me llegaron N notificaciones de caída, ¿puedes revisar qué está sucediendo?”

Estos prompts hoy no son atendibles sin ir armando el contexto desde cero cada vez: ¿qué cliente es San Julián? ¿qué equipos hay ahí? ¿por dónde llega el enlace? ¿qué tools (UISP, monitoreo, oxidized, Nagios, NetBox, ~/.ssh/config) tienen información sobre ese sitio? La idea de este proyecto es construir un índice navegable que cierre esa brecha.

Importante: Sergio dijo explícitamente que ahora no se ejecuta — esta entrada es solo para definir alcance, fuentes de datos, estructura propuesta y plan de fases. La implementación va en una sesión subsecuente cuando él priorice.

Objetivo operativo

Que cuando Sergio escriba “revisa Mina Dolores” yo pueda:

1. Resolver el alias a un cliente / sitio / enlace canónico (alias humanos ↔ slug).
2. Listar los equipos del sitio con sus IPs, vendor/modelo, role (CPE, AP, switch, PBX…), y ruta de acceso (SSH directo, jump vía VPN, GUI).
3. Consultar las herramientas adecuadas (UISP, monitoreo / es-antenas-new, oxidized, Nagios, NetBox, Grafana, journalctl, smokeping si existe) para ver estado en vivo y reciente.
4. Correlacionar alertas entrantes (caídas, flapping, recordatorios) con el sitio/enlace afectado para distinguir un evento aislado de una caída de upstream.
5. Devolver un diagnóstico inicial con hipótesis ordenadas por probabilidad + comandos read-only sugeridos para validarlas.

Todo read-only por default; mutaciones siguen necesitando autorización per-sesión (regla [[feedback_dialog_is_informative]]).

Casos de uso objetivo (con ejemplo concreto)

Caso A — “Revisa el enlace de Telcel de San Julián, reportan consumo bajo”

Flujo esperado:

1. Resolver “Telcel San Julián” → slug del enlace (telcel-san-julian o equivalente) + cliente Telcel + sitio físico.
2. Mirar UISP / monitoreo el throughput de las últimas 24h y 7 días; comparar contra baseline conocido.
3. Si hay collector SNMP del enlace: ver ifInOctets/ifOutOctets recientes vs lo esperado.
4. Verificar RF si aplica (signal, CCQ, capacity en Ubiquiti / Cambium / WiTek).
5. Si bajó algún CPE downstream: correlacionar.
6. Devolver: número actual vs esperado, posibles causas (saturación del lado del cliente, problema de RF, alguien apagó equipos), y qué consulta extra le sirve a Sergio para confirmar.

Caso B — “Mina Dolores no tiene servicio”

Flujo esperado:

1. Resolver “Mina Dolores” → cliente/sitio (¿es minadolores2 de los hosts FreePBX? ¿es enlace de internet? ¿es voz?).
2. Determinar qué servicios tiene ese cliente (internet, voz, datos, VPN administrativa) y cuál está reportado caído — preguntar si no está claro.
3. Ping/SSH read-only a los equipos canónicos del sitio.
4. Mirar UISP/monitoreo para ver último heartbeat / handshake.
5. Subir la cadena: si el sitio está aislado, revisar el siguiente hop upstream (POP, datacenter) — si ese también está caído, no es problema del cliente.
6. Devolver: alcance del outage (un equipo / sitio entero / cadena de sitios), última hora de datos buenos, hipótesis ordenada.

Caso C — “Me llegaron N notificaciones de caída, ¿qué está pasando?”

Flujo esperado:

1. Sergio pega/forwardea las notificaciones (Gmail de monitoreo, push, Telegram).
2. Yo extraigo los sitios/enlaces/dispositivos mencionados.
3. Buscar patrón: ¿comparten sitio? ¿comparten upstream/POP? ¿comparten plantilla de monitoreo (puede ser falso positivo por bug de monitoreo, ver [[project_es_antenas_plantilla_managed_vs_blackbox]])? ¿son del mismo cliente?
4. Distinguir: outage real localizado · outage real upstream que arrastra · false-positive del monitoreo (caso 2026-05-20 ifIndex Cambium) · flapping/recordatorio rebote (ya tratado en es-antenas-new).
5. Devolver: agrupación, hipótesis del incidente principal, y para cada grupo cuál es la próxima acción de validación.

Fuentes de datos disponibles (inventario)

Lista de tools y datos que ya existen y que la KB debe indexar. Cada uno con: qué tiene, cómo se consulta, qué credenciales requiere.

Estructura propuesta para la KB

Tres niveles de archivos, todos en este hub:

Nivel 1 — Mapa global

projects/electrosystems-network-map.md (este archivo) actúa como índice.

Adjuntar carpeta projects/electrosystems-network-map/:

projects/electrosystems-network-map/
├── README.md          # Resumen + cómo navegar la KB
├── ALIASES.md         # Tabla maestra de aliases → slugs (todos los nombres humanos)
├── SITES.md           # Lista todas-las-localidades con coordenadas lógicas
├── CLIENTS.md         # Lista de clientes con su footprint (sitios y servicios)
├── LINKS.md           # Enlaces backbone/cliente con endpoints y bandwidth esperado
├── PLAYBOOKS.md       # Playbooks de triage por caso (A/B/C arriba)
└── sites/
    ├── _INDEX.md
    └── <site-slug>.md  # Un archivo por sitio físico

Nivel 2 — Sitio

Cada sites/<slug>.md documenta un sitio físico: localidad, equipos, enlaces, clientes ahí servidos. Ej. sites/san-julian.md, sites/mina-dolores.md, sites/villa-ahumada.md, sites/jacala.md.

Frontmatter:

---
site: <slug>
aliases: [<nombre-humano>, ...]
type: pop | customer-premise | datacenter | aggregation
clients: [<client-slug>, ...]
upstream_site: <site-slug>      # para correlación
downstream_sites: [<site-slug>] # POPs que cuelgan
created: YYYY-MM-DD
updated: 2026-05-29
---

Cuerpo:

• Equipos en sitio (tabla: hostname, role, vendor, IP, SSH/GUI, oxidized?, UISP?, monitoreo? con link a IDs).
• Enlaces upstream/downstream.
• Clientes servidos desde aquí.
• Notas operativas (acceso físico, contactos, peculiaridades — sin nombres propios en código pero docs del hub son la excepción, [[feedback_no_client_names_in_code]]).
• Histórico de incidentes relevantes (append-only).

Nivel 3 — Enlace

Sub-bloque dentro del archivo de sitio (cuando un sitio tiene varios enlaces). O archivo sites/<slug>-<enlace>.md separado si el enlace tiene complejidad propia (caso telcel-jacala ya existe como proyecto).

Para cada enlace:

• Endpoints (sitio A ↔ sitio B), tecnología (PtP RF, fibra, L2L, túnel).
• Bandwidth nominal y baseline observado.
• IDs en UISP/monitoreo si están instrumentados.
• Cap aplicado (importante para casos como [[project_benito_juarez_service]]).

Plan de fases para construir la KB

Fase 0 — Diseño y validación (próxima sesión)

• Validar la estructura propuesta con Sergio.
• Decidir si la KB vive solo aquí (~/agy/projects/electrosystems-network-map/) o si parte se va a ~/agy/electrosystems/ (donde ya está INVENTORY.md). Recomendación: el mapa lógico de clientes/sitios/enlaces vive aquí; los perfiles de hosts individuales siguen en ~/agy/electrosystems/servers/<host>/. La KB los referencía con links relativos.
• Producir ALIASES.md mínimo con 10-15 aliases de uso frecuente para destrabar los casos A/B/C en la siguiente sesión.

Fase 1 — Cosecha automática

Generar borradores leyendo lo que ya existe:

• Parsear ~/.ssh/config y ~/.ssh/config.d/* → lista plana de hosts conocidos.
• Parsear ~/agy/electrosystems/INVENTORY.md y servers/<host>/README.md → hostnames, IPs, roles.
• Consultar monitoreo MySQL (sitios, dispositivos, enlaces — confirmar schema) → catálogo monitoreado.
• Consultar UISP API → catálogo Ubiquiti managed.
• Consultar oxidized router.db → equipos respaldados.
• Cross-referenciar las 4 fuentes; flaggear discrepancias (host en SSH config pero no en monitoreo, etc.) — eso ya es valor de la sesión monitoring-homologation, reutilizar.

Output: un primer pase de sites/_INDEX.md con stubs por sitio inferido de los datos.

Fase 2 — Llenado guiado por Sergio

Sesión donde Sergio llena los huecos que las fuentes no tienen: aliases humanos (“San Julián” → qué cliente, qué sitio, qué enlace), upstreams lógicos, bandwidth esperado por enlace, prioridad de cliente.

Patrón recomendado: ir cliente por cliente (no sitio por sitio). Empezar por los más activos en el monitoreo.

Fase 3 — Playbooks de triage

Escribir PLAYBOOKS.md con el flujo exacto para los casos A/B/C arriba. Cada uno es una receta de pasos read-only que yo puedo ejecutar cuando Sergio dispara el prompt correspondiente.

Fase 4 — Mantenimiento

• Cada vez que se toca un sitio nuevo (incidente, alta de cliente, decommission), actualizar el archivo del sitio.
• Stale check periódico: comparar monitoreo actual vs la KB; flaggear sitios/dispositivos nuevos sin doc.

Decisiones marco abiertas

1. Ubicación final de la KB: solo en ~/agy/ (este hub) vs partido entre hub + ~/agy/electrosystems/. Recomendación inicial arriba — confirmar con Sergio.
2. Granularidad del archivo por sitio: todos los sitios con archivo dedicado, o solo los que tienen ≥ N equipos/enlaces. Sitios chicos podrían compartir un sites/_misc.md.
3. Aliases multi-cliente: ¿qué hacer con nombres reutilizados (ej. “Hércules” como nombre de sitio + “Hercules” como hostname interno)? Probable: ALIASES.md con desambiguación contextual.
4. ¿Generar live o cachear? Para casos en vivo (B y C), ¿queremos que yo consulte siempre monitoreo/UISP en tiempo real, o que la KB tenga un snapshot diario? Recomendación: KB con snapshot + ruta para consulta live cuando importa.
5. Privacidad / secretos: la KB no debe contener community SNMP, passwords ni tokens. Los aliases SSH ya están en ~/.ssh/config (no aquí); credenciales de UISP/monitoreo viven en .env de los servers. Recordatorio [[ANTIGRAVITY.md hub]].
6. Relación con monitoring-homologation: ese proyecto ya está cerrando huecos UISP↔monitoreo. La KB no debe duplicar — debe referenciar. Confirmar punto de corte: la KB se queda con la vista operativa por cliente/sitio; monitoring-homologation con la vista técnica por dispositivo.

Notas técnicas

Convenciones propuestas

• Slugs kebab-case, en inglés (consistente con resto del hub), pero aliases en español porque Sergio dicta así.
• Coordenadas lógicas en lugar de geográficas: upstream_site apunta al siguiente hop relevante (POP, datacenter), no a lat/lon.
• No nombres propios en archivos canónicos ([[feedback_no_client_names_in_code]]) salvo en clients/<slug>.md que ya es la excepción documental.

Antifragilidad

• La KB debe fallar bien: si Sergio menciona un sitio no documentado, yo respondo “no lo tengo en el mapa, ¿es o ?” — no inventar. Documentar la regla aquí.
• La KB debe ser navegable sin grep: el README.md y _INDEX.md deben permitirme llegar a la respuesta en ≤3 saltos.

Riesgos

• Stale: la red cambia (clientes nuevos, decommissions, IPs renumeradas). Sin disciplina, la KB se desactualiza y empeora el triage. Mitigación: cosecha automática reincidente (Fase 4).
• Mezcla con ~/agy/electrosystems/: ya hay INVENTORY.md ahí. Cuidar de no duplicar — solo referenciar.
• Sobrediseño: si la KB es muy elaborada, Sergio no la mantiene. Empezar mínimo viable (Fase 0 + 1 + parte de 2 con 3-5 clientes piloto), validar, expandir.

Tareas pendientes

• (2026-05-25 s2) Fase 0 — decisiones marco: 4 estructurales cerradas con recomendaciones; 2 implícitas (multi-cliente / secretos).
• (2026-05-25 s2) Fase 0 — aliases casos A/B/C: San Julián / Mina Dolores / Hércules resueltos en ALIASES.md.
• (2026-05-25 s2) Fase 1 — cosecha SQL: sitios/dispositivos/enlaces cosechados de monitoreo MySQL.
• (2026-05-25 s2) Fase 1 — cosecha UISP: 399 devices clasificados por 13 regiones; gap ELP/JRZ/NOG confirmado.
• 📅 2026-06-05 — Fase 1 — resto:
  • Cosechar oxidized router.db (~210 + 158 blackBox) — opcional, ya tenemos UISP completa.
  • Cosechar monitoreo monitoreos_dispositivos para saber qué OIDs específicos se polean por enlace (input para PLAYBOOKS).
• 📅 2026-06-12 — Fase 2 — llenado guiado por Sergio:
  • Confirmar upstream lógico entre POPs: ¿chihuahua via router-totalplay? ¿parral via izzi? ¿hercules cómo llega a internet? ¿caborca/villa-ahumada cómo se cuelgan?
  • Resolver sitio fantasma nazareno (eliminar o re-activar).
  • Decidir si crear stubs para sitios UISP-only (ELP/JRZ/NOG) o queda fuera del scope KB operativa.
  • Llenar CLIENTS.md con servicios concretos por cliente ES (los 19+ clientes con SSH alias) — qué servicios, bandwidth, prioridad.
• 📅 2026-06-20 — Fase 3 — pulir PLAYBOOKS.md tras primer triage en vivo: refinar caso A (qué OID específico mirar en cada Telcel L2L), caso B (procedimiento para enlace de 1 solo AP como Mina Dolores), caso C (queries específicas a monitoreo.alertas/monitoreo.lecturas_historicas para extraer grupos).
• 📅 sin-fecha — Fase 4 — stale-check: definir cadencia (¿semanal? ¿con cada incidente?) y qué comparar (monitoreo dispositivos actuales vs KB).

En progreso

• KB con base sólida: 12 POPs documentados (5 con archivo dedicado, 7 en _misc.md), 29 enlaces clasificados, 3 aliases críticos resueltos, regla “todos los Telcel son L2L” capturada. Lista para usarse en triage real. Próxima sesión: triage real + iterar PLAYBOOKS, o completar Fase 2 (upstreams + CLIENTS detallado).

Bitácora

2026-05-25 (sesión 2 — cosecha SQL + UISP + aliases)

• Pidió Sergio: “hazme las preguntas necesarias sobre las decisiones y los aliases. Autorizo SELECT read-only contra monitoreo y la UISP API”.
• Decisiones marco cerradas (las 4 estructurales):
  1. KB solo en ~/agy/.
  2. Archivo dedicado por POP + clientes grandes; chicos en _misc.md.
  3. Snapshot cosechado + consulta live cuando importa.
  4. KB = vista operativa por cliente/sitio; monitoring-homologation = vista técnica por dispositivo. No duplicar.
  • Quedan implícitas con recomendación las otras 2 (#3 aliases multi-cliente con desambiguación contextual, #5 sin secretos — son no-brainers documentadas).
• Aliases resueltos (3 críticos):
  • “San Julián”: sitio en región Parral. Tres cosas comparten el nombre: (a) el enlace Telcel L2L Telcel Bernal-San Julián (id 14), (b) la mina San Julián cliente — tráfico va por el backbone propio (Netonix San Julián 192.168.44.53), no por el Telcel, (c) el sitio físico San Julián (relay del backbone). Desambiguación contextual en ALIASES.md.
  • “Mina Dolores”: NO es sitio independiente — es un enlace (id 2) del sitio Chihuahua con un solo AP (AP Capellina-Mina Dolores B5c 192.168.37.34, Mimosa B5c). Punto único de falla. Internet + voz (la voz va sobre el mismo enlace).
  • “Hércules”: POP de monitoreo puro — ES no entrega servicios a clientes en esa región, solo tiene internet contratado para sostener el collector monitoreo-hercules que monitorea 2 enlaces Telcel (Hércules + La Perla).
• Regla estructural confirmada: todos los enlaces Telcel son L2L. Telcel entrega un puerto en cada lado; ES monitorea ifIn/Out + errors del lado nuestro. Aplica a 10 enlaces identificados en la cosecha.
• Cosecha SQL (monitoreo MySQL):
  • Schema confirmado: sitios (12 activos es_collector=1), dispositivos (768 vivos), enlaces (29 vivos), dispositivo_enlace (pivot con posicion).
  • 12 sitios reales monitoreados: chihuahua (468 devs, 9 enlaces), parral (174, 6), caborca (63, 3), hercules (26, 2), torreon (8, 1), tepehuanes (6, 1), namiquipa/nexpa/colonia-del-valle (5, 1 c/u), villa-ahumada (4, 2), barretal (3, 1), jacala (1, 1).
  • 29 enlaces clasificados: 10 Telcel L2L (incluyendo Hércules y La Perla que no llevan “Telcel” en el nombre), 3 backbones propios RF (Chihuahua/Caborca/Parral), 16 enlaces cliente directos.
  • Sitio fantasma nazareno: existe sitio + enlace Telcel con 3 posiciones vacías. Soft-deleted o pre-deploy. Confirmar con Sergio.
• Cosecha UISP API (/nms/api/v2.1/devices):
  • 399 devices totales (180 blackBox + 102 airMax + 64 airFiber + 49 erouter + 4 eswitch). Mayor que los 210 del changelog 2026-04-29 — han subido blackBox.
  • 13 regiones por prefix [REG]: CHI 173 / PAR 74 / ELP 37 / CAB 33 / JRZ 32 / NOG 11 / NAM 9 / NEX 8 / COL 6 / TEP 6 / VIL 5 / BAR 3 / JCL 1.
  • Confirma el gap real: ELP / JRZ / NOG NO tienen collector en monitoreo MySQL pero SÍ están instrumentados en UISP. Para triage en esas regiones, el playbook tiene que ir a UISP API directo.
• Archivos creados/actualizados en la KB:
  • ALIASES.md: Mina Dolores fix + San Julián 3-cosas + Hércules + regla L2L Telcel.
  • SITES.md: tabla canónica de 12 sitios cosechados + tabla UISP por región + gap ELP/JRZ/NOG.
  • LINKS.md: 29 enlaces clasificados (10 Telcel L2L + 3 backbones + 16 cliente) con dispositivos clave.
  • sites/chihuahua.md (caso B Mina Dolores), sites/parral.md (caso A San Julián), sites/hercules.md (caso aclarado), sites/villa-ahumada.md (cliente Benito Juárez), sites/caborca.md, sites/_misc.md (7 sitios chicos), sites/_INDEX.md.
  • PLAYBOOKS.md mantenido sin cambios — ya cubre los 3 casos; falta iterar tras primer triage en vivo.
• Falta:
  • Confirmar upstream lógico entre POPs (¿chihuahua via totalplay? ¿parral via izzi? ¿hercules cómo llega a internet?). Una pregunta a Sergio en próxima sesión.
  • Resolver sitio fantasma nazareno.
  • Cruzar UISP devices ↔ monitoreo dispositivos para identificar duplicados/divergencias (eso ya es trabajo activo en monitoring-homologation).
  • Crear stubs para sitios UISP-only ELP/JRZ/NOG si Sergio quiere instrumentación operativa también allá.
  • Cosechar monitoreo monitoreos_dispositivos para saber qué OIDs específicos se polean en cada enlace Telcel (para refinar el PLAYBOOKS).
  • Iterar PLAYBOOKS tras primer triage en vivo.

2026-05-25

• Pidió Sergio: “vamos a seguir con el proyecto electrosystems-network-map”.
• Hice:
  • Tomé las recomendaciones del propio doc para las 6 decisiones marco como tentativas (KB en hub, archivo por POP, desambiguación contextual, snapshot+live, sin secretos, KB=vista operativa por cliente/sitio referenciando perfiles de hosts en ~/agy/electrosystems/servers/<host>/).
  • Creé la carpeta electrosystems-network-map/ con esqueleto completo: README.md, ALIASES.md, SITES.md, CLIENTS.md, LINKS.md, PLAYBOOKS.md, sites/_INDEX.md.
  • Cosecha automática parcial (Fase 1): parseé ~/.ssh/config (62 hosts) + ~/agy/electrosystems/INVENTORY.md (17 server profiles) y derivé: 14 regiones operativas (10 con monitoreo-<region> collector, varias con router-<region> de borde), ~19 clientes ES con SSH alias, 4 clientes Sergio freelance, 15 hosts ES infra. Cruzado con el changelog de INVENTORY (regiones UISP [CHI]/[PAR]/[ELP]/[CAB]/[NOG]/[NAM]/[COL]/[VIL], 210 managed + 158 blackBox).
  • PLAYBOOKS.md con drafts paso a paso de los 3 casos (A enlace Telcel, B sitio sin servicio, C N notificaciones). Incluí distinción explícita del caso “false-positive plantilla” para el patrón ifIndex Cambium que ya vimos el 2026-05-20.
  • Marqué los 3 aliases sin resolver de casos A/B/C en ALIASES.md: San Julián, Mina Dolores, Hércules. Listos para que Sergio los conteste en la próxima ronda.
  • Cambié frontmatter del proyecto a status: active, updated: 2026-05-25. Reestructuré tareas pendientes por fase.
• Falta:
  • Sergio confirma/ajusta las 6 decisiones marco aplicadas.
  • Resolver los 3 aliases pendientes (puramente input de Sergio).
  • Fase 1 restante: cruzar con monitoreo MySQL, UISP API, oxidized router.db (requiere SSH read-only — autorizado por default según [[feedback_prod_read_only_diagnostics_authorized]] pero quiero confirmar con Sergio antes de meter ruido en monitoreo).
  • Stubs detallados por POP en sites/<slug>.md (Fase 2).

2026-05-20

• Pidió Sergio: anotar nuevo proyecto. Documentación completa de las estructuras de red de Electrosystems para que yo (Claude) pueda usarla en sesiones futuras de triage. Objetivo final: poder atender prompts tipo “revisa el enlace de Telcel de San Julián”, “Mina Dolores no tiene servicio”, “me llegaron N notificaciones de caída”. Aclaró: ahora no se ejecuta, solo documentar el proyecto.
• Hice: capturado el proyecto con (a) objetivo operativo, (b) 3 casos de uso objetivo concretos con flujos esperados, (c) inventario de fuentes de datos disponibles y cómo consultar cada una (monitoreo/es-antenas-new, UISP, Oxidized, Nagios, NetBox, ~/.ssh/config, perfiles en ~/agy/electrosystems/servers/, WireGuard, Telegram, Gmail), (d) estructura propuesta a 3 niveles (mapa global / sitio / enlace), (e) plan de 4 fases (diseño → cosecha automática → llenado guiado → playbooks → mantenimiento), (f) 6 decisiones marco abiertas, (g) convenciones / antifragilidad / riesgos. Vinculado bidireccionalmente con proyectos relacionados (es-antenas-new, monitoreo-collector, monitoring-homologation, backup-system, backups-infra, vpn-clientes, wireguard-jrz-elp, telcel-jacala, cpe-benito-juarez).
• Falta: todo. El proyecto es captura. Próxima sesión arranca por Fase 0 cuando Sergio priorice. Recomendación al retomar: empezar por ALIASES.md mínimo con los términos exactos de los casos A/B/C, para destrabar el triage de inmediato sin esperar a la cosecha completa.