# Guía de Configuración para Scripts Backend

## Introducción

Esta guía explica cómo configurar y usar correctamente la función `load_configuration()` en scripts ubicados bajo el directorio `/backend`. La función carga configuraciones desde un archivo `script_config.json` ubicado en el mismo directorio que el script que la llama.

## Configuración del Path e Importación

### 1. Configuración estándar del Path

Para scripts ubicados en subdirectorios bajo `/backend`, usa este patrón estándar:

```python
import os
import sys

# Configurar el path al directorio raíz del proyecto
script_root = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
)
sys.path.append(script_root)

# Importar la función de configuración
from backend.script_utils import load_configuration
```

**Nota:** El número de `os.path.dirname()` anidados depende de la profundidad del script:
- Scripts en `/backend/script_groups/grupo/`: 4 niveles
- Scripts en `/backend/`: 2 niveles

### 2. Importación Correcta

**✅ Correcto:**
```python
from backend.script_utils import load_configuration
```

**❌ Incorrecto:**
```python
from script_utils import load_configuration  # No funciona desde subdirectorios
```

## Uso de la Función load_configuration()

### Implementación Básica

```python
def main():
    # Cargar configuraciones
    configs = load_configuration()
    
    # Obtener el directorio de trabajo
    working_directory = configs.get("working_directory", "")
    
    # Acceder a configuraciones por nivel
    level1_config = configs.get("level1", {})
    level2_config = configs.get("level2", {})
    level3_config = configs.get("level3", {})
    
    # Ejemplo de uso de parámetros específicos con valores por defecto
    scl_output_dir = level2_config.get("scl_output_dir", "scl_output")
    xref_output_dir = level2_config.get("xref_output_dir", "xref_output")
    
if __name__ == "__main__":
    main()
```

### Estructura del Archivo script_config.json

El archivo `script_config.json` debe estar ubicado en el mismo directorio que el script que llama a `load_configuration()`. Estructura recomendada:

```json
{
    "working_directory": "/ruta/al/directorio/de/trabajo",
    "level1": {
        "parametro_global_1": "valor1",
        "parametro_global_2": "valor2"
    },
    "level2": {
        "scl_output_dir": "scl_output",
        "xref_output_dir": "xref_output",
        "xref_source_subdir": "source",
        "aggregated_filename": "full_project_representation.md"
    },
    "level3": {
        "parametro_especifico_1": true,
        "parametro_especifico_2": 100
    }
}
```

## Ejemplo Completo de Implementación

```python
"""
Script de ejemplo que demuestra el uso completo de load_configuration()
"""

import os
import sys
import json

# Configuración del path
script_root = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
)
sys.path.append(script_root)
from backend.script_utils import load_configuration


def main():
    print("=== Cargando Configuración ===")
    
    # Cargar configuraciones
    configs = load_configuration()
    
    # Verificar que se cargó correctamente
    if not configs:
        print("Error: No se pudo cargar la configuración")
        return
    
    # Obtener configuraciones
    working_directory = configs.get("working_directory", "")
    level1_config = configs.get("level1", {})
    level2_config = configs.get("level2", {})
    level3_config = configs.get("level3", {})
    
    # Mostrar configuraciones cargadas
    print(f"Directorio de trabajo: {working_directory}")
    print("Configuración Nivel 1:", json.dumps(level1_config, indent=2))
    print("Configuración Nivel 2:", json.dumps(level2_config, indent=2))
    print("Configuración Nivel 3:", json.dumps(level3_config, indent=2))
    
    # Ejemplo de uso de parámetros con valores por defecto
    scl_output_dir = level2_config.get("scl_output_dir", "scl_output")
    xref_output_dir = level2_config.get("xref_output_dir", "xref_output")
    
    print(f"Directorio de salida SCL: {scl_output_dir}")
    print(f"Directorio de salida XREF: {xref_output_dir}")


if __name__ == "__main__":
    main()
```

## Manejo de Errores

La función `load_configuration()` maneja automáticamente los siguientes casos:

