# Consumption Measurement Operation

Măsurarea consumului pe o perioadă arbitrară, cu statistici şi predicţii bazate pe interval selectat.

## Responsabilități

- Măsurare consum liber (orice interval, nu doar sesiuni complete)
- Afişare statistici pe interval selectat
- Generare predicţii (extrapolări pe bază de trend)
- Tăiere curbei ("tail trimming") pentru a selecta porţiunea relevantă
- Salvează statisticile, NU datele măsurătorilor brute

## Diferenţa faţă de Charging Monitoring

| Aspect | Charging Monitoring | Consumption Measurement |
|---|---|---|
| Interval | Fixed (start → end charge) | Arbitrary (user-selected) |
| Storage | Sesiune completă + measurements | Statistics only |
| UI | Timeline sesiune | Graph with selection |
| Predicţii | Capacity learning | Energy extrapolation |

## Concepte

### Consumption = Energy over time

```
Energy (Wh) = ∫ P(t) dt
            = ∑ (V × A × Δt)

Power (W) = V × A (instantaneous)
Average Power (W) = Total Energy / Duration
```

## Invarianţi

- **MUST**: `startTime < endTime` (interval valid)
- **MUST**: Interval ≥ 10 secunde (minim useful)
- **MUST**: Interval ≤ 30 zile (limit practic pentru extrapolări)
- **MUST**: Statisticile trebuie salvate, măsurătorile brute se discard
- **MUST**: Fără măsurători individuale în persistență, doar agregări
- **SHOULD**: Interval tipic: 1 minut — 24 ore
- **MAY**: Predicţii valide doar pe ±1 interval (ex: dacă measured 1h, predict next 1h)

## Lifecycle

### 1. Selection interval (user interaction)

Utilizatorul deschide graficul şi selectează interval:

```
User taps start position în grafic
User drags to end position
System highlights selected region
User taps "Measure consumption"
```

**Rezultat:**
```swift
struct ConsumptionSelection {
    let startTime: Date
    let endTime: Date
    let meter: Meter
    let device: ChargedDevice?  // Optional, may be unknown
}
```

**MUST:** Times trebuie din măsurători existente (bounded)

### 2. Compute statistics

```swift
func computeConsumptionStats(
    measurements: [Measurement],
    from startTime: Date,
    to endTime: Date
) -> ConsumptionStats {
    // 1. Filter measurements în interval
    let filtered = measurements.filter { m in
        m.timestamp >= startTime && m.timestamp <= endTime
    }
    
    guard !filtered.isEmpty else {
        return .empty
    }
    
    // 2. Calculate energy
    let energy = calculateEnergy(filtered)
    
    // 3. Calculate time-based metrics
    let duration = endTime.timeIntervalSince(startTime)
    let averagePower = energy * 3600 / duration  // Convert Wh to W
    
    // 4. Power statistics
    let powers = filtered.map { $0.power }
    let peakPower = powers.max() ?? 0
    let minPower = powers.min() ?? 0
    let stdDev = calculateStdDev(powers)
    
    // 5. Voltage/Current stats
    let voltages = filtered.map { $0.voltage }
    let currents = filtered.map { $0.current }
    
    return ConsumptionStats(
        energy: energy,
        duration: duration,
        averagePower: averagePower,
        peakPower: peakPower,
        minPower: minPower,
        stdDevPower: stdDev,
        sampleCount: filtered.count,
        startVoltage: filtered.first?.voltage,
        endVoltage: filtered.last?.voltage,
        averageVoltage: voltages.average(),
        averageCurrent: currents.average()
    )
}
```

### 3. Generate predictions

```swift
func predictFutureConsumption(
    stats: ConsumptionStats,
    duration: TimeInterval
) -> ConsumptionPrediction {
    // Linear extrapolation
    let predictedEnergy = stats.averagePower * duration / 3600
    
    // Confidence bounds (±20% for stability)
    let confidence = 0.8
    let lowerBound = predictedEnergy * (1 - (1 - confidence))
    let upperBound = predictedEnergy * (1 + (1 - confidence))
    
    return ConsumptionPrediction(
        energy: predictedEnergy,
        lowerBound: lowerBound,
        upperBound: upperBound,
        confidence: confidence,
        method: "linear"
    )
}
```

**Metode:**
- **Linear**: `E_predicted = P_avg × t` (simple, stable)
- **Polynomial**: `E_predicted = a + b×t + c×t²` (for trends)
- **Exponential**: (rarely used, for battery degradation)

**MUST:** Confidence ≤ 1.0 (0-100%)
**SHOULD:** Linear enough for 1 interval ahead
**MAY:** Polynomial dacă > 2 intervals

