chore: sync project state and current artifacts
This commit is contained in:
Sepehr
@@ -0,0 +1,272 @@
|
||||
# Story 9.6: Amélioration Logging Validation Énergie
|
||||
|
||||
Status: done
|
||||
|
||||
**Epic:** 9 - Coherence Corrections (Post-Audit)
|
||||
**Priorité:** P2-IMPORTANTE
|
||||
**Estimation:** 1h
|
||||
**Dépendances:** Stories 9.3, 9.4, 9.5 (all done)
|
||||
|
||||
---
|
||||
|
||||
## Story
|
||||
|
||||
> En tant que développeur debuggant une simulation,
|
||||
> Je veux un avertissement explicite quand des composants sont ignorés dans la validation énergétique,
|
||||
> Afin d'identifier rapidement les implémentations manquantes.
|
||||
|
||||
---
|
||||
|
||||
## Contexte
|
||||
|
||||
L'audit de cohérence a révélé que `check_energy_balance()` utilise un logging de niveau DEBUG pour les composants skippés, ce qui les rend invisibles en configuration par défaut.
|
||||
|
||||
---
|
||||
|
||||
## Problème Actuel
|
||||
|
||||
```rust
|
||||
// crates/solver/src/system.rs:1873-1879
|
||||
_ => {
|
||||
components_skipped += 1;
|
||||
tracing::debug!( // ← Niveau DEBUG, pas WARNING
|
||||
node_index = node_idx.index(),
|
||||
"Component lacks full energy transfer or enthalpy data - skipping energy balance check"
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Conséquence** : Les développeurs ne sont pas avertis que certains composants sont ignorés dans la validation.
|
||||
|
||||
---
|
||||
|
||||
## Solution Proposée
|
||||
|
||||
### Changements
|
||||
|
||||
1. **Passer de DEBUG à WARN** pour les composants skippés
|
||||
2. **Inclure le type du composant** dans le message
|
||||
3. **Ajouter un résumé final** si des composants ont été skippés
|
||||
|
||||
### Implémentation
|
||||
|
||||
```rust
|
||||
// crates/solver/src/system.rs
|
||||
|
||||
pub fn check_energy_balance(&self, state: &SystemState) -> Result<(), ValidationError> {
|
||||
let mut total_heat_in = Power::from_watts(0.0);
|
||||
let mut total_heat_out = Power::from_watts(0.0);
|
||||
let mut total_work_in = Power::from_watts(0.0);
|
||||
let mut total_work_out = Power::from_watts(0.0);
|
||||
let mut components_validated = 0;
|
||||
let mut components_skipped = 0;
|
||||
let mut skipped_components: Vec<String> = Vec::new();
|
||||
|
||||
for node_idx in self.graph.node_indices() {
|
||||
let component = &self.graph[node_idx];
|
||||
|
||||
let energy_transfers = component.energy_transfers(state);
|
||||
let mass_flows = component.port_mass_flows(state);
|
||||
let enthalpies = component.port_enthalpies(state);
|
||||
|
||||
match (energy_transfers, mass_flows, enthalpies) {
|
||||
(Some((heat, work)), Ok(m_flows), Ok(h_flows)) if m_flows.len() == h_flows.len() => {
|
||||
// ... existing validation logic ...
|
||||
components_validated += 1;
|
||||
}
|
||||
_ => {
|
||||
components_skipped += 1;
|
||||
let component_info = format!(
|
||||
"{} (type: {})",
|
||||
component.name(),
|
||||
std::any::type_name_of_val(component)
|
||||
.split("::")
|
||||
.last()
|
||||
.unwrap_or("unknown")
|
||||
);
|
||||
skipped_components.push(component_info.clone());
|
||||
|
||||
tracing::warn!(
|
||||
component = %component_info,
|
||||
node_index = node_idx.index(),
|
||||
"Component lacks energy_transfers() or port_enthalpies() - SKIPPED in energy balance validation"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Résumé final si des composants ont été skippés
|
||||
if components_skipped > 0 {
|
||||
tracing::warn!(
|
||||
components_validated = components_validated,
|
||||
components_skipped = components_skipped,
|
||||
skipped = ?skipped_components,
|
||||
"Energy balance validation incomplete: {} component(s) skipped. \
|
||||
Implement energy_transfers() and port_enthalpies() for full validation.",
|
||||
components_skipped
|
||||
);
|
||||
}
|
||||
|
||||
// ... rest of validation ...
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fichiers à Modifier
|
||||
|
||||
| Fichier | Action |
|
||||
|---------|--------|
|
||||
| `crates/solver/src/system.rs` | Modifier `check_energy_balance()` |
|
||||
|
||||
---
|
||||
|
||||
## Critères d'Acceptation
|
||||
|
||||
- [x] Logging au niveau WARN (pas DEBUG)
|
||||
- [x] Message inclut le nom et type du composant
|
||||
- [x] Résumé final avec liste des composants skippés
|
||||
- [x] Test que le warning est bien émis
|
||||
|
||||
---
|
||||
|
||||
## Tests Requis
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use tracing::subscriber;
|
||||
use tracing_subscriber::layer::SubscriberExt;
|
||||
|
||||
#[test]
|
||||
fn test_warn_emitted_for_skipped_component() {
|
||||
// Setup tracing capture
|
||||
let (layer, handle) = tracing_subscriber::layer::with_test_writer();
|
||||
let _guard = subscriber::set_default(tracing_subscriber::registry().with(layer));
|
||||
|
||||
// Create system with component that lacks energy methods
|
||||
let mut system = System::new();
|
||||
// ... add component without energy_transfers() ...
|
||||
|
||||
let state = SystemState::default();
|
||||
let _ = system.check_energy_balance(&state);
|
||||
|
||||
// Verify warning was emitted
|
||||
let logs = handle.read();
|
||||
assert!(logs.contains("SKIPPED in energy balance validation"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exemple de Sortie
|
||||
|
||||
### Avant correction
|
||||
|
||||
```
|
||||
DEBUG entropyk_solver::system: Component lacks full energy transfer or enthalpy data - skipping energy balance check node_index=2
|
||||
```
|
||||
|
||||
### Après correction
|
||||
|
||||
```
|
||||
WARN entropyk_solver::system: Component lacks energy_transfers() or port_enthalpies() - SKIPPED in energy balance validation component="EV-01 (type: ExpansionValve)" node_index=2
|
||||
WARN entropyk_solver::system: Energy balance validation incomplete: 1 component(s) skipped. Implement energy_transfers() and port_enthalpies() for full validation. components_validated=4 components_skipped=1 skipped=["EV-01 (type: ExpansionValve)"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### Architecture Patterns
|
||||
|
||||
- **Tracing crate**: The project uses `tracing` for structured logging with spans
|
||||
- **Log levels**: DEBUG for detailed diagnostics, WARN for actionable issues
|
||||
- **Pattern**: Use structured fields (`node_index = value`) for searchable logs
|
||||
|
||||
### Current Implementation Analysis
|
||||
|
||||
The current code at [`crates/solver/src/system.rs:1855-1861`](crates/solver/src/system.rs:1855):
|
||||
|
||||
```rust
|
||||
_ => {
|
||||
components_skipped += 1;
|
||||
tracing::debug!(
|
||||
node_index = node_idx.index(),
|
||||
"Component lacks full energy transfer or enthalpy data - skipping energy balance check"
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Key observations:**
|
||||
1. Uses `tracing::debug!` - invisible with default `RUST_LOG=info`
|
||||
2. Missing component type information
|
||||
3. No summary at the end of validation
|
||||
|
||||
### Implementation Notes
|
||||
|
||||
1. **Getting component type**: Use `std::any::type_name_of_val(component)` (stabilized in Rust 1.76)
|
||||
2. **Component name**: Access via `component.name()` method from `Component` trait
|
||||
3. **Tracking skipped components**: Add `Vec<String>` to collect skipped component info
|
||||
|
||||
### Dependencies Status
|
||||
|
||||
| Story | Status | Notes |
|
||||
|-------|--------|-------|
|
||||
| 9-3 ExpansionValve Energy Methods | done | `ExpansionValve` now has `energy_transfers()` |
|
||||
| 9-4 FlowSource/FlowSink Energy Methods | review | Implementation complete, pending review |
|
||||
| 9-5 FlowSplitter/FlowMerger Energy Methods | ready-for-dev | Depends on this story |
|
||||
|
||||
**Note**: This story can be implemented independently - it improves logging regardless of whether other components have complete energy methods.
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
1. **Unit test**: Create a mock component without energy methods, verify warning is emitted
|
||||
2. **Integration test**: Run `check_energy_balance()` on a system with mixed components
|
||||
3. **Manual verification**: Run with `RUST_LOG=warn` and verify warnings appear
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
- File to modify: `crates/solver/src/system.rs`
|
||||
- Function: `check_energy_balance(&self, state: &StateSlice)`
|
||||
- Line range: ~1855-1861 (the `_ =>` match arm)
|
||||
|
||||
### References
|
||||
|
||||
- [Coherence Audit Report](./coherence-audit-remediation-plan.md)
|
||||
- [Story 7-2 Energy Balance Validation](./7-2-energy-balance-validation.md)
|
||||
- [Rust tracing crate docs](https://docs.rs/tracing/latest/tracing/)
|
||||
- [std::any::type_name_of_val](https://doc.rust-lang.org/std/any/fn.type_name_of_val.html)
|
||||
|
||||
---
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
z-ai/glm-5:free
|
||||
|
||||
### Debug Log References
|
||||
|
||||
- Build succeeded with `cargo build --package entropyk-solver`
|
||||
- All tests passed with `cargo test --package entropyk-solver`
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
- **Implementation**: Modified `check_energy_balance()` in `crates/solver/src/system.rs` to:
|
||||
1. Use `tracing::warn!` instead of `tracing::debug!` for skipped components
|
||||
2. Include component signature and type name in the warning message using `component.signature()` and `std::any::type_name_of_val()`
|
||||
3. Track skipped components in a `Vec<String>` and emit a summary warning at the end if any components were skipped
|
||||
- **Note**: Used `component.signature()` instead of `component.name()` because the `Component` trait doesn't have a `name()` method - `signature()` provides component identification information
|
||||
- **Tests**: Added three unit tests with proper tracing capture using `tracing_subscriber`:
|
||||
- `test_energy_balance_warns_for_skipped_components`: Verifies warning is emitted with "SKIPPED in energy balance validation"
|
||||
- `test_energy_balance_includes_component_type_in_warning`: Verifies component type is included in warning
|
||||
- `test_energy_balance_summary_warning`: Verifies summary warning with "Energy balance validation incomplete"
|
||||
- **Code Review Fix**: Added `tracing-subscriber` to dev-dependencies for proper log capture in tests
|
||||
- All acceptance criteria satisfied
|
||||
|
||||
### File List
|
||||
|
||||
- `crates/solver/src/system.rs` (modified)
|
||||
Reference in New Issue
Block a user