Rijad Zuzo
82 lines
2.4 KiB
Markdown
82 lines
2.4 KiB
Markdown
# Storage And Migrations
|
|
|
|
## Local Product Store
|
|
|
|
The product store is abstracted by `LocalDataStore`.
|
|
|
|
Implementations:
|
|
|
|
- `HiveLocalDataStore`
|
|
- `SharedPrefsLocalDataStore`
|
|
- `InMemoryLocalDataStore`
|
|
|
|
Provider:
|
|
|
|
- `lib/app/data/storage/local_data_store_provider.dart`
|
|
|
|
Default:
|
|
|
|
- `USE_HIVE_LOCAL_DB=true`
|
|
|
|
## Sync Store
|
|
|
|
The sync queue has a separate store abstraction:
|
|
|
|
- `lib/features/sync/data/storage/sync_state_store.dart`
|
|
- `HiveSyncStateStore`
|
|
- `SharedPrefsSyncStateStore`
|
|
- `InMemorySyncStateStore`
|
|
|
|
This separation is intentional. Product state and sync queue state have
|
|
different recovery and migration needs.
|
|
|
|
## Migration Behavior
|
|
|
|
On startup, `LocalRepository`:
|
|
|
|
1. Reads the configured product store.
|
|
2. If Hive is enabled and empty, attempts to import legacy shared preferences.
|
|
3. Writes the migrated data into Hive.
|
|
4. Clears the legacy store.
|
|
5. Parses `LocalDataState`.
|
|
6. Reconciles reminder schedules.
|
|
|
|
If stored JSON is invalid, the app falls back to empty seeded state.
|
|
|
|
`SyncQueueRepository` follows the same Hive-first import pattern for sync state.
|
|
|
|
## Adding Persisted Fields
|
|
|
|
Checklist:
|
|
|
|
1. Add the field to the feature-owned model.
|
|
2. Update constructor, field declaration, `copyWith`, `toJson`, and `fromJson`.
|
|
3. Use default values or nullable parsing for backward compatibility.
|
|
4. Add the field to `LocalDataState` if it is a new aggregate collection.
|
|
5. Update repository operations that should create, update, merge, or delete it.
|
|
6. Update merge behavior if the field is person-owned.
|
|
7. Update sync payloads if the backend should receive it.
|
|
8. Add tests for old JSON and new JSON.
|
|
|
|
Increase `_schemaVersion` in `LocalRepository` only when the migration needs
|
|
explicit logic or when a stored shape changes in a way that cannot be handled by
|
|
default parsing.
|
|
|
|
## Data Loss Traps
|
|
|
|
- Do not remove unknown lists from `LocalDataState.fromJson` without a migration.
|
|
- Do not clear Hive/shared preferences to "fix" parse issues except in tests.
|
|
- When deleting a person, check all person-owned collections and source links.
|
|
- When merging people, move facts, dates, signals, messages, inbox candidates,
|
|
reminders, ideas, moments, and source links to the target profile.
|
|
- Reminder scheduling is a side effect of repository writes; failures are
|
|
swallowed by design.
|
|
|
|
## Useful Tests
|
|
|
|
```bash
|
|
flutter test test/features/local
|
|
flutter test test/features/local/storage
|
|
flutter test test/features/sync/storage
|
|
```
|