98 lines
3.9 KiB
C++
98 lines
3.9 KiB
C++
// 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
|