Agente · dev-rack-editor

Propósito

Desarrollo y mantenimiento del Rack Editor de CreaRack-Pro. Cubre la app racks/, los 20 módulos JS del editor, el canvas Konva.js, el sistema de stencils, SSH integrado y backups de configuración.

Estructura de archivos

Frontend: static/js/editor/ (20 archivos, ~7.500 LOC)

Backend: racks/

racks/
├── models.py              # BoxCategory, RackGroup, Stencil, Rack, Device, ConfigBackup
├── views.py               # rack_editor (canvas), index (lista racks)
├── schemas.py             # Pydantic schemas
└── api/
    ├── racks.py           # CRUD racks + dispositivos (~360 LOC)
    ├── library.py         # Stencils + Visio import (~745 LOC)
    ├── export.py          # CSV/JSON/PDF export (~1023 LOC)
    ├── labels.py          # QR labels API
    └── trash.py           # Papelera racks

Estado global (state.js)

export const STATE = {
    rackData: null,         // Datos del rack cargados del DOM (#rack-data)
    devices: [],            // Array de dispositivos con nodos Konva
    selectedNode: null,     // Nodo Konva actualmente seleccionado
    isLocked: false,        // Bloqueo de interacción del canvas
    currentDragItem: null,  // Item arrastrándose desde la librería
    stage: null,            // Konva.Stage
    layer: null,            // Konva.Layer principal
    rackGroup: null,        // Konva.Group del frame del rack
    pos: { x: 50, y: 50 }, // Posición del rack en el canvas
    CONFIG: {
        U_HEIGHT: 35,       // Pixeles por unidad de rack (U)
        RACK_WIDTH: 400,    // Ancho fijo del rack en pixeles
        RACK_HEIGHT: 0      // Calculado: height_u × U_HEIGHT
    }
};

export const SLOT = { FULL: 'full', LEFT: 'left', RIGHT: 'right' };
export const HALF_WIDTH = 195;  // (RACK_WIDTH - 10) / 2

Estructura de un dispositivo en STATE.devices[]

{
    type: "switch",
    originalName: "Cisco 2960",
    u_height: 1,
    u_position: 15,          // Posición U desde abajo
    notes: "",
    image: "/media/uploads/...",
    db_id: 42,               // null si es nuevo (no guardado aún)
    half_width: false,
    slot: "full",            // "full" | "left" | "right"
    ports: {
        "eth0": { live: "up", label: "WAN", desired: "trunk" },  // formato enriquecido
        "sfp1": "10G"        // formato legacy (string)
    },
    management_config: { ip: "192.168.1.1", vendor: "cisco" },
    meta: { ports: {...}, notes: "...", half_width: false },
    konvaNode: Konva.Group   // Referencia al nodo visual
}

Konva.js — estructura visual

Konva.Stage (draggable, zoom con wheel)
└── Konva.Layer
    ├── STATE.rackGroup (Konva.Group)
    │   ├── Rect (fondo del rack)
    │   ├── Lines (separadores de U)
    │   └── Text (números de U: 1, 2, 3...)
    ├── DeviceGroup_1 (Konva.Group, draggable)
    │   ├── Rect (fondo), Image (stencil), Text (nombre)
    ├── DeviceGroup_2 ...
    └── DeviceGroup_N ...

Conversión coordenadas ↔ posición U

// U → Y pixel
y = STATE.pos.y + (RACK_HEIGHT - u_position × U_HEIGHT)

// Y pixel → U (al hacer drop/drag-end)
uPosition = (RACK_HEIGHT - (yRelative + deviceHeight)) / U_HEIGHT + 1

Snap y colisiones (devices.js)

Snap (dragBoundFunc)

• Distancia snap: 60px a los raíles del rack
• Full-width: snap al raíl izquierdo (STATE.pos.x)
• Half-width: snap a LEFT o RIGHT según proximidad al centro
• Vertical: snap a incrementos de U_HEIGHT (35px)

Detección de colisiones

Flujo drag-end

