system-docs/v4-archive/mind-link/docs/MINDLINK-DOCUMENTACION.md

# MindLink v11 - Documentación

## Descripción General

MindLink es una interfaz de comunicación visual tipo mindmap/linktree para entregar documentos a clientes. Presenta nodos principales (categorías) con subnodos desplegables (documentos) conectados por líneas animadas.

---

## Estructura de Datos

### Configuración General

| Campo | Tipo | Ejemplo | Descripción |
|-------|------|---------|-------------|
| `titulo` | Texto | "Proyecto Demo HST" | Título principal de la página |
| `mostrar_titulo` | Booleano | true | Mostrar/ocultar el título |
| `colores` | Texto | "#FF6B35, #E5A000, #06D6A0" | Colores en hexadecimal separados por comas |
| `fuente` | Texto | "Inter" | Nombre de la fuente tipográfica |

### Fuentes Disponibles

| Valor | Descripción |
|-------|-------------|
| `Inter` | Moderna, muy legible (recomendada) |
| `Roboto` | Google, neutra |
| `Open Sans` | Google, amigable |
| `Montserrat` | Geométrica, elegante |
| `Lato` | Equilibrada, profesional |
| `SF Pro Display` | Apple, premium |
| `system` | Fuente nativa del sistema |

---

### Nodos (Categorías)

| Campo | Tipo | Ejemplo | Descripción |
|-------|------|---------|-------------|
| `id` | Texto | "n1" | Identificador único |
| `titulo` | Texto | "Arquitectura" | Nombre de la categoría |
| `imagen` | URL | "https://..." | Imagen cuadrada (se muestra 120×120px) |
| `subnodos` | Array | [...] | Lista de documentos |

### Subnodos (Documentos)

| Campo | Tipo | Ejemplo | Descripción |
|-------|------|---------|-------------|
| `id` | Texto | "s1" | Identificador único |
| `titulo` | Texto | "Plano General" | Nombre del documento |
| `imagen` | URL | "https://..." | Miniatura 16:9 (se muestra 180×101px) |
| `tiene_preview` | Booleano | true | Icono ojo (esquina superior derecha) |
| `tiene_descarga` | Booleano | true | Icono descarga (esquina inferior izquierda) |
| `tiene_enlace` | Booleano | true | Icono enlace (esquina inferior derecha) |
| `tiene_historial` | Booleano | false | Icono reloj (esquina superior izquierda) |

---

## Iconos de Acción

Los iconos se posicionan en las **4 esquinas** del subnodo para facilitar el uso en móviles:

```
┌─────────────────────┐
│ 🕐              👁  │  🕐 = historial (tiene_historial)
│                     │  👁 = preview (tiene_preview)
│                     │
│ ⬇               🔗 │  ⬇ = descarga (tiene_descarga)
└─────────────────────┘  🔗 = enlace (tiene_enlace)
```

**Estilo visual:**
- Fondo: negro semi-transparente `rgba(0,0,0,0.5)`
- Icono: blanco
- Tamaño: 26×26px
- Radio: 4px
- Opacidad: 50% (aumenta al hacer hover)

---

## Especificaciones Visuales

### Dimensiones

| Elemento | Valor | Notas |
|----------|-------|-------|
| Nodo principal | 120×120 px | Cuadrado |
| Subnodo | 180×101 px | Ratio 16:9 |
| Radio esquinas nodo | 20px | |
| Radio esquinas subnodo | 15px | |
| Grosor líneas/bordes | 3px | |
| Gap entre subnodos | 20px | Vertical |
| Gap entre grupos | 50px | Vertical |
| Gap nodo a subnodo | 70px | Horizontal |

### Tipografía

| Elemento | Tamaño | Peso | Color |
|----------|--------|------|-------|
| Título página | 32px | 600 | #1a1a1a |
| Título nodo | 18px | 500 | Color del nodo |
| Título subnodo | 16px | 500 | Color del nodo |

### Colores por Defecto

```
#FF6B35  - Naranja (nodo 1)
#E5A000  - Amarillo (nodo 2)
#06D6A0  - Verde (nodo 3)
#0891B2  - Cyan (nodo 4)
#3B82F6  - Azul (nodo 5)
#8B5CF6  - Violeta (nodo 6)
#EC4899  - Rosa (nodo 7)
```

