Add maintainer onboarding documentation

2026-07-03 12:44:15 +02:00
parent 5d80af375e
commit d80486b25e
15 changed files with 1273 additions and 28 deletions
@@ -0,0 +1,81 @@
+# 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
+```