bogdan / USB-Meter
USB-Meter / Documentation / API Reference / UI_ALIGNMENT.md
bogdan Add agent-facing API documentation
e74fd2f 2 weeks ago History
1 contributor
473 lines | 13.834kb

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

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

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

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"
    • 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

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

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

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 - CloudKitSync.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
Gitprep Version v2.6.2 build on Mojolicious
DBViewer