# Guía de Configuración para Scripts Backend

## Introducción

Esta guía explica cómo usar la función `load_configuration()` para cargar parámetros desde un archivo `script_config.json` en los scripts del backend.

## 1. Configuración del Script

Para que tus scripts puedan encontrar los módulos del proyecto, necesitas añadir el directorio raíz al path de Python.

### Path Setup e Importación

Coloca este código al inicio de tu script:

```python
import os
import sys

# Añadir el directorio raíz al sys.path
# El número de `os.path.dirname()` depende de la profundidad del script.
# Para /backend/script_groups/grupo/script.py, son 4.
script_root = os.path.dirname(
    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
)
sys.path.append(script_root)

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

## 2. Cargar la Configuración

La función `load_configuration()` busca y carga un archivo llamado `script_config.json` que debe estar en el **mismo directorio** que el script que la ejecuta. Devuelve un diccionario con todo el contenido del JSON.

### Ejemplo de Uso

```python
def main():
    # Cargar configuraciones del archivo script_config.json
    configs = load_configuration()
    
    # Es buena práctica verificar si la configuración se cargó
    if not configs:
        print("Error: No se pudo cargar la configuración. Saliendo.")
        return
    
    # Acceder a los parámetros usando .get() para evitar errores
    working_directory = configs.get("working_directory", "")
    level1_config = configs.get("level1", {})
    level2_config = configs.get("level2", {})
    level3_config = configs.get("level3", {})
     
    # Ejemplo de uso de un parámetro específico con valor 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 trabajo: {working_directory}")
    print(f"Directorio de salida SCL: {scl_output_dir}")

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

## 3. Archivo `script_config.json`

Este archivo contiene los parámetros de tu script. La estructura interna del JSON, como el uso de `"level1"`, `"level2"`, etc., es una convención para organizar los parámetros. `load_configuration()` simplemente lee el archivo y devuelve su contenido.

**Ejemplo de `script_config.json`:**
```json
{
    "working_directory": "/ruta/al/directorio/de/trabajo",
    "level1": {
        "parametro_global_1": "valor1"
    },
    "level2": {
        "scl_output_dir": "scl_output",
        "xref_output_dir": "xref_output"
    },
    "level3": {
        "parametro_especifico_1": true
    }
}
```

## 4. Manejo de Errores

`load_configuration()` está diseñada para ser robusta:
- Si `script_config.json` no se encuentra, retorna un diccionario vacío `{}`.
- Si el JSON es inválido, imprime un error y también retorna `{}`.

**Siempre** comprueba si el diccionario devuelto está vacío para manejar estos casos de forma segura en tu script.

## 5. Jerarquía de Archivos de Configuración

El sistema utiliza un modelo de configuración en cascada para gestionar los parámetros de los scripts. Esta jerarquía permite establecer configuraciones a nivel global, de grupo y de trabajo. Antes de la ejecución, el launcher lee estos archivos, los combina y genera un único `script_config.json` en la carpeta del script. La función `load_configuration()` es la que finalmente lee este archivo consolidado.

A continuación se describe la finalidad y ubicación de cada archivo clave.

### Archivos de Valores (Parámetros)

Contienen los datos y variables que utilizará el script. La configuración se superpone en el siguiente orden: `Nivel 1 < Nivel 2 < Nivel 3`.

- **`data.json` (Nivel 1 - Global)**
  - **Ubicación:** `data/data.json`
  - **Utilidad:** Almacena variables globales disponibles para todos los scripts. Ideal para parámetros generales.
  - **Acceso:** Sus datos se cargan en la clave `"level1"` del diccionario `configs`.

- **`script_config.json` (Nivel 2 - Grupo)**
  - **Ubicación:** En la raíz de cada directorio de grupo (ej: `backend/script_groups/MiGrupo/script_config.json`).
  - **Utilidad:** Define parámetros compartidos por todos los scripts de un grupo.
  - **Acceso:** Sus datos se cargan en la clave `"level2"`.

- **`work_dir.json` (Nivel 3 - Directorio de Trabajo)**
  - **Ubicación:** Dentro del directorio de trabajo que el script va a procesar.
  - **Utilidad:** Contiene parámetros para una ejecución específica. Es el nivel más específico y sobrescribe los anteriores.
  - **Acceso:** Sus datos se cargan en la clave `"level3"`.

### Archivos de Esquema (Definiciones de Estructura)

No contienen valores, sino que describen la estructura y tipos de datos que los archivos de valores deben tener. Son usados por el launcher para validación y para generar interfaces de configuración.

- **`esquema_group.json`**
  - **Ubicación:** Raíz del directorio del grupo.
  - **Utilidad:** Define la estructura del `script_config.json` del grupo.

- **`esquema_work.json`**
  - **Ubicación:** Raíz del directorio del grupo.
  - **Utilidad:** Define la estructura del `work_dir.json`.

## 6. 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
    }
}
```