### 4. Tail trimming (user action)

Utilizatorul poate "tăia coada" pentru a refina selecţia:

```
Initial selection: 00:00 - 10:00 (10h)
User drags start: 00:30 - 10:00 (9.5h)
User drags end: 00:30 - 09:30 (9h)
Result: statistics recalculate pe [00:30, 09:30]
```

**Interactiv:**
- Slider @ start time
- Slider @ end time
- Real-time stats update

**MUST:** Recalculate stats on every trim
**SHOULD:** Debounce updates (100ms)
**MUST:** Store final selection, not intermediate states

### 5. Save consumption record

**NU salvează:** Măsurătorile individuale

**SALVEAZĂ:**
```swift
struct ConsumptionRecord {
    let id: UUID
    let meterID: UUID
    let deviceID: UUID?
    let startTime: Date
    let endTime: Date
    
    // Statistics (aggregated)
    let totalEnergy: Double  // Wh
    let averagePower: Double  // W
    let peakPower: Double
    let minPower: Double
    let stdDevPower: Double
    let sampleCount: Int
    
    // Metadata
    let createdAt: Date
    let notes: String?  // User annotation
}
```

**NOT saved:**
- ❌ Individual measurements (voltage, current per sample)
- ❌ Timestamps of each sample
- ❌ Raw power values

**REASON:** Storage efficiency + privacy

## API Public

### Selection & Stats

```swift
// User selects interval from graph
func selectConsumptionInterval(
    start: Date,
    end: Date,
    meter: Meter
) -> ConsumptionStats?

// Refine selection via tail trimming
func trimConsumptionInterval(
    from newStart: Date,
    to newEnd: Date
) -> ConsumptionStats?

// Get current statistics
func currentStats() -> ConsumptionStats?
```

### Predictions

```swift
// Predict next interval
func predictConsumption(
    for duration: TimeInterval
) -> ConsumptionPrediction?

// Extrapolate to full day/week
func extrapolateToDay() -> ConsumptionPrediction?
func extrapolateToWeek() -> ConsumptionPrediction?
```

### Persistence

```swift
// Save aggregated stats only
func saveConsumptionRecord(_ record: ConsumptionRecord) -> Bool

// Load history
func loadConsumptionRecords(for meter: Meter) -> [ConsumptionRecord]

// Discard raw data (keep stats)
func discardMeasurements(before: Date) -> Int
```

## Comportamente critice

### Interval validation

```
User selects: 10:00 AM - 10:00 AM (zero duration)
⟹ Error: "Minimum 10 seconds"

User selects: 01-May - 01-June (31 days)
⟹ Warning: "Extrapolation unreliable >7 days"
```

**MUST:** duration ≥ 10s
**SHOULD:** Warn if duration > 7 days
**SHOULD:** Cap predictions to ±1 interval

### No tail = invalid

```
Selection: 10:00-11:00
User never presses "Save"
App terminates
⟹ Selection lost (no persistence of in-progress)
```

**MUST:** NU salvează interim selections
**SHOULD:** Keep in-memory during session
**MUST:** Explicit save() required

### Power variability

```
Measuring USB charger:
Min power: 0.1W (idle)
Max power: 18W (fast charge)
StdDev: high (~5W)

Prediction: linear avg = 8W
Confidence: 0.7 (high variance)
```

**SHOULD:** Calculate stdDev
**SHOULD:** Reflect confidence (lower if high variance)
**MAY:** Suggest "Power unstable, prediction unreliable"

### Measurement gaps

```
Recording: 10:00-11:00
Meter disconnect: 10:30-10:45
Data available: 10:00-10:30 (30min) + 10:45-11:00 (15min)
User selects: 10:00-11:00 (but only 45min data)

Stats: calculate on available data
Warning: "15 minutes missing"
```

**MUST:** Alert user to gaps
**SHOULD:** Calculate on available data only
**MAY:** Adjust confidence (lower if gaps > 10%)

## Statistici generate

### Basic

| Metric | Unit | Formula |
|---|---|---|
| Total Energy | Wh | ∑(V × A × Δt) |
| Duration | seconds | endTime - startTime |
| Average Power | W | Energy × 3600 / Duration |
| Peak Power | W | max(P(t)) |
| Min Power | W | min(P(t)) |

### Advanced

| Metric | Unit | Descriere |
|---|---|---|
| StdDev Power | W | Variabilitate în putere |
| Avg Voltage | V | Media tensiune |
| Avg Current | A | Media curent |
| Sample Count | # | Measurement count |
| Confidence | % | Reliability predicţie |

## Predicţii

### Linear extrapolation

