# Charging Monitoring Operation

Monitorizarea unei sesiuni de încărcare: colectarea măsurătorilor, izolarea curbei şi calculul energiei.

## Responsabilități

- Orchestrează o sesiune de încărcare complet (start → record → end)

- Colectează măsurători de la meter la intervale regulate (~1Hz)

- Izolează porţiunea relevantă a curbei (fără pre/post charging noise)

- Calculează totalul de energie consumată (Wh)

- Persistă date în Core Data + iCloud

## Invarianţi

- **MUST**: Doar o sesiune activă per meter la orice moment

- **MUST**: Măsurătorile sunt cronologice (sortate după timestamp)

- **MUST**: Start time < end time (sauf pentru sesiunile active)

- **MUST**: Energia totală ≥ 0 (nu poate fi negativă)

- **MUST**: O sesiune completată este imutabilă

- **SHOULD**: O sesiune durează între 5 minute şi 48 ore

- **MAY**: Sesiuni orphane (meter deconectat) pot fi finalizate automat

## Stadiile sesiunii

```

idle

  ↓

startSession() → starting

  ↓

recordMeasurement() → active (repeat)

  ↓

endSession() → ended

  ↓

completed (immutable)

```

## Lifecycle

### 1. Start sesiune

```swift

let session = meter.startChargeRecord(for: device)

// ⟹ ChargeRecord(

//    id: UUID(),

//    sessionID: UUID(),

//    startTime: Date(),

//    chargedDeviceID: device.id,

//    meterID: meter.id,

//    measurements: [],

//    totalEnergy: 0

// )

```

**MUST:**

- `startTime` = `Date.now`

- `sessionID` = UUID unic

- `measurements` array = empty

- `totalEnergy` = 0

- Marchez sesiunea ca "active"

**SHOULD:**

- Notify UI: "Recording started"

- Start periodic measurement requests (1Hz timer)

- Log sesiune în analytics

### 2. Record measurement

```swift

while session.isActive {

    let measurement = meter.lastDataPoint

    session.addMeasurement(measurement)

}

```

**Frecvenţă**: 1Hz (1000ms interval)

**MUST:**

- `measurement.timestamp > session.startTime`

- Măsurătorile ordonate cronologic

- Ignore duplicate timestamps

- Validare: voltage, current ≥ 0

**SHOULD:**

- Drop măsurători dacă queue > 500 items

- Skip interval dacă meter nu are date nouă

- Log invalid measurements (don't crash)

**MAY:**

- Adjust frecvenţă dacă battery low (500ms → 2s)

- Throttle dacă temperatura critică

### 3. End sesiune

```swift

meter.endChargeRecord(session)

```

**MUST:**

- `endTime` = `Date.now`

- Calculate `totalEnergy` = ∑(V × A × Δt) pentru fiecare interval

- Call [Charge Curve Isolation](./ChargeCurveIsolation.md) pentru obţine valid range

- Marchez sesiunea ca "completed"

- Salvează în Core Data sync

**SHOULD:**

- Recalculează media power (watts)

- Calculează duration (seconds)

- Notify UI: "Recording completed"

- Archive sesiunea (backup iCloud)

**MAY:**

- Trigger conflict resolution (dacă detecta duplicate-uri)

- Trigger capacity learning (dacă sesiune completă)

## API Public

### Proprietăţi sesiune

| Proprietate | Tip | Descriere |

|---|---|---|

| `id` | UUID | Identificator unic |

| `sessionID` | UUID | Reference în persistență |

| `chargedDeviceID` | UUID | Device monitorizat |

| `meterID` | UUID | Meter folosit |

| `startTime` | Date | Moment start |

| `endTime` | Date? | Moment end (nil dacă active) |

| `measurements` | [Measurement] | Puncte colectate |

| `totalEnergy` | Double | Wh total |

| `isActive` | Bool | Status curent |

| `duration` | TimeInterval | end - start |

| `peakPower` | Double | Max watts |

| `averagePower` | Double | Mean watts |

### Metode

```swift

// Orchestrare

func startChargeRecord(for device: ChargedDevice) -> ChargeRecord

func recordMeasurement(_ measurement: Measurement, in session: ChargeRecord)

func endChargeRecord(_ session: ChargeRecord) -> ChargeRecord

// Calculaţii

func calculateTotalEnergy(measurements: [Measurement]) -> Double

func calculatePeakPower(measurements: [Measurement]) -> Double

func calculateAveragePower(measurements: [Measurement]) -> Double

// Persistență

func saveSession(_ record: ChargeRecord)

func loadSession(id: UUID) -> ChargeRecord?

```

## Comportamente critice

### Timeout pe sesiuni

- **MUST**: Dacă nu primim măsurători > 5 min, sesiunea e considerat "stale"

- **SHOULD**: Notifică utilizator: "No data received, disconnect?"

- **MAY**: Auto-finalizează după 10 min inactivitate

### Validare măsurători

```swift

func isValidMeasurement(_ m: Measurement) -> Bool {

    // Voltage: 0V — 30V (USB + other)

    // Current: 0A — 10A (typical chargers)

    // Power: 0W — 300W (practical limit)

    return m.voltage >= 0 && m.voltage <= 30 &&

           m.current >= 0 && m.current <= 10 &&

           m.power >= 0 && m.power <= 300

}

```

**MUST**: Drop invalide measurements

**SHOULD**: Log warnings pentru edge-case values

### Merge duplicate sessions

Se declanşează când:

- Două sesiuni cu overlap temporal > 50%

- Aceeaşi device + meter

Rezoluţie:

- **MUST**: Keep sesiunea cu mai multe măsurători

- **MUST**: Combină energiile: `total = session1.energy + session2.energy`

- **SHOULD**: Archive old session version

### Energia negativă (edge case)

Cauze posibile:

1. Meter inversează polarity (rare)

2. Măsurători corupte

3. Bug în parsing

**SHOULD**: Log warning

**MAY**: Absolute value: `energy = abs(energy)`

**NEVER**: Discard sesiune

## Testare

### Unit tests

```swift

// Start/end

test_startSessionCreatesValidRecord()

test_endSessionCalculatesTotalEnergy()

// Measurements

test_recordMeasurement_AddsToSession()

test_recordMeasurement_FailsIfSessionEnded()

test_measurementsAreOrdered()

test_invalidMeasurement_IsDropped()

// Calculations

test_calculateTotalEnergy_WithValidData()

test_calculateTotalEnergy_WithGaps()

test_calculatePeakPower()

test_calculateAveragePower()

// Validation

test_sessionTimeValidity()

test_sessionDuration_Max48Hours()

test_activeSessions_OnlyOne()

```

### Integration tests

- [ ] Full cycle: start → record 100 samples → end

- [ ] Sesiune pe device A, apoi device B (same meter)

- [ ] Meter disconnect → auto-finalize

- [ ] Energy = ∑ = match manual calculation

- [ ] Sesiune persistent după app restart

## Dependenţe

- [Meter.md](./Meter.md): `meter.lastDataPoint`, state

- [Charge Curve Isolation](./ChargeCurveIsolation.md): extract valid range

- [Capacity Measurement](./CapacityMeasurement.md): capacity learning

- [Charge Curve Storage](./ChargeCurveStorage.md): persistence

- Core Data: `ChargeSession` entity

## Notes

- Time-series resolution: 1Hz (1000ms)

- Energy formula: `E = ∑(V × A × Δt)` (integral numerical)

- Legat: [Charge Session Integrity](../Charge%20Session%20Integrity%20and%20Conflict%20Healing.md)