api.py

"""
API endpoints for battery and electricity settings, dashboard data, and decision intelligence.

"""

import dataclasses
import threading
from datetime import date as date_cls
from datetime import datetime, timedelta

from api_conversion import (
    BATTERY_MODEL_ATTRS as _BATTERY_MODEL_ATTRS,
)
from api_conversion import (
    HOME_MODEL_ATTRS as _HOME_MODEL_ATTRS,
)
from api_conversion import (
    convert_keys_to_camel_case,
    convert_keys_to_snake_case,
)
from api_dataclasses import (
    _ENTITY_ID_RE,
    _HA_DOMAIN_RE,
    APIConsumptionForecastComparison,
    APIDashboardHourlyData,
    APIDashboardResponse,
    APIPredictionSnapshot,
    APISavingsBucket,
    APISetupCompletePayload,
    APISnapshotComparison,
    APIStrategyForecast,
    FormattedValue,
    create_formatted_value,
)
from fastapi import APIRouter, HTTPException, Query
from loguru import logger

from core.bess import time_utils
from core.bess.health_check import describe_failing_checks, run_system_health_checks
from core.bess.savings_aggregator import DEFAULT_COUNTS, build_buckets
from core.bess.settings_store import VALID_PLATFORMS, flatten_sensors
from core.bess.time_utils import get_period_count

router = APIRouter()

#: The wizard payload field each energy provider cannot work without.
#: Mirrors BatterySystemManager._create_price_source, which needs exactly
#: these to construct a usable PriceSource (#549).
_PROVIDER_REQUIRED_FIELD: dict[str, str] = {
    "nordpool_official": "nordpoolConfigEntryId",
    "nordpool_hacs": "nordpoolEntity",
    "octopus": "octopusImportTodayEntity",
    "entsoe": "entsoeEntity",
}


def _get_hourly_settings_from_periods(schedule_manager, hour: int) -> dict:
    """Build hourly settings from period-level data.

    Compatibility layer for API endpoints that return hourly data to the
    frontend.  Picks the dominant intent (majority vote, alphabetical
    tie-break) from the 4 quarterly periods of the given hour and returns
    the corresponding control settings.
    """
    intents = schedule_manager.strategic_intents
    if not intents:
        raise ValueError("No strategic intents available")

    num_periods = len(intents)
    start_p = hour * 4
    end_p = min(start_p + 4, num_periods)
    if start_p >= num_periods:
        raise ValueError(f"Hour {hour} out of range")

    period_intents = intents[start_p:end_p]
    counts: dict[str, int] = {}
    for i in period_intents:
        counts[i] = counts.get(i, 0) + 1
    max_count = max(counts.values())
    dominant = min(i for i, c in counts.items() if c == max_count)

    # Find a period with the dominant intent and return its settings
    for p in range(start_p, end_p):
        if intents[p] == dominant:
            return schedule_manager.get_period_settings(p)

    return schedule_manager.get_period_settings(start_p)


def _deep_merge(base: dict, updates: dict) -> dict:
    """Recursively merge *updates* into *base*, preserving nested dict values.

    Nested dicts are merged key-by-key so that a partial update (e.g. only
    ``config_entry_id``) cannot erase sibling keys that already exist in the
    stored section.  All other value types are overwritten as normal.
    """
    result = dict(base)
    for key, value in updates.items():
        if isinstance(value, dict) and isinstance(result.get(key), dict):
            result[key] = _deep_merge(result[key], value)
        else:
            result[key] = value
    return result


def _strip_empty_sensor_values(sensors: dict) -> dict:
    """Remove empty-string values from sensor sub-dicts.

    Sensor sections have structure like:
        {"platform": "growatt_server_min", "shared": {...}, "growatt_server_min": {...}}

    For each sub-dict (shared, platform-specific), strip keys whose values are
    empty strings.  This ensures cleared sensors are fully removed from persistent
    storage rather than lingering as zombie entries.
    """
    result = {}
    for key, value in sensors.items():
        if isinstance(value, dict):
            cleaned = {k: v for k, v in value.items() if v != ""}
            result[key] = cleaned
        else:
            result[key] = value
    return result


def _validate_power_monitoring_sensors(
    home_section: dict, active_sensors: dict
) -> None:
    """Raise HTTPException(422) if power monitoring is being enabled without
    the phase-current sensors its phase_count requires.

    Mirrors the frontend gating in HomeFormSection.tsx/SetupWizardPage.tsx —
    this is the server-side backstop so the API itself refuses the invalid
    combination regardless of which client called it.
    """
    if not home_section.get("power_monitoring_enabled"):
        return
    phase_count = home_section.get("phase_count", 3)
    required_keys = (
        ["current_l1"]
        if phase_count == 1
        else [
            "current_l1",
            "current_l2",
            "current_l3",
        ]
    )
    required_keys = [*required_keys, "battery_charging_power_rate"]
    missing = [k for k in required_keys if not active_sensors.get(k)]
    if missing:
        raise HTTPException(
            status_code=422,
            detail=(
                "Cannot enable power monitoring: missing required sensor(s) "
                f"for {phase_count}-phase: {', '.join(missing)}. "
                "Configure them in Settings → Sensors first."
            ),
        )


_CONSUMPTION_STRATEGIES = ("fixed", "sensor", "influxdb_7d_avg", "ha_statistics")


def _validate_consumption_strategy(home_section: dict, active_sensors: dict) -> None:
    """Raise HTTPException(422) for a consumption strategy that cannot work.

    Mirrors the frontend gating in HomeFormSection.tsx — the server-side
    backstop so the API refuses the combination regardless of which client
    called it. Only ``sensor`` is checked against its sensor: it is the one
    strategy with no fallback, so without ``48h_avg_grid_import`` every
    optimization run aborts, no schedule is ever built, and the dashboard
    sits on "Initializing" forever (#558). ``ha_statistics`` and
    ``influxdb_7d_avg`` are left alone — they degrade to the fixed profile
    and report it, rather than stalling.
    """
    strategy = home_section.get("consumption_strategy")
    if strategy is None:
        return
    if strategy not in _CONSUMPTION_STRATEGIES:
        raise HTTPException(
            status_code=422,
            detail=(
                f"Unknown consumption strategy '{strategy}'. Valid values: "
                f"{', '.join(_CONSUMPTION_STRATEGIES)}."
            ),
        )
    if strategy == "sensor" and not active_sensors.get("48h_avg_grid_import"):
        raise HTTPException(
            status_code=422,
            detail=(
                "Consumption strategy 'sensor' requires the "
                "'48h_avg_grid_import' sensor, which is not configured. "
                "Configure it in Settings → Sensors first, or choose a "
                "strategy that does not need it."
            ),
        )


def _require_configured_system(bess_controller) -> None:
    """Raise HTTP 503 if the BESS system has not been configured yet.

    Call this at the top of any endpoint that requires a fully initialised
    ``BatterySystemManager`` (inverter controller, scheduler, etc.).
    The setup wizard endpoints intentionally skip this check so they remain
    reachable on a fresh install.

    Args:
        bess_controller: The global BESSController instance (already imported
            by the calling endpoint via ``from app import bess_controller``).
    """
    if not bess_controller.system.is_configured:
        raise HTTPException(
            status_code=503,
            detail="System not configured. Complete the setup wizard first.",
        )
    if not bess_controller.startup_complete:
        raise HTTPException(
            status_code=503,
            detail="System is starting up. Please wait.",
        )


def _refresh_health(bess_controller) -> None:
    """Re-run the health check so the dashboard banner reflects the latest state.

    Called after any settings mutation that could affect sensor or component
    health (home, sensors, energy-provider, inverter, battery, electricity).
    Failures are non-fatal — the banner will self-correct on the next poll.
    """
    try:
        bess_controller.system.refresh_health_check()
    except Exception as exc:
        logger.warning("Could not refresh health state after settings update: %s", exc)


# ---------------------------------------------------------------------------
# Unified settings endpoints
# ---------------------------------------------------------------------------

# Maps camelCase section names (from the API) to snake_case store keys.
_SECTION_MAP: dict[str, str] = {
    "battery": "battery",
    "home": "home",
    "electricityPrice": "electricity_price",
    "energyProvider": "energy_provider",
    "growatt": "growatt",
    "inverter": "inverter",
    "sensors": "sensors",
    "aiAnalyst": "ai_analyst",
    "demoMode": "demo_mode",
}


