# CloudKit Sync

Mecanismul de replicare a datelor către iCloud.

## Arhitectură

### Components

1. **NSPersistentCloudKitContainer**: gestionează Core Data + CloudKit automat

2. **CloudDeviceSettingsStore**: wrapper pe NSManagedObjectContext

3. **Core Data Model**: `CKModel.xcdatamodeld` (curent: USB_Meter 2)

4. **CloudKit Container**: `iCloud.ro.xdev.USB-Meter`

### Model versioning

```

USB_Meter 1 (original)

  ↓

USB_Meter 2 (fix: removed uniqueness constraints)

  ↓

USB_Meter 3? (future)

```

**Curent**: USB_Meter 2 (schema v20)

## Data Schema

### DeviceSettings entity (Core Data)

| Field | Type | Notes |

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

| `id` | UUID | Primary key |

| `macAddress` | String | Optional (for migration) |

| `meterName` | String | Chosen by user |

| `tc66TemperatureUnit` | String | "celsius" / "fahrenheit" |

| `createdAt` | Date | Immutable |

| `updatedAt` | Date | Last sync timestamp |

| `connectionMetadata` | JSON blob | Device, timestamp, expiry |

| `discoveryMetadata` | JSON blob | Last seen, seen by |

| `cloudKitRecordID` | String | Reference toward CloudKit |

### Invarianţi

- **MUST**: `macAddress` nu are `uniquenessConstraint` (not CloudKit safe)

- **MUST**: Chiar dacă `macAddress` optional, duplicate entries ar trebui merged

- **MUST**: `meterName` e unic per meter (no machine-generated names)

- **MUST**: `updatedAt` se schimbă la fiecare sync

- **SHOULD**: `connectionMetadata.expiresAt` = now() + 24h

## Sync Lifecycle

### Push (local → CloudKit)

```

User changes meterName

  ↓

AppData calls cloudStore.upsertDeviceSettings(...)

  ↓

NSManagedObjectContext saves

  ↓

NSPersistentCloudKitContainer auto-uploads to CloudKit

  ↓

CloudKit replica updated

  ↓

Other devices see change via NSPersistentCloudKitContainerEventChangeNotification

```

- **MUST**: Core Data save trebuie să se afle pe main thread

- **MUST**: CloudKit sync e asincronă (fire-and-forget)

