Entropyk/_bmad-output/implementation-artifacts/10-5-migration-deprecation.md

# 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

```rust
// 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

```rust
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

```markdown
# 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

```rust
#[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 |

---

## Références

- [Architecture Document](../../plans/boundary-condition-refactoring-architecture.md)
- [Epic 10](../planning-artifacts/epic-10-enhanced-boundary-conditions.md)