SIDEL_ScriptsManager/PROXY-SYSTEM-UPDATED.md

# Sistema de Proxy Interno - ScriptsManager (ACTUALIZADO)

## Introducción

ScriptsManager ahora incluye un sistema de proxy interno que permite el acceso elegante a scripts con aislamiento por usuario y proyecto. Este sistema reemplaza el enfoque anterior basado en argumentos de línea de comandos por una arquitectura más robusta y escalable.

## Arquitectura del Sistema

### Flujo de Comunicación

```
Usuario Externo → ScriptsManager (puerto 5002/5003) → Scripts Internos (puertos 5200-5400)
```

### Componentes Principales

1. **ScriptsManager Principal**
   - Puerto externo: 5002 (producción) / 5003 (desarrollo)
   - Maneja autenticación de usuarios
   - Gestiona proyectos y permisos
   - Actúa como proxy hacia scripts internos

2. **Scripts Proxy**
   - Rango de puertos: 5200-5400
   - Aislamiento por usuario/proyecto
   - Ejecución automática con variables de entorno preconfiguradas
   - Workspaces dedicados para cada instancia

3. **Base de Datos**
   - Tabla `script_proxy_executions` para tracking de instancias
   - Logs de ejecución integrados
   - Gestión automática de limpieza

## URLs del Sistema

### ScriptsManager Principal
```
http://localhost:5002/dashboard          # Interfaz principal (producción)
http://localhost:5003/dashboard          # Interfaz principal (desarrollo)
```

### Acceso Proxy a Scripts
```
# Formato general
/project/{project_id}/script/{script_id}/user/{user_id}/*

# Ejemplos específicos
/project/hydraulics/script/hammer_simulator/user/operator1/
/project/hydraulics/script/hammer_simulator/user/operator1/api/calculate
/project/hydraulics/script/hammer_simulator/user/operator1/api/status
```

### Endpoints de Control
```
# Iniciar script
POST /api/proxy/start
{
  "project_id": "hydraulics",
  "script_id": "hammer_simulator", 
  "user_id": "operator1"
}

# Detener script
POST /api/proxy/stop
{
  "project_id": "hydraulics",
  "script_id": "hammer_simulator",
  "user_id": "operator1"
}

# Estado de script
GET /api/proxy/status?project_id=hydraulics&script_id=hammer_simulator&user_id=operator1
```

## Implementación de Scripts Proxy

### Estructura de Metadata

Los scripts proxy deben incluir metadata específica en su cabecera:

```python
"""
ScriptsManager Metadata:
@description: Interactive Water Hammer Simulator for Syrup Pumping Systems
@required_level: operator
@category: simulation
@tags: hydraulics,water_hammer,pumping,syrup,transient_analysis
@parameters: []
@execution_timeout: 3600
@flask_port: auto
"""
```

### Variables Automáticas Disponibles

Cuando un script es ejecutado por el sistema proxy, las siguientes variables están disponibles automáticamente:

```python
# Variables de entorno automáticas
WORKSPACE_PATH    # Directorio de trabajo aislado para esta instancia
PARAMETERS        # Parámetros específicos del script
ENVIRONMENT       # Variables de entorno del usuario/proyecto
app              # Instancia Flask pre-configurada

# Variables derivadas del entorno
USER_ID           # ID del usuario que ejecuta el script
PROJECT_ID        # ID del proyecto actual
PROJECT_NAME      # Nombre del proyecto
USER_LEVEL        # Nivel de acceso del usuario
THEME            # Tema preferido del usuario
LANGUAGE         # Idioma preferido del usuario
```

### Ejemplo de Script Adaptado

```python
# IMPORTANTE: Este script funciona con el nuevo sistema de proxy de ScriptsManager
# Las siguientes variables están disponibles automáticamente:
# - WORKSPACE_PATH, PARAMETERS, ENVIRONMENT, app

import os
from flask import jsonify

# Configuración automática desde el proxy
DATA_DIR = WORKSPACE_PATH
USER_ID = ENVIRONMENT.get('USER_ID', 'unknown')
PROJECT_ID = ENVIRONMENT.get('PROJECT_ID', 'default')

# Rutas Flask (la app está pre-configurada)
@app.route("/")
def index():
    return f"Script ejecutándose para usuario {USER_ID} en proyecto {PROJECT_ID}"

@app.route("/api/status")
def status():
    return jsonify({
        "status": "running",
        "user_id": USER_ID,
        "project_id": PROJECT_ID,
        "workspace": WORKSPACE_PATH
    })
```

## Configuración de Docker

### Networking Bridge

El sistema utiliza networking bridge en lugar de host mode para mejor aislamiento:

```yaml
version: '3.8'

services:
  scriptsmanager:
    build: .
    networks:
      - scriptsmanager_network
    ports:
      - "5002:5002"
      - "5200-5400:5200-5400"
    environment:
      - DATABASE_URL=postgresql://scriptsmanager:scriptsmanager_dev_password@postgres:5432/scriptsmanager

networks:
  scriptsmanager_network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
```

### Workspaces

Los workspaces se montan como volúmenes para persistencia:

```yaml
volumes:
  - ./workspaces:/app/workspaces
```

## Migración de Scripts Existentes

### Pasos para Adaptar Scripts

1. **Eliminar Argumentos de Línea de Comandos**
   ```python
   # ANTES
   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--data-dir')
   args = parser.parse_args()
   
   # DESPUÉS
   DATA_DIR = WORKSPACE_PATH  # Variable automática
   ```

