Esquemas

Los esquemas son diagramas de relaciones interactivos que capturan cómo se conectan los activos entre sí — no solo dónde están en el mapa. Úselos para modelar circuitos eléctricos, rutas de empalme de fibra, relleno de conductos, etapas de flujo de aguas residuales o cualquier otra relación lógica difícil de ver únicamente en una vista geográfica. Los esquemas tienen control de versiones y pueden vincularse directamente a entidades del mapa.

¿Qué Son los Esquemas?

Esquemas vs. Entidades del Mapa:

Las Entidades del Mapa muestran dónde están las cosas (relaciones espaciales, geografía)
Los Esquemas muestran cómo se conectan las cosas (relaciones lógicas, dependencias)

Casos de Uso:

Redes de Servicios Públicos

Modelar circuitos eléctricos (postes → transformadores → puntos de servicio)
Mostrar rutas de cables a través de conductos
Visualizar flujos de capacidad a través de segmentos de red

Flujos de Procesos

Etapas de una planta de tratamiento de aguas residuales
Dependencias de un proceso de fabricación
Enrutamiento de la cadena de suministro

Jerarquías Organizativas

Dependencias de mantenimiento de equipos
Cadenas de propiedad de activos
Rutas de prestación de servicios

Conexiones Físicas

Diagramas de empalme de fibra óptica
Topología de red de fontanería
Conexiones de conductos de HVAC

Interfaz del Editor de Esquemas

El Editor de Esquemas aparece en una ventana emergente desde la barra de herramientas de la página del mapa. Ofrece un editor de diagramas con todas las funciones, con algoritmos de diseño automático y posicionamiento manual.

Componentes Principales

Lienzo del Diagrama (centro)

Visualización interactiva de nodos y aristas
Arrastre los nodos para reposicionarlos manualmente
Haga clic en los elementos para seleccionarlos y editarlos
Zona de colocación para añadir entidades desde el mapa

Barra de Herramientas (abajo)

Añadir Nodo - Crear nodos del diagrama (personalizados o vinculados a entidades del mapa)
Añadir Arista - Crear conexiones entre nodos
Selector de Diseño - Elegir algoritmo de diseño automático
Diseño Automático - Aplicar el diseño seleccionado para borrar todas las posiciones manuales
Actualizar - Reinicializar el diagrama a partir de los datos

Editor de Elementos (panel inferior)

Editar las propiedades del nodo o arista seleccionado
Editor de código para la manipulación JSON avanzada
Formulario visual para propiedades comunes
Eliminar con confirmación (reversible mediante versiones)

Panel de Metadatos (arriba)

Nombre del esquema (editable en línea)
Propiedades personalizadas (pares clave-valor)
Integración con la gestión de versiones

Creación de Esquemas

Paso 1: Crear un Esquema

