// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2025 - 2026, Patrick Schurig / ETM PowerSync
#pragma once

#include "../types/surpluscontext.h"
#include "../types/plan.h"

/*!
 * \brief Interface pure du planificateur d'énergie.
 *
 * Les implémentations concrètes héritent de QObject + IScheduler.
 *
 * \invariant getPlan() retourne IMMÉDIATEMENT (modèle cache, AGENTS invariant 5).
 *   SocketScheduler retourne son dernier plan en cache et recalcule en arrière-plan.
 * \invariant getPlan() retourne TOUJOURS un Plan valide (isValid() == true).
 *   SocketScheduler embarque un RuleBasedScheduler en fallback — jamais d'abstain
 *   qui remonterait à l'arbitre (AGENTS règle 6).
 * \invariant Toute LoadAction du Plan retourné a \c reason non vide, en français.
 */
class IScheduler {
public:
    virtual ~IScheduler() = default;

    /*!
     * \brief Calcule le plan d'optimisation à partir du contexte courant.
     * \param ctx Contexte surplus (site, compteur, PV, batterie, charges, tarif).
     * \return Plan avec au moins un Slot — jamais Plan::isValid() == false.
     * \note Retourne immédiatement depuis le cache ; le recalcul est asynchrone.
     */
    virtual Plan getPlan(const SurplusContext &ctx) = 0;
};