Merge branch 'feat/off-peak-hours' into 'master'

Feat/off peak hours

See merge request !58

docs/ecolyo/technical/doctypes.md

@@ -691,7 +691,7 @@ This doctype is used to store the enedis maxpower values retrieved by the konnec
 
 **Description :**
 
-This doctype is used to store the enedis monthly analysis, it includes the month average half-hour consumption for weekdays and weekends, the minimum half-hour load, and the max power consumption of the month.
+This doctype is used to store the enedis monthly analysis, it includes the month average half-hour consumption for weekdays and weekends, the minimum half-hour load, the max power consumption of the month, and the consumption ratio during off-peak hours.
 
 **Doctype:**
 
@@ -705,5 +705,6 @@ This doctype is used to store the enedis monthly analysis, it includes the month
 | weekEndDaysHalfHourAverageValues    | number[] |  Half-hour average value for weekend days (saturday and sunday)                                                                          |
 | month  | number         | Month of the analysis               |
 | year  | number         | Year of the analysis |
-| minLoad | number or null         | Minimum half hour load of the month                                                                 |
+| minimumLoad | number or null         | Minimum half hour load of the month                                                                 |
 | maxpower | number or null           | Max power value of the month                                                               |
+| offPeakHoursRatio | number or null           | Consumption ratio during off-peak hours                                                     |

docs/ecolyo/technical/services/enedis_halfhour_monthly_analysis.md

@@ -12,13 +12,19 @@ The service will run everyday 3rd of month at 8.00 am, as defined in the manifes
 
 ## Main responsibilities of the service
 
-The service is responsible of calculating the average consumption load for half hour timestep on a given month. It is exclusively for Electricity fluid. The data result is stored in the doctype *com.grandlyon.enedis.monthly.analysis.data*
+It is **exclusively** for electricity fluid ⚡
+
+The service is responsible of calculating :
+
+- the average consumption load for half hour timestep on a given month
+- the maximum power consumed
+- the off-peak hours consumption ratio (if off-peak hours are found)
 
 Main steps are the following :
 
-- Check `com.grandlyon.enedis.minute` doctype. If the doctype contains entries, it means the half-hour consumption tracking has been activated, and there is data to use.
+- Check `com.grandlyon.enedis.minute` doctype. If the doctype contains entries, it means the half-hour consumption tracking has been activated, and there is data to use. If not, the service stops.
 
-- If there is half-hour data, creates the average consumption load for the last month (for the analysis) and store it in the doctype `com.grandlyon.enedis.monthly.analysis.data`
+- If there is half-hour data, it calculates all the data described above and store the results in the doctype `com.grandlyon.enedis.monthly.analysis.data`
 
 - Checks **if there is other entries** in this doctype, if so, it means the service has already run before, so we create and store enedis monthly analysis for every month between the first entry in the enedis.minute doctype and the first entry in the enedis.monthly.analysis doctype. This way we will have an analysis available until the first month the half-hour consumption tracking has been activated
 
@@ -38,7 +44,7 @@ This function is charged to do the following things :
 
 - For each half-hour data push the data in a global 2 dimensional array ; there is 2 global array, one for week-end days and the other for weekdays
 
-- At the point we have 2 global array with each 48 arrays filled with the corresponding values. To illustrate this, here is an example of how the data is sorted : 
+- At the point we have 2 global array with each 48 arrays filled with the corresponding values. To illustrate this, here is an example of how the data is sorted :
 
 ```
 weekEndValuesArray : [
@@ -62,13 +68,28 @@ EnedisMonthlyAnalysisData {
   weekEndDaysHalfHourAverageValues: number[]
   minimumLoad: number
   maxpower: number
+  offPeakHoursRatio: number
   month: number
   year: number
 }
 ```
 
-## Important rules
+### Important rules
 
 - The empty half-hour values represented by a "-1" are not pushed in the valuesArray so we can keep an accurate average
 - We have no choice but to get the half-hour values day per day because cozy limits the request result number to 1000 entries, and it is not enough to get a maximum of 48*31= 1488 entries per month, plus it doesn't allows us to properly calculate and average and handle the empty values.
 - This service is quite long to run so we decided to run it 2 hours before the newsletter sending, this way user can acces his last enedis analysis once he received the newsletter.
+
+## Computing off-peak hours consumption ratio
+
+The objective of this part is to calculate the percentage of consumption occurring during off-peak hours within the analysis month.
+
+- The `EnedisMonthlyAnalysisDataService.getOffPeakHours` method is utilized to retrieve off-peak hours stored in the `io.cozy.accounts` doctype.
+- If no off-peak hours are found, the function returns a null value for `offPeakHoursRatio`.
+- Upon successful retrieval of off-peak hours, the `EnedisMonthlyAnalysisDataService.getOffPeakHoursRatio` method is called to compute the ratio of consumption during off-peak hours.
+
+Within this method, the following steps are taken:
+
+1. Off-peak hour ranges are rounded to the nearest half-hour to facilitate the retrieval of half-hourly consumption data from the `com.grandlyon.enedis.minute` doctype. For example, a range such as 8H02-15H50 is rounded to 8H00-16H00.
+2. Ranges including midnight are split into two separate intervals to ensure accurate computation. For instance, a range like 22H00-6H00 is divided into 22H00-23H59 and 0H00-6H00.
+3. For each range composing the off-peak hours, we get the half-hour loads of the analysis month included in the range. We sum of all these loads and divide it by the month total consumption to get a ratio.

docs/konnectors/enedis-sge.md

@@ -64,6 +64,7 @@ For standalone cmd you can find konnector results in `/data/importedData.json`
 | getData | Get daily data |
 | getMaxPowerData | Get daily Max Power data |
 | getHalfHourData | Get half-hour data |
+| getOffPeakHours | Get off-peak hours if activated in contract and store them in cozy.account  |
 | processData | Given a doctype, parse and format data before storing and aggregating |
 | setStartDate | Save startDate with the right time range |
 | storeData | Save data to user's cozy |
@@ -183,6 +184,8 @@ Method : **POST**
 
 Data Route : **enedis_SGE_enedis_SGE_ConsultationDonneesTechniquesContractuelles/1.0**
 
+This route also gives off-peak hours, if the user chose a contract with off-peak hours
+
 ```xml
 <?xml version='1.0' encoding='utf-8'?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
@@ -199,6 +202,33 @@ Data Route : **enedis_SGE_enedis_SGE_ConsultationDonneesTechniquesContractuelles
   </soapenv:Envelope>
 ```
 
+Response :
+
+```xml
+<point id="12345678912345">
+  <donneesGenerales>
+    <etatContractuel code="SERVC">
+      <libelle>En service</libelle>
+    </etatContractuel>
+    <adresseInstallation>
+      <numeroEtNomVoie>208 BIS RUE GARIBALDI</numeroEtNomVoie>
+      <codePostal>69003</codePostal>
+      <commune code="69383">
+        <libelle>LYON 3</libelle>
+      </commune>
+    </adresseInstallation>
+    <niveauOuvertureServices>2</niveauOuvertureServices>
+  </donneesGenerales>
+  <situationComptage>
+    <dispositifComptage>
+      <relais>
+        <plageHeuresCreuses>HC (22H00-6H00)</plageHeuresCreuses>
+      </relais>
+    </dispositifComptage>
+  </situationComptage>
+</point>
+```
+
 #### Get user PDL
 
 Method : **POST**