@router.get("/api/settings")
async def get_settings():
    """Return all settings enriched with computed battery fields.

    Sensor keys are system identifiers (snake_case) and are intentionally
    not converted to camelCase — all other sections use camelCase field names.
    """
    from copy import deepcopy

    from app import bess_controller

    try:
        data = deepcopy(bess_controller.settings_store.data)

        # Enrich battery section with computed kWh fields derived from SOC limits
        battery = data.get("battery", {})
        total = battery.get("total_capacity", 0.0)
        battery["min_soe_kwh"] = total * battery.get("min_soc", 0.0) / 100.0
        battery["max_soe_kwh"] = total * battery.get("max_soc", 0.0) / 100.0
        battery["reserved_capacity"] = battery["min_soe_kwh"]
        data["battery"] = battery

        # Enrich the inverter section with the domain vendor service calls
        # actually go to, so the UI can show the platform default as a
        # placeholder without duplicating PLATFORM_SERVICE_DOMAIN client-side.
        inverter = data.get("inverter", {})
        inverter["resolved_service_domain"] = (
            bess_controller.settings_store.get_service_domain()
        )
        data["inverter"] = inverter

        # Return the full per-platform sensors structure from the store.
        # Also include a flat "activeSensors" view for backwards compatibility.
        data.pop("sensors", None)
        result = convert_keys_to_camel_case(data)
        result["sensors"] = bess_controller.settings_store.data.get("sensors", {})
        return result
    except Exception as e:
        logger.error(f"Error getting settings: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.patch("/api/settings")
async def patch_settings(updates: dict):
    """Partial-update settings — only provided sections are touched.

    Each top-level key must be a known section name (camelCase).  Field values
    within each section are converted from camelCase to snake_case before being
    merged into the persistent store and applied to the running system.
    """
    from app import bess_controller

    try:
        for camel_key, section_data in updates.items():
            store_key = _SECTION_MAP.get(camel_key)
            if store_key is None:
                raise HTTPException(
                    status_code=400, detail=f"Unknown settings section: {camel_key!r}"
                )

            # Sensor keys are system identifiers — skip camelCase conversion
            if store_key == "sensors":
                snake_data = section_data
            else:
                snake_data = convert_keys_to_snake_case(section_data)

            # Validate before persisting — sensors need entity ID format checked first.
            if store_key == "sensors":
                for key, value in snake_data.items():
                    if isinstance(value, dict):
                        # Per-platform sub-dict — validate entity IDs within
                        for v in value.values():
                            if v and isinstance(v, str) and not _ENTITY_ID_RE.match(v):
                                raise HTTPException(
                                    status_code=422,
                                    detail=f"Invalid entity ID format: {v!r}",
                                )
                    elif isinstance(value, str) and value and key != "platform":
                        if not _ENTITY_ID_RE.match(value):
                            raise HTTPException(
                                status_code=422,
                                detail=f"Invalid entity ID format: {value!r}",
                            )

            if store_key == "inverter":
                domain = snake_data.get("service_domain")
                if domain and not _HA_DOMAIN_RE.match(domain):
                    raise HTTPException(
                        status_code=422,
                        detail=(
                            f"Invalid Home Assistant integration domain: {domain!r}"
                        ),
                    )

            # Read-modify-write: merge into the existing section.
            # Use deep merge so that partial updates to nested sub-dicts (e.g.
            # nordpool_official.config_entry_id) do not erase sibling keys.
            section = bess_controller.settings_store.get_section(store_key)
            section = _deep_merge(section, snake_data)

            # Strip empty-string sensor values so they don't persist as
            # zombie entries.  An empty string means "remove this sensor".
            if store_key == "sensors":
                section = _strip_empty_sensor_values(section)

            # Validate power-monitoring sensor requirements BEFORE persisting —
            # must run ahead of save_section so an invalid combination is never
            # written to disk, even though the client still gets a 422.
            if store_key == "home":
                effective_sensors = {
                    **bess_controller.settings_store.get_active_sensors(),
                    **flatten_sensors(updates.get("sensors") or {}),
                }
                _validate_power_monitoring_sensors(section, effective_sensors)
                _validate_consumption_strategy(section, effective_sensors)

            if store_key == "sensors":
                # A sensor removal (e.g. unmapping a phase-current sensor) can
                # break an already-enabled power-monitoring config just as
                # much as an explicit disable-without-sensors on the home
                # section can — validate against the persisted home config.
                persisted_home = bess_controller.settings_store.get_section("home")
                _validate_power_monitoring_sensors(
                    persisted_home, flatten_sensors(section)
                )
                _validate_consumption_strategy(persisted_home, flatten_sensors(section))

            bess_controller.settings_store.save_section(store_key, section)

            # Apply in-memory updates for sections that drive live behaviour
            if store_key == "battery":
                in_mem = {k: v for k, v in section.items() if k in _BATTERY_MODEL_ATTRS}
                if in_mem:
                    bess_controller.system.update_settings({"battery": in_mem})
                td = section.get("temperature_derating")
                if isinstance(td, dict):
                    obj = bess_controller.system.temperature_derating
                    if "enabled" in td:
                        obj.enabled = td["enabled"]
                    if "weather_entity" in td:
                        obj.weather_entity = td["weather_entity"]

            elif store_key == "home":
                # Filtered to known HomeSettings fields — a stale pre-migration
                # key (e.g. 'consumption') can coexist with its renamed
                # successor if a migration was ever interrupted (see
                # HOME_MODEL_ATTRS's comment in api_conversion.py); passing it
                # straight through would raise AttributeError.
                # (Power-monitoring sensor validation already ran above, before
                # save_section, so the invalid combination is never persisted.)
                in_mem = {k: v for k, v in section.items() if k in _HOME_MODEL_ATTRS}
                bess_controller.system.update_settings({"home": in_mem})

            elif store_key == "electricity_price":
                # PriceSettings attribute names match the store field names directly
                bess_controller.system.update_settings({"price": section})

            elif store_key == "energy_provider":
                # Apply the new provider live so a restart is not required when
                # switching between nordpool, nordpool_official, and octopus.
                bess_controller.system.update_settings({"energy_provider": section})

            elif store_key == "growatt":
                # Platform switching lives in the "inverter" branch below;
                # this section only carries the Growatt cloud device_id.
                if "device_id" in section:
                    bess_controller.ha_controller.growatt_device_id = section[
                        "device_id"
                    ]

            elif store_key == "inverter":
                # device_id here is the Huawei battery device (the Growatt
                # cloud device_id lives in the growatt section above). Apply
                # it live for the same reason that branch does — otherwise an
                # edit in Settings only takes effect after a restart.
                if "device_id" in section:
                    bess_controller.ha_controller.huawei_device_id = section[
                        "device_id"
                    ]
                platform = section.get("platform")
                if platform:
                    bess_controller.system.switch_inverter_platform(platform)
                else:
                    raise HTTPException(
                        status_code=400,
                        detail="Inverter section requires a 'platform' field",
                    )

                # Only GEN4 (solax_modbus_growatt_min) accepts an explicit
                # control_mode here: GEN3 (solax_modbus_growatt_sph) was
                # already resolved to "vpp" by switch_inverter_platform()
                # above, and re-applying a stale client-side "tou" default
                # would raise, since GEN3 rejects any other value.
                control_mode = section.get("control_mode")
                if control_mode and platform == "solax_modbus_growatt_min":
                    bess_controller.system.switch_control_mode(control_mode)

            elif store_key == "demo_mode":
                enabled = section.get("enabled", False)
                bess_controller.system.set_demo_mode(enabled)

        # Any of the sections above (sensors directly, or growatt/inverter via
        # a platform switch) can change service_domain and the grid/battery
        # signed-sensor polarities — refresh those unconditionally rather
        # than only on a key match.
        # ha_controller.sensors is a live settings_store view (#334) and
        # needs no equivalent refresh.
        bess_controller.refresh_service_domain()
        bess_controller.refresh_power_polarities()
        _refresh_health(bess_controller)
        return await get_settings()

    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error updating settings: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


def _aggregate_quarterly_to_hourly(
    quarterly_periods: list[APIDashboardHourlyData],
    _battery_capacity: float,
    currency: str,
) -> list[APIDashboardHourlyData]:
    """Aggregate quarterly (15-min) periods into hourly periods.

    Args:
        quarterly_periods: List of quarterly period data (96 periods for normal day)
        battery_capacity: Battery capacity in kWh
        currency: Currency code

    Returns:
        List of hourly aggregated data (24 hours for normal day)
    """
    if not quarterly_periods:
        return []

    # Priority order for tie-breaking: prioritize action over inaction
    intent_priority = {
        "GRID_CHARGING": 5,
        "BATTERY_EXPORT": 4,
        "LOAD_SUPPORT": 3,
        "SOLAR_STORAGE": 2,
        "IDLE": 1,
    }

    def dominant_intent(intents: list[str]) -> str:
        """Most common intent among the 4 quarters; ties broken by priority."""
        intent_counts: dict[str, int] = {}
        for intent_item in intents:
            intent_counts[intent_item] = intent_counts.get(intent_item, 0) + 1
        max_count = max(intent_counts.values())
        candidates = [i for i, c in intent_counts.items() if c == max_count]
        return max(candidates, key=lambda x: intent_priority.get(x, 0))

    hourly_periods = []
    num_hours = (len(quarterly_periods) + 3) // 4  # Round up to handle DST

    for hour in range(num_hours):
        # Get the 4 quarterly periods for this hour
        start_idx = hour * 4
        end_idx = min(start_idx + 4, len(quarterly_periods))
        quarter_periods = quarterly_periods[start_idx:end_idx]

        if not quarter_periods:
            continue

        # Use the last period's values for state-based fields
        last_period = quarter_periods[-1]

        # Determine dominant strategic intent (most common in the 4 periods)
        # If there's a tie, prioritize action over inaction
        dominant_strategic_intent = dominant_intent(
            [p.strategicIntent for p in quarter_periods]
        )

        # Curtailment (#501) is independent of intent -- a curtailed quarter
        # can classify as SOLAR_STORAGE (battery still charging at its rate
        # limit while the surplus above it curtails), so never filter by the
        # dominant intent. If any quarter was curtailed, the hour as
        # displayed is (at least partly) a curtailed export, not a purely
        # profitable one.
        hour_curtailed = any(p.curtailed for p in quarter_periods)

        # Observed intent must aggregate across all 4 quarters too, not just
        # the last one — a re-plan only updates strategicIntent going
        # forward, so a stale strategicIntent can persist for an elapsed hour
        # even though most/all of its quarters were genuinely observed
        # executing something else (#486). dataSource itself stays tied to
        # the last quarter (unchanged) — actualSavingsSoFar/predictedRemaining
        # Savings (api_dataclasses.py) bucket a whole hour's summed
        # hourlySavings by this field, so flipping it to "actual" as soon as
        # any one quarter is actual would count still-predicted quarters'
        # costs as realized.
        actual_quarters = [p for p in quarter_periods if p.dataSource == "actual"]
        observed_intents = [
            p.observedIntent for p in actual_quarters if p.observedIntent
        ]
        hour_observed_intent = (
            dominant_intent(observed_intents)
            if observed_intents
            else last_period.observedIntent
        )

        # Sum energy values across the 4 quarters
        hourly_period = APIDashboardHourlyData(
            period=hour,
            dataSource=last_period.dataSource,
            timestamp=last_period.timestamp,
            # Sum energy flows
            solarProduction=create_formatted_value(
                sum(p.solarProduction.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            homeConsumption=create_formatted_value(
                sum(p.homeConsumption.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            gridImported=create_formatted_value(
                sum(p.gridImported.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            gridExported=create_formatted_value(
                sum(p.gridExported.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            batteryCharged=create_formatted_value(
                sum(p.batteryCharged.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            batteryDischarged=create_formatted_value(
                sum(p.batteryDischarged.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            batteryAction=create_formatted_value(
                sum(p.batteryAction.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            # Average prices
            buyPrice=create_formatted_value(
                sum(p.buyPrice.value for p in quarter_periods) / len(quarter_periods),
                "price",
                currency,
            ),
            sellPrice=create_formatted_value(
                sum(p.sellPrice.value for p in quarter_periods) / len(quarter_periods),
                "price",
                currency,
            ),
            # Use last period's SOC and SOE
            batterySocStart=last_period.batterySocStart,
            batterySocEnd=last_period.batterySocEnd,
            batterySoeStart=last_period.batterySoeStart,
            batterySoeEnd=last_period.batterySoeEnd,
            # Sum detailed energy flows
            solarToHome=create_formatted_value(
                sum(p.solarToHome.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            solarToBattery=create_formatted_value(
                sum(p.solarToBattery.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            solarToGrid=create_formatted_value(
                sum(p.solarToGrid.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            clippedSolar=create_formatted_value(
                sum(p.clippedSolar.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            gridToHome=create_formatted_value(
                sum(p.gridToHome.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            gridToBattery=create_formatted_value(
                sum(p.gridToBattery.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            batteryToHome=create_formatted_value(
                sum(p.batteryToHome.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            batteryToGrid=create_formatted_value(
                sum(p.batteryToGrid.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            # Solar-only scenario fields
            gridImportNeeded=create_formatted_value(
                sum(p.gridImportNeeded.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            # Sum costs and savings
            importCost=create_formatted_value(
                sum(p.importCost.value for p in quarter_periods), "currency", currency
            ),
            exportRevenue=create_formatted_value(
                sum(p.exportRevenue.value for p in quarter_periods),
                "currency",
                currency,
            ),
            hourlyCost=create_formatted_value(
                sum(p.hourlyCost.value for p in quarter_periods), "currency", currency
            ),
            gridCost=create_formatted_value(
                sum(p.gridCost.value for p in quarter_periods), "currency", currency
            ),
            batteryCycleCost=create_formatted_value(
                sum(p.batteryCycleCost.value for p in quarter_periods),
                "currency",
                currency,
            ),
            hourlySavings=create_formatted_value(
                sum(p.hourlySavings.value for p in quarter_periods),
                "currency",
                currency,
            ),
            gridOnlyCost=create_formatted_value(
                sum(p.gridOnlyCost.value for p in quarter_periods), "currency", currency
            ),
            solarOnlyCost=create_formatted_value(
                sum(p.solarOnlyCost.value for p in quarter_periods),
                "currency",
                currency,
            ),
            solarExcess=create_formatted_value(
                sum(p.solarExcess.value for p in quarter_periods),
                "energy_kwh_only",
                currency,
            ),
            solarSavings=create_formatted_value(
                sum(p.solarSavings.value for p in quarter_periods), "currency", currency
            ),
            batterySavings=create_formatted_value(
                sum(p.batterySavings.value for p in quarter_periods),
                "currency",
                currency,
            ),
            netSavings=create_formatted_value(
                sum(p.netSavings.value for p in quarter_periods), "currency", currency
            ),
            # Use dominant strategic intent with tie-breaking (same logic as Growatt schedule)
            strategicIntent=dominant_strategic_intent,
            observedIntent=hour_observed_intent,
            curtailed=hour_curtailed,
            directSolar=sum(p.directSolar for p in quarter_periods),
        )

        hourly_periods.append(hourly_period)

    return hourly_periods


@router.get("/api/dashboard/available-dates")
async def get_dashboard_available_dates():
    """List ISO dates that have dashboard data available (for date-picker greying).

    Today is always included even though it is deliberately excluded from
    DailyViewStore.list_available_dates() by design — today's view is
    persisted continuously, but only past days are listed as history.
    """
    from app import bess_controller

    if not bess_controller.system.is_configured:
        raise HTTPException(
            status_code=503,
            detail="System not configured. Complete the setup wizard first.",
        )

    persisted_dates = bess_controller.system.daily_view_store.list_available_dates()
    today = time_utils.today().isoformat()
    dates = sorted(set(persisted_dates) | {today})
    return {"dates": dates}


@router.get("/api/dashboard")
async def get_dashboard_data(
    resolution: str = Query("quarter-hourly", pattern="^(hourly|quarter-hourly)$"),
    date: str | None = Query(
        None, description="ISO date (YYYY-MM-DD) for a historical day; omit for today"
    ),
):
    """Unified dashboard endpoint using dataclass-based implementation for type safety.

    Args:
        resolution: Data resolution - 'hourly' (24 periods) or 'quarter-hourly' (96 periods)
        date: Optional historical date. Past days are read from the persisted
            DailyViewStore rather than the live in-memory system state, so
            tomorrow's schedule and real-time battery SOC don't apply.
    """
    from app import bess_controller

    # On a fresh install, the system is unconfigured — 503 so the frontend
    # redirects to the setup wizard.
    if not bess_controller.system.is_configured:
        raise HTTPException(
            status_code=503,
            detail="System not configured. Complete the setup wizard first.",
        )

    # During startup (configured system, background init still running) or
    # post-wizard backfill, return an "initializing" response so the
    # frontend shows a spinner instead of an error.
    if not bess_controller.startup_complete:
        logger.info("Dashboard requested during startup — returning initializing state")
        return {
            "error": "initializing",
            "message": "System is starting up. The optimization schedule will be ready shortly.",
            "status": bess_controller.startup_status,
        }

    target_date = date_cls.fromisoformat(date) if date else None
    is_historical = target_date is not None and target_date != time_utils.today()

    try:
        logger.debug(
            f"Starting dashboard data retrieval with resolution={resolution}, date={date}"
        )

        if is_historical:
            daily_view = bess_controller.system.daily_view_store.load_day(target_date)
            if daily_view is None:
                raise HTTPException(
                    status_code=404,
                    detail=f"No historical data available for {target_date.isoformat()}",
                )
        else:
            # Guard: if no schedule exists yet the system is still initializing
            # (post-wizard backfill running in background).
            if not bess_controller.system.schedule_store.get_latest_schedule():
                logger.info(
                    "Dashboard requested before schedule is ready — returning initializing state"
                )
                return {
                    "error": "initializing",
                    "message": "System is initializing. The optimization schedule will be ready shortly.",
                }

            # Get daily view data (always quarterly internally)
            daily_view = bess_controller.system.get_current_daily_view()

        logger.debug(f"Daily view retrieved with {len(daily_view.periods)} periods")

        # Get system components
        controller = bess_controller.ha_controller
        settings = bess_controller.system.get_settings()
        battery_capacity = settings["battery"].total_capacity
        currency = bess_controller.system.home_settings.currency

        # Convert periods to API format (works for both hourly and quarterly)
        hourly_dataclass_instances = [
            APIDashboardHourlyData.from_internal(
                period_data, battery_capacity, currency
            )
            for period_data in daily_view.periods
        ]

        # Convert to hourly if requested
        if resolution == "hourly":
            logger.debug(
                f"Converting {len(hourly_dataclass_instances)} quarterly periods to hourly"
            )
            hourly_dataclass_instances = _aggregate_quarterly_to_hourly(
                hourly_dataclass_instances, battery_capacity, currency
            )
            logger.debug(
                f"Aggregated to {len(hourly_dataclass_instances)} hourly periods"
            )

        # Extract tomorrow's optimization data from ScheduleStore.
        # Not applicable when browsing a historical day — there's no "tomorrow"
        # schedule relative to a past date.
        tomorrow_data: list[APIDashboardHourlyData] | None = None
        if not is_historical:
            try:
                today_period_count = get_period_count(time_utils.today())
                tomorrow_period_count = get_period_count(
                    time_utils.today() + timedelta(days=1)
                )
                tomorrow_periods = []
                # Resolved by exact timestamp (not positional index -
                # optimization_period) so a standalone next-day schedule
                # (period_data[0] anchored to tomorrow 00:00 despite
                # optimization_period=0) is read correctly without needing
                # to special-case its anchor.
                for period_idx in range(
                    today_period_count,
                    today_period_count + tomorrow_period_count,
                ):
                    period_data = (
                        bess_controller.system.schedule_store.get_period_data_at(
                            time_utils.period_index_to_timestamp(period_idx)
                        )
                    )
                    if period_data is not None:
                        tomorrow_periods.append(period_data)
                if tomorrow_periods:
                    tomorrow_data = [
                        APIDashboardHourlyData.from_internal(
                            p, battery_capacity, currency
                        )
                        for p in tomorrow_periods
                    ]
                    if resolution == "hourly":
                        tomorrow_data = _aggregate_quarterly_to_hourly(
                            tomorrow_data, battery_capacity, currency
                        )
                    else:
                        # Tomorrow's periods are indexed relative to the start of the
                        # optimization window (e.g. 96..191 for a 96-period day).
                        # The frontend maps period index to wall-clock time, so period 0
                        # must represent 00:00 of the displayed day.
                        tomorrow_data = [
                            dataclasses.replace(p, period=i)
                            for i, p in enumerate(tomorrow_data)
                        ]
            except (AttributeError, KeyError, ValueError) as e:
                logger.warning(f"Failed to get tomorrow's optimization data: {e}")
                tomorrow_data = None

        # Calculate basic totals from dataclass fields directly (no dict access)
        basic_totals = {
            "totalSolarProduction": sum(
                h.solarProduction.value for h in hourly_dataclass_instances
            ),
            "totalHomeConsumption": sum(
                h.homeConsumption.value for h in hourly_dataclass_instances
            ),
            "totalBatteryCharged": sum(
                h.batteryCharged.value for h in hourly_dataclass_instances
            ),
            "totalBatteryDischarged": sum(
                h.batteryDischarged.value for h in hourly_dataclass_instances
            ),
            "totalGridImport": sum(
                h.gridImported.value for h in hourly_dataclass_instances
            ),
            "totalGridExport": sum(
                h.gridExported.value for h in hourly_dataclass_instances
            ),
            "avgBuyPrice": (
                sum(h.buyPrice.value for h in hourly_dataclass_instances)
                / len(hourly_dataclass_instances)
                if hourly_dataclass_instances
                else 0
            ),
        }

        # Calculate costs from dataclass fields directly - using ACTUAL backend calculations
        total_optimized_cost = sum(
            h.hourlyCost.value for h in hourly_dataclass_instances
        )
        total_grid_only_cost = sum(
            h.gridOnlyCost.value for h in hourly_dataclass_instances
        )
        total_solar_only_cost = sum(
            h.solarOnlyCost.value for h in hourly_dataclass_instances
        )
        total_net_grid_cost = sum(h.gridCost.value for h in hourly_dataclass_instances)

        costs = {
            "gridOnly": total_grid_only_cost,
            "solarOnly": total_solar_only_cost,
            "optimized": total_optimized_cost,
            "netGrid": total_net_grid_cost,
        }

        # Issue #287: when a 2-day DP plan is active, tomorrow_data already
        # holds the deferred-to-tomorrow slice — fold it into a full-horizon
        # total so the dashboard doesn't make a correctly-deferred decision
        # look like a loss.
        if tomorrow_data:
            costs["netGridFullHorizon"] = total_net_grid_cost + sum(
                h.gridCost.value for h in tomorrow_data
            )
            costs["gridOnlyFullHorizon"] = total_grid_only_cost + sum(
                h.gridOnlyCost.value for h in tomorrow_data
            )
            costs["horizonDays"] = 2
        else:
            costs["horizonDays"] = 1

        if is_historical:
            # No live sensor state applies to a past day — derive SOC from the
            # last persisted period instead of reading the current battery sensor.
            last_period = daily_view.periods[-1]
            battery_soc: float = (
                last_period.energy.battery_soe_end / battery_capacity
            ) * 100.0
            strategic_summary: dict[str, int] = {}
            for period_data in daily_view.periods:
                intent = period_data.decision.strategic_intent
                strategic_summary[intent] = strategic_summary.get(intent, 0) + 1
        else:
            battery_soc = controller.get_battery_soc()

            # Strategic intent summary from actual schedule data
            try:
                schedule_manager = bess_controller.system._inverter_controller
                strategic_summary_data = schedule_manager.get_strategic_intent_summary()
                # Convert to count format expected by frontend
                strategic_summary = {
                    intent: data.get("count", 0)
                    for intent, data in strategic_summary_data.items()
                }
            except Exception as e:
                logger.error(f"Failed to get strategic intent summary: {e}")
                raise ValueError(
                    f"Strategic intent summary is required but failed to load: {e}"
                ) from e

        # Create the dataclass response using pre-created hourly instances
        response = APIDashboardResponse.from_dashboard_data(
            daily_view=daily_view,
            controller=controller,
            totals=basic_totals,
            costs=costs,
            strategic_summary=strategic_summary,
            battery_soc=battery_soc,
            battery_capacity=battery_capacity,
            currency=currency,
            hourly_data_instances=hourly_dataclass_instances,
            resolution=resolution,
            tomorrow_data=tomorrow_data,
        )

        if is_historical:
            # currentPeriod is computed from wall-clock "now" in from_dashboard_data,
            # which doesn't apply to a past day — no row should show as "Current".
            response.currentPeriod = -1

        logger.debug("Dashboard response created successfully using dataclasses")

        # Return dataclass directly - already has camelCase fields
        return response.__dict__

    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error generating dashboard data: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


# Canonical inverter endpoints (/api/inverter/*) plus legacy /api/growatt/* aliases
@router.get("/api/inverter/status")
@router.get("/api/growatt/inverter_status")
async def get_inverter_status():
    """Get comprehensive real-time inverter status data."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        # Safety checks to avoid None references
        if bess_controller.system is None:
            logger.error("Battery system not initialized")
            raise HTTPException(
                status_code=503, detail="Battery system not initialized"
            )

        controller = bess_controller.system._controller
        if controller is None:
            logger.error("Battery controller not initialized")
            raise HTTPException(
                status_code=503, detail="Battery controller not initialized"
            )

        battery_settings = bess_controller.system.battery_settings

        # Get current battery mode from schedule for current hour. Only
        # tou_register controllers actually have a batt_mode register;
        # vpp_power controllers surface vpp_power_pct/vpp_remote_control
        # instead, and period_list controllers have neither -- mirrors
        # _mode_display_fields()'s contract (see get_period_settings()).
        current_mode_fields: dict = {}
        try:
            now = time_utils.now()
            schedule_manager = bess_controller.system._inverter_controller
            current_period = now.hour * 4 + now.minute // 15
            period_settings = schedule_manager.get_period_settings(current_period)
            if "batt_mode" in period_settings:
                current_mode_fields = {"battery_mode": period_settings["batt_mode"]}
            elif "vpp_power_pct" in period_settings:
                current_mode_fields = {
                    "vpp_power_pct": period_settings["vpp_power_pct"],
                    "vpp_remote_control": period_settings["vpp_remote_control"],
                }
        except Exception as e:
            logger.warning(f"Failed to get current battery mode: {e}")

        battery_soc = controller.get_battery_soc()
        if battery_soc is None:
            raise ValueError("battery_soc sensor is unavailable")
        battery_soe = (battery_soc / 100.0) * battery_settings.total_capacity
        grid_charge_enabled = controller.grid_charge_enabled()
        charge_power_rate = controller.get_charging_power_rate()
        discharge_power_rate = controller.get_discharging_power_rate()
        battery_charge_power = controller.get_battery_charge_power()
        battery_discharge_power = controller.get_battery_discharge_power()

        inverter_platform = bess_controller.system.inverter_platform
        control_model = schedule_manager.CONTROL_MODEL

        response = {
            "battery_soc": battery_soc,
            "battery_soe": battery_soe,
            "battery_charge_power": battery_charge_power,
            "battery_discharge_power": battery_discharge_power,
            **current_mode_fields,
            "grid_charge_enabled": grid_charge_enabled,
            "charge_stop_soc": battery_settings.max_soc,
            "discharge_stop_soc": battery_settings.min_soc,
            "charge_power_rate": charge_power_rate,
            "discharge_power_rate": discharge_power_rate,
            "discharge_inhibit_active": controller.get_discharge_inhibit_active(),
            "inverter_platform": inverter_platform,
            "control_model": control_model,
            "timestamp": datetime.now().isoformat(),
        }

        # Convert to camelCase for API consistency
        return convert_keys_to_camel_case(response)

    except Exception as e:
        logger.error(f"Error getting inverter status: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/inverter/schedule")
@router.get("/api/growatt/detailed_schedule")
async def get_growatt_detailed_schedule():
    """Get detailed Growatt-specific schedule information with strategic intents."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        schedule_manager = bess_controller.system._inverter_controller
        control_model = schedule_manager.CONTROL_MODEL
        battery_settings = bess_controller.system.battery_settings
        current_hour = time_utils.now().hour

        # Get TOU intervals directly from schedule manager
        try:
            tou_intervals = schedule_manager.get_all_tou_segments()
        except Exception as e:
            logger.error(f"Failed to get TOU intervals: {e}")
            tou_intervals = []

        # Get strategic intent summary
        intent_distribution = {}
        strategic_summary = {}
        try:
            strategic_summary = schedule_manager.get_strategic_intent_summary()
            for intent, data in strategic_summary.items():
                intent_distribution[intent] = data.get("count", 0)
        except Exception as e:
            logger.error(f"Failed to get strategic intent summary: {e}")

        # Build hourly schedule data
        schedule_data = []
        charge_hours = 0
        discharge_hours = 0
        idle_hours = 0
        mode_distribution = {}

        for hour in range(24):
            try:
                hourly_settings = _get_hourly_settings_from_periods(
                    schedule_manager, hour
                )
                battery_mode = hourly_settings.get("batt_mode")
                if battery_mode is not None:
                    mode_distribution[battery_mode] = (
                        mode_distribution.get(battery_mode, 0) + 1
                    )

                strategic_intent = hourly_settings.get("strategic_intent", "IDLE")

                # Determine action and color based on strategic intent
                if strategic_intent == "GRID_CHARGING":
                    action = "GRID_CHARGE"
                    action_color = "blue"
                    charge_hours += 1
                elif strategic_intent == "SOLAR_CHARGING":
                    action = "SOLAR_CHARGE"
                    action_color = "green"
                    charge_hours += 1
                elif strategic_intent == "IDLE":
                    action = "IDLE"
                    action_color = "gray"
                    idle_hours += 1
                else:
                    action = "EXPORT"
                    action_color = "red"
                    discharge_hours += 1

                # Get price for this hour
                price = 1.0
                try:
                    price_entries = (
                        bess_controller.system.price_manager.get_today_prices()
                    )
                    if hour < len(price_entries):
                        price = price_entries[hour]
                except Exception as e:
                    logger.warning(f"Failed to get price for hour {hour}: {e}")

                schedule_data.append(
                    {
                        "hour": hour,
                        "mode": "idle",
                        **(
                            {"batt_mode": battery_mode, "batteryMode": battery_mode}
                            if battery_mode is not None
                            else {}
                        ),
                        **(
                            {
                                "vpp_power_pct": hourly_settings["vpp_power_pct"],
                                "vpp_remote_control": hourly_settings[
                                    "vpp_remote_control"
                                ],
                            }
                            if "vpp_power_pct" in hourly_settings
                            else {}
                        ),
                        "grid_charge": hourly_settings.get("grid_charge", False),
                        "discharge_rate": hourly_settings.get("discharge_rate", 100),
                        "dischargePowerRate": hourly_settings.get(
                            "discharge_rate", 100
                        ),
                        "chargePowerRate": hourly_settings.get("charge_rate", 100),
                        "strategic_intent": strategic_intent,
                        "intent_description": schedule_manager._get_intent_description(
                            strategic_intent
                        ),
                        "action": action,
                        "action_color": action_color,
                        "battery_action": 0.0,
                        "battery_action_kw": 0.0,
                        "batteryCharged": 0,
                        "batteryDischarged": 0,
                        "price": price,
                        "electricity_price": price,
                        "grid_power": 0,
                        "is_current": hour == current_hour,
                    }
                )

            except Exception as e:
                logger.error(f"Error processing hour {hour}: {e}")
                schedule_data.append(
                    {
                        "hour": hour,
                        "mode": "idle",
                        **(
                            {
                                "batt_mode": "load_first",
                                "batteryMode": "load_first",  # Add alias for frontend compatibility
                            }
                            if control_model == "tou_register"
                            else {}
                        ),
                        "grid_charge": False,
                        "discharge_rate": 100,
                        "dischargePowerRate": 100,  # Add alias
                        "chargePowerRate": 100,  # Default charge power rate
                        "strategic_intent": "IDLE",
                        "intent_description": "",
                        "action": "IDLE",
                        "action_color": "gray",
                        "battery_action": 0.0,
                        "batteryCharged": 0.0,  # Add for frontend compatibility
                        "batteryDischarged": 0.0,  # Add for frontend compatibility
                        "soc": 50.0,
                        "batterySocEnd": 50.0,  # Add for frontend compatibility
                        "price": 1.0,
                        "electricity_price": 1.0,
                        "grid_power": 0,
                        "is_current": hour == current_hour,
                    }
                )
                idle_hours += 1

        # Get period groups from schedule manager (15-minute resolution)
        period_groups = []
        try:
            today_soc_values: list[float | None] = []
            today_actions: list[float] = []
            today_curtailed: list[bool] = []
            today_reconciled_intents: list[str] | None = None
            if bess_controller.system.schedule_store.get_latest_schedule():
                today_period_count_local = get_period_count(time_utils.today())
                planned_intents = schedule_manager.strategic_intents
                today_reconciled_intents = []
                # Resolved by exact timestamp (not positional index -
                # optimization_period) so a standalone next-day schedule
                # (period_data[0] anchored to tomorrow 00:00 despite
                # optimization_period=0) is read correctly without needing
                # to special-case its anchor.
                for period_idx in range(today_period_count_local):
                    planned_intent = (
                        planned_intents[period_idx]
                        if planned_intents and period_idx < len(planned_intents)
                        else "IDLE"
                    )
                    pd_today = bess_controller.system.schedule_store.get_period_data_at(
                        time_utils.period_index_to_timestamp(period_idx)
                    )
                    if pd_today is not None:
                        soe = pd_today.energy.battery_soe_end
                        today_soc_values.append(
                            (soe / battery_settings.total_capacity * 100.0)
                            if battery_settings.total_capacity > 0
                            else None
                        )
                        today_actions.append(pd_today.decision.battery_action or 0.0)
                        # Reconcile with observed_intent for actual periods so the
                        # label reflects real physical flow, not the stale plan.
                        observed_intent = pd_today.decision.observed_intent
                        today_reconciled_intents.append(
                            observed_intent
                            if pd_today.data_source == "actual" and observed_intent
                            else planned_intent
                        )
                        today_curtailed.append(pd_today.decision.curtailed)
                    else:
                        today_soc_values.append(None)
                        today_actions.append(0.0)
                        today_reconciled_intents.append(planned_intent)
                        today_curtailed.append(False)
            raw_groups = schedule_manager.get_detailed_period_groups(
                intents=today_reconciled_intents,
                actions=today_actions if today_actions else None,
                soc_values=today_soc_values if today_soc_values else None,
                curtailed=today_curtailed if today_curtailed else None,
            )
            prev_soc: float | None = None
            for group in raw_groups:
                soc_end = group["soc_end_pct"]
                soc_delta_kwh: float | None = None
                if (
                    soc_end is not None
                    and prev_soc is not None
                    and battery_settings.total_capacity > 0
                ):
                    soc_delta_kwh = (
                        (soc_end - prev_soc) / 100.0 * battery_settings.total_capacity
                    )
                prev_soc = soc_end
                period_groups.append(
                    {
                        "start_time": group["start_time"],
                        "end_time": group["end_time"],
                        **(
                            {
                                "vpp_power_pct": group["vpp_power_pct"],
                                "vpp_remote_control": group["vpp_remote_control"],
                            }
                            if "vpp_power_pct" in group
                            else (
                                {"batt_mode": group["batt_mode"]}
                                if "batt_mode" in group
                                else {}
                            )
                        ),
                        "dominant_intent": group["intent"],
                        "intent_counts": {group["intent"]: group["period_count"]},
                        "period_count": group["period_count"],
                        "duration_minutes": group["duration_minutes"],
                        "charge_power_rate": group["charge_rate"],
                        "discharge_power_rate": group["discharge_rate"],
                        "grid_charge": group["grid_charge"],
                        "total_action_kwh": group["total_action_kwh"],
                        "soc_end_pct": soc_end,
                        "soc_delta_kwh": soc_delta_kwh,
                        "curtailed": group["curtailed"],
                    }
                )
        except (ValueError, KeyError, AttributeError) as e:
            logger.error(f"Failed to get period groups: {e}")

        # Extract tomorrow's period groups from ScheduleStore (same source as dashboard)
        tomorrow_period_groups: list[dict] | None = None
        try:
            if bess_controller.system.schedule_store.get_latest_schedule():
                today_period_count = get_period_count(time_utils.today())
                tomorrow_period_count = get_period_count(
                    time_utils.today() + timedelta(days=1)
                )
                tomorrow_intents: list[str] = []
                tomorrow_actions: list[float] = []
                tomorrow_soc_values: list[float | None] = []
                tomorrow_curtailed: list[bool] = []
                # Resolved by exact timestamp (not positional index -
                # optimization_period) so a standalone next-day schedule
                # (period_data[0] anchored to tomorrow 00:00 despite
                # optimization_period=0) is read correctly without needing
                # to special-case its anchor.
                for period_idx in range(
                    today_period_count,
                    today_period_count + tomorrow_period_count,
                ):
                    pd = bess_controller.system.schedule_store.get_period_data_at(
                        time_utils.period_index_to_timestamp(period_idx)
                    )
                    if pd is not None:
                        tomorrow_intents.append(pd.decision.strategic_intent)
                        tomorrow_actions.append(pd.decision.battery_action or 0.0)
                        soe = pd.energy.battery_soe_end
                        tomorrow_soc_values.append(
                            (soe / battery_settings.total_capacity * 100.0)
                            if battery_settings.total_capacity > 0
                            else None
                        )
                        tomorrow_curtailed.append(pd.decision.curtailed)
                    else:
                        tomorrow_soc_values.append(None)
                        tomorrow_curtailed.append(False)
                if tomorrow_intents:
                    raw_tomorrow_groups = schedule_manager.get_detailed_period_groups(
                        intents=tomorrow_intents,
                        actions=tomorrow_actions,
                        soc_values=tomorrow_soc_values,
                        curtailed=tomorrow_curtailed,
                    )
                    tomorrow_period_groups = []
                    prev_soc_tmr: float | None = None
                    for group in raw_tomorrow_groups:
                        soc_end = group["soc_end_pct"]
                        soc_delta_kwh_tmr: float | None = None
                        if (
                            soc_end is not None
                            and prev_soc_tmr is not None
                            and battery_settings.total_capacity > 0
                        ):
                            soc_delta_kwh_tmr = (
                                (soc_end - prev_soc_tmr)
                                / 100.0
                                * battery_settings.total_capacity
                            )
                        prev_soc_tmr = soc_end
                        tomorrow_period_groups.append(
                            {
                                "start_time": group["start_time"],
                                "end_time": group["end_time"],
                                **(
                                    {
                                        "vpp_power_pct": group["vpp_power_pct"],
                                        "vpp_remote_control": group[
                                            "vpp_remote_control"
                                        ],
                                    }
                                    if "vpp_power_pct" in group
                                    else (
                                        {"batt_mode": group["batt_mode"]}
                                        if "batt_mode" in group
                                        else {}
                                    )
                                ),
                                "dominant_intent": group["intent"],
                                "intent_counts": {
                                    group["intent"]: group["period_count"]
                                },
                                "period_count": group["period_count"],
                                "duration_minutes": group["duration_minutes"],
                                "charge_power_rate": group["charge_rate"],
                                "discharge_power_rate": group["discharge_rate"],
                                "grid_charge": group["grid_charge"],
                                "total_action_kwh": group["total_action_kwh"],
                                "soc_end_pct": soc_end,
                                "soc_delta_kwh": soc_delta_kwh_tmr,
                                "curtailed": group["curtailed"],
                            }
                        )
        except (AttributeError, KeyError, ValueError) as e:
            logger.warning(f"Failed to get tomorrow's period groups: {e}")
            tomorrow_period_groups = None

        inverter_platform = bess_controller.system.inverter_platform

        response = {
            "current_hour": current_hour,
            "inverter_platform": inverter_platform,
            "control_model": control_model,
            "tou_intervals": tou_intervals,
            "schedule_data": schedule_data,
            "period_groups": period_groups,
            "tomorrow_period_groups": tomorrow_period_groups,
            "mode_distribution": mode_distribution,
            "intent_distribution": intent_distribution,
            "hour_distribution": {
                "charge": charge_hours,
                "discharge": discharge_hours,
                "idle": idle_hours,
            },
            "strategic_intent_summary": strategic_summary,
        }

        return convert_keys_to_camel_case(response)

    except Exception as e:
        logger.error(f"Error in get_growatt_detailed_schedule: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/growatt/tou_settings")
async def get_tou_settings():
    """Get current TOU (Time of Use) settings with strategic intent information."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    logger.info("/api/growatt/tou_settings")

    try:
        # Safety checks
        if bess_controller.system is None:
            logger.error("Battery system not initialized")
            raise HTTPException(
                status_code=503, detail="Battery system not initialized"
            )

        if bess_controller.system._inverter_controller is None:
            logger.error("Schedule manager not initialized")
            raise HTTPException(
                status_code=503, detail="Schedule manager not initialized"
            )

        schedule_manager = bess_controller.system._inverter_controller
        tou_intervals = schedule_manager.get_all_tou_segments()
        current_hour = time_utils.now().hour

        # Enhanced TOU intervals with hourly settings and strategic intents
        enhanced_tou_intervals = []
        for interval in tou_intervals:
            enhanced_interval = interval.copy()
            start_hour = int(interval["start_time"].split(":")[0])
            try:
                settings = _get_hourly_settings_from_periods(
                    schedule_manager, start_hour
                )
                enhanced_interval["grid_charge"] = settings.get("grid_charge", False)
                enhanced_interval["discharge_rate"] = settings.get(
                    "discharge_rate", 100
                )
                enhanced_interval["strategic_intent"] = settings.get(
                    "strategic_intent", "IDLE"
                )
            except Exception as e:
                logger.error(
                    f"Error getting hourly settings for hour {start_hour}: {e}"
                )
                enhanced_interval["grid_charge"] = False
                enhanced_interval["discharge_rate"] = 100
                enhanced_interval["strategic_intent"] = "IDLE"

            # Calculate interval hours to help frontend
            start_hour = int(interval["start_time"].split(":")[0])
            end_hour = int(interval["end_time"].split(":")[0])
            if end_hour < start_hour:  # Handle overnight intervals
                end_hour += 24
            enhanced_interval["hours"] = end_hour - start_hour + 1
            enhanced_interval["is_active"] = (
                start_hour <= current_hour % 24 <= end_hour % 24 and interval["enabled"]
            )

            enhanced_tou_intervals.append(enhanced_interval)

        return convert_keys_to_camel_case({"tou_settings": enhanced_tou_intervals})

    except Exception as e:
        logger.error(f"Error getting TOU settings: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/growatt/strategic_intents")
async def get_strategic_intents():
    """Get strategic intent information for the current schedule."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        # Safety checks
        if bess_controller.system is None:
            logger.error("Battery system not initialized")
            raise HTTPException(
                status_code=503, detail="Battery system not initialized"
            )

        if bess_controller.system._inverter_controller is None:
            logger.error("Schedule manager not initialized")
            raise HTTPException(
                status_code=503, detail="Schedule manager not initialized"
            )

        schedule_manager = bess_controller.system._inverter_controller

        # Get strategic intent summary
        strategic_summary = schedule_manager.get_strategic_intent_summary()

        # Get hourly strategic intents
        hourly_intents = []
        for hour in range(24):
            try:
                settings = _get_hourly_settings_from_periods(schedule_manager, hour)
                intent = settings.get("strategic_intent", "IDLE")
                description = schedule_manager._get_intent_description(intent)

                hourly_intents.append(
                    {
                        "hour": hour,
                        "intent": intent,
                        "description": description,
                        "battery_action": 0.0,
                        "grid_charge": settings.get("grid_charge", False),
                        "discharge_rate": settings.get("discharge_rate", 100),
                        "is_current": hour == time_utils.now().hour,
                    }
                )
            except Exception as e:
                logger.error(f"Error getting hourly settings for hour {hour}: {e}")
                raise ValueError(
                    f"Hourly settings data is required for hour {hour} but failed to load: {e}"
                ) from e

        response = {
            "summary": strategic_summary,
            "hourly_intents": hourly_intents,
        }

        return convert_keys_to_camel_case(response)

    except Exception as e:
        logger.error(f"Error getting strategic intents: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/system-health")
async def get_system_health():
    """Get comprehensive system health including detailed sensor diagnostics."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        logger.debug("Starting system health check")

        # Run actual health checks
        health_results = run_system_health_checks(bess_controller.system)

        logger.debug(f"Health check completed: {health_results}")
        return convert_keys_to_camel_case(health_results)
    except Exception as e:
        logger.error(f"Error getting system health: {e}")
        # Return error state that frontend can handle

        error_result = {
            "timestamp": datetime.now().isoformat(),
            "system_mode": "unknown",
            "checks": [],
            "summary": {
                "total_components": 0,
                "ok_components": 0,
                "warning_components": 0,
                "error_components": 1,
                "overall_status": "ERROR",
            },
        }
        return convert_keys_to_camel_case(error_result)


@router.post("/api/system-health/recheck")
async def recheck_system_health():
    """Manually re-run health checks and refresh the cached dashboard banner state.

    Unlike GET /api/system-health (which runs a fresh check but doesn't touch
    the cache), this updates ``_cached_health_results``/``_critical_sensor_failures``
    so the dashboard banner immediately reflects the result — for a "Recheck now"
    button after the user fixes a sensor in Home Assistant.
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        health_results = bess_controller.system.refresh_health_check()
        return convert_keys_to_camel_case(health_results)
    except Exception as e:
        logger.error(f"Error refreshing system health: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/dashboard-health-summary")
async def get_dashboard_health_summary():
    """Get lightweight health summary for dashboard alert banner - only critical issues."""
    from app import bess_controller

    # During background startup, return a clean summary — health checks
    # haven't run yet so there's nothing meaningful to report.  This check
    # must come before _require_configured_system which would 503 during startup.
    if bess_controller.system.is_configured and not bess_controller.startup_complete:
        return convert_keys_to_camel_case(
            {
                "has_critical_errors": False,
                "has_warnings": False,
                "critical_issues": [],
                "total_critical_issues": 0,
                "timestamp": datetime.now().isoformat(),
                "system_mode": "initializing",
            }
        )

    _require_configured_system(bess_controller)

    try:
        logger.debug("Starting dashboard health summary check")

        # Check if system is in degraded mode first
        if bess_controller.system.has_critical_sensor_failures():
            # System is in degraded mode due to critical sensor failures
            critical_failures = bess_controller.system.get_critical_sensor_failures()
            cached_results = bess_controller.system.get_cached_health_results() or {}
            components_by_name = {
                component.get("name"): component
                for component in cached_results.get("checks", [])
            }
            critical_issues = []
            for failure in critical_failures:
                component = components_by_name.get(failure, {})
                critical_issues.append(
                    {
                        "component": failure,
                        "description": "Critical sensor configuration issue detected",
                        "detail": describe_failing_checks(component),
                        "status": "ERROR",
                    }
                )

            summary = {
                "has_critical_errors": True,
                "has_warnings": False,
                "critical_issues": critical_issues,
                "total_critical_issues": len(critical_issues),
                "timestamp": datetime.now().isoformat(),
                "system_mode": "degraded",
            }
        else:
            # System is healthy, use cached health check from startup (fast!)
            health_results = bess_controller.system.get_cached_health_results()

            # If no cached results (shouldn't happen), return minimal response
            if not health_results:
                logger.warning(
                    "No cached health results available, returning minimal response"
                )
                summary = {
                    "has_critical_errors": False,
                    "has_warnings": False,
                    "critical_issues": [],
                    "total_critical_issues": 0,
                    "timestamp": datetime.now().isoformat(),
                    "system_mode": (
                        "demo" if bess_controller.ha_controller.test_mode else "unknown"
                    ),
                }
                return convert_keys_to_camel_case(summary)

            # Extract critical and warning information
            critical_issues = []
            has_critical_error = False

            for component in health_results.get("checks", []):
                status = component.get("status", "UNKNOWN")
                is_required = component.get("required", False)

                # Show required components with ERROR status as critical
                if is_required and status == "ERROR":
                    has_critical_error = True
                    critical_issues.append(
                        {
                            "component": component.get("name", "Unknown"),
                            "description": component.get("description", ""),
                            "detail": describe_failing_checks(component),
                            "status": status,
                        }
                    )
                # Show all components (required or not) with WARNING or ERROR status
                elif status in ["WARNING", "ERROR"]:
                    critical_issues.append(
                        {
                            "component": component.get("name", "Unknown"),
                            "description": component.get("description", ""),
                            "detail": describe_failing_checks(component),
                            "status": status,
                        }
                    )

            has_warnings = any(
                issue["status"] == "WARNING" for issue in critical_issues
            )
            summary = {
                "has_critical_errors": has_critical_error,
                "has_warnings": has_warnings,
                "critical_issues": critical_issues,
                "total_critical_issues": len(critical_issues),
                "timestamp": datetime.now().isoformat(),
                "system_mode": health_results.get("system_mode", "normal"),
            }

        logger.debug(f"Dashboard health summary: {summary}")
        return convert_keys_to_camel_case(summary)

    except Exception as e:
        logger.error(f"Error getting dashboard health summary: {e}")
        # Return safe error state
        error_summary = {
            "has_critical_errors": True,
            "has_warnings": False,
            "critical_issues": [
                {
                    "component": "System Health Check",
                    "description": "Unable to perform health check",
                    "status": "ERROR",
                }
            ],
            "total_critical_issues": 1,
            "timestamp": datetime.now().isoformat(),
            "system_mode": "unknown",
        }
        return convert_keys_to_camel_case(error_summary)


def _get_missing_historical_hours(bess_controller) -> list[int]:
    """Compute today's missing historical-data hours up to the current hour."""
    periods = bess_controller.system.historical_store.get_today_periods()
    current_hour = time_utils.now().hour
    current_period = current_hour * 4
    missing_periods = [i for i in range(current_period) if periods[i] is None]
    return list({p // 4 for p in missing_periods})


@router.get("/api/historical-data-status")
async def get_historical_data_status():
    """Check if historical data is incomplete and needs attention.

    Returns information about missing historical data that may affect
    dashboard accuracy and optimization quality.
    """
    from app import bess_controller

    # During background startup, historical data hasn't been fetched yet.
    if bess_controller.system.is_configured and not bess_controller.startup_complete:
        return convert_keys_to_camel_case(
            {
                "is_incomplete": False,
                "missing_hours": [],
                "completed_hours": [],
                "total_missing": 0,
                "total_completed": 0,
                "message": "System is starting up.",
                "timestamp": datetime.now().isoformat(),
                "dismissed": False,
            }
        )

    _require_configured_system(bess_controller)

    try:
        # Get today's periods (quarterly resolution)
        periods = bess_controller.system.historical_store.get_today_periods()
        current_hour = time_utils.now().hour

        # Find missing periods up to current hour (periods = hour * 4)
        current_period = current_hour * 4
        missing_periods = [i for i in range(current_period) if periods[i] is None]
        completed_periods = [i for i in range(current_period) if periods[i] is not None]

        # Convert to hours for reporting (backwards compatibility)
        missing_hours = list({p // 4 for p in missing_periods})
        completed_hours = list({p // 4 for p in completed_periods})

        is_incomplete = len(missing_periods) > 0
        dismissed = (
            is_incomplete
            and bess_controller.system.is_historical_data_warning_dismissed(
                missing_hours
            )
        )

        status = {
            "is_incomplete": is_incomplete,
            "missing_hours": missing_hours,
            "completed_hours": completed_hours,
            "total_missing": len(missing_hours),
            "total_completed": len(completed_hours),
            "message": (
                f"Missing historical data for {len(missing_hours)} hours. "
                f"Dashboard values may be inaccurate until data collection is complete."
                if is_incomplete
                else "Historical data is complete for today."
            ),
            "timestamp": datetime.now().isoformat(),
            "dismissed": dismissed,
        }

        return convert_keys_to_camel_case(status)

    except Exception as e:
        logger.error(f"Error checking historical data status: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.post("/api/historical-data-status/dismiss")
async def dismiss_historical_data_warning():
    """Dismiss today's historical-data-incomplete warning.

    The dismissal is keyed to today's date and the exact set of missing
    hours, so a new gap (or the same gap recurring on a later day) still
    surfaces the banner.
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        missing_hours = _get_missing_historical_hours(bess_controller)
        bess_controller.system.dismiss_historical_data_warning(missing_hours)
        return {"success": True}
    except Exception as e:
        logger.error(f"Error dismissing historical data warning: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/prediction-analysis/snapshots")
async def get_prediction_snapshots():
    """Get all prediction snapshots for today."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        snapshots = (
            bess_controller.system.prediction_snapshot_store.get_all_snapshots_today()
        )

        # Get currency from home settings
        currency = bess_controller.system.home_settings.currency

        # Convert to API format
        api_snapshots = [
            APIPredictionSnapshot.from_internal(snapshot, currency)
            for snapshot in snapshots
        ]

        response = {
            "snapshots": [s.__dict__ for s in api_snapshots],
            "count": len(api_snapshots),
        }

        return convert_keys_to_camel_case(response)

    except Exception as e:
        logger.error(f"Error fetching prediction snapshots: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/prediction-analysis/timeline")
async def get_prediction_timeline():
    """Get timeline showing how predicted savings evolved throughout the day."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        snapshots = (
            bess_controller.system.prediction_snapshot_store.get_all_snapshots_today()
        )

        # Build timeline data
        timeline_data = {
            "timestamps": [s.snapshot_timestamp.isoformat() for s in snapshots],
            "optimization_periods": [s.optimization_period for s in snapshots],
            "predicted_savings": [s.predicted_daily_savings for s in snapshots],
            "growatt_schedule_counts": [len(s.growatt_schedule) for s in snapshots],
        }

        return convert_keys_to_camel_case(timeline_data)

    except Exception as e:
        logger.error(f"Error building prediction timeline: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/savings/aggregate")
async def get_savings_aggregate(
    period: str = Query(..., pattern="^(day|week|month|year)$"),
    count: int | None = Query(None, ge=1, le=520),  # 520 weeks is roughly 10 years
    date: str | None = Query(
        None, description="ISO date (YYYY-MM-DD) to anchor the buckets to; omit for now"
    ),
):
    """Get day/week/month/year savings aggregates, anchored to `date` (or now).

    `day` is today's live (in-progress) view when no snapshot has been
    persisted for it yet and `date` is omitted or equals today; any other
    date (including a historical `day` request) reads the persisted daily
    history only, same as `/api/dashboard`'s historical-day handling.
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        target_date = date_cls.fromisoformat(date) if date else time_utils.today()
    except ValueError as e:
        raise HTTPException(
            status_code=422, detail=f"Invalid date {date!r}: {e}"
        ) from e

    try:
        resolved_count = count or DEFAULT_COUNTS[period]

        today_view = None
        if (
            period == "day"
            and target_date == time_utils.today()
            and target_date.isoformat()
            not in bess_controller.system.daily_view_store.list_available_dates()
        ):
            now = time_utils.now()
            current_period = now.hour * 4 + now.minute // 15
            today_view = bess_controller.system.daily_view_builder.build_daily_view(
                current_period, bess_controller.system.export_curtailment_active
            )

        buckets = build_buckets(
            period,
            resolved_count,
            bess_controller.system.daily_view_store,
            today=target_date,
            today_view=today_view,
        )
        currency = bess_controller.system.home_settings.currency

        api_buckets = [APISavingsBucket.from_internal(b, currency) for b in buckets]

        response = {
            "buckets": [b.__dict__ for b in api_buckets],
            "count": len(api_buckets),
        }

        return convert_keys_to_camel_case(response)

    except Exception as e:
        logger.error(f"Error building savings aggregate: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/savings/history/disk-usage")
async def get_savings_history_disk_usage():
    """Get disk usage of the persisted daily savings history."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        usage = bess_controller.system.daily_view_store.get_disk_usage()
        return convert_keys_to_camel_case(usage)
    except Exception as e:
        logger.error(f"Error getting savings history disk usage: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.delete("/api/savings/history")
async def delete_savings_history():
    """Clear all persisted daily savings history."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        bess_controller.system.daily_view_store.clear_all()
        usage = bess_controller.system.daily_view_store.get_disk_usage()
        return convert_keys_to_camel_case(usage)
    except Exception as e:
        logger.error(f"Error clearing savings history: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/prediction-analysis/comparison")
async def get_prediction_comparison(
    snapshot_period: int = Query(
        ..., ge=0, le=95, description="Period index for snapshot"
    )
):
    """Compare snapshot predictions vs what actually happened."""
    from app import bess_controller

    _require_configured_system(bess_controller)
    from core.bess.prediction_analyzer import PredictionAnalyzer

    try:
        # Get snapshot at specified period
        snapshot = (
            bess_controller.system.prediction_snapshot_store.get_snapshot_at_period(
                snapshot_period
            )
        )

        if not snapshot:
            raise HTTPException(
                status_code=404,
                detail=f"No snapshot found for period {snapshot_period}",
            )

        # Get current state

        now = time_utils.now()
        current_period = now.hour * 4 + now.minute // 15

        # Build current daily view
        current_daily_view = bess_controller.system.daily_view_builder.build_daily_view(
            current_period, bess_controller.system.export_curtailment_active
        )

        # Get current Growatt schedule
        current_growatt_schedule = (
            bess_controller.system._inverter_controller.tou_intervals.copy()
        )

        # Analyze deviations
        analyzer = PredictionAnalyzer()
        comparison = analyzer.compare_snapshot_to_current(
            snapshot=snapshot,
            current_daily_view=current_daily_view,
            current_growatt_schedule=current_growatt_schedule,
        )

        # Get currency from home settings
        currency = bess_controller.system.home_settings.currency

        # Convert to API format
        api_comparison = APISnapshotComparison.from_internal(comparison, currency)

        return convert_keys_to_camel_case(api_comparison.__dict__)

    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error comparing predictions: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/prediction-analysis/snapshot-comparison")
async def compare_two_snapshots(
    period_a: int = Query(..., description="First snapshot period to compare"),
    period_b: int = Query(..., description="Second snapshot period to compare"),
):
    """Compare two prediction snapshots to see how predictions evolved."""
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        # Get both snapshots
        snapshot_a = (
            bess_controller.system.prediction_snapshot_store.get_snapshot_at_period(
                period_a
            )
        )
        snapshot_b = (
            bess_controller.system.prediction_snapshot_store.get_snapshot_at_period(
                period_b
            )
        )

        if not snapshot_a:
            raise HTTPException(
                status_code=404, detail=f"No snapshot found for period {period_a}"
            )
        if not snapshot_b:
            raise HTTPException(
                status_code=404, detail=f"No snapshot found for period {period_b}"
            )

        # Get currency
        currency = bess_controller.system.home_settings.currency

        # Build period maps for defensive lookup (handles edge cases where
        # DailyView might have fewer periods due to HA restart gaps)
        period_map_a = {p.period: p for p in snapshot_a.daily_view.periods}
        period_map_b = {p.period: p for p in snapshot_b.daily_view.periods}

        # Build comprehensive comparison for all 96 periods
        period_comparisons = []
        for period_idx in range(96):
            period_a_data = period_map_a.get(period_idx)
            period_b_data = period_map_b.get(period_idx)

            # Skip periods missing from either snapshot
            if period_a_data is None or period_b_data is None:
                logger.warning(
                    f"Skipping period {period_idx} in snapshot comparison - "
                    f"missing from {'A' if period_a_data is None else 'B'}"
                )
                continue

            # Calculate battery action (net charging/discharging)
            battery_action_a = (
                period_a_data.energy.battery_charged
                - period_a_data.energy.battery_discharged
            )
            battery_action_b = (
                period_b_data.energy.battery_charged
                - period_b_data.energy.battery_discharged
            )

            # Build comparison for this period
            comparison = {
                "period": period_idx,
                # Snapshot A data
                "snapshotA": {
                    "solar": create_formatted_value(
                        period_a_data.energy.solar_production,
                        "energy_kwh_only",
                        currency,
                    ),
                    "consumption": create_formatted_value(
                        period_a_data.energy.home_consumption,
                        "energy_kwh_only",
                        currency,
                    ),
                    "batteryAction": create_formatted_value(
                        battery_action_a, "energy_kwh_only", currency
                    ),
                    "batterySoe": create_formatted_value(
                        period_a_data.energy.battery_soe_end,
                        "energy_kwh_only",
                        currency,
                    ),
                    "gridImport": create_formatted_value(
                        period_a_data.energy.grid_imported, "energy_kwh_only", currency
                    ),
                    "gridExport": create_formatted_value(
                        period_a_data.energy.grid_exported, "energy_kwh_only", currency
                    ),
                    "cost": create_formatted_value(
                        period_a_data.economic.hourly_cost, "currency", currency
                    ),
                    "gridOnlyCost": create_formatted_value(
                        period_a_data.economic.grid_only_cost, "currency", currency
                    ),
                    "savings": create_formatted_value(
                        period_a_data.economic.hourly_savings, "currency", currency
                    ),
                    "dataSource": period_a_data.data_source,
                },
                # Snapshot B data
                "snapshotB": {
                    "solar": create_formatted_value(
                        period_b_data.energy.solar_production,
                        "energy_kwh_only",
                        currency,
                    ),
                    "consumption": create_formatted_value(
                        period_b_data.energy.home_consumption,
                        "energy_kwh_only",
                        currency,
                    ),
                    "batteryAction": create_formatted_value(
                        battery_action_b, "energy_kwh_only", currency
                    ),
                    "batterySoe": create_formatted_value(
                        period_b_data.energy.battery_soe_end,
                        "energy_kwh_only",
                        currency,
                    ),
                    "gridImport": create_formatted_value(
                        period_b_data.energy.grid_imported, "energy_kwh_only", currency
                    ),
                    "gridExport": create_formatted_value(
                        period_b_data.energy.grid_exported, "energy_kwh_only", currency
                    ),
                    "cost": create_formatted_value(
                        period_b_data.economic.hourly_cost, "currency", currency
                    ),
                    "gridOnlyCost": create_formatted_value(
                        period_b_data.economic.grid_only_cost, "currency", currency
                    ),
                    "savings": create_formatted_value(
                        period_b_data.economic.hourly_savings, "currency", currency
                    ),
                    "dataSource": period_b_data.data_source,
                },
                # Differences (B - A)
                "delta": {
                    "solar": create_formatted_value(
                        period_b_data.energy.solar_production
                        - period_a_data.energy.solar_production,
                        "energy_kwh_only",
                        currency,
                    ),
                    "consumption": create_formatted_value(
                        period_b_data.energy.home_consumption
                        - period_a_data.energy.home_consumption,
                        "energy_kwh_only",
                        currency,
                    ),
                    "batteryAction": create_formatted_value(
                        battery_action_b - battery_action_a, "energy_kwh_only", currency
                    ),
                    "batterySoe": create_formatted_value(
                        period_b_data.energy.battery_soe_end
                        - period_a_data.energy.battery_soe_end,
                        "energy_kwh_only",
                        currency,
                    ),
                    "gridImport": create_formatted_value(
                        period_b_data.energy.grid_imported
                        - period_a_data.energy.grid_imported,
                        "energy_kwh_only",
                        currency,
                    ),
                    "gridExport": create_formatted_value(
                        period_b_data.energy.grid_exported
                        - period_a_data.energy.grid_exported,
                        "energy_kwh_only",
                        currency,
                    ),
                    "cost": create_formatted_value(
                        period_b_data.economic.hourly_cost
                        - period_a_data.economic.hourly_cost,
                        "currency",
                        currency,
                    ),
                    "gridOnlyCost": create_formatted_value(
                        period_b_data.economic.grid_only_cost
                        - period_a_data.economic.grid_only_cost,
                        "currency",
                        currency,
                    ),
                    "savings": create_formatted_value(
                        period_b_data.economic.hourly_savings
                        - period_a_data.economic.hourly_savings,
                        "currency",
                        currency,
                    ),
                },
            }
            period_comparisons.append(comparison)

        def _interval_display_fields(interval: dict) -> dict:
            if "vpp_power_pct" in interval:
                return {
                    "vpp_power_pct": interval["vpp_power_pct"],
                    "vpp_remote_control": interval["vpp_remote_control"],
                }
            if "batt_mode" in interval:
                return {"batt_mode": interval["batt_mode"]}
            return {}

        # Build response
        response = {
            "snapshotAPeriod": period_a,
            "snapshotATimestamp": snapshot_a.snapshot_timestamp.isoformat(),
            "snapshotBPeriod": period_b,
            "snapshotBTimestamp": snapshot_b.snapshot_timestamp.isoformat(),
            "periodComparisons": period_comparisons,
            "growattScheduleA": [
                {
                    "segmentId": i + 1,
                    **_interval_display_fields(interval),
                    "startTime": interval["start_time"],
                    "endTime": interval["end_time"],
                    "enabled": interval.get("enabled", True),
                }
                for i, interval in enumerate(snapshot_a.growatt_schedule)
            ],
            "growattScheduleB": [
                {
                    "segmentId": i + 1,
                    **_interval_display_fields(interval),
                    "startTime": interval["start_time"],
                    "endTime": interval["end_time"],
                    "enabled": interval.get("enabled", True),
                }
                for i, interval in enumerate(snapshot_b.growatt_schedule)
            ],
        }

        return convert_keys_to_camel_case(response)

    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error comparing snapshots: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/consumption-forecast-comparison")
async def get_consumption_forecast_comparison():
    """Compare ALL consumption forecast strategies against actual consumption.

    Returns each strategy's hourly profile, actual consumption, and accuracy
    metrics (MAE) so the frontend can visualise which strategy performs best.
    """
    from app import bess_controller

    try:
        comparison = bess_controller.system.get_consumption_forecast_comparison()
        currency = bess_controller.system.home_settings.currency
        actual_hourly = comparison["actual_hourly"]

        strategies_response = []
        for strat in comparison["strategies"]:
            forecast = strat["forecast"]
            hourly_profile: list[FormattedValue] = []
            if forecast:
                for hour in range(24):
                    base = hour * 4
                    hourly_kwh = sum(forecast[base : base + 4])
                    hourly_profile.append(
                        create_formatted_value(hourly_kwh, "energy_kwh_only", currency)
                    )

            # Compute MAE against actual for hours with data
            mae = None
            if forecast and comparison["actual_hours_available"] > 0:
                errors = []
                for hour in range(24):
                    actual = actual_hourly[hour]
                    if actual is not None:
                        base = hour * 4
                        predicted = sum(forecast[base : base + 4])
                        errors.append(abs(predicted - actual))
                if errors:
                    mae = sum(errors) / len(errors)

            strategies_response.append(
                APIStrategyForecast(
                    name=strat["name"],
                    isActive=strat["is_active"],
                    available=strat["available"],
                    error=strat["error"],
                    totalKwh=(
                        create_formatted_value(
                            strat["total_kwh"], "energy_kwh_only", currency
                        )
                        if strat["total_kwh"] is not None
                        else None
                    ),
                    hourlyProfile=hourly_profile,
                    mae=(
                        create_formatted_value(mae, "energy_kwh_only", currency)
                        if mae is not None
                        else None
                    ),
                )
            )

        # Build actual hourly profile for frontend chart
        actual_profile: list[FormattedValue | None] = []
        for hour in range(24):
            val = actual_hourly[hour]
            if val is not None:
                actual_profile.append(
                    create_formatted_value(val, "energy_kwh_only", currency)
                )
            else:
                actual_profile.append(None)

        response = APIConsumptionForecastComparison(
            activeStrategy=comparison["active_strategy"],
            strategies=strategies_response,
            actualHourlyProfile=actual_profile,
            actualHoursAvailable=comparison["actual_hours_available"],
        )

        return convert_keys_to_camel_case(dataclasses.asdict(response))

    except Exception as e:
        logger.error(f"Error fetching consumption forecast comparison: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/export-debug-data")
async def export_debug_data(compact: bool = True):
    """Export comprehensive debug data as markdown report.

    Returns a markdown file containing all system state, logs, historical data,
    predictions, schedules, and settings for debugging purposes.

    Args:
        compact: If True (default), serves all three debug use cases —
            scenario replay, AI behaviour analysis, and prediction drift analysis.
            Logs are filtered to key events + last 50 lines (not the full log).
            Snapshots are rendered as a 5-field evolution table (not full JSON).
            Set to False only when a raw field not present in compact mode is needed
            (full log, all schedules, all snapshots as JSON). Expect 30-80 MB.

    Security:
    - Via HA ingress (browser): HA handles authentication
    - Via direct port 8080 (local network): Network access is the auth

    Returns:
        PlainTextResponse: Markdown file with complete debug data
    """
    from fastapi.responses import PlainTextResponse

    from app import bess_controller
    from core.bess.debug_data_exporter import DebugDataAggregator
    from core.bess.debug_report_formatter import DebugReportFormatter

    try:
        # Aggregate all system data
        aggregator = DebugDataAggregator(
            bess_controller.system,
            settings_data=bess_controller.settings_store.data,
        )
        export_data = aggregator.aggregate_all_data(compact=compact)

        # Format as markdown report
        formatter = DebugReportFormatter()
        markdown_content = formatter.format_report(export_data)

        # Generate filename with timestamp
        timestamp = datetime.now().strftime("%Y-%m-%d-%H%M%S")
        filename = f"bess-debug-{timestamp}.md"

        return PlainTextResponse(
            content=markdown_content,
            media_type="text/markdown",
            headers={"Content-Disposition": f"attachment; filename={filename}"},
        )
    except Exception as e:
        logger.error(f"Error exporting debug data: {e}", exc_info=True)

        # Return minimal error report as markdown
        timestamp = datetime.now().isoformat()
        error_report = f"""# BESS Manager Debug Export (ERROR)

**Export Date**: {timestamp}

## Error During Export

Failed to generate debug export:

```
{e!s}
```

Please check the BESS Manager logs for details.
"""

        filename = f"bess-debug-error-{datetime.now().strftime('%Y-%m-%d-%H%M%S')}.md"
        return PlainTextResponse(
            content=error_report,
            media_type="text/markdown",
            headers={"Content-Disposition": f"attachment; filename={filename}"},
        )


@router.get("/api/runtime-failures")
async def get_runtime_failures():
    """Get all active runtime failures.

    Returns a list of runtime failures that have occurred during system operation.
    Failures are tracked when API calls to Home Assistant fail after all retry attempts.

    Returns:
        list[dict]: List of active runtime failures with details
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        failures = bess_controller.system.get_runtime_failures()
        # Convert to dict format for API response
        return [failure.__dict__ for failure in failures]
    except Exception as e:
        logger.error(f"Error getting runtime failures: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.post("/api/runtime-failures/{failure_id}/dismiss")
async def dismiss_runtime_failure(failure_id: str):
    """Dismiss a specific runtime failure.

    Marks the failure as acknowledged, removing it from the active failures list.
    The failure will no longer appear in the UI.

    Args:
        failure_id: Unique identifier of the failure to dismiss

    Returns:
        dict: Success confirmation
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        bess_controller.system.dismiss_runtime_failure(failure_id)
        return {"success": True, "message": f"Failure {failure_id} dismissed"}
    except ValueError:
        raise HTTPException(
            status_code=404, detail=f"Failure with id {failure_id} not found"
        ) from None
    except Exception as e:
        logger.error(f"Error dismissing runtime failure {failure_id}: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.post("/api/runtime-failures/dismiss-all")
async def dismiss_all_runtime_failures():
    """Dismiss all active runtime failures.

    Marks all failures as acknowledged, clearing the active failures list.
    No failures will appear in the UI until new failures occur.

    Returns:
        dict: Success confirmation with count of dismissed failures
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        count = bess_controller.system.dismiss_all_runtime_failures()
        return {"success": True, "message": f"Dismissed {count} runtime failures"}
    except Exception as e:
        logger.error(f"Error dismissing all runtime failures: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.get("/api/health-recoveries")
async def get_health_recoveries():
    """Get pending health-check recoveries (components that self-resolved).

    A component that goes ERROR/WARNING -> OK between health checks is
    recorded here, so an intermittent sensor issue is not silently lost if
    nobody was watching the live status banner when it recovered.

    Returns:
        list[dict]: Pending recoveries, newest first
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        recoveries = bess_controller.system.get_health_recoveries()
        return convert_keys_to_camel_case([dataclasses.asdict(r) for r in recoveries])
    except Exception as e:
        logger.error(f"Error getting health recoveries: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.post("/api/health-recoveries/acknowledge")
async def acknowledge_health_recoveries():
    """Acknowledge (clear) all pending health-check recoveries.

    Returns:
        dict: Success confirmation with count of recoveries acknowledged
    """
    from app import bess_controller

    _require_configured_system(bess_controller)

    try:
        count = bess_controller.system.acknowledge_health_recoveries()
        return {"success": True, "message": f"Acknowledged {count} health recoveries"}
    except Exception as e:
        logger.error(f"Error acknowledging health recoveries: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


# ---------------------------------------------------------------------------
# AI Analyst chat endpoints
# ---------------------------------------------------------------------------


def _get_ai_service():
    """Lazy-initialise and return the shared AIAnalystService."""
    from app import bess_controller

    if not hasattr(bess_controller, "_ai_analyst_service"):
        from ai_chat import AIAnalystService

        bess_controller._ai_analyst_service = AIAnalystService(
            bess_controller.settings_store
        )
    return bess_controller._ai_analyst_service, bess_controller


@router.get("/api/ai/chat/status")
async def ai_chat_status():
    """Check whether the AI analyst is configured and enabled."""
    service, _ = _get_ai_service()
    return service.get_status()


@router.post("/api/ai/chat/start")
async def ai_chat_start():
    """Start a new AI chat session with fresh system context."""
    service, ctrl = _get_ai_service()

    status = service.get_status()
    if not status["configured"]:
        raise HTTPException(
            status_code=400,
            detail="AI Analyst not configured. Add an API key in Settings.",
        )

    result = service.start_session(ctrl.system)
    return result


@router.post("/api/ai/chat/stream")
async def ai_chat_stream(body: dict):
    """Stream an AI response as Server-Sent Events.

    Body:
        sessionId: Active session UUID.
        message: The user's question.

    Returns:
        StreamingResponse with text/event-stream media type.
    """
    from fastapi.responses import StreamingResponse

    service, _ = _get_ai_service()
    session_id = body.get("sessionId", "")
    message = body.get("message", "").strip()

    if not session_id or not message:
        raise HTTPException(
            status_code=400, detail="sessionId and message are required"
        )

    return StreamingResponse(
        service.stream_response(session_id, message),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",
        },
    )


@router.post("/api/ai/chat/refresh")
async def ai_chat_refresh(body: dict):
    """Refresh the system context for an existing chat session."""
    service, ctrl = _get_ai_service()
    session_id = body.get("sessionId", "")

    if not session_id:
        raise HTTPException(status_code=400, detail="sessionId is required")

    try:
        return service.refresh_context(session_id, ctrl.system)
    except KeyError as err:
        raise HTTPException(
            status_code=404, detail="Session not found or expired"
        ) from err


@router.get("/api/setup/status")
async def get_setup_status():
    """Return whether the setup wizard is needed.

    A wizard is needed when no sensor entity IDs are configured. Existing users
    with a full sensor configuration are unaffected and will receive wizard_needed=false.

    Returns:
        dict: wizard_needed, configured_sensors count, total_sensors count
    """
    from app import bess_controller

    sensors = bess_controller.settings_store.get_active_sensors()
    total = len(sensors)
    configured = sum(1 for v in sensors.values() if v)
    system_configured = bess_controller.system.is_configured
    return convert_keys_to_camel_case(
        {
            "wizard_needed": configured == 0 or not system_configured,
            "configured_sensors": configured,
            "total_sensors": total,
            "system_configured": system_configured,
        }
    )


_PROVIDER_PRICING_DEFAULTS: dict[str, dict] = {
    "nordpool_official": {
        "spotMultiplier": 1.0,
        "exportSpotMultiplier": 1.0,
    },
    "nordpool_hacs": {
        "spotMultiplier": 1.0,
        "exportSpotMultiplier": 1.0,
    },
    "entsoe": {
        "spotMultiplier": 1.0175,
        "exportSpotMultiplier": 1.018,
    },
    "octopus": {
        "spotMultiplier": 1.0,
        "exportSpotMultiplier": 1.0,
    },
}


def _pricing_defaults_for_discovery(integrations: dict) -> dict:
    """Return suggested spot-multiplier defaults matching the auto-detected provider."""
    if integrations.get("octopus_found") and not integrations.get("nordpool_found"):
        return _PROVIDER_PRICING_DEFAULTS["octopus"]
    if integrations.get("entsoe_found") and not integrations.get("nordpool_found"):
        return _PROVIDER_PRICING_DEFAULTS["entsoe"]
    if integrations.get("nordpool_config_entry_id"):
        return _PROVIDER_PRICING_DEFAULTS["nordpool_official"]
    if integrations.get("nordpool_custom_area"):
        return _PROVIDER_PRICING_DEFAULTS["nordpool_hacs"]
    return _PROVIDER_PRICING_DEFAULTS["nordpool_official"]


@router.post("/api/setup/discover")
async def run_setup_discovery():
    """Run auto-discovery of inverter and pricing integrations.

    Inverter platforms are detected from the HA entity registry alone —
    the ``platform`` field to identify the integration, then ``unique_id``
    suffixes to map its entities onto BESS sensor keys.  Neither changes
    when a user renames an entity, so there is no entity_id pattern
    matching in this path.

    ``/api/states`` is still read, but only for things the registry does
    not carry: the HACS Nordpool area, Octopus/ENTSO-e price entities, and
    phase-current sensors.

    Returns:
        dict: Discovery results including found sensors, missing sensors, and
              integration metadata (nordpool_area)
    """
    from app import bess_controller

    try:
        ha = bess_controller.ha_controller

        integrations, states = ha.discover_integrations()
        logger.info(
            "Setup discover: nordpool_area=%s, nordpool_custom_area=%s, "
            "nordpool_config_entry_id=%s, currency=%s, vat_multiplier=%s",
            integrations.get("nordpool_area"),
            integrations.get("nordpool_custom_area"),
            integrations.get("nordpool_config_entry_id"),
            integrations.get("currency"),
            integrations.get("vat_multiplier"),
        )

        # Persist locale-appropriate defaults when discovery detects a
        # non-Swedish locale.  Bootstrap defaults hardcode SEK/SE4/1.25 which
        # are wrong for e.g. UK Octopus users.  Overwrite the pricing fields
        # now so the store has correct values even if the wizard never
        # completes.  (#113)
        detected_currency = integrations.get("currency")
        detected_vat = integrations.get("vat_multiplier")
        if detected_currency or detected_vat is not None:
            from core.bess.settings import CYCLE_COST_BY_CURRENCY

            home = bess_controller.settings_store.get_section("home")
            elec = bess_controller.settings_store.get_section("electricity_price")
            battery = bess_controller.settings_store.get_section("battery")
            changed = False
            battery_changed = False
            if detected_currency and home.get("currency") != detected_currency:
                home["currency"] = detected_currency
                changed = True
                cycle_cost = CYCLE_COST_BY_CURRENCY.get(detected_currency)
                if cycle_cost is not None:
                    battery["cycle_cost_per_kwh"] = cycle_cost
                    battery_changed = True
            if detected_vat is not None and elec.get("vat_multiplier") != detected_vat:
                elec["vat_multiplier"] = detected_vat
                changed = True
            # For Octopus-only users, clear Swedish-specific cost fields
            if integrations.get("octopus_found") and not integrations.get(
                "nordpool_found"
            ):
                if elec.get("additional_costs", 0) != 0:
                    elec["additional_costs"] = 0.0
                    changed = True
                if elec.get("tax_reduction", 0) != 0:
                    elec["tax_reduction"] = 0.0
                    changed = True
                ep = bess_controller.settings_store.get_section("energy_provider")
                if ep.get("provider") != "octopus":
                    ep["provider"] = "octopus"
                    bess_controller.settings_store.save_section("energy_provider", ep)
            if battery_changed:
                bess_controller.settings_store.save_section("battery", battery)
            if changed:
                bess_controller.settings_store.save_section("home", home)
                bess_controller.settings_store.save_section("electricity_price", elec)
                logger.info(
                    "Persisted locale defaults: currency=%s, vat=%s, cycle_cost=%s",
                    detected_currency,
                    detected_vat,
                    battery.get("cycle_cost_per_kwh") if battery_changed else None,
                )

        sensors: dict[str, str] = {}
        missing_sensors: list[str] = []
        platform_sensors: dict[str, dict[str, str]] = {}

        # Registry-based discovery (robust against entity renaming)
        registry = ha.fetch_entity_registry()
        (
            platform_sensors,
            detected_platform,
            platform_disabled,
        ) = ha.discover_sensors_from_registry(registry)
        disabled_sensors: dict[str, str] = {}
        platform_disabled_sensors: dict[str, dict[str, str]] = platform_disabled
        if platform_sensors:
            # When local modbus is detected alongside cloud, use modbus as
            # the primary sensor source (it provides TOU control entities).
            effective_platform = detected_platform
            if (
                detected_platform
                and detected_platform.startswith("growatt_server")
                and "solax_modbus_growatt_min" in platform_sensors
            ):
                effective_platform = "solax_modbus_growatt_min"
            elif (
                detected_platform
                and detected_platform.startswith("growatt_server")
                and "solax_modbus_growatt_sph" in platform_sensors
            ):
                effective_platform = "solax_modbus_growatt_sph"
            sensors = dict(platform_sensors.get(effective_platform, {}))
            disabled_sensors = dict(platform_disabled.get(effective_platform, {}))
            _suffix_maps = {
                "growatt_server_min": ha.GROWATT_MIN_SUFFIX_MAP,
                "growatt_server_sph": ha.GROWATT_SPH_SUFFIX_MAP,
                "solax_modbus_growatt_min": ha.SOLAX_GROWATT_MIN_SUFFIX_MAP,
                "solax_modbus_growatt_sph": ha.SOLAX_GROWATT_SPH_SUFFIX_MAP,
                "solax_modbus_native": ha.SOLAX_NATIVE_SUFFIX_MAP,
            }
            suffix_map = _suffix_maps.get(effective_platform, ha.GROWATT_MIN_SUFFIX_MAP)
            all_bess_keys = list(set(suffix_map.values()))
            # Single-segment TOU: Modbus GEN4 only needs slot 1 entities
            if effective_platform == "solax_modbus_growatt_min":
                all_bess_keys = [
                    k
                    for k in all_bess_keys
                    if not (k.startswith("tou_time_") and k[9:10] in "23456789")
                ]
            # A disabled sensor is not "missing" — the entity exists and the
            # user only has to switch it on.  Keep the two conditions apart
            # so the wizard can give the actionable message (#549).
            missing_sensors = [
                k
                for k in all_bess_keys
                if k not in sensors and k not in disabled_sensors
            ]

        current_sensors = ha.discover_current_sensors(states)
        for phase_key, entity_id in current_sensors.items():
            if phase_key not in sensors:
                sensors[phase_key] = entity_id

        # Discover optional integration sensors (Solcast, Weather, EV, etc.)
        optional_sensors = ha.discover_optional_sensors(states, registry)
        for key, entity_id in optional_sensors.items():
            if key not in sensors:
                sensors[key] = entity_id

        # Discover Octopus Energy entity IDs for pricing form auto-fill
        octopus_entities = ha.discover_octopus_entities(registry)

        # Convert top-level keys to camelCase but preserve sensor keys as
        # snake_case since they are BESS config keys, not API field names.
        detected_phase_count = (
            sum(1 for k in ("current_l1", "current_l2", "current_l3") if k in sensors)
            or None
        )
        result = convert_keys_to_camel_case(
            {
                "growatt_found": integrations["growatt_found"],
                "growatt_device_id": integrations["growatt_device_id"],
                "huawei_found": integrations["huawei_found"],
                "huawei_device_id": integrations.get("huawei_device_id"),
                "solax_found": integrations["solax_found"],
                "solax_has_growatt_tou": integrations.get(
                    "solax_has_growatt_tou", False
                ),
                "solax_has_growatt_gen3": integrations.get(
                    "solax_has_growatt_gen3", False
                ),
                "solis_found": integrations.get("solis_found", False),
                "nordpool_found": integrations["nordpool_found"],
                "nordpool_area": integrations["nordpool_area"],
                "nordpool_custom_area": integrations.get("nordpool_custom_area"),
                "nordpool_custom_entity": integrations.get("nordpool_custom_entity"),
                "nordpool_config_entry_id": integrations["nordpool_config_entry_id"],
                "octopus_found": integrations["octopus_found"],
                "entsoe_found": integrations.get("entsoe_found", False),
                "entsoe_entity": integrations.get("entsoe_entity"),
                "missing_sensors": missing_sensors,
                # Auto-detected hints
                "detected_inverter_platforms": integrations[
                    "detected_inverter_platforms"
                ],
                "detected_phase_count": detected_phase_count,
                "currency": integrations["currency"],
                "vat_multiplier": integrations["vat_multiplier"],
            }
        )
        # Attach sensor dicts without key conversion
        result["sensors"] = sensors
        result["platformSensors"] = platform_sensors
        # Sensor keys left unmapped because their only registry match is
        # disabled in HA — the wizard blocks on these and names the entity
        # to enable, rather than persisting a mapping that 404s (#549).
        # Per-platform like platformSensors, because the user can switch the
        # inverter tab away from the auto-detected platform and the gate has
        # to follow that choice.
        result["disabledSensors"] = disabled_sensors
        result["platformDisabledSensors"] = platform_disabled_sensors
        # Suggested spot-multiplier defaults for the auto-detected provider —
        # already camelCase, attach after conversion to avoid double-conversion.
        result["pricingDefaults"] = _pricing_defaults_for_discovery(integrations)
        # Attach Octopus entities for pricing form auto-fill
        if octopus_entities:
            result["octopusEntities"] = octopus_entities
        return result
    except Exception as e:
        logger.error(f"Error during setup discovery: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e


@router.post("/api/setup/complete")
async def setup_complete(payload: APISetupCompletePayload):
    """Atomic wizard completion: persist all sections and apply live.

    Called when the user finishes the 6-step setup wizard. Saves all
    sections to bess_settings.json atomically and then applies changes to the
    running system so BESS can start without a restart.
    """
    from app import bess_controller

    try:
        # A provider without its own required configuration can never fetch
        # a price, so the whole optimizer aborts every cycle with "No price
        # data available".  Reject it here rather than persisting a config
        # that is guaranteed to fail (#549).  This runs before
        # apply_discovered_config below, which persists on its own.
        if payload.provider is not None:
            required_field = _PROVIDER_REQUIRED_FIELD.get(payload.provider)
            if required_field and not getattr(payload, required_field, None):
                raise HTTPException(
                    status_code=400,
                    detail=(
                        f"Energy provider '{payload.provider}' requires "
                        f"'{required_field}', which is empty. Select the "
                        f"provider you actually have configured in Home "
                        f"Assistant, or install the integration first."
                    ),
                )

        sections: dict = {}

        # --- sensors & discovery ---
        # Sensors go directly into sections; discovery fields (nordpool area,
        # config_entry_id, growatt device_id) are merged additively via
        # apply_discovered_config which handles its own persistence.
        if payload.sensors:
            sections["sensors"] = payload.sensors
        if (
            payload.nordpoolArea
            or payload.nordpoolConfigEntryId
            or payload.growattDeviceId
            or payload.huaweiDeviceId
        ):
            bess_controller.apply_discovered_config(
                sensor_map={},  # sensors already in sections — avoid double-write
                nordpool_area=payload.nordpoolArea,
                nordpool_config_entry_id=payload.nordpoolConfigEntryId,
                growatt_device_id=payload.growattDeviceId,
                huawei_device_id=payload.huaweiDeviceId,
            )

        # All sections use read-modify-write so that keys not managed by the wizard
        # (e.g. temperature_derating in battery, config_entry_id in energy_provider)
        # are preserved when save_all replaces the section.
        #
        # Each section is driven by a mapping of payload-field-name → store-key.
        # Adding a new wizard field only requires adding one entry to the mapping;
        # the guard and the write are both derived from it automatically.

        # --- battery ---
        # maxChargeDischargePower maps to two store keys — handled separately below.
        _BATTERY_MAP = {
            "totalCapacity": "total_capacity",
            "minSoc": "min_soc",
            "maxSoc": "max_soc",
            "cycleCost": "cycle_cost_per_kwh",
        }
        if any(getattr(payload, f) is not None for f in _BATTERY_MAP) or (
            payload.maxChargeDischargePower is not None
        ):
            battery = bess_controller.settings_store.get_section("battery")
            for field, key in _BATTERY_MAP.items():
                if getattr(payload, field) is not None:
                    battery[key] = getattr(payload, field)
            if payload.maxChargeDischargePower is not None:
                battery["max_charge_power_kw"] = payload.maxChargeDischargePower
                battery["max_discharge_power_kw"] = payload.maxChargeDischargePower
            sections["battery"] = battery

        # --- home ---
        _HOME_MAP = {
            "consumption": "default_hourly",
            "currency": "currency",
            "consumptionStrategy": "consumption_strategy",
            "maxFuseCurrent": "max_fuse_current",
            "voltage": "voltage",
            "safetyMarginFactor": "safety_margin",
            "phaseCount": "phase_count",
            "powerMonitoringEnabled": "power_monitoring_enabled",
        }
        if any(getattr(payload, f) is not None for f in _HOME_MAP):
            home = bess_controller.settings_store.get_section("home")
            for field, key in _HOME_MAP.items():
                if getattr(payload, field) is not None:
                    home[key] = getattr(payload, field)
            effective_sensors = {
                **bess_controller.settings_store.get_active_sensors(),
                **flatten_sensors(sections.get("sensors") or {}),
            }
            _validate_power_monitoring_sensors(home, effective_sensors)
            _validate_consumption_strategy(home, effective_sensors)
            sections["home"] = home

        # --- electricity price ---
        # area can also come from nordpoolArea (discovery) — handled separately.
        _PRICE_MAP = {
            "markupRate": "markup_rate",
            "vatMultiplier": "vat_multiplier",
            "additionalCosts": "additional_costs",
            "taxReduction": "tax_reduction",
            "spotMultiplier": "spot_multiplier",
            "exportSpotMultiplier": "export_spot_multiplier",
        }
        area = payload.area or payload.nordpoolArea
        if any(getattr(payload, f) is not None for f in _PRICE_MAP) or area:
            elec = bess_controller.settings_store.get_section("electricity_price")
            if area:
                elec["area"] = area
            for field, key in _PRICE_MAP.items():
                if getattr(payload, field) is not None:
                    elec[key] = getattr(payload, field)
            sections["electricity_price"] = elec

        # --- energy provider ---
        # Always include energy_provider in sections when discovery provided
        # a config_entry_id (so the live price source picks it up), or when
        # the wizard explicitly set a provider.
        if payload.provider is not None or payload.nordpoolConfigEntryId:
            ep = bess_controller.settings_store.get_section("energy_provider")
            if payload.provider is not None:
                ep["provider"] = payload.provider
            # Persist Nordpool HACS entity when provider is nordpool_hacs
            if payload.provider == "nordpool_hacs" and payload.nordpoolEntity:
                ep["nordpool_hacs"] = {"entity": payload.nordpoolEntity}
            # Persist Octopus entity IDs when provider is octopus
            if payload.provider == "octopus" and payload.octopusImportTodayEntity:
                ep["octopus"] = {
                    "import_today_entity": payload.octopusImportTodayEntity,
                    "import_tomorrow_entity": payload.octopusImportTomorrowEntity,
                    "export_today_entity": payload.octopusExportTodayEntity,
                    "export_tomorrow_entity": payload.octopusExportTomorrowEntity,
                }
            # Persist ENTSO-e entity when provider is entsoe
            if payload.provider == "entsoe" and payload.entsoeEntity:
                ep["entsoe"] = {"entity": payload.entsoeEntity}
            sections["energy_provider"] = ep

        # --- inverter ---
        if payload.inverterPlatform is not None:
            _platform = payload.inverterPlatform
            if _platform not in VALID_PLATFORMS:
                raise HTTPException(
                    status_code=400,
                    detail=f"Unknown inverter platform '{_platform}', "
                    f"expected one of {list(VALID_PLATFORMS)}",
                )
            inv_section = bess_controller.settings_store.get_section("inverter")
            inv_section["platform"] = _platform
            if payload.inverterControlMode is not None:
                inv_section["control_mode"] = payload.inverterControlMode
            if payload.inverterServiceDomain is not None:
                inv_section["service_domain"] = payload.inverterServiceDomain
            if payload.huaweiDeviceId:
                inv_section["device_id"] = payload.huaweiDeviceId
            sections["inverter"] = inv_section
            if payload.growattDeviceId:
                growatt_section = bess_controller.settings_store.get_section("growatt")
                growatt_section["device_id"] = payload.growattDeviceId
                sections["growatt"] = growatt_section

        # --- demo mode ---
        if payload.demoMode is not None:
            sections["demo_mode"] = {"enabled": payload.demoMode}

        # Persist all sections atomically
        bess_controller.settings_store.save_all(sections)

        # Activate the inverter controller on the live system.  On a fresh
        # install this is the first time a platform is set, transitioning the
        # system from unconfigured → operational.
        if "inverter" in sections:
            bess_controller.system.switch_inverter_platform(
                sections["inverter"]["platform"]
            )
            # switch_inverter_platform() resets control_mode to its platform
            # default — apply an explicit wizard choice afterward. Only
            # solax_modbus_growatt_min (GEN4) accepts an explicit choice here:
            # GEN3 (solax_modbus_growatt_sph) was already resolved to "vpp"
            # by switch_inverter_platform() above, and re-applying a stale
            # client-side "tou" default would raise, since GEN3 rejects any
            # other value.
            if (
                payload.inverterControlMode is not None
                and sections["inverter"]["platform"] == "solax_modbus_growatt_min"
            ):
                bess_controller.system.switch_control_mode(payload.inverterControlMode)

        # Apply settings to live system so BESS starts immediately without
        # requiring a restart. Unconditional, not gated on payload.sensors:
        # an inverter platform switch above also changes service_domain and
        # the power polarities. ha_controller.sensors is a live settings_store
        # view (#334) and needs no equivalent refresh.
        bess_controller.refresh_service_domain()
        bess_controller.refresh_power_polarities()
        if payload.growattDeviceId:
            bess_controller.ha_controller.growatt_device_id = payload.growattDeviceId
        if payload.huaweiDeviceId:
            bess_controller.ha_controller.huawei_device_id = payload.huaweiDeviceId

        def _nn(d: dict) -> dict:
            """Strip None values so update() only overwrites explicitly provided fields."""
            return {k: v for k, v in d.items() if v is not None}

        live_updates: dict = {}
        if "battery" in sections:
            # BatterySettings.update() takes snake_case (store field names)
            # directly — no camelCase translation (issue #197, #219).
            live_updates["battery"] = _nn(
                {
                    "total_capacity": payload.totalCapacity,
                    "min_soc": payload.minSoc,
                    "max_soc": payload.maxSoc,
                    "max_charge_power_kw": payload.maxChargeDischargePower,
                    "max_discharge_power_kw": payload.maxChargeDischargePower,
                    "cycle_cost_per_kwh": payload.cycleCost,
                }
            )
        if "home" in sections:
            # HomeSettings.update() takes snake_case (store field names)
            # directly — no camelCase translation (issue #197, #219).
            live_updates["home"] = _nn(
                {
                    "default_hourly": payload.consumption,
                    "currency": payload.currency,
                    "consumption_strategy": payload.consumptionStrategy,
                    "max_fuse_current": payload.maxFuseCurrent,
                    "voltage": payload.voltage,
                    "safety_margin": payload.safetyMarginFactor,
                    "phase_count": payload.phaseCount,
                    "power_monitoring_enabled": payload.powerMonitoringEnabled,
                }
            )
        if "electricity_price" in sections:
            # PriceSettings.update() takes snake_case (store field names)
            # directly — no camelCase translation (issue #197).
            live_updates["price"] = _nn(
                {
                    "area": sections["electricity_price"].get("area"),
                    "markup_rate": payload.markupRate,
                    "vat_multiplier": payload.vatMultiplier,
                    "additional_costs": payload.additionalCosts,
                    "tax_reduction": payload.taxReduction,
                    "spot_multiplier": payload.spotMultiplier,
                    "export_spot_multiplier": payload.exportSpotMultiplier,
                }
            )
        if live_updates:
            bess_controller.system.update_settings(live_updates)

        # Apply energy_provider live so the price source uses the discovered
        # config_entry_id (not the stale/mock value from the initial settings).
        if "energy_provider" in sections:
            bess_controller.system.update_settings(
                {"energy_provider": sections["energy_provider"]}
            )

        # Apply demo mode live
        if payload.demoMode is not None:
            bess_controller.system.set_demo_mode(payload.demoMode)

        # Backfill historical data in the background (may take many seconds for 20+
        # InfluxDB queries), then build the schedule with correct historical context.
        # The dashboard returns an 'initializing' response until the schedule is ready.
        def _backfill_then_schedule() -> None:
            try:
                bess_controller.system.reinitialize_historical_data()
                logger.info("Historical backfill complete after wizard setup")
            except Exception as backfill_err:
                logger.warning(
                    "Historical backfill failed after setup: %s", backfill_err
                )
            try:
                now = time_utils.now()
                current_period = now.hour * 4 + now.minute // 15
                bess_controller.system.update_battery_schedule(
                    current_period=current_period
                )
                logger.info("Schedule built with historical data after wizard setup")
            except Exception as sched_err:
                logger.warning("Could not build schedule after backfill: %s", sched_err)

        threading.Thread(target=_backfill_then_schedule, daemon=True).start()

        # Start the periodic scheduler if this is a fresh install and the
        # scheduler was deferred during BESSController.start().
        bess_controller.start_scheduler()

        # Re-run health check so the dashboard banner reflects the new configuration
        # instead of the stale failures recorded at startup (before sensors were set).
        try:
            bess_controller.system.refresh_health_check()
        except Exception as health_err:
            logger.warning("Could not re-run health check after setup: %s", health_err)

        logger.info(f"Setup complete: saved sections {list(sections.keys())}")
        return {"success": True, "saved_sections": list(sections.keys())}
    except HTTPException:
        # Preserve the original status code (e.g. 422 from sensor/platform
        # validation) instead of masking it as a generic 500 below.
        raise
    except Exception as e:
        logger.error(f"Error completing setup: {e}")
        raise HTTPException(status_code=500, detail=str(e)) from e