# MANUAL DE USUARIO - HST (Servidor 72.62.2.84)

## Introducción

HST es un servidor especializado en gestión de activos digitales y API de datos. Aloja la API principal (HST-API), tres instancias de Directus para gestión de contenidos, y un sistema de grafos con capacidades avanzadas de indexación.

## Información del Servidor

| Aspecto | Detalles |
|--------|----------|
| **IP** | 72.62.2.84 |
| **Usuario** | root |
| **Acceso SSH** | ssh root@72.62.2.84 -i ~/.ssh/tzzr |
| **Ubicación** | Servidor HST |
| **Rol** | API, gestión de contenidos, sistema de grafos |

## Servicios Disponibles

### 1. HST-API (API Principal)

**Puerto**: 5001
**URL**: http://72.62.2.84:5001
**Documentación**: http://72.62.2.84:5001/docs (OpenAPI/Swagger)
**Base de datos**: PostgreSQL integrada

#### Características:
- API REST para gestión de activos
- Autenticación con tokens JWT
- Documentación interactiva Swagger
- Rate limiting y logging automático

#### Endpoints Principales:

```bash
# Listar activos
curl http://72.62.2.84:5001/api/v1/assets -H "Authorization: Bearer [token]"

# Obtener activo por ID
curl http://72.62.2.84:5001/api/v1/assets/[id] -H "Authorization: Bearer [token]"

# Crear nuevo activo
curl -X POST http://72.62.2.84:5001/api/v1/assets \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi activo",
    "description": "Descripción",
    "tags": ["tag1", "tag2"],
    "metadata": {}
  }'

# Actualizar activo
curl -X PUT http://72.62.2.84:5001/api/v1/assets/[id] \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nuevo nombre"}'

# Eliminar activo
curl -X DELETE http://72.62.2.84:5001/api/v1/assets/[id] \
  -H "Authorization: Bearer [token]"
```

#### Obtener Token de Autenticación:

```bash
# Login
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[usuario]",
    "password": "[contraseña]"
  }'

# Respuesta incluye token JWT
# Usar en headers: Authorization: Bearer [token]
```

#### Ver Documentación:
Visita http://72.62.2.84:5001/docs en el navegador para documentación interactiva Swagger.

### 2. Directus CMS (3 Instancias)

**Instancias**: 8055, 8056, 8057
**URLs**:
- Instancia 1: http://72.62.2.84:8055
- Instancia 2: http://72.62.2.84:8056
- Instancia 3: http://72.62.2.84:8057

**Uso**: Gestión de contenidos, colecciones de datos, interfaz administrativa

#### Características Directus:
- Interfaz web intuitiva para CRUD
- Gestión de usuarios y permisos
- API REST para acceso programático
- Webhooks para automatización
- Auditoría de cambios

#### Acceder a Directus:

```bash
# Abrir en navegador
# http://72.62.2.84:8055 (u 8056/8057)

# Usar SSH forward si accedes remotamente
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055

# Luego visitar http://localhost:8055 localmente
```

#### Operaciones en Directus:

```bash
# Obtener token de acceso
curl -X POST http://72.62.2.84:8055/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email]",
    "password": "[contraseña]"
  }'

# Listar colecciones
curl http://72.62.2.84:8055/collections \
  -H "Authorization: Bearer [token]"

# Obtener items de colección
curl http://72.62.2.84:8055/items/[colección] \
  -H "Authorization: Bearer [token]"

# Crear item
curl -X POST http://72.62.2.84:8055/items/[colección] \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "campo1": "valor1",
    "campo2": "valor2"
  }'
```

### 3. Graph System (Sistema de Grafos)

**Componente**: Sistema de indexación y consulta de grafos
**Nodos**: 709
**Edges**: 1134
**Propósito**: Análisis relacional, búsqueda semántica, navegación de conectividades

#### Estadísticas del Grafo:

