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

#include <QDateTime>
#include "../types/loadaction.h"
#include "../types/loaddescriptor.h"
#include "../types/surpluscontext.h"

/*!
 * \brief Vue runtime minimale exposée par un adaptateur à l'arbitre.
 */
struct LoadTelemetry {
    double    currentPowerW = 0;  //!< Puissance mesurée (W).
    bool      available     = true; //!< Faux si l'appareil nymea est absent ou en erreur.
    QDateTime lastActionAt;         //!< Dernier instant où applyAction() a produit un effet.
};

/*!
 * \brief Interface pure des adaptateurs de charge.
 *
 * Les implémentations concrètes héritent de QObject + ILoadAdapter et déclarent leurs
 * propres signaux (telemetryChanged, descriptorChanged).
 *
 * \invariant Les adaptateurs EXÉCUTENT, ils ne décident pas (AGENTS règle 2).
 * \invariant applyAction() écrête les valeurs selon les limites matérielles réelles
 *   (second filet après l'écrêtage de l'arbitre).
 * \invariant applyAction() avec \c reason vide doit être rejetée silencieusement.
 * \invariant Les méthodes non-applyAction() retournent immédiatement (pas de I/O bloquant).
 */
class ILoadAdapter {
public:
    virtual ~ILoadAdapter() = default;

    /*!
     * \brief Description statique de la charge : capacités, limites, priorité, needs.
     * \return LoadDescriptor construit depuis la configuration matérielle.
     * \note Peut être rappelé à chaque cycle — l'implémentation doit être légère.
     */
    virtual LoadDescriptor descriptor() const = 0;

    /*!
     * \brief Télémétrie runtime (puissance, disponibilité, dernière action).
     * \return LoadTelemetry issue de l'état courant de l'appareil nymea.
     */
    virtual LoadTelemetry  telemetry()    const = 0;

    /*!
     * \brief Construit l'entrée §5 loads[] pour le SurplusContext.
     * \return LoadContext incluant declared, limits, needs et télémétrie type-spécifique.
     */
    virtual LoadContext    toLoadContext() const = 0;

    /*!
     * \brief Applique l'action et retourne ce qui a réellement été envoyé au matériel.
     *
     * L'arbitre a déjà écrêté selon les limites et le budget — ceci est le second filet.
     *
     * \param action Action à appliquer. Doit avoir \c reason non vide.
     * \return L'action après écrêtage matériel (peut différer de l'entrée).
     * \note Retour silencieux sans effet si \c action.reason est vide.
     */
    virtual LoadAction     applyAction(const LoadAction &action) = 0;
};