Story 10.5: Migration et Dépréciation des Anciens Types

Epic: 10 - Enhanced Boundary Conditions
Priorité: P1-HIGH
Estimation: 2h
Statut: backlog
Dépendances: Stories 10-2, 10-3, 10-4

Story

En tant que développeur de la librairie Entropyk,
Je veux déprécier les anciens types FlowSource et FlowSink avec un guide de migration,
Afin de garantir une transition en douceur pour les utilisateurs existants.

Contexte

Les types FlowSource et FlowSink existants doivent être progressivement remplacés par les nouveaux types typés:

Ancien Type	Nouveau Type
`FlowSource::incompressible("Water", ...)`	`BrineSource::water(...)`
`FlowSource::incompressible("MEG", ...)`	`BrineSource::glycol_mixture("MEG", ...)`
`FlowSource::compressible("R410A", ...)`	`RefrigerantSource::new("R410A", ...)`
`FlowSink::incompressible(...)`	`BrineSink::water(...)` ou `BrineSink::glycol_mixture(...)`
`FlowSink::compressible(...)`	`RefrigerantSink::new(...)`

Spécifications Techniques

1. Ajouter Attributs de Dépréciation

// crates/components/src/flow_boundary.rs

#[deprecated(
    since = "0.2.0",
    note = "Use RefrigerantSource or BrineSource instead. \
            See migration guide in docs/migration/boundary-conditions.md"
)]
pub struct FlowSource { /* ... */ }

#[deprecated(
    since = "0.2.0",
    note = "Use RefrigerantSink or BrineSink instead. \
            See migration guide in docs/migration/boundary-conditions.md"
)]
pub struct FlowSink { /* ... */ }

2. Mapper les Anciens Constructeurs

impl FlowSource {
    #[deprecated(
        since = "0.2.0",
        note = "Use BrineSource::water() for water or BrineSource::glycol_mixture() for glycol"
    )]
    pub fn incompressible(
        fluid: impl Into<String>,
        p_set_pa: f64,
        h_set_jkg: f64,
        outlet: ConnectedPort,
    ) -> Result<Self, ComponentError> {
        // Log de warning
        log::warn!(
            "FlowSource::incompressible is deprecated. \
             Use BrineSource::water() or BrineSource::glycol_mixture() instead."
        );
        
        // Créer le type approprié en interne
        let fluid = fluid.into();
        if fluid == "Water" {
            // Déléguer vers BrineSource::water()
        } else {
            // Déléguer vers BrineSource::glycol_mixture()
        }
    }
    
    #[deprecated(
        since = "0.2.0",
        note = "Use RefrigerantSource::new() instead"
    )]
    pub fn compressible(
        fluid: impl Into<String>,
        p_set_pa: f64,
        h_set_jkg: f64,
        outlet: ConnectedPort,
    ) -> Result<Self, ComponentError> {
        log::warn!(
            "FlowSource::compressible is deprecated. \
             Use RefrigerantSource::new() instead."
        );
        // ...
    }
}

3. Créer le Guide de Migration

# docs/migration/boundary-conditions.md

# Migration Guide: Boundary Conditions

## Overview

The `FlowSource` and `FlowSink` types have been replaced with typed alternatives:
- `RefrigerantSource` / `RefrigerantSink` - for refrigerants
- `BrineSource` / `BrineSink` - for liquid heat transfer fluids
- `AirSource` / `AirSink` - for humid air

## Migration Examples

### Water Source (Before)

\`\`\`rust
let source = FlowSource::incompressible("Water", 3.0e5, 63_000.0, port)?;
\`\`\`

### Water Source (After)

\`\`\`rust
let source = BrineSource::water(
    Temperature::from_celsius(15.0),
    Pressure::from_pascals(3.0e5),
    port
)?;
\`\`\`

### Refrigerant Source (Before)

\`\`\`rust
let source = FlowSource::compressible("R410A", 10.0e5, 280_000.0, port)?;
\`\`\`

### Refrigerant Source (After)

\`\`\`rust
let source = RefrigerantSource::new(
    "R410A",
    Pressure::from_pascals(10.0e5),
    Enthalpy::from_joules_per_kg(280_000.0),
    port
)?;
\`\`\`

## Benefits of New Types

1. **Type Safety**: Fluid type is explicit in the type name
2. **Concentration Support**: BrineSource supports glycol concentration
3. **Vapor Quality**: RefrigerantSource supports vapor quality input
4. **Psychrometrics**: AirSource supports humidity and wet bulb temperature
\`\`\`

Fichiers à Modifier

Fichier	Action
`crates/components/src/flow_boundary.rs`	Ajouter attributs `#[deprecated]`
`docs/migration/boundary-conditions.md`	Créer guide de migration
`CHANGELOG.md`	Documenter les changements breaking

Critères d'Acceptation

FlowSource marqué #[deprecated] avec message explicite
FlowSink marqué #[deprecated] avec message explicite
Type aliases IncompressibleSource, etc. également dépréciés
Guide de migration créé avec exemples
CHANGELOG mis à jour
Tests existants passent toujours (rétrocompatibilité)

Tests Requis

#[cfg(test)]
mod tests {
    #[test]
    fn test_deprecated_flow_source_still_works() {
        // Vérifier que les anciens types fonctionnent encore
        // (avec warning de dépréciation)
    }
    
    #[test]
    fn test_migration_water_source() {
        // Vérifier que le nouveau type donne les mêmes résultats
    }
    
    #[test]
    fn test_migration_refrigerant_source() {
        // Vérifier que le nouveau type donne les mêmes résultats
    }
}

Timeline de Suppression

Version	Action
0.2.0	Dépréciation avec warnings
0.3.0	Les anciens types sont cachés par défaut (feature flag)
1.0.0	Suppression complète des anciens types

5.7 KiB Raw Blame History