# Core Operations

Operaţii principale care orchestrează aplicaţia.

## AppData Lifecycle

`AppData` este singleton-ul global care orchestrează toate subsistemele.

### Inițializare

```swift
let appData = AppData()
```

- **MUST**: Se instanțiază în `AppDelegate.application(_:didFinishLaunchingWithOptions:)`
- **MUST**: Se accesează din `SceneDelegate.scene(_:willConnectTo:options:)`
- **MUST**: Inițializează `NSPersistentCloudKitContainer` cu name `"CKModel"`
- **MUST**: Inițializează `CloudDeviceSettingsStore` (wraps NSManagedObjectContext)

### Startup sequence

1. `AppDelegate.application(_:didFinishLaunchingWithOptions:)`:
   - Crează `AppData()`
   - Inițializează Core Data stack
   - Încarcă migrări din `cloudStoreRebuildVersion`

2. `SceneDelegate.scene(_:willConnectTo:options:)`:
   - Apelează `appData.activateCloudDeviceSync(context: sceneContext)`
   - Inițiază BT scanning
   - Inițiază CloudKit sync

### Shutdown sequence

- **SHOULD**: Finalizează sesiuni active la app terminate
- **MUST**: Salvează Core Data context (`saveIfNeeded()`)
- **SHOULD**: Deconectează BT graceful

## Bluetooth Connection Management

### Connection state machine

```
notPresent
  ↓
peripheralNotConnected ← (user disconnect)
  ↓
peripheralConnectionPending
  ↓
peripheralConnected
  ↓
peripheralReady
  ↓
comunicating ↔ dataIsAvailable
```

### Operations

```swift
// Conectare inițială
blutooth.connect(to peripheralUUID: UUID, type: Model)
// MUST: inițiază CBCentralManager scan
// MUST: se conectează la UUID specific
// SHOULD: timeout = 5s
// MUST: pe succes, tranzițe la peripheralConnected

// Deconectare
bluetooth.disconnect(from meter: Meter)
// MUST: anulează reconnect logic
// MUST: eliberează resurse
// MUST: marchez ca manual disconnect

// Auto-reconnect
bluetooth.autoReconnect(meter: Meter, backoff: Backoff)
// SHOULD: exponential backoff: 1s, 2s, 4s, 8s, max 60s
// MUST: anulează dacă utilizator disconnect manual
// MUST: max 3 retry-uri consecutive
```

## Measurement Recording

### Session lifecycle

```swift
let session = meter.startChargeRecord(for: device)
```

1. **Start**: Crează `ChargeRecord(sessionID: UUID(), startTime: now())`
2. **Measure**: La fiecare 1-2s:
   ```swift
   let measurement = meter.lastDataPoint
   session.addMeasurement(measurement)
   ```
3. **End**: 
   ```swift
   meter.endChargeRecord(session)
   ```
   - Calculează `totalEnergy = ∑(V * A * Δt)`
   - Marchez ca `completed`
   - Salvează în Core Data

### Invarianţi

- **MUST**: O sesiune activă per meter
- **MUST**: Măsurătorile sunt cronologice
- **MUST**: `startTime <= now() <= (endTime || ∞)`
- **MUST**: Energia ≥ 0

### Recording frequency

- **SHOULD**: Măsurători la ~1Hz (1000ms interval)
- **MAY**: Reduce frequency dacă battery low
- **SHOULD**: Drop măsurători dacă queue > 100 items

## Cloud Sync

### Main concepts

- **DeviceSettings**: entitate Core Data persistă MAC, name, temperature unit
- **CloudDeviceSettingsStore**: wrapper pe NSManagedObjectContext
- **Rebuild version**: `cloudStoreRebuildVersion` (curent: 3)

### Sync flow

1. **Upload**: Locale changes → Core Data → CloudKit
   ```swift
   cloudStore.upsertDeviceSettings(
       macAddress: "AA:BB:CC:DD:EE:FF",
       meterName: "Kitchen Meter",
       tc66TemperatureUnit: .celsius,
       connectionMetadata: ...
   )
   ```
   - MUST: salvează în Core Data sync
   - MUST: CloudKit container replica-ază automat

2. **Download**: CloudKit changes → Core Data → UI
   - **MUST**: NSPersistentCloudKitContainer sincronizează automat
   - **SHOULD**: Refresh UI după fetch

3. **Conflict resolution**: Dacă două modificări simultane
   - **MUST**: Mergi pe "last write wins" dacă timestamps diferă
   - **SHOULD**: Loghează conflictul pentru debugging

### Discovery throttling

- **MUST**: Max 1 discovery per device per 120s
- **SHOULD**: Previne CloudKit thrashing din repeat BT advertisements
- **MUST**: Reseta timer dacă device disconnect-ează

## Device Settings Persistence

### MAC address mapping

```swift
// CloudDeviceSettingsStore.swift
func upsertDeviceSettings(
    macAddress: String,
    meterName: String,
    tc66TemperatureUnit: TemperatureUnitPreference?,
    connectionMetadata: ConnectionMetadata?,
    discoveryMetadata: DiscoveryMetadata?
)
```

- **MUST**: macAddress optional (datorită migration)
- **MUST**: meterName unic pe meter (no duplicates)
- **SHOULD**: connectionMetadata.expiresAt = now() + 24h

### Legacy KV Store

`NSUbiquitousKeyValueStore` sincronizează:
- `MeterNames`: {macAddress → meterName}
- `TC66TemperatureUnits`: {macAddress → unit}

- **MUST**: Menţinere backward compat
- **SHOULD**: Migrate pe Core Data la first sync
- **MAY**: Drop la următoarea major version

## Error handling

### Bluetooth errors

```
Error: BT peripheral not found
→ Retry connect cu backoff
→ Max 3 retries, apoi fallback offline mode

Error: Characteristic not found
→ Log error
→ Mark meter incompatible (UI warning)

Error: Read timeout
→ Retry measurement request
→ Increment timeout counter
```

### CloudKit errors

```
Error: Network unavailable
→ Queue pending changes
→ Retry la next network change

Error: Conflict detected
→ Merge data (last write wins)
→ Retry sync

Error: Quota exceeded
→ Log error
→ Notify user (prune old data?)
```

## Testare

### Unit tests

```swift
test_appDataInitializes_CoreDataAndCloudKit()
test_bluetoothConnectInitiatesProperStateTransition()
test_bluetoothDisconnect_CleansUp()
test_autoReconnectBackoff_ExponentialScaling()
test_sessionStartCreatesValidRecord()
test_sessionEndCalculatesEnergy()
test_cloudSyncUpsert_SavesToCoreData()
test_discoveryThrottling_RespectsTiming()
test_conflictResolution_LastWriteWins()
```

### Integration tests

- [ ] Full app startup (BT + CloudKit)
- [ ] Connect meter → start session → record measurements → end session
- [ ] Disconnect meter → reconnect avec backoff
- [ ] Device settings sync CloudKit → other device
- [ ] Offline mode (queue changes, sync later)

## Dependenţe

- `AppData`: orchestrează tot
- `BluetoothManager`: gestionează Core Bluetooth
- `CloudDeviceSettingsStore`: Core Data + CloudKit
- `ChargeInsightsStore`: sesiuni persistente
- `ConsumptionMonitorStore`: monitorizare consum

## Notes

- Legat: [CloudKit Sync](./CloudKitSync.md)
- Legat: [Bluetooth Discovery](./BluetoothDiscovery.md)
- Referință: AppDelegate.swift, SceneDelegate.swift