```
Measured: P_avg = 10W over 1 hour
Predict next 1h: E = 10W × 1h = 10Wh
Bounds: ±(1-confidence)% = ±20% = [8Wh, 12Wh]
```

### Time scaling

```
Measured: 5W average over 10 minutes
Predict over 1 hour: 5W × 6 = 30Wh
Predict over 24h: 5W × 144 = 720Wh

But confidence decreases with time:
- 1×interval: 80% confidence
- 2×interval: 60% confidence
- 5×interval: 40% confidence
- 10+×interval: 20% confidence
```

**MUST:** Confidence degrades dengan scaling
**SHOULD:** Warn if confidence < 50%

## Testare

### Unit tests

```swift
test_selectConsumptionInterval_ValidDates()
test_selectConsumptionInterval_MinimumDuration()
test_trimConsumptionInterval_UpdatesStats()
test_computeConsumptionStats_ValidData()
test_computeConsumptionStats_EmptyRange()
test_calculateAveragePower()
test_predictConsumption_Linear()
test_predictConsumption_ConfidenceDegrades()
test_extrapolateToDay_WithinBounds()
test_recordDoesNotStoreMeasurements()
test_discardMeasurements_KeepsStats()
```

### Integration tests

- [ ] Select 1h interval → get stats
- [ ] Trim tail → stats recalculate
- [ ] Predict next 1h → confidence 80%
- [ ] Predict next 24h → confidence drops to 40%
- [ ] Save record → measurements discarded, stats kept
- [ ] Load record → only stats available
- [ ] Measurement gap detected → warning shown
- [ ] High power variance → confidence reduced

## Edge cases

### Very short interval

```
User selects: 10:00:00 - 10:00:05 (5 seconds)
⟹ Error: below 10s minimum
```

**MUST:** Reject

### Very long interval

```
User selects: 01-Jan - 31-Dec (365 days)
⟹ Warning: "Extrapolation unreliable beyond 7 days"
Confidence: 20%
```

**SHOULD:** Accept but warn
**SHOULD:** Reduce confidence

### Single measurement

```
Interval: 10:00:00 - 10:00:01
Data points: 1 (only start)
Energy: 0 (insufficient interval)
⟹ Error: "Need minimum 10 measurements"
```

**MUST:** Require ≥ 10 samples

### No voltage/current data

```
Meter type: Unknown or not reporting
Power available: yes
Voltage/Current: null

Stats: calculate energy from power only
Avg Voltage: null
Avg Current: null
```

**SHOULD:** Handle gracefully
**MAY:** Show "Limited data available"

## Storage model

### What IS saved

```json
{
  "id": "UUID",
  "meterID": "UUID",
  "startTime": "2026-05-23T10:00:00Z",
  "endTime": "2026-05-23T11:00:00Z",
  "totalEnergy": 12.5,
  "averagePower": 12.5,
  "peakPower": 18.0,
  "minPower": 1.2,
  "stdDevPower": 4.5,
  "sampleCount": 3600,
  "createdAt": "2026-05-23T11:02:00Z"
}
```

### What is NOT saved

```
❌ individual measurements
❌ voltage samples
❌ current samples  
❌ power curve
❌ battery levels
❌ meter metadata
```

## Dependenţe

- [Charging Monitoring](./ChargingMonitoring.md): access to meter data
- [Charge Curve Storage](./ChargeCurveStorage.md): query full measurements
- Core Data: ConsumptionRecord entity
- UI: Graph view with interval selection

## UI Components

### Graph with selection

```
┌─────────────────────────────────┐
│  Power (W)                      │
│  20 ├──────┐                    │
│     │ ████ │  ← user selection  │
│  10 ├──████└────┐               │
│     │          │               │
│   0 └──────────┴───────────────┘
│     10:00   10:30    11:00
│     ↑start           ↑end
│     (draggable)      (draggable)
└─────────────────────────────────┘
```

### Stats display

```
Selected Interval: 10:00 — 10:30 (30 min)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Energy:         6.3 Wh
Average Power:  12.6 W
Peak Power:     18.0 W
Min Power:      1.2 W
Variance:       ±4.5 W
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prediction (next 30 min):
  Energy:       6.3 Wh (confidence: 80%)
  Range:        5.0 — 7.6 Wh
```

## Notes

- **Not a charge session**: No device pairing, no capacity learning
- **Independent operation**: Coexists with ChargeInsights
- **Low storage footprint**: Only aggregates, not raw curves
- **Privacy-friendly**: Discards detailed measurements
- **Real-time**: Updates on interval selection/trimming
- Related: [Charging Monitoring](./ChargingMonitoring.md) for full sessions