# UI Alignment to API Documentation

Mapare UI ↔ Operații documentate. Status implementare şi TODO-uri pentru a alinia UI la documentație.

---

## 1. Charging Monitoring

**Documentație:** [ChargingMonitoring.md](./ChargingMonitoring.md)

### Responsabilități

- ✅ Start → record → end sesiune

- ✅ Colectare măsurători ~1Hz

- ✅ Calculul energiei totale

- ⚠️ Timeout logic (incomplete)

### UI Components

| File | Status | Alignment | TODO |

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

| `MeterChargeRecordTabView.swift` | ✅ Exists | Good | Document timeout handling |

| `ChargeRecordSheetView.swift` | ✅ Exists | Fair | Add measurement count UI |

| `ChargeSessionCompletionSheetView.swift` | ✅ Exists | Fair | Show isolation interval |

| `BatteryCheckpointEditorSheetView.swift` | ✅ Exists | Good | Add stdDev visualization |

### Current UI Flow

```

MeterChargeRecordTabView

├─ [Start recording button]

├─ [Live power graph]

├─ [Energy counter (Wh)]

├─ [Duration counter]

└─ [Stop recording button]

   └─ ChargeRecordSheetView

      ├─ [Completion details]

      ├─ [Battery checkpoints]

      ├─ [Charger selection]

      └─ [Save/discard]

```

### Needed Alignments

1. **Invariant validation display**

   - MUST show error if start without device

   - SHOULD show warning if session > 24h

   - SHOULD show warning if measurement gap > 5min

2. **Measurement monitoring**

   - SHOULD display sample count (ex: "324 samples")

   - SHOULD show last update time

   - MAY show power trend (trending up/down/stable)

3. **Isolation visualization**

   - After stop, show isolated interval on curve

   - Highlight [real_start, real_end]

   - Show pre/post noise regions

---

## 2. Capacity Measurement

**Documentație:** [CapacityMeasurement.md](./CapacityMeasurement.md)

### Responsabilități

- ✅ Learning din discharge sessions

- ⚠️ Health tracking (not visible in UI)

- ⚠️ Weighted average (calculated, not displayed)

### UI Components

| File | Status | Alignment | TODO |

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

| `ChargeSessionDetailView.swift` | ✅ Exists | Poor | Add capacity learning |

| `ChargedDeviceSettingsView.swift` | ✅ Exists | Poor | Show measured vs rated capacity |

| — | ❌ Missing | — | Battery health indicator |

| — | ❌ Missing | — | Capacity trend graph |

### Current UI

```

ChargeSessionDetailView

├─ [Session info: date, duration, energy]

├─ [Device/charger info]

└─ [Checkpoint list]

```

### Needed Alignments

1. **Capacity learning indicator**

   - IF session = complete discharge (0% → 100%)

     - Show: "Capacity learning: 2950 mAh ✓"

   - ELSE

     - Show: "Partial discharge (15%), no capacity learning"

2. **Battery health display**

   - NEW section: "Battery Health"

     ```

     Measured capacity:    2950 mAh

     Rated capacity:       3000 mAh

     Health:               98% ✓

     ```

   - IF health < 80%: Show warning "Aged battery"

3. **Multiple measurement history**

   - NEW tab: "Capacity History"

   - Show last 5 discharge cycles

   - Chart: capacity over time

   - Show trend: "Stable" / "Degrading" / "Improving"

---

## 3. Charge Curve Isolation

**Documentație:** [ChargeCurveIsolation.md](./ChargeCurveIsolation.md)

### Responsabilități

- ✅ Detect start (power threshold)

- ✅ Detect end (trickle charge)

- ⚠️ Visual feedback (weak)

### UI Components

| File | Status | Alignment | TODO |

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

| `ChargeRecordSheetView.swift` | ✅ Exists | Fair | Add isolation visualization |

| `TimeSeriesChart.swift` | ✅ Exists | Good | Highlight isolated region |

### Current UI

```

ChargeRecordSheetView

├─ [Total energy]

├─ [Duration]

└─ [Checkpoints]

```

### Needed Alignments

1. **Isolated interval visualization**

   - After completion, show original curve with:

     ```

     Power (W)

     20├──────────────────────

       │ NOISE (discarded)

     10├──────┐

       │ ISOLATED REGION ████████

      5├──────┘

       │ NOISE (discarded)

     0└──────────────────────

     ```

2. **Detection feedback**

   - Show: "Auto-isolated [10:15–10:45] (30 min)"

   - If manual override: "Custom selection [10:16–10:43]"

