7f204ebf3a
Complète la couverture : 31 → 6 avertissements. Les 6 restants sont exactement les deux fichiers différés jusqu'à l'étape 3 (relayrouter.h 3, energyarbitrator.h 3, ce dernier étant la cible d'ECS-412). energyratioscalculator.h traité EN PREMIER, pour la raison qui le distingue : c'était le seul endroit où l'absence de documentation cachait une règle métier. La règle était en fait écrite — mais en commentaires « // », invisibles à doxygen, donc invérifiables. Conversion en blocs Doxygen SANS réécriture du fond : les trois cas de reseed de la baseline (premier appel, changement de jour local, compteur non monotone) et la garantie « dénominateur ≤ 0 → n/a, jamais de NaN » deviennent des invariants opposables. Précisé au passage que le paramètre `now` doit être en heure LOCALE — passer de l'UTC déplacerait la frontière de journée. Reste du lot : loadaction.h (quels champs sont significatifs selon le kind), plan.h ([from, to[ et l'interdiction de retourner un plan invalide), loaddescriptor.h, loadconfigstore.h (tolérance de chargement : un fichier absent n'est pas une erreur, une entrée invalide est ignorée seule). Build amd64 0 erreur. Simulation : 7/7, dont testEnergyRatiosAlignment. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
102 lines
4.5 KiB
C++
102 lines
4.5 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 ENERGYRATIOSCALCULATOR_H
|
||
#define ENERGYRATIOSCALCULATOR_H
|
||
|
||
#include <QDateTime>
|
||
|
||
/*!
|
||
* \brief [Phase 2] Ratios énergétiques canoniques (autoconsommation / autonomie), en %.
|
||
*
|
||
* Source canonique côté energymanager : remplace le seam interim app-side
|
||
* (\c EnergyRatiosInterim.compute). **PUR MESURE** (frontière GPL) : dérive par Δ de
|
||
* cumuls sur la période affichée (journée depuis minuit local), pas par intégration du
|
||
* signal live → déterministe, pas de drift de polling.
|
||
*
|
||
* \par Formules
|
||
* \code
|
||
* autonomie = (Δ totalConsumption − Δ totalAcquisition) / Δ totalConsumption
|
||
* autoconsommation = (Δ totalProduction − Δ totalReturn) / Δ totalProduction
|
||
* \endcode
|
||
*
|
||
* \invariant Reseed de la baseline dans trois cas, et seulement ceux-là : premier appel,
|
||
* changement de jour local, OU compteur non monotone (Δ < 0 — redémarrage de nymead,
|
||
* thing ré-ajouté, rollover).
|
||
* \invariant Dénominateur ≤ 0 → résultat marqué n/a (\c valid == false). **Jamais de NaN**,
|
||
* jamais un 0 % qui se ferait passer pour une mesure.
|
||
* \invariant Porté 1:1 de l'interim app — toute divergence de formule est un défaut.
|
||
*/
|
||
class EnergyRatiosCalculator
|
||
{
|
||
public:
|
||
/*! \brief Résultat d'un calcul : deux ratios, chacun accompagné de sa validité. */
|
||
struct Ratios {
|
||
bool autoconsommationValid = false; //!< Faux = n/a (dénominateur nul) — ne pas afficher \c autoconsommation.
|
||
double autoconsommation = 0.0; //!< Part de la production consommée sur place, % dans [0, 100].
|
||
bool autonomieValid = false; //!< Faux = n/a (dénominateur nul) — ne pas afficher \c autonomie.
|
||
double autonomie = 0.0; //!< Part de la consommation couverte sans soutirage, % dans [0, 100].
|
||
};
|
||
|
||
/*! \brief Construit sans baseline : le premier \c compute() la posera. */
|
||
EnergyRatiosCalculator() = default;
|
||
|
||
/*!
|
||
* \brief Réinitialise la baseline (ex. changement d'installation).
|
||
* \note Le \c compute() suivant repose la baseline et retourne donc n/a sur les deux
|
||
* ratios : sans écart de cumuls, il n'y a rien à mesurer.
|
||
*/
|
||
void reset();
|
||
|
||
/*!
|
||
* \brief Calcule les deux ratios depuis les cumuls courants.
|
||
* \param totalProduction Cumul de production. Unité libre — elle s'annule dans le ratio.
|
||
* \param totalReturn Cumul réinjecté au réseau, même unité.
|
||
* \param totalConsumption Cumul de consommation, même unité.
|
||
* \param totalAcquisition Cumul soutiré au réseau, même unité.
|
||
* \param now Horodatage en heure **LOCALE** : sert à détecter le changement
|
||
* de jour, donc le reseed. Passer de l'UTC fausserait la frontière
|
||
* de journée.
|
||
* \return Les deux ratios ; un ratio dont le dénominateur est ≤ 0 revient \c valid == false.
|
||
*/
|
||
Ratios compute(double totalProduction,
|
||
double totalReturn,
|
||
double totalConsumption,
|
||
double totalAcquisition,
|
||
const QDateTime &now);
|
||
|
||
private:
|
||
static bool ratio(double numerator, double denominator, double *outPercent);
|
||
static qint64 localDay(const QDateTime &now);
|
||
|
||
bool m_hasBaseline = false;
|
||
double m_baseProduction = 0.0;
|
||
double m_baseReturn = 0.0;
|
||
double m_baseConsumption = 0.0;
|
||
double m_baseAcquisition = 0.0;
|
||
qint64 m_baseDay = 0;
|
||
};
|
||
|
||
#endif // ENERGYRATIOSCALCULATOR_H
|