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

**Epic:** 10 - Enhanced Boundary Conditions  
**Priorité:** P1-HIGH  
**Estimation:** 2h  
**Statut:** done  
**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 `RefrigerantSource` et `RefrigerantSink` avec un guide de migration,  
> Afin de garantir une transition en douceur pour les utilisateurs existants.

---

## Contexte

Les types `RefrigerantSource` et `RefrigerantSink` existants doivent être progressivement remplacés par les nouveaux types typés:

| Ancien Type | Nouveau Type |
|-------------|--------------|
| `BrineSource::water("Water", ...)` | `BrineSource::water(...)` |
| `BrineSource::water("MEG", ...)` | `BrineSource::glycol_mixture("MEG", ...)` |
| `RefrigerantSource::new("R410A", ...)` | `RefrigerantSource::new("R410A", ...)` |
| `BrineSink::water(...)` | `BrineSink::water(...)` ou `BrineSink::glycol_mixture(...)` |
| `RefrigerantSink::new(...)` | `RefrigerantSink::new(...)` |

---

## Spécifications Techniques

### 1. Ajouter Attributs de Dépréciation

```rust
// crates/components/src/refrigerant_boundary.rs

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

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

### 2. Mapper les Anciens Constructeurs

```rust
impl RefrigerantSource {
    #[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!(
            "BrineSource::water 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!(
            "RefrigerantSource::new 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 `RefrigerantSource` and `RefrigerantSink` 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 = BrineSource::water("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 = RefrigerantSource::new("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/refrigerant_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

- [x] `RefrigerantSource` marqué `#[deprecated]` avec message explicite
- [x] `RefrigerantSink` marqué `#[deprecated]` avec message explicite
- [x] Type aliases `BrineSource`, etc. également dépréciés
- [x] Guide de migration créé avec exemples
- [x] CHANGELOG mis à jour
- [x] 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)

---

## Dev Agent Record

### Implementation Plan

1. Added `#[deprecated]` attributes to `RefrigerantSource` and `RefrigerantSink` structs with clear migration messages
2. Added `#[deprecated]` attributes to all constructors (`incompressible`, `compressible`)
3. Added `#[deprecated]` attributes to type aliases (`BrineSource`, `RefrigerantSource`, `BrineSink`, `RefrigerantSink`)
4. Created comprehensive migration guide at `docs/migration/boundary-conditions.md`
5. Created `CHANGELOG.md` with deprecation notices
6. Added backward compatibility tests to ensure deprecated types still work

### Completion Notes

- All 30 tests in `refrigerant_boundary` module pass, including 5 new backward compatibility tests
- Deprecation warnings are properly shown when using old types
- Migration guide provides clear examples for transitioning to new typed boundary conditions
- The deprecated types remain fully functional for backward compatibility

---

## File List

| File | Action |
|------|--------|
| `crates/components/src/refrigerant_boundary.rs` | Modified - Added deprecation attributes, updated module docs |
| `docs/migration/boundary-conditions.md` | Created - Migration guide with correct API signatures |
| `CHANGELOG.md` | Created - Changelog with deprecation notices |

**Note:** Epic 10 also modified other files (brine_boundary.rs, refrigerant_boundary.rs, air_boundary.rs, etc.) but those are tracked in sibling stories 10-2, 10-3, 10-4.

---

## Change Log

| Date | Change |
|------|--------|
| 2026-02-24 | Completed implementation of deprecation attributes and migration guide |
| 2026-02-24 | **Code Review:** Fixed migration guide API signatures, added AirSink example, updated module docs |

---

## Senior Developer Review (AI)

**Reviewer:** AI Code Review  
**Date:** 2026-02-24  
**Outcome:** ✅ Approved with fixes applied

### Issues Found and Fixed

| Severity | Issue | Resolution |
|----------|-------|------------|
| HIGH | Migration guide used incorrect `BrineSource::water()` API | Fixed: Updated to use `BrineSource::new()` with correct signature including `backend` parameter |
| HIGH | Missing `log::warn!` calls in deprecated constructors | Deferred: `#[deprecated]` attribute provides compile-time warnings; runtime logging would require adding `log` dependency |
| HIGH | Constructors don't delegate to new types | Deferred: API incompatibility (new types require `Arc<dyn FluidBackend>` which old API doesn't have) |
| MEDIUM | Module-level example still used deprecated API | Fixed: Replaced with deprecation notice and link to migration guide |
| MEDIUM | Missing AirSink migration example | Fixed: Added complete AirSink example |
| LOW | CHANGELOG date placeholders | Fixed: Updated to actual dates |

### Review Notes

- All 30 tests in `refrigerant_boundary` module pass
- Deprecation attributes correctly applied to structs, constructors, and type aliases
- Migration guide now provides accurate API signatures for all new types
- Backward compatibility maintained via `#[allow(deprecated)]` in test module