# 23. Offline Mode & Sync Conflict Resolution

meta:
  id: ios-production-23
  feature: ios-production
  priority: P2
  depends_on: [ios-production-21]
  tags: [backend, offline, production]

objective:
- Implement robust offline mode with sync conflict resolution for all user actions

deliverables:
- Offline queue improvements
- Sync conflict resolution strategy
- Offline UI indicators
- Data consistency guarantees

steps:
1. Audit existing offline support:
   - Review iOS/Kordant/Services/OfflineQueue.swift
   - Review CacheManager.swift
   - Identify gaps in offline handling
2. Improve offline queue:
   - Support all mutation types (add, update, delete)
   - Add request deduplication
   - Add request ordering (dependencies)
   - Increase max retry count with exponential backoff
3. Implement conflict resolution:
   - Define strategy per data type:
     - Server wins for most data (alerts, exposures)
     - Last write wins for user preferences
     - Merge for watchlist items
   - Add conflict detection (version numbers or timestamps)
   - Show conflict UI for manual resolution (if needed)
4. Add offline UI:
   - Offline indicator in status bar
   - Disabled actions when offline
   - "Sync pending" badges on modified items
   - Pull-to-refresh with offline state
5. Implement data consistency:
   - Optimistic updates (update UI immediately, sync in background)
   - Rollback on sync failure
   - Verify server state after sync
   - Handle partial sync failures
6. Add background sync:
   - Process queue on app foreground
   - Process queue on network restoration
   - Schedule periodic sync attempts
7. Test offline scenarios:
   - Create watchlist item offline → syncs when online
   - Delete exposure offline → syncs when online
   - Modify settings offline → syncs when online
   - Conflicting edits on multiple devices

tests:
- Unit: Test queue ordering and deduplication
- Integration: Test sync after offline period
- E2E: Test conflicting edits resolution

acceptance_criteria:
- All mutations queued when offline
- Queue processed automatically when online
- Optimistic updates show immediately
- Failed operations roll back UI changes
- Conflict resolution strategy defined per data type
- Offline indicator visible in UI
- Sync pending badges on modified items
- No data loss during sync failures
- Background sync on app foreground and network restore
- Unit tests for all offline scenarios

validation:
- Enable airplane mode → create watchlist item → badge shows
- Disable airplane mode → item syncs → badge clears
- Edit same item on web and iOS → conflict resolved correctly
- Kill app during sync → queue persists, resumes on relaunch

notes:
- Current OfflineQueue exists but may need enhancement
- CRDTs (Conflict-free Replicated Data Types) are ideal for sync
- Consider using Realm or Core Data with sync for complex cases
- Simple server-wins strategy is acceptable for MVP