Servicio: port_labels — Formato único de etiquetas de puerto (Regla 2)

Propósito

Módulo único de utilidades para formatear etiquetas de puertos en la API y servicios de red. Regla 2: Elimina duplicación literal de las funciones _port_label() y _get_ports() que vivían en:

• network/api/port_connections.py (endpoint CRUD de conexiones)
• network/services/cable_report.py (generador de informes)

Ambas hacían exactamente lo mismo (procesaban puertos de perfiles para generar etiquetas legibles) — ahora fuente única de verdad.

Funciones públicas

format_port_label(port: dict, profile: dict = None) -> str

Genera la etiqueta legible de un puerto.

Entrada:

• port (dict): puerto del perfil, estructura {name, description, speed_bps, direction, ...}
• profile (dict, opt): contexto del perfil si aplica

Salida: string como "ge-0/0/1 (10Gbps ↔)" o "Eth1/47 (1Gbps)".

Lógica:

1. Extrae nombre del puerto (port["name"])
2. Si tiene descripción, la incluye entre paréntesis
3. Si tiene velocidad, formatea con speed_label_to_bps() (p.ej. “10Gbps”)
4. Si tiene direction (envío/recepción), añade flecha (→/←/↔)

Fuente: originalmente en port_connections.py L154 y cable_report.py L391.

get_ports_from_profile(profile: dict, exclude_connected: bool = False) -> list

Extrae la lista de puertos disponibles de un perfil.

Entrada:

• profile (dict): modelo DeviceProfile serializado
• exclude_connected (bool): si True, filtra puertos ya conectados

Salida: lista de dicts [{name, description, speed_bps, ...}, ...]

Lógica:

1. Accede a profile.get("ports", []) o json.loads(profile["ports"]) si es string
2. Ordena por clave numérica (_sort_port_key)
3. Opcionalmente filtra por PortConnection.objects.filter(source_port=puerto)

Fuente: originalmente en port_connections.py L182.

map_to_port_key(port_name: str) -> tuple

Convierte un nombre de puerto a clave de orden (helper para sort).

Entrada: "ge-0/0/1", "Eth1/47", "eth0", etc.

Salida: tupla (tipo_num, modulo, puerto) para sort natural.

Lógica: extrae números de la cadena y los convierte a int para comparación numérica.

Fuente: originalmente en cable_report.py L381.

Integración

Reemplazos directos:

• port_connections.py: importa from network.services.port_labels import format_port_label, get_ports_from_profile
• cable_report.py: importa ídem

Eliminación de duplicados:

• port_connections.py: borra _port_label(), _get_ports(), _sort_port_key()
• cable_report.py: borra _port_label(), _get_ports(), _port_label_legacy()

Historía

Creado en commit 14e9074 (sesión 118, auditoría suprema SA5) como rectificación de hallazgo BAJA/deuda (Regla 2: Duplicación). El análisis de auditoría (auditoria-suprema-network-sa5.js) lo identificó en la sección “Cable Report + Port suggestion”:

_port_label y _get_ports están DUPLICADOS literalmente en port_connections.py y en services/cable_report.py (el comentario L24 lo admite “copied from port_connections API”) → deuda de unificacion.

Esfuerzo de rectificación: S (pequeño).

Véase también

• [[entity—network—endpoint—port-connections]]
• [[entity—network—service—cable-report]]
• [[incident—20260609—auditoria-sa5-red-network]]
• [[concept—architecture—code-reuse]]