adds syncing

2025-12-08 06:02:34 +00:00 · 2025-08-27 16:17:21 +02:00
parent 1191d06e53
commit 709cf2cbd9
24 changed files with 3809 additions and 226 deletions
--- a/WEBDAV_SYNC_IMPLEMENTATION.md
+++ b/WEBDAV_SYNC_IMPLEMENTATION.md
@@ -0,0 +1,287 @@
+# WebDAV Cloud Sync Implementation
+
+## Overview
+
+This document describes the WebDAV cloud sync implementation for the Supplements Tracker Flutter app. The implementation allows users to synchronize their supplement data across multiple devices using WebDAV-compatible servers like Nextcloud, ownCloud, or any standard WebDAV server.
+
+## Architecture
+
+### Core Components
+
+#### 1. Data Models Enhanced with Sync Metadata
+
+All core data models (`Supplement`, `SupplementIntake`, `Ingredient`) have been enhanced with sync metadata:
+
+- `syncId: String` - Unique identifier for sync operations (UUID)
+- `lastModified: DateTime` - Timestamp of last modification
+- `syncStatus: SyncStatus` - Current sync state (pending, synced, modified, conflict, etc.)
+- `isDeleted: bool` - Soft delete flag for sync purposes
+
+#### 2. Sync Enumerations (`lib/models/sync_enums.dart`)
+
+- `SyncStatus` - Track individual record sync states
+- `SyncOperationStatus` - Overall sync operation states
+- `ConflictResolutionStrategy` - How to handle conflicts
+- `SyncFrequency` - Auto-sync timing options
+- `ConflictType` - Types of sync conflicts
+
+#### 3. Sync Data Models (`lib/models/sync_data.dart`)
+
+- `SyncData` - Complete data structure for WebDAV JSON format
+- `SyncConflict` - Represents conflicts between local and remote data
+- `SyncResult` - Results and statistics from sync operations
+- `SyncStatistics` - Detailed sync operation metrics
+
+#### 4. WebDAV Sync Service (`lib/services/webdav_sync_service.dart`)
+
+Core service handling WebDAV communication:
+- Server configuration and authentication
+- Data upload/download operations
+- Conflict detection and basic resolution
+- Network connectivity checking
+- Device identification
+
+#### 5. Sync Provider (`lib/providers/sync_provider.dart`)
+
+State management layer for sync operations:
+- Manages sync status and progress
+- Handles user configuration
+- Coordinates between WebDAV service and UI
+- Manages conflict resolution workflow
+
+#### 6. UI Components
+
+- `SyncSettingsScreen` - Complete WebDAV configuration interface
+- Integration with existing settings screen
+- Real-time sync status indicators
+- Conflict resolution dialogs
+
+### Database Schema Changes
+
+The database has been upgraded to version 6 with sync support:
+
+```sql
+-- New sync columns added to existing tables
+ALTER TABLE supplements ADD COLUMN syncId TEXT NOT NULL UNIQUE;
+ALTER TABLE supplements ADD COLUMN lastModified TEXT NOT NULL;
+ALTER TABLE supplements ADD COLUMN syncStatus TEXT NOT NULL DEFAULT 'pending';
+ALTER TABLE supplements ADD COLUMN isDeleted INTEGER NOT NULL DEFAULT 0;
+
+-- Similar columns added to supplement_intakes table
+
+-- New sync metadata table
+CREATE TABLE sync_metadata (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  key TEXT NOT NULL UNIQUE,
+  value TEXT NOT NULL,
+  lastUpdated TEXT NOT NULL
+);
+
+-- Device info table for multi-device conflict resolution
+CREATE TABLE device_info (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  deviceId TEXT NOT NULL UNIQUE,
+  deviceName TEXT NOT NULL,
+  lastSyncTime TEXT,
+  createdAt TEXT NOT NULL
+);
+```
+
+## Sync Process Flow
+
+### 1. Configuration Phase
+1. User enters WebDAV server URL, username, and password/app password
+2. System tests connection and validates credentials
+3. Creates sync directory on server if needed
+4. Stores encrypted credentials locally using `flutter_secure_storage`
+
+### 2. Sync Operation
+1. Check network connectivity
+2. Download remote sync data (JSON file from WebDAV)
+3. Compare with local data using timestamps and sync IDs
+4. Detect conflicts (modification, deletion, creation conflicts)
+5. Merge data according to conflict resolution strategy
+6. Upload merged data back to server
+7. Update local sync status
+
+### 3. Conflict Resolution
+- **Last-write-wins**: Prefer most recently modified record
+- **Prefer Local**: Always keep local changes
+- **Prefer Remote**: Always keep remote changes
+- **Manual**: Present conflicts to user for individual resolution
+
+## Security Considerations
+
+### Data Protection
+- Credentials stored using `flutter_secure_storage` with platform encryption
+- Support for app passwords instead of main account passwords
+- No sensitive data logged in release builds
+
+### Network Security
+- HTTPS enforced for WebDAV connections
+- Connection testing before storing credentials
+- Proper error handling for authentication failures
+
+## Supported WebDAV Servers
+
+### Tested Compatibility
+- **Nextcloud** - Full compatibility with automatic path detection
+- **ownCloud** - Full compatibility with automatic path detection
+- **Generic WebDAV** - Manual path configuration required
+
+### Server Requirements
+- WebDAV protocol support
+- File read/write permissions
+- Directory creation permissions
+- Basic or digest authentication
+
+## Data Synchronization Format
+
+### JSON Structure
+```json
+{
+  "version": 1,
+  "deviceId": "device_12345_67890",
+  "deviceName": "John's Phone",
+  "syncTimestamp": "2024-01-15T10:30:00.000Z",
+  "supplements": [
+    {
+      "syncId": "uuid-supplement-1",
+      "name": "Vitamin D3",
+      "ingredients": [...],
+      "lastModified": "2024-01-15T09:15:00.000Z",
+      "syncStatus": "synced",
+      "isDeleted": false,
+      // ... other supplement fields
+    }
+  ],
+  "intakes": [
+    {
+      "syncId": "uuid-intake-1",
+      "supplementId": 1,
+      "takenAt": "2024-01-15T08:00:00.000Z",
+      "lastModified": "2024-01-15T08:00:30.000Z",
+      "syncStatus": "synced",
+      "isDeleted": false,
+      // ... other intake fields
+    }
+  ],
+  "metadata": {
+    "totalSupplements": 5,
+    "totalIntakes": 150
+  }
+}
+```
+
+## Usage Instructions
+
+### Initial Setup
+1. Navigate to Settings → Cloud Sync
+2. Enter your WebDAV server details:
+   - Server URL (e.g., `https://cloud.example.com`)
+   - Username
+   - Password or app password
+   - Optional device name
+3. Test connection
+4. Configure sync preferences
+
+### Sync Options
+- **Manual Sync**: Sync on demand via button press
+- **Auto Sync**: Automatic background sync at configured intervals
+  - Every 15 minutes
+  - Hourly
+  - Every 6 hours
+  - Daily
+
+### Conflict Resolution
+- Configure preferred resolution strategy in settings
+- Review individual conflicts when they occur
+- Auto-resolve based on chosen strategy
+
+## Implementation Status
+
+### ✅ Completed (Phase 1)
+- Core sync architecture and data models
+- WebDAV service implementation
+- Database schema with sync support
+- Basic UI for configuration and management
+- Manual sync operations
+- Conflict detection
+- Secure credential storage
+
+### 🔄 Future Enhancements (Phase 2+)
+- Background sync scheduling
+- Advanced conflict resolution UI
+- Sync history and logs
+- Client-side encryption option
+- Multiple server support
+- Bandwidth optimization
+- Offline queue management
+
+## Dependencies Added
+
+```yaml
+dependencies:
+  webdav_client: ^1.2.2      # WebDAV protocol client
+  connectivity_plus: ^6.0.5   # Network connectivity checking
+  flutter_secure_storage: ^9.2.2  # Secure credential storage
+  uuid: ^4.5.0               # UUID generation for sync IDs
+  crypto: ^3.0.5             # Data integrity verification
+```
+
+## File Structure
+
+```
+lib/
+├── models/
+│   ├── sync_enums.dart           # Sync-related enumerations
+│   ├── sync_data.dart            # Sync data models
+│   ├── supplement.dart           # Enhanced with sync metadata
+│   ├── supplement_intake.dart    # Enhanced with sync metadata
+│   └── ingredient.dart           # Enhanced with sync metadata
+├── services/
+│   ├── webdav_sync_service.dart  # WebDAV communication
+│   └── database_helper.dart      # Enhanced with sync methods
+├── providers/
+│   └── sync_provider.dart        # Sync state management
+└── screens/
+    └── sync_settings_screen.dart # Sync configuration UI
+```
+
+## Error Handling
+
+The implementation includes comprehensive error handling for:
+- Network connectivity issues
+- Authentication failures
+- Server unavailability
+- Malformed sync data
+- Storage permission issues
+- Conflicting concurrent modifications
+
+## Testing Recommendations
+
+### Unit Tests
+- Sync data serialization/deserialization
+- Conflict detection algorithms
+- Merge logic validation
+
+### Integration Tests
+- WebDAV server communication
+- Database sync operations
+- Cross-device sync scenarios
+
+### User Testing
+- Multi-device sync workflows
+- Network interruption recovery
+- Large dataset synchronization
+- Conflict resolution user experience
+
+## Performance Considerations
+
+- Incremental sync (only changed data)
+- Compression for large datasets
+- Connection timeout handling
+- Memory-efficient JSON processing
+- Background processing for large operations
+
+This implementation provides a solid foundation for cloud synchronization while maintaining data integrity and user experience across multiple devices.