// SPDX-License-Identifier: GPL-3.0-or-later

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* Copyright (C) 2013 - 2024, nymea GmbH
* Copyright (C) 2024 - 2025, chargebyte austria GmbH
*
* This file is part of nymea-energy-plugin-nymea.
*
* nymea-energy-plugin-nymea.s free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* nymea-energy-plugin-nymea.s distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with nymea-energy-plugin-nymea. If not, see <https://www.gnu.org/licenses/>.
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

#ifndef ISCHEDULINGSTRATEGY_H
#define ISCHEDULINGSTRATEGY_H

#include <QObject>
#include <QList>
#include <QString>

#include "types/energytimeslot.h"
#include "types/flexibleload.h"
#include "types/schedulerconfig.h"

// Abstract interface for energy scheduling strategies.
//
// Contract:
//   - computeSchedule() receives a full context (forecast timeline + flexible loads +
//     configuration) and returns a fully annotated timeline.
//   - Every returned slot that has non-zero allocations MUST have a non-empty
//     decisionReason — this is a hard requirement for user trust.
//   - explainDecision() provides slot-level explainability for a specific load.
//   - Strategies can be swapped at runtime by SchedulerManager::setStrategy().
//
// To add a new strategy:
//   1. Subclass ISchedulingStrategy and implement all pure-virtual methods.
//   2. Give it a unique strategyId() string (e.g. "my-custom-strategy").
//   3. Register it with SchedulerManager::registerStrategy().
//   4. Select it via SchedulerManager::setStrategy() or JSON-RPC SetSchedulerStrategy.
//   5. (Optional) Override isAvailable() if the strategy requires external resources.
class ISchedulingStrategy : public QObject
{
    Q_OBJECT
public:
    explicit ISchedulingStrategy(QObject *parent = nullptr) : QObject(parent) {}
    virtual ~ISchedulingStrategy() = default;

    // Unique identifier used in JSON-RPC and settings persistence
    virtual QString strategyId() const = 0;

    // User-facing display name
    virtual QString displayName() const = 0;

    // Short description of how this strategy makes decisions
    virtual QString description() const = 0;

    // Core scheduling entry point.
    // Receives the full 24–48h forecast and all known flexible loads.
    // Returns a complete timeline with all allocations and decision reasons populated.
    // INVARIANT: every returned slot with non-zero allocations must have non-empty decisionReason.
    virtual QList<EnergyTimeSlot> computeSchedule(
        const QList<EnergyTimeSlot> &forecast,
        const QList<FlexibleLoad>   &loads,
        const SchedulerConfig       &config
    ) = 0;

    // Returns a human-readable explanation of why a specific allocation was made
    // for the given load in the given slot. Used by the UI "Pourquoi ?" feature.
    virtual QString explainDecision(
        const EnergyTimeSlot &slot,
        const FlexibleLoad   &load
    ) const = 0;

    // Returns true if the strategy is ready to compute schedules.
    // Override to return false if e.g. an AI model has not been loaded yet.
    virtual bool isAvailable() const { return true; }

signals:
    // Emitted after computeSchedule() completes (may be used for async strategies)
    void scheduleComputed(const QList<EnergyTimeSlot> &schedule);

    // Emitted when the strategy becomes unavailable
    void strategyUnavailable(const QString &reason);
};

#endif // ISCHEDULINGSTRATEGY_H