# 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

| Proprietate | Tip | Descriere | Observaţii |

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

| `id` | UUID | Identificator unic | Generat la criere |

| `name` | String | Nume (ex: "Anker 10000mAh") | Ales de utilizator |

| `macAddress` | String | Adresa BT | Pentru identificare unică |

| `capacity` | Int | Capacitate în mAh | Trebuie să fie > 0 |

| `dischargeSessions` | [DischargeSession] | Sesiunile de descărcare | Cronologice |

| `totalEnergyDelivered` | Double | Total Wh furnizat | Calculat din sesiuni |

| `createdAt` | Date | Data creării | Immutable |

| `lastDischargedAt` | Date? | Data ultimei sesiuni | Nullable |

### Metode

```swift

// 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

```swift

// 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](../Powerbank%20Category.md)

- [Charge Session Integrity](../Charge%20Session%20Integrity%20and%20Conflict%20Healing.md)

- **Status**: Adăugat recent (commit: 0772cad)

- **Merge class+template**: plan în progress, schema v20