refactor: enhance order store management with backfill tracking and migration

Author: dvejsada

custom_components/rohlikcz/__init__.py

@@ -50,16 +50,31 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     _LOGGER.info("Platforms setup complete")
 
-    # If analytics enabled, fetch full order history + enrich in background
-    if analytics:
-        async def _fetch_history():
-            try:
-                if rohlik_hub.order_store:
+    # If analytics enabled, run initial backfill or resume interrupted enrichment
+    if analytics and rohlik_hub.order_store:
+        store = rohlik_hub.order_store
+        needs_backfill = not store.backfill_complete
+        needs_enrichment = (
+            store.backfill_complete
+            and (store.unenriched_order_ids or store.uncategorized_product_ids())
+        )
+
+        if needs_backfill:
+            async def _fetch_history():
+                try:
                     await rohlik_hub.fetch_full_order_history(hass=hass)
-            except Exception as err:
-                _LOGGER.error("Background order history fetch failed: %s", err)
-
-        entry.async_create_background_task(hass, _fetch_history(), "rohlik_fetch_history")
+                except Exception as err:
+                    _LOGGER.error("Background order history fetch failed: %s", err)
+
+            entry.async_create_background_task(hass, _fetch_history(), "rohlik_fetch_history")
+        elif needs_enrichment:
+            async def _resume_enrichment():
+                try:
+                    await rohlik_hub.enrich_order_details(hass=hass)
+                except Exception as err:
+                    _LOGGER.error("Background enrichment resume failed: %s", err)
+
+            entry.async_create_background_task(hass, _resume_enrichment(), "rohlik_resume_enrichment")
 
     # Reload when options change (user reconfigures analytics)
     entry.async_on_unload(entry.add_update_listener(_async_reload_entry))

custom_components/rohlikcz/hub.py

@@ -51,7 +51,7 @@ class OrderStore:
 
     def __init__(self, storage_dir: str, user_id: str, hass: HomeAssistant):
         self._path = os.path.join(storage_dir, f"rohlikcz_{user_id}_orders.json")
-        self._data = {"version": 2, "user_id": user_id, "tracking_since": None, "orders": {}, "product_categories": {}}
+        self._data = {"version": 3, "user_id": user_id, "tracking_since": None, "backfill_complete": False, "orders": {}, "product_categories": {}}
         self._hass = hass
 
     @classmethod
@@ -67,15 +67,28 @@ def _load_sync(self) -> None:
             try:
                 with open(self._path, "r") as f:
                     self._data = json.load(f)
+                migrated = False
                 # Migrate v1 → v2
                 if self._data.get("version", 1) < 2:
                     self._data["version"] = 2
                     if "product_categories" not in self._data:
                         self._data["product_categories"] = {}
-                    self._save_sync()
+                    migrated = True
                     _LOGGER.info("Migrated order store from v1 to v2")
                 elif "product_categories" not in self._data:
                     self._data["product_categories"] = {}
+                # Migrate v2 → v3 (add backfill_complete flag)
+                if self._data.get("version", 1) < 3:
+                    self._data["version"] = 3
+                    # Existing stores with tracking_since already set had a
+                    # successful backfill in a prior run; mark it complete so
+                    # we don't re-download everything on next restart.
+                    if "backfill_complete" not in self._data:
+                        self._data["backfill_complete"] = self._data.get("tracking_since") is not None
+                    migrated = True
+                    _LOGGER.info("Migrated order store from v2 to v3")
+                if migrated:
+                    self._save_sync()
             except (json.JSONDecodeError, OSError) as err:
                 _LOGGER.error(f"Failed to load order store: {err}")
 
@@ -143,6 +156,15 @@ def orders(self) -> dict:
     def tracking_since(self) -> str | None:
         return self._data.get("tracking_since")
 
+    @property
+    def backfill_complete(self) -> bool:
+        """Whether the initial full order history download has finished."""
+        return self._data.get("backfill_complete", False)
+
+    def mark_backfill_complete(self) -> None:
+        """Mark the initial backfill as done (caller must async_save)."""
+        self._data["backfill_complete"] = True
+
     def yearly_total(self, year: str) -> float:
         """Sum of order amounts for a given year (e.g. '2026')."""
         return sum(
@@ -427,6 +449,10 @@ async def fetch_full_order_history(self, hass=None) -> dict:
         if self._order_store:
             enrich_stats = await self.enrich_order_details(hass=hass)
             enrich_stats["new_orders"] = new_orders
+            # Mark backfill as done so we don't re-download on next restart
+            if not self._order_store.backfill_complete:
+                self._order_store.mark_backfill_complete()
+                await self._order_store.async_save()
             return enrich_stats
 
         return {"total_orders": 0, "new_orders": 0}