# API Reference

Această documentație defineşte comportamentul aşteptat al entităţilor principale şi operaţiilor aplicaţiei. Scopul este să prevenim regresia şi divergenţele în timp ce aplicaţia evoluează cu ajutorul agenţilor.

## Entităţi principale

1. **[Meter](./Meter.md)** - Contor Bluetooth (UM25C, UM34C, TC66C)
   - Reprezentarea unui dispozitiv BT conectat
   - Starea conectorului, metadatele descoperiri
   - Operaţii: connect, disconnect, fetch measurements

2. **[ChargedDevice](./ChargedDevice.md)** - Dispozitiv încărcat prin meter
   - Modelul unui dispozitiv care se încarcă
   - Sesiuni de încărcare, integritate date
   - Operaţii: start session, record measurement, end session

3. **[Powerbank](./Powerbank.md)** - Sursă de energie portabilă
   - Modelul unei baterii externe
   - Starea încărcării, sesiiuni de descărcare
   - Operaţii: track discharge, merge duplicates

## Operaţii core

1. **[Charging Monitoring](./ChargingMonitoring.md)** - Monitorizarea unei sesiuni de încărcare
   - Start → record measurements → end
   - Colectare date la ~1Hz
   - Validare măsurători, calculul energiei
   - Timeout şi reconnect logic

2. **[Capacity Measurement](./CapacityMeasurement.md)** - Măsurarea capacităţii bateriei
   - Learning din complete discharge cycles
   - Formula: Capacity = Energy / Nominal_Voltage
   - Weighted moving average din sesiuni multiple
   - Battery health tracking

3. **[Charge Curve Isolation](./ChargeCurveIsolation.md)** - Izolarea curbei de încărcare
   - Detectare real start (power threshold)
   - Detectare real end (trickle charge)
   - Eliminare zgomot pre/post-charge
   - Combined method (power + battery fallback)

4. **[Charge Curve Storage](./ChargeCurveStorage.md)** - Stocarea curbelor
   - Persistență în Core Data
   - Sincronizare CloudKit
   - Compresie: downsampling, agregare
   - Archive sesiuni vechi

5. **[Consumption Measurement](./ConsumptionMeasurement.md)** - Măsurare consum arbitrar
   - Interval liber, nu doar sesiuni complete
   - Selectare din grafic + tail trimming
   - Statistici: energy, power, variance
   - Predicţii cu confidence bounds
   - Salvează stats, NU măsurători brute

6. **[Idle Consumption Measurement](./IdleConsumptionMeasurement.md)** - Măsurare consum inactiv
   - Device la 100% + după top-up
   - Auto-detect idle phase (power stabilizat)
   - Selection pe grafic pentru refine
   - Profil idle per (device, charger type)
   - Folosit pentru auto-terminate şi bilanț energetic
   - Corectare energie: total - idle_energy

7. **[CloudKit Sync](./CloudKitSync.md)** - Sincronizare date în CloudKit
   - Mecanismul de replicare către iCloud
   - Conflictele şi rezoluţii
   - Rebuild logic şi versioning

8. **[Bluetooth Discovery](./BluetoothDiscovery.md)** - Descoperire dispozitive BT
   - Scanning, throttling, caching
   - Advertisement handling
   - Device identification

9. **[Core Operations](./Operations.md)** - Operaţii principale
   - App lifecycle (AppData, SceneDelegate)
   - Connection management
   - State persistence

## Convenţii

- **MUST**: Comportament obligatoriu, nu se poate schimba fără update complet
- **SHOULD**: Comportament aşteptat, regresia = bug
- **MAY**: Comportament opţional, nu afectează integralitate

## Model versioning

- **Model versioning**: `cloudStoreRebuildVersion` în AppData
- **Upgrade path**: UnitTests validează migrări la versionare nouă
- **Backward compatibility**: Legacy sync via `NSUbiquitousKeyValueStore`

## UI Alignment

- **[UI_ALIGNMENT.md](./UI_ALIGNMENT.md)** — Mapare UI ↔ Documentație
  - Status implementare per operație
  - Needed UI changes untuk align cu docs
  - Checklist alignment per priority

---

Fiecare fişier conţine:

- Responsabilităţi (ce face această entitate)
- Invarianţi (condiţii care trebuie să fie adevărate)
- API public (metodele şi proprietăţile expuse)
- Comportamente critice (cazuri speciale, edge cases)
- Testare (cum validăm corectitudinea)