dragend →
  1. Validar dentro de límites del rack
  2. Calcular u_position desde Y pixel
  3. checkCollision(targetU, uHeight, slot)
  4. Si colisión → revertir posición anterior
  5. Si válido → actualizar device.u_position y device.slot
  6. Disparar auto-save

Undo/Redo (history_adapter.js)

Usuario edita → saveState() → createSnapshot() → STATE_MANAGER.push(snapshot)
Usuario Ctrl+Z → STATE_MANAGER.undo() → restoreState(snapshot)
                                              → limpia STATE.devices
                                              → re-crea nodos Konva
                                              → restaura selección
                                              → dispara auto-save

Auto-save (editor_api.js)

Debounce 500ms. Serializa STATE.devices y envía:

PUT /api/racks/{rackId}/devices
Body: { devices: [{ db_id, type, name, u_position, u_height, notes,
                    image, half_width, slot, ports, management_config }] }

Panel de propiedades

Secciones (PropertiesPanelRenderer.js)

1. Cabecera: nombre editable, tipo
2. Imagen: preview stencil
3. Posición: U position (lectura) + altura en U
4. Management Config: IP, vendor, hostname
5. Puertos Ethernet: grid hasta 48 puertos (formato enriquecido o legacy)
6. Puertos SFP: grid hasta 8 puertos (layout 2 columnas)
7. Notas: textarea editable
8. Acciones: Delete, Clone, Save to Library, QR, SSH, Backups

Formato de puertos

// Enriquecido (preferido)
{ "eth0": { "live": "up", "label": "WAN", "desired": "trunk" } }

// Legacy (string simple)
{ "eth0": "connected" }

El renderer detecta automáticamente el formato.

Eventos clave (PropertiesPanelEvents.js)

Sistema de stencils (ui_library.js)

Estructura de un stencil

{
    id: 123,
    name: "Cisco Catalyst 2960",
    image_path: "/media/uploads/stencils/cisco_2960.png",
    default_u_height: 1,
    manufacturer: "Cisco",
    category: "Switches",
    extra_data: '{"half_width": false, "ports": {...}}'
}

Drag desde librería al canvas

1. Stencil con data-id, data-name, data-type, data-height, data-image
2. dragstart → metadata en STATE.currentDragItem
3. drop sobre canvas → calcula U desde coordenadas del mouse
4. addDeviceToRack() con datos del stencil
5. STATE.currentDragItem = null

Importación Visio (pipeline 2 pasos)

1. POST /api/racks/visio/analyze (FormData .vssx/.vdx/.vss) → session_id + masters encontrados
2. POST /api/racks/visio/confirm { session_id, masters, category_name } → crea stencils
3. DELETE /api/racks/cleanup/session/{id} → limpia archivos temporales

Auto-Provision Panel (auto_provision_panel.js)

Lee localStorage['auto_provision_pending'] al cargar el editor:

// Formato v2 (actual)
{
    version: 2,
    racks: {
        "rack_42": [
            { name: "SW-Core-01", type: "switch", stencil_id: 123,
              management_config: { ip: "10.0.1.1", vendor: "cisco" } }
        ]
    }
}

Solo muestra dispositivos pendientes para el rack actual. Al arrastrar un stencil al canvas, el management_config se auto-rellena desde el pending device y se elimina del localStorage.

SSH Integration

Flujo de conexión

1. Usuario click “SSH” en panel de propiedades
2. SshConfigModal muestra formulario con datos de management_config
3. Check de alcanzabilidad: GET http://localhost:5050/check?host={ip}&port={port}
4. Usuario confirma → openSSHSession(deviceId, displayName)
5. Modal con terminal xterm.js embebido
6. WebSocket: ws://localhost:5050/ws/terminal/{sessionId} via Local Agent

Estado global SSH

window.editorSSHClient   // Instancia SSH activa
window.editorDeviceId    // ID del dispositivo conectado
window.editorSFTP        // Instancia SFTPFileManager

Backups de configuración (backups.js)

Snapshots de running-config via SSH.

