CtrEditor/TSNet_Phase2_Architecture.md

# TSNet Phase 2 Integration Architecture

## Overview

Este documento describe la arquitectura completa del sistema TSNet Phase 2 integrado con CtrEditor, que proporciona simulación hidráulica unificada para tanques, bombas y tuberías.

## Arquitectura del Sistema

### Principios de Diseño

1. **Separación de Responsabilidades**: Los componentes UI se enfocan en visualización, TSNet maneja todos los cálculos hidráulicos
2. **Configuración Inmutable**: La configuración se captura al inicio de simulación y permanece congelada durante la ejecución
3. **Thread Safety**: Diseñado para uso seguro en entornos multi-threaded
4. **Trazabilidad**: Logging comprensivo para debugging y monitoreo

### Componentes Principales

#### 1. Adaptadores TSNet

Los adaptadores actúan como puentes entre los componentes UI de CtrEditor y el motor de simulación TSNet.

##### TSNetTankAdapter
```csharp
// Ubicación: HydraulicSimulator/TSNet/Components/TSNetTankAdapter.cs
public class TSNetTankAdapter
{
    public TankConfiguration Configuration { get; private set; }
    public TSNetTankResults Results { get; private set; }
    public string TankId => tankId;
    
    public void CaptureConfigurationForSimulation()
    public void ResetCalculatedValues()
}
```

**Responsabilidades**:
- Capturar configuración de tanques al inicio de simulación
- Almacenar resultados calculados por TSNet
- Proporcionar ID único para identificación en TSNet

##### TSNetPumpAdapter
```csharp
// Ubicación: HydraulicSimulator/TSNet/Components/TSNetPumpAdapter.cs
public class TSNetPumpAdapter
{
    public PumpConfiguration Configuration { get; private set; }
    public TSNetPumpResults Results { get; private set; }
    public string NodeId => nodeId;
    
    public void CaptureConfigurationForSimulation()
    public void ResetCalculatedValues()
}
```

**Responsabilidades**:
- Capturar configuración de bombas (head, flujo máximo, velocidad)
- Almacenar resultados operacionales de TSNet
- Gestionar estado operacional de la bomba

##### TSNetPipeAdapter
```csharp
// Ubicación: HydraulicSimulator/TSNet/Components/TSNetPipeAdapter.cs
public class TSNetPipeAdapter
{
    public PipeConfiguration Configuration { get; private set; }
    public TSNetPipeResults Results { get; private set; }
    public string PipeId => pipeId;
    
    public void CaptureConfigurationForSimulation()
    public void ResetCalculatedValues()
}
```

**Responsabilidades**:
- Capturar configuración de tuberías (longitud, diámetro, rugosidad)
- Almacenar resultados de flujo y pérdidas de presión
- Gestionar propiedades del fluido

#### 2. Clases de Resultados

##### TSNetTankResults
```csharp
public class TSNetTankResults
{
    // Resultados hidráulicos calculados
    public double CalculatedLevelM { get; set; }
    public double CalculatedVolumeL { get; set; }
    public double CalculatedPressureBar { get; set; }
    public double InletFlowM3s { get; set; }
    public double OutletFlowM3s { get; set; }
    public double NetFlowM3s { get; set; }
    
    // Propiedades del fluido
    public int CalculatedFluidType { get; set; }
    public string CalculatedFluidDescription { get; set; }
    public double CalculatedFluidTemperature { get; set; }
    
    // Estado
    public bool IsOverflowing { get; set; }
    public bool IsEmpty { get; set; }
    public string Status { get; set; }
    public DateTime Timestamp { get; set; }
}
```

##### TSNetPumpResults
```csharp
public class TSNetPumpResults
{
    // Resultados operacionales
    public double CalculatedFlowM3s { get; set; }
    public double CalculatedFlowLMin { get; set; }
    public double CalculatedHeadM { get; set; }
    public double InletPressureBar { get; set; }
    public double OutletPressureBar { get; set; }
    public double PressureDifferentialBar { get; set; }
    public double CalculatedEfficiency { get; set; }
    public double PowerConsumptionKW { get; set; }
    
    // Estado operacional
    public bool IsOperating { get; set; }
    public bool IsCavitating { get; set; }
    public string OperationalStatus { get; set; }
    public DateTime Timestamp { get; set; }
}
```