- **SHOULD**: Notify UI după local save (don't wait for CloudKit)

- **MAY**: Log upload errors

### Pull (CloudKit → local)

```

iCloud change appears

  ↓

NSPersistentCloudKitContainer notifies

  ↓

AppData observes NSPersistentCloudKitContainerEventChangeNotification

  ↓

Merge remote change with local state

  ↓

Core Data context updated

  ↓

UI refreshes

```

- **MUST**: Merge strategy = "last write wins" (basate pe timestamp)

- **MUST**: Conflict resolution e automat (NSMergeByPropertyObjectTrumpMergePolicy)

- **SHOULD**: Loghează merge pentru debugging

- **MAY**: Notifică user dacă conflict major

### Conflict scenarios

**Scenario 1**: Same meter renamed on two devices simultaneously

```

Device A: "Kitchen Meter" → "Main Meter"  (10:00:00)

Device B: "Kitchen Meter" → "Lab Meter"   (10:00:05)

```

Resolution: Last timestamp wins → "Lab Meter" (Device B @ 10:00:05)

**Scenario 2**: Duplicate entries cu aceeași MAC

```

Device A: macAddress = "AA:BB:CC:DD:EE:FF", meterName = "Meter 1"

Device B (after restore): macAddress = "AA:BB:CC:DD:EE:FF", meterName = "Meter 1"

```

Resolution: Merge duplicate entries, keep one record (last write wins)

## Discovery Throttling

### Logică

```swift

func recordDiscovery(for macAddress: String) {

    let lastSeen = discoveryMetadata[macAddress]?.lastSeen

    let now = Date()

    if now.timeIntervalSince(lastSeen ?? .distantPast) >= 120 {

        // OK: permit sync

        cloudStore.recordDiscovery(macAddress, discoveredAt: now)

    }

    // else: skip (under throttle window)

}

```

- **MUST**: Max 1 discovery record per device per 120s

- **SHOULD**: Throttle pe app level (nu pe CloudKit)

- **MUST**: Reseta timer dacă device disconnect-ează

- **REASON**: Prevent CloudKit thrashing din repeat BT advertisements

### Impact

- BT scan at 0s, 30s, 60s, 90s, 120s, ... (periodc)

- Doar descoperirile la 0s, 120s, 240s, ... sunt syncate la CloudKit

- Alte descoperiri sunt cached local

## Rebuild logic

### Background

Issue (March 2025):

- Old `uniquenessConstraint` pe `macAddress` = incompatibil cu CloudKit

- Old rebuild logic: delete ALL + recreate = delete storm în CloudKit

- Old naming: `meterName` = platform model ("iPad") = irelevant pe CloudKit

### Fix

**Schema migration**: USB_Meter 1 → USB_Meter 2

- Removed `uniquenessConstraint`

- Made `macAddress` optional

- Changed device name = hostname (all platforms)

**Rebuild refactoring**: `rebuildCanonicalStoreIfNeeded()`

```swift

func rebuildCanonicalStoreIfNeeded(newVersion: Int) {

    if cloudStoreRebuildVersion >= newVersion { return }

    // Update winner in-place, delete only duplicates

    let groupedByMAC = groupEntries(by: \.macAddress)

    for (mac, entries) in groupedByMAC {

        guard entries.count > 1 else { continue }

        let winner = entries.max(by: \.updatedAt)

        let losers = entries.filter { $0.id != winner.id }

        // Delete losers only, keep winner

        for loser in losers {

            context.delete(loser)

        }

    }

    cloudStoreRebuildVersion = newVersion

    try? context.save()

}

```

- **MUST**: Update winner în-place (nu delete+recreate)

- **MUST**: Delete doar duplicate entries (nu pe toti)

- **MUST**: Set `cloudStoreRebuildVersion = 3` după fix

- **REASON**: Prevent delete storms în CloudKit

### Version history

- **v1**: Original schema (cu uniqueness constraint)

- **v2**: First rebuild (delete all + recreate) — DEPRECATED

- **v3**: Correct rebuild (update in-place + delete duplicates only)

## Legacy data migration

### NSUbiquitousKeyValueStore (deprecated)

```swift

// Legacy stores

let meterNames = NSUbiquitousKeyValueStore.default.dictionary(forKey: "MeterNames")

// → {macAddress → meterName}

let tempUnits = NSUbiquitousKeyValueStore.default.dictionary(forKey: "TC66TemperatureUnits")

// → {macAddress → unit}

```

### Migration path

1. Read from KV store

2. For each MAC address:

   ```swift

   cloudStore.upsertDeviceSettings(

       macAddress: mac,

       meterName: meterNames[mac],

       tc66TemperatureUnit: tempUnits[mac]

   )

   ```

3. Mark as migrated în defaults

- **MUST**: Menţine KV store pentru backward compat

- **SHOULD**: Migrate pe startup dacă not migrated

- **MAY**: Drop KV store la next major version

## Testing

### Unit tests

```swift

test_cloudStoreSaves_ToNSManagedObjectContext()

test_upsertDeviceSettings_CreatesOrUpdates()

test_discoveryThrottling_RespectsTiming()

test_conflictResolution_LastWriteWins()

test_rebuildCanonicalStore_UpdatesWinner_DeletesDuplicates()

test_macAddressNoDuplicates_AfterRebuild()

```

### Integration tests

- [ ] Multiple devices sync settings via CloudKit

- [ ] Conflict detected and resolved

- [ ] Rebuild v3 migrates old data correctly

- [ ] Discovery throttling prevents CloudKit thrashing

- [ ] Legacy KV store data migrates to Core Data

## Error handling

### Network errors

```

Error: Network unavailable

→ Fail fast (don't retry immediately)

→ Queue pending changes in Core Data

→ Retry at next network change (observe URLSession events)

```

### CloudKit quota errors

```

Error: Quote exceeded (too many records)

→ Log error

→ Notify user: "iCloud storage full"

→ Option: Archive old charge records

```

### Merge conflicts

```

Error: Conflict detected

→ Auto-resolve via "last write wins"

→ Log both versions for debugging

→ Notify user if significant loss

```

## Dependencies

- `NSPersistentCloudKitContainer`: from CloudKit framework

- `CloudDeviceSettingsStore`: wrapper in AppData.swift

- `CKModel.xcdatamodeld`: Core Data schema

- `NSUbiquitousKeyValueStore`: legacy (deprecated)

## References

- Commit: [Fix CloudKit sync (Mar 2025)](https://github.com/...)

- Documentaţie: [Project Memory - Fix CloudKit sync](../../MEMORY.md)

- Issue: [[001 Catalyst TabView Freeze]]