Powerbank Entity

Reprezentarea unei baterii externe (sursă de energie portabilă).

Responsabilități

• Modelarea unei surse portabile de putere
• Gestionarea sesiunilor de descărcare
• Urmărirea stării de încărcare
• Detectarea şi merge-ul duplicate-ilor

Invarianţi

• MUST: Fiecare Powerbank are un id (UUID) unic
• MUST: Capacity (mAh) trebuie să fie pozitiv
• MUST: Un Powerbank poate avea multiple sesiuni de descărcare (neordonate pe timp)
• MUST: Sesiunile sunt asociate unui Meter specific
• SHOULD: Powerbank-ul cu 0 sesiuni ar trebui marcat pentru curatare
• MUST: Nu pot exista duplicate fizice pe același MAC address fără merge explicare

Categoriile

Un Powerbank este o subcategorie a ChargedDevice cu class = .powerbank.

API Public

Proprietăţi

Metode

// Gestionare sesiuni
func startDischargeSession(meter: Meter) -> DischargeSession
// MUST: sessionID = UUID()
// MUST: startTime = now()
// MUST: retur DischargeSession cu status "active"
// SHOULD: capacity nu scade (immutable)

func recordDischargePoint(_ measurement: Measurement, in session: DischargeSession)
// Înregistrează o măsurătoare de descărcare
// MUST: measurement.timestamp > session.startTime
// MUST: nu merge dacă sesiunea e completată

func endDischargeSession(_ session: DischargeSession)
// MUST: endTime = now()
// MUST: calculează energie furnizată = ∑(V * A * Δt)
// MUST: marchez sesiunea ca "completed"

func recalculateTotalEnergy()
// Recalculează totalul de Wh furnizat
// SHOULD: se apelează după merge

// Duplicate handling
func mergeWith(_ other: Powerbank)
// MUST: combină toate sesiunile din ambele PB-uri
// MUST: elimină duplicate-urile de sesiuni
// MUST: recalculează totalul
// SHOULD: logs operaţia
// MUST: marchez celalalt Powerbank ca "merged"

// Naming
func rename(to newName: String)
// MUST: actualizează name property
// MUST: persistă în Core Data

Comportamente critice

Sesiuni de descărcare

• MUST: Doar o sesiune activă per Powerbank la orice moment
• MUST: Sesiunile completate nu pot fi modificate
• SHOULD: Sesiunile care durează > 48h sunt marcate cu warning (posibil inactive)
• MAY: Sesiuni orfane (meter deconectat > 2h) pot fi finalizate automat

Calculul energiei

• MUST: Energie furnizată = ∑(V_out * A_out * Δt) pentru intervale
• MUST: Unitatea = Wh (Watt-hours)
• MUST: Trebuie să fie ne-negativă (energia nu poate fi absorbi-u înapoi)
• SHOULD: Loghează warning dacă energia e negativă (date inconsistente)

Duplicate detection și merge

Se declanşează când: 1. Două Powerbanks cu același MAC address 2. Două Powerbanks cu sesiuni suprapuse pe aceeași perioadă

Rezoluţie: - MUST: Sesiunea cu mai multe măsurători = "winner" - MUST: Energiile sunt adunate (∑) - MUST: Sesiunile sunt deduplicate după sessionID - SHOULD: Old Powerbank e marcat ca "merged" - MAY: Notifică utilizator

State after merge

• MUST: După merge, alte referințe la old Powerbank trebuie actualizate
• MUST: Sessionuri din old PB redirecţionează la new PB
• SHOULD: Old PB e marcat ReadOnly sau Hidden

Testare

Unit tests

// Sesiuni
test_startSessionCreatesValidRecord()
test_endSessionCalculatesEnergy()
test_activeSessions_OnlyOne()

// Măsurători
test_recordPointFailsIfSessionEnded()
test_measurementOrdering()

// Merge
test_mergeDetectsDuplicates()
test_mergeKeepsMoreCompleteData()
test_mergeRecalculatesTotalEnergy()
test_mergeMarksOldAsMerged()

// Naming
test_renameUpdatesPersistence()

// Validare
test_capacityMustBePositive()
test_energyCannotBeNegative()

Integration tests

• [ ] Powerbank apare după start sesiune
• [ ] Sesiuni complete salvate în Core Data
• [ ] CloudKit sync merge-ul corect
• [ ] Energiile sunt consistente post-merge
• [ ] Name changes persistent pe CloudKit
• [ ] Capacity e immutable (nu se schimbă)

Dependenţe

• Meter: pentru măsurători
• ChargeInsightsStore: persistență sesiuni
• CloudKitSync: replicare iCloud
• ChargedDevice: Powerbank e subcategorie

Notes

Documentaţie asoc: - Powerbank Category - Charge Session Integrity - Status: Adăugat recent (commit: 0772cad) - Merge class+template: plan în progress, schema v20