##### TSNetPipeResults
```csharp
public class TSNetPipeResults
{
    // Resultados de flujo
    public double CalculatedFlowM3s { get; set; }
    public double CalculatedFlowLMin { get; set; }
    public double FlowVelocityMs { get; set; }
    public string FlowDirection { get; set; }
    
    // Propiedades hidráulicas
    public double PressureDropBar { get; set; }
    public double ReynoldsNumber { get; set; }
    public string FlowRegime { get; set; }
    public double FrictionFactor { get; set; }
    public double HeadLossM { get; set; }
    
    // Análisis del flujo
    public bool IsFlowActive { get; set; }
    public bool IsFlowReversed { get; set; }
    public string FlowStatus { get; set; }
    public DateTime Timestamp { get; set; }
}
```

### Integración con Componentes UI

#### Patrón de Integración

Cada componente hidráulico (osHydTank, osHydPump, osHydPipe) sigue el mismo patrón de integración:

##### 1. Inicialización del Adapter

```csharp
// En el constructor del componente
public osHydTank()
{
    // ... inicialización base ...
    
    // Inicializar TSNet adapter
    TSNetAdapter = new TSNetTankAdapter(this);
    
    // ... resto de inicialización ...
}
```

##### 2. Captura de Configuración

```csharp
// En ucLoaded - cuando el componente se carga completamente
private void ucLoaded(object sender, RoutedEventArgs e)
{
    // Capturar configuración para TSNet
    TSNetAdapter?.CaptureConfigurationForSimulation();
    
    // Configurar propiedades específicas del componente
    // ... 
}
```

##### 3. Actualización de Control (Solo Visual)

```csharp
// UpdateControl ahora SOLO maneja actualizaciones visuales
public override void UpdateControl(double TimeNow)
{
    if (!IsLoaded) return;
    
    // SOLO actualizaciones visuales - NO cálculos hidráulicos
    UpdateVisualState();
    UpdateColorIndication();
    UpdateAnimations();
    
    // Los cálculos hidráulicos los hace TSNet
}
```

##### 4. Aplicación de Resultados TSNet

```csharp
// ApplyHydraulicResults aplica EXCLUSIVAMENTE datos de TSNet
protected override void ApplyHydraulicResults(
    Dictionary<string, double> flows, 
    Dictionary<string, double> pressures)
{
    try
    {
        if (TSNetAdapter?.Results != null)
        {
            // Aplicar resultados de TSNet al componente
            CurrentFlow = TSNetAdapter.Results.CalculatedFlowM3s;
            CurrentPressure = TSNetAdapter.Results.CalculatedPressureBar;
            
            // Actualizar propiedades visuales basadas en TSNet
            UpdateVisualPropertiesFromTSNet();
            
            // Log para debugging
            LogTSNetApplication();
        }
    }
    catch (Exception ex)
    {
        dataDebug.AddDataToDebugger($"Error applying TSNet results: {ex.Message}");
    }
}
```

## Flujo de Datos

### 1. Inicio de Simulación

```
Usuario inicia simulación
    ↓
Componentes capturan configuración
    ↓
TSNet recibe configuración inmutable
    ↓
Simulación comienza
```

### 2. Durante la Simulación

```
TSNet calcula resultados hidráulicos
    ↓
Resultados se almacenan en Results classes
    ↓
ApplyHydraulicResults actualiza componentes UI
    ↓
UpdateControl actualiza solo aspectos visuales
```

### 3. Fin de Simulación

```
Simulación termina
    ↓
ResetCalculatedValues limpia resultados
    ↓
Componentes listos para nueva simulación
```

## Eliminación de Cálculos Duplicados

### Antes de TSNet Phase 2

Cada componente tenía sus propios cálculos hidráulicos:

```csharp
// ELIMINADO - ya no se hace
private void CalculateInternalPressure()
{
    // Cálculos internos duplicados
}

private void UpdateInternalFlow()
{
    // Lógica hidráulica local
}
```

### Después de TSNet Phase 2

Todos los cálculos hidráulicos los hace TSNet:

```csharp
// NUEVO - solo aplicar resultados TSNet
private void ApplyTSNetResults()
{
    if (TSNetAdapter?.Results != null)
    {
        // Usar valores calculados por TSNet
        CurrentPressure = TSNetAdapter.Results.CalculatedPressureBar;
        CurrentFlow = TSNetAdapter.Results.CalculatedFlowM3s;
    }
}
```

## Beneficios de la Arquitectura

### 1. **Consistencia**
- Todos los cálculos hidráulicos provienen de una sola fuente (TSNet)
- No hay discrepancias entre componentes
- Resultados coherentes en toda la red