1. **Archivo no encontrado**: Retorna un diccionario vacío `{}`
2. **JSON inválido**: Retorna un diccionario vacío y muestra un mensaje de error
3. **Errores de lectura**: Retorna un diccionario vacío y muestra un mensaje de error

### Verificación de Configuración Válida

```python
configs = load_configuration()

# Verificar que se cargó correctamente
if not configs:
    print("Advertencia: No se pudo cargar la configuración, usando valores por defecto")
    working_directory = "."
else:
    working_directory = configs.get("working_directory", ".")

# Verificar directorio de trabajo
if not os.path.exists(working_directory):
    print(f"Error: El directorio de trabajo no existe: {working_directory}")
    return
```

## Mejores Prácticas

1. **Siempre proporciona valores por defecto** al usar `.get()`:
   ```python
   valor = config.get("clave", "valor_por_defecto")
   ```

2. **Verifica la existencia de directorios críticos**:
   ```python
   if not os.path.exists(working_directory):
       print(f"Error: Directorio no encontrado: {working_directory}")
       return
   ```

3. **Documenta los parámetros esperados** en tu script:
   ```python
   # Parámetros esperados en level2:
   # - scl_output_dir: Directorio de salida para archivos SCL
   # - xref_output_dir: Directorio de salida para referencias cruzadas
   ```

4. **Usa nombres de parámetros consistentes** en todos los scripts del mismo grupo.

## Definición Técnica de load_configuration()

```python
def load_configuration() -> Dict[str, Any]:
    """
    Load configuration from script_config.json in the current script directory.

    Returns:
        Dict containing configurations with levels 1, 2, 3 and working_directory

    Example usage in scripts:
        from backend.script_utils import load_configuration

        configs = load_configuration()
        level1_config = configs.get("level1", {})
        level2_config = configs.get("level2", {})
        level3_config = configs.get("level3", {})
        working_dir = configs.get("working_directory", "")
    """
```

La función utiliza `inspect.stack()` para determinar automáticamente el directorio del script que la llama, asegurando que siempre busque el archivo `script_config.json` en la ubicación correcta.

## Documentación de Scripts para el Launcher

El sistema de launcher utiliza archivos JSON para mostrar información sobre los grupos de scripts y scripts individuales en la interfaz web.

### Archivo description.json (Descripción del Grupo)

Ubicación: En el directorio raíz del grupo de scripts.

```json
{
  "name": "Nombre del Grupo",
  "description": "Descripción del propósito y funcionalidad del grupo",
  "version": "1.0",
  "author": "Nombre del Autor"
}
```

### Archivo scripts_description.json (Descripción de Scripts)

Ubicación: En el directorio raíz del grupo de scripts.

```json
{
    "nombre_script.py": {
        "display_name": "Nombre para mostrar en la UI",
        "short_description": "Descripción breve del script",
        "long_description": "Descripción detallada con explicación completa de funcionalidad, pasos que ejecuta, y contexto de uso",
        "hidden": false
    },
    "script_interno.py": {
        "display_name": "Script Interno",
        "short_description": "Script de uso interno",
        "long_description": "",
        "hidden": true
    }
}
```

### Propiedades Importantes

- **hidden**: `true` oculta el script del launcher (útil para scripts auxiliares)
- **display_name**: Nombre amigable que aparece en la interfaz
- **short_description**: Se muestra en la lista de scripts
- **long_description**: Se muestra al expandir detalles del script

### Ejemplo Práctico

Para un grupo "XML Parser to SCL":

**description.json:**
```json
{
  "name": "Siemens-Tia : 03 : Procesador de XML LAD-SCL-AWL",
  "description": "Scripts que procesan archivos XML exportados de TIA, convirtiendo LAD a SCL",
  "version": "1.0",
  "author": "Miguel"
}
```

**scripts_description.json:**
```json
{
    "x0_main.py": {
        "display_name": "1: Procesar Exportación XML completa",
        "short_description": "Conversor principal de LAD/FUP XML a SCL",
        "long_description": "Script orquestador que procesa todos los archivos XML...",
        "hidden": false
    },
    "x1_to_json.py": {
        "display_name": "x1_to_json",
        "short_description": "Converter XML interno",
        "long_description": "",
        "hidden": true
    }
}
```