# ChargedDevice Entity

Reprezentarea unui dispozitiv care se încarcă prin meter.

## Responsabilități

- Modelarea unui dispozitiv (iPhone, Watch, Charger, Powerbank, Other)
- Gestionarea sesiunilor de încărcare
- Colectarea de măsurători durante sesiune
- Calculul integrității şi detectării conflictelor

## Invarianţi

- **MUST**: Fiecare ChargedDevice are un `id` (UUID) unic
- **MUST**: O sesiune de încărcare are timestamp-uri valide: `startTime <= currentTime <= endTime`
- **MUST**: Măsurătorile într-o sesiune sunt ordonate cronologic
- **MUST**: O sesiune activă pe un dispozitiv trebuie să aibă un singur Meter asociat
- **MUST**: Energia calculată (Wh) trebuie să fie ne-negativă
- **SHOULD**: Un device cu 0 măsurători ar trebui marcat pentru curatare pe CloudKit
- **MAY**: Duplicate sessions pe același MAC pot fi mergate după detectare

## API Public

### Proprietăţi

| Proprietate | Tip | Descriere | Observaţii |
|---|---|---|---|
| `id` | UUID | Identificator unic | Generat la creare |
| `deviceName` | String | Nume ales de utilizator | De ex: "My iPhone 15" |
| `deviceClass` | ChargedDeviceClass | Tip: iPhone, Watch, Charger, Powerbank, Other | |
| `kind` | ChargedDeviceKind | Device sau Charger | Derivat din `deviceClass` |
| `createdAt` | Date | Data creării | Immutable |
| `chargeRecords` | [ChargeRecord] | Lista sesiunilor de încărcare | Sorted by startTime |
| `totalEnergy` | Double | Total Wh consumat/furnizat | Calculat din sesiuni |
| `lastChargedAt` | Date? | Data ultimei sesiuni | Nullable |

### Metode

```swift
// Gestionare sesiuni
func startSession(meter: Meter) -> ChargeRecord
// MUST: sessionID este UUID unic
// MUST: startTime = now()
// MUST: retur ChargeRecord cu status "active"

func recordMeasurement(_ measurement: Measurement, in session: ChargeRecord)
// MUST: measurement.timestamp > session.startTime
// SHOULD: measure-urile sunt colectate la ~1Hz
// MUST: nu merge dacă sesiunea e finalizată

func endSession(_ record: ChargeRecord)
// MUST: endTime = now()
// MUST: calculează total energy din măsurători
// MUST: marchez sesiunea ca "completed"

func recalculateTotalEnergy()
// Recalculează sum-ul de Wh din toate sesiunile
// SHOULD: se apelează după conflict resolution

// Naming
func renameToDevice(_ newName: String)
// MUST: actualizează proprietatea şi persistă

// Conflict handling
func mergeWith(_ other: ChargedDevice, keepingRecords: Bool = true)
// MUST: combină sessions de pe ambele device-uri
// MUST: remove-ă duplicates după MAC address
// SHOULD: logs merge operation pentru debug
```

## Comportamente critice

### Sesiuni de încărcare

- **MUST**: Doar o singură sesiune per device poate fi activă la orice moment
- **MUST**: Sesiunile completate sunt imutable
- **SHOULD**: Sesiunile care durează > 24h sunt marcate cu warning
- **MAY**: Sesiuni orphaned (meter deconectat > 1h) pot fi finalizate automat

### Calculul energiei

- **MUST**: Energia = ∑(V * A * Δt) pentru fiecare interval
- **MUST**: Unitatea trebuie să fie Wh (Watt-hours)
- **SHOULD**: Energia negativă în sesiune = problema în măsurători, loghează warning

### Conflict detection și rezoluție

Se declanşează când:
1. Două sesiuni cu aceeași categorie de device în same time window
2. Două sesiuni pe aceeași meter cu overlap temporal

Rezoluţie:
- **MUST**: Sesiunea cu mai multe măsurători = "winner"
- **MUST**: Energiile sunt combinate (∑)
- **SHOULD**: Old session data este archived (Core Data snapshot)
- **MAY**: Notifică utilizator despre merge

### State management

- **MUST**: Active session nu poate fi schimbat în mod normal (read-only)
- **MUST**: State tranzițion: idle → active → completed (nu poate reveni)
- **SHOULD**: Completed sesiuni sunt persistent în Core Data

## Testare

### Unit tests

```swift
// Sesiuni
test_startSessionCreatesValidRecord()
test_endSessionCalculatesEnergy()
test_activeSessions_CanOnlyBeOne()
test_sessionTimeValidation()

// Măsurători
test_recordMeasurementFailsIfSessionEnded()
test_measurementsAreOrdered()
test_emptySessionsCalculateZeroEnergy()

// Conflict
test_mergeDetectsDuplicateSessions()
test_mergeKeepsMoreCompleteMeasurements()
test_mergeRecalculates_TotalEnergy()

// Naming
test_renameUpdatesPersistence()
```

### Integration tests

- [ ] Device apare în Charged Devices list după start sesiune
- [ ] Sesiuni complete salvate în Core Data
- [ ] CloudKit sync nu pierde sesiuni
- [ ] Energiile sunt consistente după conflict merge
- [ ] Device name e persistent

## Dependenţe

- `Meter`: conectare şi măsurători
- `ChargeInsightsStore`: persistență sesiuni
- `CloudKitSync`: replicare iCloud

## Notes

Documentaţie asoc:
- [Charge Session Integrity](../Charge%20Session%20Integrity%20and%20Conflict%20Healing.md)
- [No Ampere-Hours in UI](../No%20Ampere-Hours%20in%20UI%20or%20Model.md)