3. **Noise estimation**

   - Show: "Pre-charge noise: 15% of total"

   - Show: "Post-charge noise: 5% of total"

---

## 4. Charge Curve Storage

**Documentație:** [ChargeCurveStorage.md](./ChargeCurveStorage.md)

### Responsabilități

- ✅ Persist to Core Data

- ✅ CloudKit sync

- ⚠️ Compression visible to user

### UI Components

| File | Status | Alignment | TODO |

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

| `ChargedDeviceSessionsView.swift` | ✅ Exists | Good | Show compression status |

| `ChargeSessionDetailView.swift` | ✅ Exists | Good | Show sample count |

### Current UI

```

ChargedDeviceSessionsView

├─ [Session list (sorted by date)]

└─ [Each row: date, duration, energy]

```

### Needed Alignments

1. **Compression indicator**

   - IF session < 7 days: "Full resolution (3600 samples)"

   - ELSE IF session < 365 days: "Downsampled (360 samples)"

   - ELSE: "Archived (metadata only)"

2. **Sync status**

   - NEW badge: ☁️ (synced) / ⏳ (pending) / ⚠️ (conflict)

3. **Storage estimate**

   - Footer: "Storage: 2.4 MB (on device) + 1.2 MB (iCloud)"

---

## 5. Consumption Measurement

**Documentație:** [ConsumptionMeasurement.md](./ConsumptionMeasurement.md)

### Responsabilități

- ✅ Select arbitrary interval

- ✅ Tail trimming (graph selection)

- ✅ Display statistics

- ⚠️ Predictions (weak implementation)

- ✅ Discard measurements

### UI Components

| File | Status | Alignment | TODO |

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

| `ConsumptionMonitorView.swift` | ✅ Exists | Good | Strengthen predictions |

| `TimeSeriesChart.swift` | ✅ Exists | Good | Add interval selection |

### Current UI

```

ConsumptionMonitorView

├─ [Meter selection]

├─ [Active session card]

├─ [Live metrics (Power, Energy, Time)]

├─ [Aggregation duration selector (300s default)]

├─ [Inventory list]

└─ [Saved sessions]

```

### Needed Alignments

1. **Tail trimming improvements**

   - Current: "Stop" button

   - NEW: Interactive graph with draggable endpoints

   ```

   Power (W)

   20├──────────────────

     │ ◄─ drag start

     │  [selected region]

   10├──────────────────► drag end

     │

   0 └──────────────────

     10:00   10:30   11:00

   ```

2. **Prediction display**

   - Current: Only shows "Aggregation duration" selector

   - NEW: Add prediction section

   ```

   Measured (10:00–10:30): 12.5W avg

   Predict next 30 min:     12.5Wh ±2.5Wh (80% confidence)

   Predict next 24h:        300Wh ±120Wh (40% confidence ⚠️)

   ```

3. **Statistics card**

   - Current: Only total energy + duration

   - NEW: Add table

   ```

   Total Energy:     12.5 Wh

   Avg Power:        25 W

   Peak Power:       32 W

   Min Power:        15 W

   Variance (σ):     ±3.2 W

   Measurement #:    1800 samples

   ```

4. **Measurement discard confirmation**

   - Current: ✓ (button exists)

   - NEW: Show "Discarding measurements, keeping stats..."

---

## 6. Idle Consumption Measurement

**Documentație:** [IdleConsumptionMeasurement.md](./IdleConsumptionMeasurement.md)

### Responsabilități

- ❌ NOT implemented in UI

- ❌ NO idle detection

- ❌ NO idle profiles

### Current State

```

Status: ❌ MISSING

```

### Required Implementation

#### New Views

1. **IdleConsumptionSetupView**

   ```

   ┌─────────────────────────────┐

   │ Measure Idle Consumption    │

   ├─────────────────────────────┤

   │ Device:      [iPhone 15  ▼] │

   │ Charger:     [USB-C 20W ▼] │

   │ Battery:     [100% ✓]      │

   ├─────────────────────────────┤

   │  [Start measurement]        │

   └─────────────────────────────┘

   ```

2. **IdleConsumptionMonitorView**

   ```

   ┌──────────────────────────────┐

   │ Recording idle consumption...│

   ├──────────────────────────────┤

   │ Power (W)              5 W   │

   │  Trend: ↘ (stabilizing)     │

   │                              │

   │ Time elapsed:      00:15:32  │

   │                              │

   │ Status:  ✓ Idle detected     │

   │         (power < 5W, stable) │

   │                              │

   │  [Confirm]   [Discard]       │

   └──────────────────────────────┘

   ```