Abra la página del mapa (https://demo.aptli.io/map)
Haga clic en Barra de Herramientas del Mapa → botón Esquemas
El Editor de Esquemas se abre en una ventana emergente
Aparece un lienzo de diagrama vacío

Paso 2: Añadir Nodos

Opción A: Nodos Personalizados (no vinculados al mapa)

Haga clic en el botón Añadir Nodo
Seleccione el modo Personalizado (predeterminado)
Introduzca el nombre del nodo (p. ej., "Transformador A")
Elija el tipo de geometría: Point, LineString o Polygon
Haga clic en Confirmar

Opción B: Desde Entidades Existentes del Mapa

Haga clic en el botón Añadir Nodo
Cambie al modo Desde Entidad
Seleccione la entidad en el desplegable (muestra todas las entidades del mapa)
Haga clic en Confirmar (el nodo se vincula a la entidad mediante featureId)

Opción C: Arrastrar desde el Mapa

Localice la tarjeta de entidad en la interfaz del mapa
Arrastre la tarjeta de entidad al Editor de Esquemas
Suelte sobre el lienzo (dentro del área con borde discontinuo)
Se crea automáticamente un nodo con el tipo de geometría detectado

Paso 3: Añadir Conexiones (Aristas)

Haga clic en el botón Añadir Arista
Seleccione el nodo Origen en el desplegable
Seleccione el nodo Destino en el desplegable
Opcionalmente introduzca una etiqueta para la arista (p. ej., "alimenta", "capacidad: 100 A")
Haga clic en Confirmar

Múltiples Aristas:

Los mismos dos nodos pueden tener múltiples aristas (sin límite)
Útil para flujos bidireccionales o distintos tipos de relaciones
Ejemplo: Nodo A → Nodo B (suministro), Nodo B → Nodo A (retorno)

Paso 4: Organizar el Diseño

Diseños Automáticos (desde el desplegable):

Cuadrícula 2×2, 3×3, 4×4, 5×5 - Disposiciones fijas en cuadrícula
Círculo - Nodos dispuestos en círculo
Breadth First - Diseño de árbol jerárquico (grafos dirigidos)
Concéntrico - Anillos basados en conectividad
Aleatorio - Nodos dispersos al azar

Posicionamiento Manual:

Seleccionar un preset de diseño u omitir
Arrastrar nodos individuales a las posiciones deseadas
Las posiciones manuales se guardan en los datos de la versión
Las posiciones manuales tienen prioridad sobre los algoritmos de diseño

Restablecer Diseño:

Haga clic en el botón Diseño Automático → borra todas las posiciones manuales
Vuelve a aplicar el algoritmo de diseño seleccionado en el desplegable

Paso 5: Editar Elementos

Seleccionar Elemento:

Haga clic en cualquier nodo o arista del lienzo
El panel Editor de Elementos aparece abajo

Editar Propiedades del Nodo:

Nombre - Etiqueta de visualización (edición en línea o editor de código)
Tipo de Geometría - Point, LineString o Polygon
Enlace a Entidad - featureId que conecta con la entidad del mapa
Propiedades Personalizadas - Añadir cualquier dato clave-valor

Editar Propiedades de la Arista:

Etiqueta - Descripción de la conexión
Origen - Nodo de inicio (cambiar mediante editor de código)
Destino - Nodo final (cambiar mediante editor de código)

Editor de Código (Avanzado):

Haga clic en Mostrar Código en el Editor de Elementos
La representación JSON aparece en el área de texto
Edite directamente (estructura completa del elemento)
Haga clic en Formatear JSON para imprimir con formato
Haga clic en Aplicar Cambios (valida con esquema Zod)
Se muestran errores de validación si la estructura no es válida

Eliminar Elemento:

Seleccionar el elemento
Hacer clic en el botón Eliminar en el Editor de Elementos
Aparece el diálogo de confirmación de eliminación
El elemento se elimina (el cambio se registra en el historial de versiones)

Configuración del Diseño

Cada esquema guarda su algoritmo de diseño preferido en la base de datos. Al reabrir un esquema, aplica automáticamente el diseño guardado.

Diseño Persistente:

La selección del desplegable se almacena por esquema
Predeterminado: Cuadrícula 3×3
El cambio persiste entre sesiones

Manual vs. Automático:

Si ALGÚN nodo tiene posición manual → usa diseño "preset" (respeta posiciones)
Si NINGÚN nodo tiene posición manual → aplica el algoritmo del desplegable
Haga clic en Diseño Automático para borrar posiciones y volver a aplicar el algoritmo

Cambio de Diseños:

Cambiar la selección del desplegable
El diseño se aplica inmediatamente
Todas las posiciones manuales se borran
El nuevo diseño se confirma en el historial de versiones

Gestión de Versiones

Los esquemas utilizan el mismo sistema de versión/confirmación que las entidades del mapa.

Confirmaciones Automáticas:

Cada cambio crea una entrada de versión
Añadir/eliminar nodo → confirmado
Añadir/eliminar arista → confirmado
Editar propiedades del elemento → confirmado
Cambiar diseño → confirmado

Historial de Versiones:

Acceso mediante el Administrador de Versiones (barra de herramientas del mapa)
Revisar todos los cambios del diagrama a lo largo del tiempo
Revertir a estados anteriores
Fusionar ediciones sin conexión de colaboradores
Enviar → Solicitar Confirmación desde la barra de herramientas; los no administradores envían los borradores a la cola del administrador para su aprobación (véase Admin → Versiones)

Edición Sin Conexión:

Crear/editar esquemas sin conexión
Los cambios se almacenan localmente en el almacenamiento del navegador
Sincronizar al volver a estar en línea
Detección de conflictos para ediciones concurrentes

Funciones Avanzadas

Integración con Arrastrar y Soltar

Los esquemas se integran con el sistema de arrastrar y soltar de Aptli:

Del Mapa al Esquema:

Arrastrar tarjetas de entidad desde los paneles de capas
Arrastrar elementos de la lista de entidades seleccionadas
Soltar en el lienzo del Editor de Esquemas
Se crea automáticamente un nodo con enlace featureId

Detección del Tipo de Geometría:

Entidades Point → icono de punto
Entidades LineString → icono de línea
Entidades Polygon → icono de polígono
Los iconos ayudan a identificar los tipos de nodo de un vistazo

Edición de Código en Vivo

El Editor de Código permite la manipulación directa de JSON para usuarios avanzados.

Validación:

Todas las ediciones se validan antes de aplicarse
id es obligatorio (debe ser una cadena no vacía)
geometryType debe ser Point, LineString o Polygon (si está presente)
Las coordenadas de posición deben ser números
Las aristas requieren source y target
Los nodos no pueden tener source ni target

Casos de Uso:

Cambios masivos de propiedades (copiar y pegar JSON)
Añadir relaciones sin UI (source/target manual)
Depurar problemas de estructura de datos
Copiar un elemento a otro esquema

Múltiples Relaciones

A diferencia de muchas herramientas de diagramación, Aptli admite aristas ilimitadas entre los mismos nodos:

Ejemplo - Flujos Bidireccionales:

Transformador A → Punto de Servicio B (suministro eléctrico, 240V)
Punto de Servicio B → Transformador A (datos de telemetría)
Transformador A → Punto de Servicio B (notificaciones de fallos)

Sin Protección Contra Duplicados:

Elección de diseño intencionada
Algunas relaciones están auténticamente duplicadas
El usuario es responsable de gestionar el número de aristas
El editor de código muestra todas las aristas para su revisión

Propiedades Personalizadas

Tanto los nodos como las aristas admiten propiedades personalizadas:

Propiedades a Nivel de Esquema:

Editar en el panel de metadatos (parte superior del editor)
Pares clave-valor almacenados como JSON
Usar para metadatos de todo el diagrama
Ejemplos: "voltage: 240V", "network_segment: north"

Propiedades a Nivel de Elemento:

Editar mediante el editor de código (objeto data)
Añadir cualquier campo más allá de la estructura estándar
Las propiedades extra se conservan y se almacenan junto al elemento
Ejemplos: capacity, status, install_date

Integración con Entidades del Mapa

Vinculación de Entidades (featureId):

Los nodos pueden referenciar una entidad del mapa por ID
Bidireccional: clic en el nodo del esquema → resalta la entidad del mapa
Útil para diagramas de red que reflejan la infraestructura real

Nodos Independientes:

Los nodos personalizados no requieren entidades del mapa
Útiles para conceptos abstractos (etapas, procesos, agrupaciones lógicas)
Mezcle nodos vinculados e independientes en el mismo diagrama

Consideraciones de Sincronización:

El esquema no se actualiza automáticamente si se elimina la entidad vinculada
Un featureId huérfano aparece como faltante (gestión manual)
Mejora futura: limpieza automática al eliminar la entidad

Mejores Prácticas

Cuándo Usar Esquemas

Buenos Casos de Uso:

Topología de red difícil de ver en el mapa (zonas densas)
Flujos lógicos que no coinciden con la geografía (rutas de prestación de servicios)
Dependencias de equipos a grandes distancias
Procesos de varias etapas con secuencia clara
Modelado de relaciones independiente de la ubicación

Cuándo NO Usar:

Simple proximidad espacial (use en su lugar herramientas de buffer del mapa)
Visualizaciones puntuales (exporte GeoJSON y use herramientas externas)
Conexiones que cambian con frecuencia (alto coste de mantenimiento)
Diagramas de cara al público (los esquemas son herramientas internas)

Convenciones de Nombres

Nombres de Esquemas:

Sea específico: "Empalme de Fibra Distrito Norte" no "Fibra 1"
Incluya fecha/versión si es temporal: "Plan de Red Q4 2025"
Use referencias de ubicación: "Circuito A del Transformador del Centro"

Nombres de Nodos:

Coincidir con los nombres de las entidades del mapa cuando estén vinculados (autocompletado)
Para nodos personalizados, use identificadores claros: "Etapa 3: Filtración"
Evite nombres genéricos: "Nodo 1", "Punto A"

Etiquetas de Aristas:

Describa la relación: "alimenta", "reporta a", "depende de"
Incluya capacidad: "100A", "10 Gbps", "500 GPM"
Use terminología coherente en el mismo tipo de esquema

Consejos de Gestión de Versiones

Frecuencia de Confirmaciones:

Cada cambio se confirma automáticamente (no hacen falta confirmaciones manuales)
El historial de versiones puede hacerse largo en diagramas activos
Use la compresión de versiones para reducir el almacenamiento (función futura)

Descripciones de Versión:

Actualmente no se capturan en la UI (todas las confirmaciones se generan automáticamente)
Use propiedades del esquema para registrar hitos importantes
Ejemplo de propiedad: "last_audit: 2025-02-14, auditor: jdoe"

Seguridad de la Reversión:

Pruebe la reversión primero en un entorno que no sea de producción
Verifique que todas las entidades vinculadas siguen existiendo tras la reversión
Comuníquese con el equipo antes de reversiones importantes

Consideraciones de Rendimiento

Diagramas Grandes:

Más de 100 nodos pueden ralentizar el renderizado
Considere dividirlos en varios esquemas
Use los algoritmos de diseño (más rápidos que el posicionamiento manual)

Aristas Complejas:

Muchas aristas entre los mismos nodos pueden superponerse
El posicionamiento manual ayuda a separar aristas superpuestas
Mejora futura: enrutamiento/agrupación de aristas

Uso en Móvil:

El Editor de Esquemas está optimizado para escritorio
La vista móvil funciona pero está limitada por el tamaño de la pantalla
Se recomienda como mínimo una tableta para editar

Atajos de Teclado

Nota: los atajos de teclado aún no están implementados. Mejora futura.

Previsto:

Tecla Delete para eliminar el elemento seleccionado
Ctrl+Z / Cmd+Z para deshacer (mediante reversión de versión)
Teclas de flecha para desplazar el nodo seleccionado
Ctrl+C / Ctrl+V para copiar y pegar nodos

Exportación y Compartir

Actual:

Los esquemas se almacenan en la base de datos (no exportables como archivos)
Compartir mediante permisos de usuario (todos los usuarios con acceso al mapa ven los esquemas)
El historial de versiones proporciona un registro de auditoría

Mejoras Futuras:

Exportar como imagen PNG/SVG
Exportar como GraphML/Cypher para herramientas externas
Exportar como JSON para copia de seguridad/migración
Generar URL para compartir una vista específica del esquema

Conceptos del Mapa - Cómo funcionan las entidades del mapa y cómo interactuar con ellas
Gestión de Versiones - Flujo de trabajo de versiones y confirmación utilizado por los esquemas
Interacción con Entidades del Mapa - Seleccionar, editar y trabajar con entidades