### 2. **Mantenibilidad**
- Lógica hidráulica centralizada en TSNet
- Componentes UI enfocados en visualización
- Fácil debugging y modificación

### 3. **Escalabilidad**
- Nuevos componentes hidráulicos siguen el mismo patrón
- TSNet puede manejar redes complejas
- Performance optimizada

### 4. **Trazabilidad**
- Logging comprensivo en cada paso
- Estados claramente definidos
- Fácil identificación de problemas

## Debugging y Monitoreo

### Logging Integrado

Cada adapter incluye logging detallado:

```csharp
private void LogTSNetApplication()
{
    try
    {
        dataDebug.AddDataToDebugger($"Tank {TSNetAdapter.TankId} - TSNet Results Applied:");
        dataDebug.AddDataToDebugger($"  Pressure: {TSNetAdapter.Results.CalculatedPressureBar} bar");
        dataDebug.AddDataToDebugger($"  Level: {TSNetAdapter.Results.CalculatedLevelM} m");
        dataDebug.AddDataToDebugger($"  Volume: {TSNetAdapter.Results.CalculatedVolumeL} L");
        dataDebug.AddDataToDebugger($"  Updated: {TSNetAdapter.Results.Timestamp}");
    }
    catch (Exception ex)
    {
        dataDebug.AddDataToDebugger($"Error logging TSNet application: {ex.Message}");
    }
}
```

### Estados de Validación

Los adapters incluyen validación de estado:

```csharp
public bool IsConfigurationValid()
{
    return Configuration != null && 
           !string.IsNullOrEmpty(TankId) && 
           Configuration.MinLevelM >= 0 && 
           Configuration.MaxLevelM > Configuration.MinLevelM;
}
```

## Extensibilidad

### Nuevos Componentes Hidráulicos

Para agregar un nuevo componente hidráulico:

1. **Crear Adapter Class**:
```csharp
public class TSNetNewComponentAdapter
{
    public NewComponentConfiguration Configuration { get; private set; }
    public TSNetNewComponentResults Results { get; private set; }
    
    public void CaptureConfigurationForSimulation() { }
    public void ResetCalculatedValues() { }
}
```

2. **Crear Results Class**:
```csharp
public class TSNetNewComponentResults
{
    public DateTime Timestamp { get; set; }
    // ... propiedades específicas del componente
}
```

3. **Integrar en Componente UI**:
```csharp
public class osNewComponent : osBase
{
    public TSNetNewComponentAdapter? TSNetAdapter { get; private set; }
    
    public osNewComponent()
    {
        TSNetAdapter = new TSNetNewComponentAdapter(this);
    }
    
    // Seguir el patrón estándar de integración
}
```

## Archivos de Configuración

### Estructura del Proyecto

```
HydraulicSimulator/
├── TSNet/
│   ├── Components/
│   │   ├── TSNetTankAdapter.cs
│   │   ├── TSNetPumpAdapter.cs
│   │   ├── TSNetPipeAdapter.cs
│   │   └── TSNetResults.cs
│   ├── TSNetSimulationManager.cs
│   └── TSNetINPGenerator.cs
├── Tests/
│   └── TSNetIntegrationTest.cs
└── HydraulicSimulationManager.cs

ObjetosSim/
├── HydraulicComponents/
│   ├── osHydTank.cs       # Integrado con TSNetTankAdapter
│   ├── osHydPump.cs       # Integrado con TSNetPumpAdapter
│   └── osHydPipe.cs       # Integrado con TSNetPipeAdapter
└── osBase.cs
```

## Consideraciones de Performance

### Optimizaciones Implementadas

1. **Configuración Inmutable**: Se captura una sola vez al inicio
2. **Lazy Loading**: Los adapters se inicializan solo cuando se necesitan
3. **Caching**: Los resultados se cachean hasta la siguiente actualización
4. **Thread Safety**: Locks mínimos para máximo rendimiento

### Métricas de Performance

- **Tiempo de inicio**: Reducido al eliminar cálculos duplicados
- **Memory footprint**: Optimizado con objetos compartidos
- **CPU usage**: Menor al centralizar cálculos en TSNet

## Conclusión

La integración TSNet Phase 2 proporciona una arquitectura robusta, escalable y mantenible para simulación hidráulica en CtrEditor. La separación clara entre cálculo (TSNet) y visualización (componentes UI) mejora tanto la consistencia como la performance del sistema.

La implementación sigue principios de ingeniería de software sólidos y proporciona una base excelente para futuras expansiones del sistema hidráulico.