Vendors soportados: Cisco IOS/IOS-XE · Arista EOS · Juniper JunOS

SFTP Sidebar (sftp_ui.js)

sftp_ui.js → HTTP → Local Agent :5050 → asyncssh → Dispositivo de red

Endpoints Agent:

Modelos Django

Rack

class Rack(models.Model):
    name, location, notes
    height_u = IntegerField(default=42)
    status   # active | planned | deprecated | maintenance
    organization = FK(Organization)
    groups = M2M(RackGroup)
    deleted_at = DateTimeField(null=True)  # Soft delete
    is_template = BooleanField(default=False)

Device

class Device(models.Model):
    rack = FK(Rack, on_delete=CASCADE)
    name, notes
    u_position = IntegerField()
    u_height = IntegerField(default=1)
    model_data = TextField(default="{}")         # JSON: half_width, slot, ports, image, type
    management_config = TextField(default="{}")   # JSON: ip, vendor (credenciales Fernet encrypted)
    status  # online | offline | warning | unknown

    @property
    def management_ip(self)     # Extrae IP de management_config
    @property
    def management_vendor(self)  # Extrae vendor de management_config

Stencil

class Stencil(models.Model):
    name, image_path
    default_u_height = IntegerField(default=1)
    manufacturer, category
    extra_data = TextField(default="{}")   # JSON: half_width, ports
    organization = FK(Organization, null=True)  # null = stencil global del sistema

ConfigBackup

class ConfigBackup(models.Model):
    device = FK(Device), rack = FK(Rack)
    config_text = TextField()              # Running-config completo
    config_hash = CharField(max_length=64) # SHA256
    backup_type  # auto | manual | pre_change
    vendor, device_version
    created_by = FK(User, null=True)

API Endpoints (41+ bajo /api/racks/)

Racks CRUD

Stencils y librería

Export, Labels, Trash

Flujo de carga del editor

GET /editor/{rack_id}/
    ↓ Django → template editor.html
    ↓ main.js bootstrap
    ├── Lee #rack-data del DOM → STATE.rackData
    ├── Calcula CONFIG.RACK_HEIGHT = height_u × U_HEIGHT
    ├── konva_setup.js → Stage, Layer, rackGroup
    ├── fitRackToView() → centra rack en viewport
    ├── devices.js → addDeviceToRack() por cada device
    ├── ui_library.js → carga stencils en panel izquierdo
    ├── auto_provision_panel.js → check localStorage pending
    └── history_adapter.js → snapshot inicial

Convenciones y restricciones

• El auto-save tiene debounce 500ms — no llamar a PUT /api/racks/{id}/devices directamente, usar triggerAutoSave()
• Siempre guardar snapshot Undo antes de operaciones destructivas: dispatchEvent('request-save-history')
• Los nodos Konva se destruyen con konvaNode.destroy() — no eliminar del array STATE.devices sin destruir el nodo primero
• management_config en el modelo Device tiene credenciales cifradas con Fernet — no acceder directamente, usar _decrypt_if_needed()
• Stencils con organization=null son globales del sistema — no eliminarlos desde la UI de organización
• Soft delete en Rack: usar rack.soft_delete() — nunca rack.delete()
• Formato de puertos enriquecido {live, label, desired} es el preferido para nuevos dispositivos — el renderer soporta ambos pero el legacy (string) es solo para retrocompatibilidad

Véase también

• [[concept—racks—editor]] — concepto del Rack Editor
• [[crearack-tech—backend—rack-editor]] — implementación backend del Rack Editor
• [[crearack—conceptos—rack-editor-conceptos]] — conceptos base del Rack Editor
• [[crearack—racks—crear-rack]] — crear un rack desde la UI
• [[crearack—racks—dispositivos]] — dispositivos dentro del rack
• [[crearack—racks—stencils-crear]] — crear stencils personalizados
• [[entity—racks—model—rack]] — modelo principal del Rack Editor
• [[entity—racks—model—device]] — dispositivos instalados en un rack
• [[entity—racks—model—stencil]] — plantillas visuales de dispositivos