Los colores rotan automáticamente: nodo 8 usa color 1, etc.

### Fondo de Fallback

Cuando una imagen no carga, se muestra fondo gris `#ccc`. Esto evita espacios en blanco y texto fantasma.

---

## Animaciones

| Elemento | Duración | Función | Delay |
|----------|----------|---------|-------|
| Movimiento vertical del nodo | 400ms | ease-out | - |
| Revelado de líneas | 450ms | linear | 80ms |
| Aparición subnodos | instantánea | - | 30ms |

### Secuencia al Expandir
1. El nodo se desplaza verticalmente para centrarse con sus subnodos
2. Las líneas se revelan con efecto de máscara deslizante
3. Los subnodos aparecen instantáneamente

### Secuencia al Colapsar
1. Las líneas desaparecen
2. Los subnodos se ocultan
3. El nodo vuelve a su posición

---

## Centrado Automático

El contenedor principal se centra horizontalmente con flexbox:

- **Con subnodos expandidos**: Ancho = nodo + gap + subnodo (~400px)
- **Todo colapsado**: Ancho = solo nodos (~180px)

El ancho cambia con transición suave (400ms).

---

## Integración con NocoDB

### Estructura de Tablas Recomendada

**Tabla: `proyectos`**
```
id | titulo | mostrar_titulo | colores | fuente
```

**Tabla: `nodos`**
```
id | proyecto_id | titulo | imagen | orden
```

**Tabla: `subnodos`**
```
id | nodo_id | titulo | imagen | tiene_preview | tiene_descarga | tiene_enlace | tiene_historial | orden
```

### Campo de Imagen

Usar campo tipo **Attachment** de NocoDB. La URL del archivo se usa directamente.

Para optimizar imágenes automáticamente, considerar:
- **Cloudinary**: `https://res.cloudinary.com/cuenta/image/upload/w_180,h_101,c_fill/imagen.jpg`
- **Redimensionado manual** antes de subir

### Tamaños de Imagen Recomendados

| Tipo | Subir | Se muestra como |
|------|-------|-----------------|
| Nodo | 240×240 px | 120×120 px |
| Subnodo | 360×202 px | 180×101 px |

Subir al doble para pantallas retina.

---

## Ejemplo JSON Completo

```json
{
  "titulo": "Proyecto Cliente X",
  "mostrar_titulo": true,
  "colores": "#FF6B35, #06D6A0, #3B82F6",
  "fuente": "Montserrat",
  "nodos": [
    {
      "id": "n1",
      "titulo": "Planos",
      "imagen": "https://ejemplo.com/planos-thumb.jpg",
      "subnodos": [
        {
          "id": "s1",
          "titulo": "Planta Baja",
          "imagen": "https://ejemplo.com/planta-baja.jpg",
          "tiene_preview": true,
          "tiene_descarga": true,
          "tiene_enlace": false,
          "tiene_historial": true
        },
        {
          "id": "s2",
          "titulo": "Planta Alta",
          "imagen": "https://ejemplo.com/planta-alta.jpg",
          "tiene_preview": true,
          "tiene_descarga": true,
          "tiene_enlace": true,
          "tiene_historial": false
        }
      ]
    }
  ]
}
```

---

## Pendiente de Implementar

- [ ] Conexión real con API de NocoDB
- [ ] Sistema de autenticación con PIN
- [ ] Funcionalidad real de iconos:
  - [ ] Preview: abrir modal con documento
  - [ ] Descarga: descargar archivo
  - [ ] Enlace: copiar URL al portapapeles
  - [ ] Historial: mostrar versiones anteriores
- [ ] Responsive móvil (adaptar a pantallas pequeñas)
- [ ] Integración en aplicación empresarial

---

## Historial de Versiones

| Versión | Cambios principales |
|---------|---------------------|
| v11 | Colores/fuentes configurables, centrado mejorado, iconos en 4 esquinas, fix texto duplicado |
| v10 | Imágenes base64 incrustadas (demo) |
| v9 | Esquinas redondeadas 20px/15px, iconos 50% opacidad |
| v8 | Subnodos aparecen instantáneamente |
| v7-v1 | Iteraciones de diseño y animación |