3. **IdleConsumptionReviewView**

   ```

   ┌──────────────────────────────┐

   │ Idle Profile (Adjust)        │

   ├──────────────────────────────┤

   │ Power (W)                    │

   │ 5 ├─────────────────         │

   │   │     ◄─ slide to adjust   │

   │ 0 │ ████████████► idle       │

   │   └────────────────────      │

   │   10:15      10:45           │

   │                              │

   │ Idle Power:    0.25 W        │

   │ Duration:      30 min        │

   │ Confidence:    85% ✓         │

   │                              │

   │ [Save profile]   [Retry]     │

   └──────────────────────────────┘

   ```

4. **DeviceIdleProfilesView**

   ```

   ┌──────────────────────────────┐

   │ Idle Profiles                │

   ├──────────────────────────────┤

   │ iPhone 15:                   │

   │  └─ USB-C 20W:     0.25 W   │

   │  └─ MagSafe:       0.20 W   │

   │                              │

   │ iPad Pro:                    │

   │  └─ USB-C 30W:     0.45 W   │

   │                              │

   │  [Measure new]   [Edit]      │

   └──────────────────────────────┘

   ```

#### Integration Points

1. **ChargeSessionCompletionSheetView**

   - Add row: "Auto-terminate when: [idle power + 50%]"

   - When user selects idle profile, pre-fill

2. **MeterChargeRecordTabView**

   - Show idle indicator when power drops below threshold

   - "Idle detected, session can auto-terminate"

3. **ChargedDeviceSettingsView**

   - NEW section: "Idle Consumption Profile"

   - Show measured idle power per charger

   - Link to "Measure idle..."

---

## 7. System Core Operations

**Documentație:**

- [Operations.md](./Operations.md)

- [CloudKitSync.md](./CloudKitSync.md)

- [BluetoothDiscovery.md](./BluetoothDiscovery.md)

### Status: ✅ Mostly implemented

| Component | UI File | Status |

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

| BT Discovery | `SidebarMeterCardView.swift` | ✅ Good |

| Connection | `MeterHomeTabView.swift` | ✅ Good |

| CloudKit sync | (implicit) | ✅ Good |

### Needed Alignments

1. **CloudKit sync status display**

   - Current: No visible indicator

   - NEW: Badge in meter card "☁️ synced @ 10:45"

2. **Connection retry display**

   - Current: Just shows "Offline"

   - NEW: "Offline (retry in 8s...)" or "Reconnecting..."

3. **Discovery throttling indicator**

   - MAY: Show "Last scan: 45s ago" in debug view

---

## Summary Table

| Operation | Documentație | UI Status | Alignment | Priority |

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

| Charging Monitoring | ✅ | ✅ Impl | Fair | Medium |

| Capacity Learning | ✅ | ⚠️ Partial | Poor | High |

| Curve Isolation | ✅ | ✅ Impl | Fair | Medium |

| Curve Storage | ✅ | ✅ Impl | Good | Low |

| Consumption Meas. | ✅ | ✅ Impl | Good | Low |

| **Idle Consumption** | ✅ | ❌ Missing | — | **High** |

| Cloud Sync | ✅ | ✅ Impl | Good | Low |

| BT Discovery | ✅ | ✅ Impl | Good | Low |

---

## Alignment Checklist

### High Priority (implement next)

- [ ] Idle Consumption Measurement (all 4 new views)

- [ ] Capacity Learning display in ChargeSessionDetailView

- [ ] Battery Health section in ChargedDeviceSettingsView

- [ ] Curve Isolation visualization in ChargeRecordSheetView

### Medium Priority (refine)

- [ ] Consumption prediction UI (confidence bounds)

- [ ] Measurement validation warnings

- [ ] Compression status indicators

### Low Priority (nice-to-have)

- [ ] Discovery throttling display

- [ ] Retry countdown in connection status

- [ ] Storage estimate footer

---

## Implementation Guide

### For each operation:

1. **Read documentation** (`ChargingMonitoring.md`, etc.)

2. **Identify required UI** (sections above)

3. **Check invariants** (MUST/SHOULD/MAY)

4. **Implement/update views**

5. **Add validation errors**

6. **Test with unit tests**

7. **Link to documentation in comments**

Example comment in code:

```swift

// See: Documentation/API Reference/ChargingMonitoring.md

// MUST: recordMeasurement fails if sessionState < active

if !session.isActive {

    throw SessionError.invalidState

}

```

---

## Notes

- This document is a living checklist

- Update as UI aligns with docs

- Link each UI file to relevant docs

- Mark `// DOCUMENTED` in code for traced invariants