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 - Contor Bluetooth (UM25C, UM34C, TC66C)

   • Reprezentarea unui dispozitiv BT conectat
   • Starea conectorului, metadatele descoperiri
   • Operaţii: connect, disconnect, fetch measurements

2. ChargedDevice - 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 - 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 - 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 - 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 - 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 - Stocarea curbelor

   • Persistență în Core Data
   • Sincronizare CloudKit
   • Compresie: downsampling, agregare
   • Archive sesiuni vechi

5. Consumption Measurement - 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 - 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 - Sincronizare date în CloudKit

   • Mecanismul de replicare către iCloud
   • Conflictele şi rezoluţii
   • Rebuild logic şi versioning

8. Bluetooth Discovery - Descoperire dispozitive BT

   • Scanning, throttling, caching
   • Advertisement handling
   • Device identification

9. Core Operations - 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 — 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)