2. **Remover Configuración de Flask Manual**
   ```python
   # ANTES
   from flask import Flask
   app = Flask(__name__)
   app.run(host='0.0.0.0', port=5200)
   
   # DESPUÉS
   # La app ya está configurada y en ejecución
   # Solo definir las rutas
   ```

3. **Usar Variables de Entorno Automáticas**
   ```python
   # ANTES
   user_id = args.user_id
   project_id = args.project_id
   
   # DESPUÉS
   user_id = ENVIRONMENT.get('USER_ID')
   project_id = ENVIRONMENT.get('PROJECT_ID')
   ```

### Script de Ejemplo Completo

Ver `hammer_simulator_proxy.py` para un ejemplo completo de script adaptado al sistema proxy.

## Desarrollo y Testing

### Iniciar en Modo Desarrollo

```bash
# Iniciar solo la base de datos
docker compose up postgres -d

# Iniciar en modo desarrollo
docker compose --profile dev up scriptsmanager-dev
```

### Ejecutar Migración

```bash
# Desde el contenedor
source activate scriptsmanager
python scripts/migrate_proxy_system.py
```

### Testing del Sistema Proxy

```bash
# Probar conexión al sistema principal
curl http://localhost:5003/dashboard

# Iniciar un script proxy
curl -X POST http://localhost:5003/api/proxy/start \
  -H "Content-Type: application/json" \
  -d '{"project_id": "hydraulics", "script_id": "hammer_simulator", "user_id": "operator1"}'

# Verificar estado
curl "http://localhost:5003/api/proxy/status?project_id=hydraulics&script_id=hammer_simulator&user_id=operator1"

# Acceder al script directamente
curl http://localhost:5003/project/hydraulics/script/hammer_simulator/user/operator1/
```

## Estado Actual de la Implementación

### ✅ Completado

1. **Servicio Proxy Principal** (`app/services/script_proxy_service.py`)
   - Sistema completo de gestión de puertos (5200-5400)
   - Health checks automáticos cada 30 segundos
   - Limpieza de procesos zombie cada 5 minutos
   - Logs detallados y sistema de auditoría

2. **Rutas Flask** (`app/routes/proxy_routes.py`) 
   - Endpoints para iniciar/detener/consultar scripts
   - Proxy transparente hacia scripts internos
   - Validación de permisos y parámetros

3. **Modelos de Base de Datos** (`app/models/__init__.py`)
   - Tabla `script_proxy_executions` para tracking
   - Integración con logs de ejecución existentes
   - Índices optimizados para performance

4. **Integración Script Executor** (`app/services/script_executor.py`)
   - Métodos para proxy execution
   - Gestión de workspaces aislados
   - Variables de entorno automáticas

5. **Script Adaptado** (`hammer_simulator_proxy.py`)
   - Versión completa funcional del simulador
   - Interface web integrada con Bootstrap y Chart.js
   - APIs REST para cálculos y exportación

6. **Configuración Docker** (`docker-compose.yml`)
   - Networking bridge en lugar de host mode
   - Mapeo de puertos 5200-5400
   - Configuración de red aislada

### 🔄 En Progreso

- **Script Original** (`hammer_simulator.py`) marcado como legacy
- **Documentación** actualizada con ejemplos completos

### 📋 Próximos Pasos

1. **Testing Completo**
   - Ejecutar migración de base de datos
   - Probar inicio/parada de scripts proxy
   - Validar aislamiento entre usuarios/proyectos

2. **Optimizaciones**
   - Cache de resultados frecuentes
   - Métricas de performance
   - Balanceador de carga para alta demanda

3. **Más Scripts**
   - Adaptar scripts adicionales al sistema proxy
   - Templates para facilitar conversión
   - Herramientas de migración automática

## Archivos Clave Creados/Modificados

```
app/
├── services/
│   ├── script_proxy_service.py     # ✅ NUEVO - Servicio proxy principal
│   └── script_executor.py          # ✅ MODIFICADO - Integración proxy
├── routes/
│   └── proxy_routes.py             # ✅ NUEVO - Rutas Flask proxy
├── models/
│   └── __init__.py                 # ✅ MODIFICADO - Nueva tabla proxy
├── backend/script_groups/hammer/
│   ├── hammer_simulator.py         # ✅ MARCADO LEGACY
│   └── hammer_simulator_proxy.py   # ✅ NUEVO - Versión adaptada
└── app.py                          # ✅ MODIFICADO - Registro blueprint

scripts/
└── migrate_proxy_system.py         # ✅ NUEVO - Migración BD

docker-compose.yml                   # ✅ MODIFICADO - Bridge networking
PROXY-SYSTEM-README.md              # ✅ ACTUALIZADO - Documentación completa
```

## Comandos Rápidos

```bash
# Iniciar desarrollo
docker compose --profile dev up scriptsmanager-dev

# Migrar base de datos  
docker compose exec scriptsmanager-dev bash -c "source activate scriptsmanager && python scripts/migrate_proxy_system.py"

# Probar sistema proxy
curl -X POST http://localhost:5003/api/proxy/start -H "Content-Type: application/json" -d '{"project_id": "hydraulics", "script_id": "hammer_simulator_proxy", "user_id": "operator1"}'

# Acceder a script
curl http://localhost:5003/project/hydraulics/script/hammer_simulator_proxy/user/operator1/
```

El sistema proxy está **completamente implementado y listo para testing**. ¡Todos los componentes están en su lugar y la documentación está actualizada!