```
┌─────────────────────┐
│   GRAPH STATISTICS  │
├─────────────────────┤
│ Total Nodes: 709    │
│ Total Edges: 1134   │
│ Density: 0.0044     │
│ Avg Degree: 3.20    │
└─────────────────────┘
```

#### Consultas al Sistema de Grafos:

```bash
# Obtener nodo por ID
curl http://72.62.2.84:5001/api/v1/graph/nodes/[node-id] \
  -H "Authorization: Bearer [token]"

# Obtener nodos por tipo
curl "http://72.62.2.84:5001/api/v1/graph/nodes?type=[tipo]" \
  -H "Authorization: Bearer [token]"

# Obtener vecinos de un nodo
curl http://72.62.2.84:5001/api/v1/graph/nodes/[node-id]/neighbors \
  -H "Authorization: Bearer [token]"

# Obtener caminos más cortos entre dos nodos
curl "http://72.62.2.84:5001/api/v1/graph/shortest-path?from=[id1]&to=[id2]" \
  -H "Authorization: Bearer [token]"

# Búsqueda por propiedades
curl "http://72.62.2.84:5001/api/v1/graph/search?query=[término]&type=[tipo]" \
  -H "Authorization: Bearer [token]"

# Estadísticas del grafo
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer [token]"
```

#### Estructura de Nodos

Tipos principales de nodos:

```
- entity: Entidades principales
- document: Documentos y archivos
- concept: Conceptos abstractos
- organization: Organizaciones
- person: Personas
- asset: Activos digitales
- tag: Etiquetas y clasificadores
```

#### Tipos de Edges

Relaciones entre nodos:

```
- HAS: Relación de pertenencia
- REFERENCES: Referencia
- RELATED_TO: Relacionado con
- DEPENDS_ON: Depende de
- CREATED_BY: Creado por
- MODIFIED_BY: Modificado por
- TAGGED_WITH: Etiquetado con
```

## Gestión de Tags

El sistema de tags permite clasificar y filtrar activos dinámicamente.

### Tags Disponibles

```bash
# Listar todos los tags
curl http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer [token]"

# Obtener tag específico
curl http://72.62.2.84:5001/api/v1/tags/[tag-name] \
  -H "Authorization: Bearer [token]"

# Crear nuevo tag
curl -X POST http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nuevo-tag",
    "description": "Descripción del tag",
    "color": "#FF5733"
  }'

# Actualizar tag
curl -X PUT http://72.62.2.84:5001/api/v1/tags/[tag-name] \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"description": "Nueva descripción"}'

# Eliminar tag
curl -X DELETE http://72.62.2.84:5001/api/v1/tags/[tag-name] \
  -H "Authorization: Bearer [token]"
```

### Aplicar Tags a Activos

```bash
# Agregar tag a activo
curl -X POST http://72.62.2.84:5001/api/v1/assets/[asset-id]/tags \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"tag": "[tag-name]"}'

# Quitar tag de activo
curl -X DELETE http://72.62.2.84:5001/api/v1/assets/[asset-id]/tags/[tag-name] \
  -H "Authorization: Bearer [token]"

# Filtrar activos por tag
curl "http://72.62.2.84:5001/api/v1/assets?tags=[tag-name]" \
  -H "Authorization: Bearer [token]"

# Filtrar activos por múltiples tags
curl "http://72.62.2.84:5001/api/v1/assets?tags=[tag1],[tag2]" \
  -H "Authorization: Bearer [token]"
```

### Jerarquía de Tags

```bash
# Crear tag secundario
curl -X POST http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subcategoría",
    "parent": "categoría-principal",
    "description": "Subtag"
  }'

# Obtener tags por categoría
curl "http://72.62.2.84:5001/api/v1/tags?parent=[parent-tag]" \
  -H "Authorization: Bearer [token]"
```

## API Endpoints Principales

