Add scan flow MVP and local Axiom skill workspace

This snapshot establishes the camera-to-result recognition flow and related tests while checking in the project skill/docs assets required for the configured local tooling.
2026-04-19 21:11:32 +02:00
parent 577214d474
commit a60a76b797
679 changed files with 138964 additions and 73 deletions
--- a/.claude/skills/axiom-cloud-sync/SKILL.md
+++ b/.claude/skills/axiom-cloud-sync/SKILL.md
@@ -0,0 +1,423 @@
+---
+name: axiom-cloud-sync
+description: Use when choosing between CloudKit vs iCloud Drive, implementing reliable sync, handling offline-first patterns, or designing sync architecture - prevents common sync mistakes that cause data loss
+license: MIT
+compatibility: iOS 10+, macOS 10.12+
+metadata:
+  version: "1.0.0"
+  last-updated: "2025-12-25"
+---
+
+# Cloud Sync
+
+## Overview
+
+**Core principle**: Choose the right sync technology for the data shape, then implement offline-first patterns that handle network failures gracefully.
+
+Two fundamentally different sync approaches:
+- **CloudKit** — Structured data (records with fields and relationships)
+- **iCloud Drive** — File-based data (documents, images, any file format)
+
+## Quick Decision Tree
+
+```
+What needs syncing?
+
+├─ Structured data (records, relationships)?
+│  ├─ Using SwiftData? → SwiftData + CloudKit (easiest, iOS 17+)
+│  ├─ Need shared/public database? → CKSyncEngine or raw CloudKit
+│  └─ Custom persistence (GRDB, SQLite)? → CKSyncEngine (iOS 17+)
+│
+├─ Documents/files users expect in Files app?
+│  └─ iCloud Drive (UIDocument or FileManager)
+│
+├─ Large binary blobs (images, videos)?
+│  ├─ Associated with structured data? → CKAsset in CloudKit
+│  └─ Standalone files? → iCloud Drive
+│
+└─ App settings/preferences?
+   └─ NSUbiquitousKeyValueStore (simple key-value, 1MB limit)
+```
+
+## CloudKit vs iCloud Drive
+
+| Aspect | CloudKit | iCloud Drive |
+|--------|----------|--------------|
+| **Data shape** | Structured records | Files/documents |
+| **Query support** | Full query language | Filename only |
+| **Relationships** | Native support | None (manual) |
+| **Conflict resolution** | Record-level | File-level |
+| **User visibility** | Hidden from user | Visible in Files app |
+| **Sharing** | Record/database sharing | File sharing |
+| **Offline** | Local cache required | Automatic download |
+
+## Red Flags
+
+If ANY of these appear, STOP and reconsider:
+
+- ❌ "Store JSON files in CloudKit" — Wrong tool. Use iCloud Drive for files
+- ❌ "Build relationships manually in iCloud Drive" — Wrong tool. Use CloudKit
+- ❌ "Assume sync is instant" — Network fails. Design offline-first
+- ❌ "Skip conflict handling" — Conflicts WILL happen on multiple devices
+- ❌ "Use CloudKit for user documents" — Users can't see them. Use iCloud Drive
+- ❌ "Sync on app launch only" — Users expect continuous sync
+
+## Offline-First Pattern
+
+**MANDATORY**: All sync code must work offline first.
+
+```swift
+// ✅ CORRECT: Offline-first architecture
+class OfflineFirstSync {
+    private let localStore: LocalDatabase  // GRDB, SwiftData, Core Data
+    private let syncEngine: CKSyncEngine
+
+    // Write to LOCAL first, sync to cloud in background
+    func save(_ item: Item) async throws {
+        // 1. Save locally (instant)
+        try await localStore.save(item)
+
+        // 2. Queue for sync (non-blocking)
+        syncEngine.state.add(pendingRecordZoneChanges: [
+            .saveRecord(item.recordID)
+        ])
+    }
+
+    // Read from LOCAL (instant)
+    func fetch() async throws -> [Item] {
+        return try await localStore.fetchAll()
+    }
+}
+
+// ❌ WRONG: Cloud-first (blocks on network)
+func save(_ item: Item) async throws {
+    // Fails when offline, slow on bad network
+    try await cloudKit.save(item)
+    try await localStore.save(item)
+}
+```
+
+## Conflict Resolution Strategies
+
+Conflicts occur when two devices edit the same data before syncing.
+
+### Strategy 1: Last-Writer-Wins (Simplest)
+
+```swift
+// Server always has latest, client accepts it
+func resolveConflict(local: CKRecord, server: CKRecord) -> CKRecord {
+    return server  // Accept server version
+}
+```
+
+**Use when**: Data is non-critical, user won't notice overwrites
+
+### Strategy 2: Merge (Most Common)
+
+```swift
+// Combine changes from both versions
+func resolveConflict(local: CKRecord, server: CKRecord) -> CKRecord {
+    let merged = server.copy() as! CKRecord
+
+    // For each field, apply custom merge logic
+    merged["notes"] = mergeText(
+        local["notes"] as? String,
+        server["notes"] as? String
+    )
+    merged["tags"] = mergeSets(
+        local["tags"] as? [String] ?? [],
+        server["tags"] as? [String] ?? []
+    )
+
+    return merged
+}
+```
+
+**Use when**: Both versions contain valuable changes
+
+### Strategy 3: User Choice
+
+```swift
+// Present conflict to user
+func resolveConflict(local: CKRecord, server: CKRecord) async -> CKRecord {
+    let choice = await presentConflictUI(local: local, server: server)
+    return choice == .keepLocal ? local : server
+}
+```
+
+**Use when**: Data is critical, user must decide
+
+## Common Patterns
+
+### Pattern 1: SwiftData + CloudKit (Recommended for New Apps)
+
+```swift
+import SwiftData
+
+// Automatic CloudKit sync with zero configuration
+@Model
+class Note {
+    var title: String
+    var content: String
+    var createdAt: Date
+
+    init(title: String, content: String) {
+        self.title = title
+        self.content = content
+        self.createdAt = Date()
+    }
+}
+
+// Container automatically syncs if CloudKit entitlement present
+let container = try ModelContainer(for: Note.self)
+```
+
+**Limitations**:
+- Private database only (no public/shared)
+- Automatic sync (less control over timing)
+- No custom conflict resolution
+- `@Attribute(.unique)` not supported with CloudKit sync — remove if using CloudKit
+
+### Pattern 2: CKSyncEngine (Custom Persistence)
+
+```swift
+// For GRDB, SQLite, or custom databases
+class MySyncManager: CKSyncEngineDelegate {
+    private let engine: CKSyncEngine
+    private let database: GRDBDatabase
+
+    func handleEvent(_ event: CKSyncEngine.Event) async {
+        switch event {
+        case .stateUpdate(let update):
+            // Persist sync state
+            await saveSyncState(update.stateSerialization)
+
+        case .fetchedDatabaseChanges(let changes):
+            // Apply changes to local DB
+            for zone in changes.modifications {
+                await handleZoneChanges(zone)
+            }
+
+        case .sentRecordZoneChanges(let sent):
+            // Mark records as synced
+            for saved in sent.savedRecords {
+                await markSynced(saved.recordID)
+            }
+        }
+    }
+}
+```
+
+See `axiom-cloudkit-ref` for complete CKSyncEngine setup.
+
+### Pattern 3: iCloud Drive Documents
+
+```swift
+import UIKit
+
+class MyDocument: UIDocument {
+    var content: Data?
+
+    override func contents(forType typeName: String) throws -> Any {
+        return content ?? Data()
+    }
+
+    override func load(fromContents contents: Any, ofType typeName: String?) throws {
+        content = contents as? Data
+    }
+}
+
+// Save to iCloud Drive (visible in Files app)
+let url = FileManager.default.url(forUbiquityContainerIdentifier: nil)?
+    .appendingPathComponent("Documents")
+    .appendingPathComponent("MyFile.txt")
+
+let doc = MyDocument(fileURL: url!)
+doc.content = "Hello".data(using: .utf8)
+doc.save(to: url!, for: .forCreating)
+```
+
+See `axiom-icloud-drive-ref` for NSFileCoordinator and conflict handling.
+
+## Anti-Patterns
+
+### 1. Ignoring Sync State
+
+```swift
+// ❌ WRONG: No awareness of pending changes
+var items: [Item] = []  // Are these synced? Pending? Conflicted?
+
+// ✅ CORRECT: Track sync state
+struct SyncableItem {
+    let item: Item
+    let syncState: SyncState  // .synced, .pending, .conflict
+}
+```
+
+### 2. Blocking UI on Sync
+
+```swift
+// ❌ WRONG: UI blocks until sync completes
+func viewDidLoad() async {
+    items = try await cloudKit.fetchAll()  // Spinner forever on airplane
+    tableView.reloadData()
+}
+
+// ✅ CORRECT: Show local data immediately
+func viewDidLoad() {
+    items = localStore.fetchAll()  // Instant
+    tableView.reloadData()
+
+    Task {
+        await syncEngine.fetchChanges()  // Background update
+    }
+}
+```
+
+### 3. CloudKit Schema Not Deployed to Production
+
+CloudKit has **separate schemas for Development and Production**. Your app in the App Store can only access the Production environment. If you add record types, fields, or indexes in Development but never deploy them, queries in Production return empty results with no error.
+
+```
+❌ Works in Xcode/TestFlight (Development) → empty results in App Store (Production)
+   Queries silently return zero results — no CKError, no crash, no clue.
+
+✅ Before every App Store submission:
+   1. CloudKit Console → Select container
+   2. "Deploy Schema Changes" → Review changes → Deploy
+   3. Test with Production environment in Xcode scheme settings
+```
+
+**Time cost of skipping**: 3-7 days (rejection cycle + debugging "why does it work in TestFlight but not production?"). This is the #1 CloudKit gotcha for first-time submitters.
+
+### 4. No Retry Logic
+
+```swift
+// ❌ WRONG: Single attempt
+try await cloudKit.save(record)
+
+// ✅ CORRECT: Exponential backoff
+func saveWithRetry(_ record: CKRecord, attempts: Int = 3) async throws {
+    for attempt in 0..<attempts {
+        do {
+            try await cloudKit.save(record)
+            return
+        } catch let error as CKError where error.isRetryable {
+            let delay = pow(2.0, Double(attempt))
+            try await Task.sleep(for: .seconds(delay))
+        }
+    }
+    throw SyncError.maxRetriesExceeded
+}
+```
+
+## Sync State Indicators
+
+Always show users the sync state:
+
+```swift
+enum SyncState {
+    case synced       // ✓ (checkmark)
+    case pending      // ↻ (arrows)
+    case conflict     // ⚠ (warning)
+    case offline      // ☁ with X
+}
+
+// In SwiftUI
+HStack {
+    Text(item.title)
+    Spacer()
+    SyncIndicator(state: item.syncState)
+}
+```
+
+## Entitlement Checklist
+
+Before sync will work:
+
+1. **Xcode → Signing & Capabilities**
+   - ✓ iCloud capability added
+   - ✓ CloudKit checked (for CloudKit)
+   - ✓ iCloud Documents checked (for iCloud Drive)
+   - ✓ Container selected/created
+
+2. **Apple Developer Portal**
+   - ✓ App ID has iCloud capability
+   - ✓ CloudKit container exists (for CloudKit)
+
+3. **CloudKit Console (before App Store submission)**
+   - ✓ Schema deployed to Production (record types, fields, indexes)
+   - ✓ Test with Production environment in Xcode scheme to verify queries work
+
+4. **Device**
+   - ✓ Signed into iCloud
+   - ✓ iCloud Drive enabled (Settings → [Name] → iCloud)
+
+## Large Dataset Sync
+
+When syncing 10,000+ records, naive approaches cause timeouts and launch slowdowns.
+
+### Initial Sync Strategy
+
+```swift
+// ❌ WRONG: Fetch everything at once
+let allRecords = try await database.fetchAll()
+syncEngine.state.add(pendingRecordZoneChanges: allRecords.map { .saveRecord($0.recordID) })
+
+// ✅ CORRECT: Batch initial sync
+func performInitialSync(batchSize: Int = 200) async throws {
+    var cursor: CKQueryOperation.Cursor? = nil
+
+    repeat {
+        let (results, nextCursor) = try await database.records(
+            matching: query,
+            resultsLimit: batchSize,
+            desiredKeys: nil,
+            continuationCursor: cursor
+        )
+        // Process batch
+        try await localStore.saveBatch(results.compactMap { try? $0.1.get() })
+        cursor = nextCursor
+    } while cursor != nil
+}
+```
+
+### Incremental Sync (After Initial)
+
+CKSyncEngine handles incremental sync automatically — it fetches only changes since the last sync token. Ensure you persist `stateSerialization` so the engine doesn't re-fetch everything on next launch.
+
+### Performance Guidelines
+
+| Dataset Size | Strategy | Notes |
+|-------------|----------|-------|
+| < 1,000 records | Default CKSyncEngine | Works out of the box |
+| 1,000–10,000 | Batch initial sync | 200-record batches, show progress UI |
+| 10,000+ | Pagination + background | Use BGProcessingTask for initial sync |
+| 100,000+ | Server-side filtering | Only sync what user needs, lazy-load rest |
+
+**Key insight**: Initial sync is the bottleneck. After initial sync, CKSyncEngine's incremental approach handles large datasets efficiently because it only fetches deltas.
+
+## Pressure Scenarios
+
+### Scenario 1: "Just skip conflict handling for v1"
+
+**Situation**: Deadline pressure to ship without conflict resolution.
+
+**Risk**: Users WILL edit on multiple devices. Data WILL be lost silently.
+
+**Response**: "Minimum viable conflict handling takes 2 hours. Silent data loss costs users and generates 1-star reviews."
+
+### Scenario 2: "Sync on app launch is enough"
+
+**Situation**: Avoiding continuous sync complexity.
+
+**Risk**: Users expect changes to appear within seconds, not on next launch.
+
+**Response**: Use CKSyncEngine or SwiftData which handle continuous sync automatically.
+
+## Related Skills
+
+- `axiom-cloudkit-ref` — Complete CloudKit API reference
+- `axiom-icloud-drive-ref` — File-based sync with NSFileCoordinator
+- `axiom-cloud-sync-diag` — Debugging sync failures
+- `axiom-storage` — Choosing where to store data locally