feat: order history & spending analytics sensors

[kwaczek]

Summary

• Order History Storage: Persistent JSON-based OrderStore with paginated API fetch for full order history backfill
• Spending Analytics Sensors: 10 new sensors for category spending (L0–L3) and per-item spending, each with "this year" and "all time" variants
• Config Flow: Two-step wizard (login → analytics) with opt-in checkboxes for analytics levels, configurable top N items (default 10), and hide discontinued products toggle
• Options Flow: All analytics settings reconfigurable on existing entries via the Configure button
• Background Processing: Full order history download and enrichment runs in the background without blocking the config flow
• Localized Notifications: Progress notifications during enrichment in EN/CS based on HA language setting

Test plan

• Production deployment tested with 484 orders
• Fresh Docker HA instance: full wizard flow (login → analytics → completion) works end-to-end
• Options flow: changing top N and hide discontinued works on existing entries
• Sensors correctly display top N items with total_count attribute
• Discontinued products excluded when hide option is enabled
• Background history fetch completes without blocking UI
• Verify on clean install without analytics enabled (base sensors only)

🤖 Generated with Claude Code

[dvejsada]

@kwaczek Thank you for this PR. However, please kindly add to make this (i.e. total history fetching and analytics) optional in the config with default being off - I would presume that may people (and I am one of them) do not want this kind of details to be fetched and stored in HA, incl. all history.

[kwaczek]

@dvejsada It is optional during the wizard and turned off by default. Spin off a new HA in docker and check the wizard

[Copilot]

Pull request overview

This PR introduces persistent order-history storage and opt-in spending analytics for the Rohlik.cz Home Assistant integration, including a two-step config flow/options flow and background backfill/enrichment with localized progress notifications.

Changes:

• Added JSON-backed OrderStore with order backfill + item/category enrichment paths and new related services.
• Added opt-in analytics sensors (yearly/all-time totals, category L0–L3, per-item) gated by config/options.
• Updated config flow/options flow, translations, and documentation to support analytics settings and usage.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
custom_components/rohlikcz/hub.py	Adds OrderStore, enrichment logic, background enrichment scheduling, and localized notifications.
custom_components/rohlikcz/rohlik_api.py	Adds pagination + order detail/category fetch + enrichment helper methods.
custom_components/rohlikcz/sensor.py	Adds analytics sensors and gates them based on selected options.
custom_components/rohlikcz/config_flow.py	Implements 2-step config flow (login → analytics) and OptionsFlow for analytics settings.
custom_components/rohlikcz/__init__.py	Passes options into hub, adds migration + reload listener, schedules background history fetch.
custom_components/rohlikcz/const.py	Adds icons, analytics option constants, and new service constant(s).
custom_components/rohlikcz/services.py	Registers fetch_order_history and enrich_orders services.
custom_components/rohlikcz/services.yaml	Documents new services for HA service UI.
custom_components/rohlikcz/translations/en.json	Adds analytics step/options UI strings and new entity translation keys.
custom_components/rohlikcz/translations/cs.json	Adds analytics step/options UI strings and new entity translation keys (Czech).
custom_components/rohlikcz/manifest.json	Bumps integration version to 0.4.0.
tests/test_order_store.py	Adds a standalone test script for basic store/dedup/aggregation behavior.
readme.md	Documents analytics setup, sensor list, and new backfill action.
docs/plans/2026-02-26-order-history-sensors.md	Implementation plan documentation for order history sensors.
docs/plans/2026-02-26-order-history-sensors-design.md	Design doc for order history sensors.
docs/plans/2026-02-26-config-flow-analytics-options.md	Implementation plan for analytics config/options flow.
docs/plans/2026-02-26-category-item-analytics.md	Implementation plan for category/item analytics enrichment + sensors.

Comments suppressed due to low confidence (1)

custom_components/rohlikcz/services.py:176

• register_services(hass) is called from async_setup_entry, and the integration now reloads entries when options change. Since register_services unconditionally calls hass.services.async_register(...), a reload will attempt to re-register the same services in the same HA runtime (potentially raising and breaking reload). Make service registration idempotent (e.g., check hass.services.has_service(DOMAIN, ...) / store a flag in hass.data) or register/unregister services in a way that is safe across reloads.

    # Register the services
    hass.services.async_register(
        DOMAIN,
        SERVICE_ADD_TO_CART,
        async_add_to_cart_service,
        schema=vol.Schema({
            vol.Required(ATTR_CONFIG_ENTRY_ID): cv.string,
            vol.Required(ATTR_PRODUCT_ID): cv.positive_int,
            vol.Required(ATTR_QUANTITY, default=1): cv.positive_int,
        }),
        supports_response=True
    )

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

For the yearly L0 category sensor, total_orders is filtered to the current year (store.yearly_count(year)), but enriched_orders uses store.enriched_count (all-time). This makes the attributes inconsistent/misleading for “this year”. Consider computing an enriched-order count filtered by the same year.