### Activos

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/v1/assets` | Listar activos |
| GET | `/api/v1/assets/[id]` | Obtener activo |
| POST | `/api/v1/assets` | Crear activo |
| PUT | `/api/v1/assets/[id]` | Actualizar activo |
| DELETE | `/api/v1/assets/[id]` | Eliminar activo |

### Tags

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/v1/tags` | Listar tags |
| POST | `/api/v1/tags` | Crear tag |
| PUT | `/api/v1/tags/[name]` | Actualizar tag |
| DELETE | `/api/v1/tags/[name]` | Eliminar tag |

### Sistema de Grafos

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| GET | `/api/v1/graph/nodes` | Listar nodos |
| GET | `/api/v1/graph/nodes/[id]` | Obtener nodo |
| GET | `/api/v1/graph/nodes/[id]/neighbors` | Vecinos de nodo |
| GET | `/api/v1/graph/edges` | Listar edges |
| GET | `/api/v1/graph/shortest-path` | Camino más corto |
| GET | `/api/v1/graph/search` | Búsqueda |
| GET | `/api/v1/graph/stats` | Estadísticas |

### Directus

| Método | Endpoint (instancia 8055) | Descripción |
|--------|----------|-------------|
| POST | `/auth/login` | Autenticación |
| GET | `/collections` | Listar colecciones |
| GET | `/items/[collection]` | Listar items |
| POST | `/items/[collection]` | Crear item |
| PATCH | `/items/[collection]/[id]` | Actualizar item |
| DELETE | `/items/[collection]/[id]` | Eliminar item |

## Ejemplos de Uso Comunes

### Flujo: Crear Activo con Tags en el Grafo

```bash
# 1. Obtener token
TOKEN=$(curl -s -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario",
    "password": "contraseña"
  }' | jq -r '.token')

# 2. Crear activo
ASSET=$(curl -s -X POST http://72.62.2.84:5001/api/v1/assets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nuevo Activo",
    "description": "Descripción",
    "tags": []
  }' | jq -r '.id')

echo "Activo creado: $ASSET"

# 3. Crear tag si no existe
curl -s -X POST http://72.62.2.84:5001/api/v1/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mi-tag",
    "description": "Mi etiqueta"
  }'

# 4. Asociar tag al activo
curl -s -X POST http://72.62.2.84:5001/api/v1/assets/$ASSET/tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag": "mi-tag"}'

echo "Tag asociado al activo"

# 5. Crear nodo en el grafo
curl -s -X POST http://72.62.2.84:5001/api/v1/graph/nodes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "asset",
    "properties": {
      "asset_id": "'$ASSET'",
      "name": "Nuevo Activo"
    }
  }'

echo "Nodo del grafo creado"
```

### Flujo: Buscar Activos por Tag y Explorar Relaciones

```bash
# 1. Buscar activos por tag
curl "http://72.62.2.84:5001/api/v1/assets?tags=importante" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 2. Para cada activo, obtener su nodo en el grafo
ASSET_ID="[obtenido del paso anterior]"
GRAPH_NODE=$(curl -s "http://72.62.2.84:5001/api/v1/graph/nodes?asset_id=$ASSET_ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.nodes[0].id')

# 3. Explorar vecinos del nodo
curl "http://72.62.2.84:5001/api/v1/graph/nodes/$GRAPH_NODE/neighbors" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 4. Encontrar caminos a otros nodos
curl "http://72.62.2.84:5001/api/v1/graph/shortest-path?from=$GRAPH_NODE&to=[otro-nodo]" \
  -H "Authorization: Bearer $TOKEN" | jq '.'
```

## Mantenimiento y Operaciones

### Verificar Estado de Servicios

```bash
# Conectar al servidor
ssh root@72.62.2.84 -i ~/.ssh/tzzr

# Verificar servicios activos
systemctl status

# Ver logs de HST-API
journalctl -u hst-api -f

# Ver logs de Directus
journalctl -u directus -f
```

### Backup de Datos

```bash
# Descargar datos de Directus (instancia 8055)
curl "http://72.62.2.84:8055/items/[colección]?export=json" \
  -H "Authorization: Bearer $TOKEN" > backup.json

# Backup de grafo
curl "http://72.62.2.84:5001/api/v1/graph/export" \
  -H "Authorization: Bearer $TOKEN" > grafo-backup.json

# Guardar en R2
aws s3 cp backup.json "s3://architect/backups/hst-backup-$(date +%Y%m%d).json" \
  --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
```

