Расширение getHistoryAvg возможностью интегрального рассчета среднего значения

[ai91]

Описание проблемы:
Исходная реализация getHistoryAvg занимается простым подсчётом среднего значения всех сохраненных значений в запрашиваемом интервале. При таком подходе есть два проблемных сценария:

1. Если данные поступают нерегулярно
2. Если из-за встроенной в majordomo дедупликации данных, повторяющиеся значения не сохраняются в БД.

Пример:
На данном графике имеется свойство, в которое поступало нулевое значение до 3:34, а в 3:35 и далее начало поступать значение 10000.

Если вызвать getHistoryAvg для интервала 3:30 - 4:30, то базовая имплементация обнаружит в БД только два значения: 3:34 - 0, и 3:35 - 10000. Соответсвенно результат среднего будет 5000. Значение верно математически для сохранённых данных, но неверно в прикладном смысле: среднее потребление электроустановкой за прошедший час не равно 5000Вт, а близко к 9000Вт.

Решение:
Данный пуллреквест расширяет системную функцию getHistoryAvg дополнительным опциональным параметром integral:
function getHistoryAvg($varname, $start_time, $stop_time = 0, $integral = false)
При передаче параметра integral: true, функция находит значения для моментов времени start_time и stop_time методом интерполяции между ближайшими сохранёнными точками вокруг них, после чего рассчитывается среднее значение интегрированием методом трапеций.
Изменения обратно-совместимы, т.е. если не менять пользовательский код, то поведение не меняется.

Примеры использования:
Пример 1:

getHistoryAvg('OTest.power', strtotime('2024-01-27 03:30:00'), strtotime('2024-01-27 04:30:00')) = 5000
getHistoryAvg('OTest.power', strtotime('2024-01-27 03:30:00'), strtotime('2024-01-27 04:30:00'), true) = 9105

Пример 2:

getHistoryAvg('OTest.power', strtotime('2024-01-27 03:30:00'), strtotime('2024-01-27 03:40:00')) = 5000
getHistoryAvg('OTest.power', strtotime('2024-01-27 03:30:00'), strtotime('2024-01-27 03:40:00'), true) = 4633

Пример 3:
Когда данные поступают регулярно и без дублирующих значений, результаты одинаковы.

getHistoryAvg('OElectricity.gridValueIn', strtotime('2024-01-28 07:00:00'), strtotime('2024-01-28 08:00:00')) = 301
getHistoryAvg('OElectricity.gridValueIn', strtotime('2024-01-28 07:00:00'), strtotime('2024-01-28 08:00:00'), true) = 301

Пример 4:
Данные поступают регулярно, но некоторые дублирующие значения были не сохранены majordomo:

getHistoryAvg('OElectricity.gridValueIn', strtotime('2024-01-28 06:00:00'), strtotime('2024-01-28 07:00:00')) = 314
getHistoryAvg('OElectricity.gridValueIn', strtotime('2024-01-28 06:00:00'), strtotime('2024-01-28 07:00:00'), true) = 316

TODO: после мерджа, необходимо обновить документацию:

1. https://mdminfo.ru/wiki/GetHistoryAvg
2. https://kb.mjdm.ru/vstroennie-v-majordomo-funkcii/3
3. https://mjdm.ru/forum/viewtopic.php?t=2997