### Monitoreo

```bash
# Estadísticas del grafo
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# Contador de activos
curl "http://72.62.2.84:5001/api/v1/assets?limit=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.total'

# Usar en script de monitoreo
while true; do
  echo "[$(date)] Estado del sistema HST:"
  curl -s http://72.62.2.84:5001/api/v1/graph/stats \
    -H "Authorization: Bearer $TOKEN" | jq '.node_count, .edge_count'
  sleep 300  # Cada 5 minutos
done
```

## Troubleshooting

### HST-API no responde

```bash
# Verificar si está corriendo
ps aux | grep hst-api

# Ver logs
journalctl -u hst-api -n 50

# Reiniciar servicio
systemctl restart hst-api

# Verificar puerto
netstat -tlnp | grep 5001
```

### Error de autenticación

```bash
# Verificar credenciales válidas
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"usuario","password":"contraseña"}'

# Si error 401, credenciales incorrectas
# Si error 500, problema de servidor
```

### Directus (8055/8056/8057) no accesible

```bash
# SSH forwarding si accedes remotamente
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055

# Verificar que Directus está corriendo
ps aux | grep directus

# Ver logs de Directus
journalctl -u directus -n 50
```

### Grafo bloqueado o lento

```bash
# Estadísticas actuales
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# Si hay muchos nodos/edges, considerar:
# - Archiving de datos viejos
# - Índices de base de datos
# - Optimización de consultas
```

## Configuración Importante

### Variables de Entorno (en servidor HST)

```bash
# HST-API
export HST_API_PORT=5001
export HST_DATABASE_URL="postgresql://hst_user:password@localhost/hst_db"
export HST_JWT_SECRET="[tu-secret-jwt]"

# Directus (múltiples instancias)
export DIRECTUS_HOST=0.0.0.0
export DIRECTUS_PORT=8055  # Varía por instancia
export DIRECTUS_ADMIN_EMAIL="admin@example.com"
export DIRECTUS_ADMIN_PASSWORD="[contraseña]"
```

### Puertos en Firewall

Asegúrate de que estos puertos estén abiertos:
- 5001: HST-API
- 8055, 8056, 8057: Directus (3 instancias)
- 5432: PostgreSQL (si es accesible)

```bash
# Verificar firewall
ufw status

# Si es necesario, abrir puertos
ufw allow 5001/tcp
ufw allow 8055/tcp
ufw allow 8056/tcp
ufw allow 8057/tcp
```

## Referencias Rápidas

### Puertos Importantes
- **HST-API**: 5001
- **Directus 1**: 8055
- **Directus 2**: 8056
- **Directus 3**: 8057

### URLs Frecuentes
```
API Docs: http://72.62.2.84:5001/docs
HST-API: http://72.62.2.84:5001
Directus 1: http://72.62.2.84:8055
Directus 2: http://72.62.2.84:8056
Directus 3: http://72.62.2.84:8057
```

### Comandos Frecuentes

```bash
# Conectar al servidor
ssh root@72.62.2.84 -i ~/.ssh/tzzr

# Forward Directus localmente
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055

# Obtener token
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"usuario","password":"contraseña"}'

# Listar activos
curl http://72.62.2.84:5001/api/v1/assets \
  -H "Authorization: Bearer [token]"

# Stats del grafo
curl http://72.62.2.84:5001/api/v1/graph/stats \
  -H "Authorization: Bearer [token]"
```

## Documentación Completa

Para documentación completa de cada servicio:
- **HST-API**: http://72.62.2.84:5001/docs (OpenAPI/Swagger)
- **Directus**: Documentación en cada instancia o https://docs.directus.io
- **Sistema de Grafos**: Consulta documentación interna en `s3://architect/system/`

---

**Última actualización**: Diciembre 2025
**Versión**: 1.0