Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found
Select Git revision

Target

Select target project
  • web-et-numerique/factory/llle_project/self-data-technical-doc
1 result
Select Git revision
Show changes
Showing
with 209 additions and 272 deletions
# Routes
:warning: WIP :warning:
The different routes exposed by the backend are described by Swagger documentation.
Once the api deployed, the documentation is accessible at https://HOSTNAME/swagger/index.html
\ No newline at end of file
This section will allow you to launch a proper local environment for Ecolyo-Agent
# Launch Ecoylo Agent
## Initialisation of the project
This section will allow you to launch a proper local environment for Ecolyo-Agent
### Clone the project repository
## Local usage
### Initialisation of the project
Use following commands in your favorite terminal to clone the project:
Clone the projects using thefollowing commands
```
```sh
git clone https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-client
git clone https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-server
```
## Installation of the project
### Installation of node modules
### Installation of the project
To install required node module, open a terminal on the root folder of the backoffice-client project and type the following command:
To install required node modules, open a terminal on the root folder of the backoffice-client project and type the following command:
```
```sh
yarn install
```
## Local usage
Before launching the application, ensure you've properly filled the .env file according to the template. If needed please refer to a team member.
Before launching the application, ensure you've properly filled the `.env` file according to the template. If needed please refer to a team member.
In order to launch the project in local with the backend working launch the following command
......@@ -49,49 +46,50 @@ Do not use the app with the port 3000, you won't be able to login.
> :warning: **If you are launching the project from a Windows OS** : Make sure to comment the 'extra_hosts' lines in the docker-compose.local file. Otherwise, you you won't be able to access your machine's localhost from the docker container.
## Backend and Database
#### Backend and Database
In order to get Backend documentation, please refer directly to the [backend project](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-server)
In order to get Backend documentation, please refer directly to the [backend readme](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-server/-/blob/dev/README.md)
## Nginx
#### Nginx
The nginx server redirects https requests from front-end to the backend on port 1443.
It has two configuration files :
- nginx/site.conf, used for local development
- nginx/site.prod.conf, used for production
- `nginx/site.conf`, used for local development
- `nginx/site.prod.conf`, used for production
The nginx server needs local ssl certificates in order to run an interact with backend, these certificates are present in the project.
#### Check success
## Check success
To check if the application starts successfully, launch the command
To check if the application starts successfully, launch the command
```bash
docker logs backoffice-client_backend_1
```
You should obtain the following messages:
> --- Server is starting ---
> --- Server is starting ---
> Token signing key set
> Mock OAuth2 server Listening on: http://localhost:8090
Once the application is started, you can access it here: https://localhost
Once the application is started, you can access it here: [localhost](https://localhost)
## Test on alpha
## Alpha usage
In order to test the app on alpha you can do the following steps:
- Build locally your docker image for the client and/or the server
```
```sh
docker build . -t registry.forge.grandlyon.com/web-et-numerique/llle_project/backoffice-<server/client>:your-tag
```
- Push the image
```
```sh
docker push registry.forge.grandlyon.com/web-et-numerique/llle_project/backoffice-<server/client>:your-tag
```
......@@ -99,46 +97,44 @@ docker push registry.forge.grandlyon.com/web-et-numerique/llle_project/backoffic
- Then launch the app, it will pull automatically the new images
```
```sh
docker-compose up -d
```
- If you have access denied issue, try to docker login
```
```sh
docker login registry.forge.grandlyon.com/web-et-numerique/llle_project/
```
- If you want to update alpha using the same image tag with edited image, just pull manually your new image and rebuild the concerned image
- If you want to update alpha using the same image tag with edited image, just pull manually your new image and rebuild the concerned image
```
```sh
docker pull registry.forge.grandlyon.com/web-et-numerique/llle_project/backoffice-<server/client>:your-tag
docker-compose up -d
```
If you need to work with prices on alpha, you will need to init the prices database.
If you need to work with prices on alpha, you will need to init the prices database.
- First get the mysql container id
```
```sh
docker ps
```
- Then get into the container
```
```sh
docker exec -it <container-id> bash
```
- Then execute the mysql script that imports all the prices in DB
```
```sh
mysql --local-infile=1 -uroot -p backoffice < /dbinit/dbinit.sql
```
You will be prompted for the admin password, use the db password set in the .env file.
Now you're ready to edit your prices on alpha !
......@@ -44,7 +44,7 @@ It allows us to create variables, nested rules, mixins, functions, and do mathem
Package for Go that implements a request router and dispatcher for matching incoming requests to their respective handler.
It allows us to easily create and manage routes/APIs
It allows us to easily create and manage routes/APIs
## Swag
......
This section will allow you to install a proper local environment step by step for Ecolyo-Agent using VSCode IDE.
## VSCode
### Install VSCode
Installation for VSCode can be found here: [Installation of VSCode](https://code.visualstudio.com/).
### Extensions
Installation of Extension is explained here: [Installation of Extensions](https://code.visualstudio.com/docs/editor/extension-gallery).
Here are the list of important extensions to install:
- Prettier - Code formatter
- ES7 React/Redux/GraphQL/React-Native snippets
- GitLens - Git supercharged
- Markdown Preview
- Go
Optional extensions:
- Bracket Pair Colorizer 2
- CSS Peek
- Auto Rename Tag
- indent-rainbow
- TabOut
- Liveshare (pair programming extension)
### User settings
Open the project with VSCode and add the following code into .vscode/settings.json:
```
{
"workbench.colorCustomizations": {
/* Put anything you like here */
},
"editor.snippetSuggestions": "top",
"editor.tabSize": 2,
"editor.formatOnSave": true,
"diffEditor.ignoreTrimWhitespace": false,
"window.zoomLevel": 0,
"gitlens.advanced.messages": {
"suppressShowKeyBindingsNotice": true
},
"breadcrumbs.enabled": true,
"workbench.settings.editor": "json",
"editor.tabSize": 2,
"editor.formatOnSave": true,
"editor.formatOnPaste": true
}
```
If this file is not empty, you can simply add the following lines to it:
```
"gitlens.advanced.messages": {
"suppressShowKeyBindingsNotice": true
},
"breadcrumbs.enabled": true,
"workbench.settings.editor": "json",
"editor.formatOnSave": true,
"diffEditor.ignoreTrimWhitespace": false,
"window.zoomLevel": 0,
```
## Git
The project is using Gitlab, you will need to install Git to checkout the project.
Installation for Git can be found here: [Installation of Git](https://git-scm.com/) (current version : 1.17)
## Node
For this project, Node version 14 is required.Download [node-v14](https://nodejs.org/en/download/).
Node.js® is a JavaScript runtime built on Chrome's V8 JavaScript engine.
## Yarn
Yarn is used as package manager for this project. Feel free to use the one you prefer but we advice to install yarn as all the documentation is described with this package manager.
Installation for yarn can be found here: [Installation of Yarn](https://classic.yarnpkg.com/fr/docs/install/).
## Docker
Docker is a tool designed to make it easier to create, deploy, and run applications by using containers. Containers allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and ship it all out as one package. By doing so, thanks to the container, the developer can rest assured that the application will run on any other Linux machine regardless of any customized settings that machine might have that could differ from the machine used for writing and testing the code.
### Install Docker
Installation of Docker can be found here: [Installation of Docker](https://www.docker.com/get-started).
### Install Docker-Compose
Installation of Docker-Compose (according to your OS) is explained here: [Installation of Docker-Compose](https://docs.docker.com/compose/install/).
## Golang
Golang (or Go for short) is an open source programming language that makes it easy to build simple, reliable, and efficient software. It is used in this project for the backend.
Installation of Go (according to your OS) is explained here: [Installation of Go](https://golang.org/doc/install) (current version: 1.17).
Ecolyo-Agent is a backoffice for the Ecolyo app that allows to create and edit content for the newsletters sent to the users
# Ecolyo Agent
This project is split into two parts: backend and front-end; each has its own repository
Ecolyo-Agent is a backoffice for the Ecolyo app that allows to create and edit content for the newsletters sent to the users.
This project is split between a backend and frontend; each project has its own repository.
!!! info ""
If you are a new developer tasked to work on this project, check the [setup your environment](./getting_started/setup_your_environment.md) and [launch the application on local](./getting_started/launch_local_application.md) to start the application.
If you are a new developer tasked to work on this project, check the [setup your environment](../../setup_your_environment.md) and [launch the application on local](./getting_started/launch_local_application.md) to start the application.
## Repositories
## ![gitlab](../../img/gitlab-logo.svg) Repositories
[Ecolyo-Agent backend gitlab repository](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-server)
[Ecolyo-Agent front-end gitlab repository](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-client)
\ No newline at end of file
[Ecolyo-Agent front-end gitlab repository](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-client)
# Analysis
This section explains the analysis screen and how information are displayed.
## Description
......
# Challenge
This section explain all the functionalities in the challenge part
## Quiz
......@@ -52,8 +54,8 @@ Calculation of custom question is done by combination of all parameters:
Retrieve the **date** of day/month/year (define by _timeStep_) from the last week, month, year (define by _interval_), if there is no data in this interval, then it will go back to a previous interval, up to a maximum of 6 months
```
example: What day did I consumme the most on the last week ?
```js
// example: What day did I consumme the most on the last week ?
type = CustomQuestionType.DATA
timeStep = TimeStep.DAY
interval = TimeStep.WEEK
......@@ -61,8 +63,8 @@ period = {}
singleFluid = false
```
```
example: What day did I consumme the most #fluid in #unit on the last week ?
```js
// example: What day did I consumme the most #fluid in #unit on the last week ?
type = CustomQuestionType.DATA
timeStep = TimeStep.DAY
interval = TimeStep.WEEK
......@@ -74,8 +76,8 @@ singleFluid = true
Retrieve the **date** of day/month/year (define by _timeStep_) from a week, month, year (define by _interval_) of _period_
```
example: What month did I consumme the most on year 2020 ?
```js
// example: What month did I consumme the most on year 2020 ?
type = CustomQuestionType.DATA
timeStep = TimeStep.MONTH
interval = TimeStep.YEAR
......@@ -89,8 +91,8 @@ singleFluid = false
Retrieve the **maxload** value of day/month/year (define by _timeStep_) from the last week, month, year (define by _interval_).
```
example: Which is your daily max consumption on the last week ?
```js
// example: Which is your daily max consumption on the last week ?
type = CustomQuestionType.MAXLOAD
timeStep = TimeStep.DAY
interval = TimeStep.WEEK
......@@ -102,8 +104,8 @@ singleFluid = false
Retrieve the **maxload** value of day/month/year (define by _timeStep_) from a week, month, year (define by _interval_) of _period_
```
example: Which is your daily max consumption on january 2020 ?
```js
// example: Which is your daily max consumption on january 2020 ?
type = CustomQuestionType.MAXLOAD
timeStep = TimeStep.DAY
interval = TimeStep.MONTH
......@@ -117,8 +119,8 @@ singleFluid = false
Retrieve the **average** of day/month/year (define by _timeStep_) from the last week, month, year (define by _interval_).
```
example: Which is your daily average consumption on last week ?
```js
// example: Which is your daily average consumption on last week ?
type = CustomQuestionType.AVERAGE
timeStep = TimeStep.DAY
interval = TimeStep.WEEK
......@@ -130,8 +132,8 @@ singleFluid = false
Retrieve the **average** of day/month/year (define by _timeStep_) from a week, month, year (define by _interval_) of _period_
```
example: Which is your daily average consumption on january 2020 ?
```js
// example: Which is your daily average consumption on january 2020 ?
type = CustomQuestionType.AVERAGE
timeStep = TimeStep.DAY
interval = TimeStep.MONTH
......@@ -143,8 +145,8 @@ singleFluid = false
Retrieve the **average** of the _weekday_ from a week, month, year (define by _interval_).
```
example: Which is your daily average consumption on wednesdays of last month?
```js
// example: Which is your daily average consumption on wednesdays of last month?
type = CustomQuestionType.AVERAGE
timeStep = TimeStep.DAY
interval = TimeStep.MONTH
......@@ -191,7 +193,7 @@ When the user finish the exploration, he gets a success message and five more st
Action is a feature which in the user has to apply an ecogesture for a given duration in order to reduce his consumption. An action refers to the model **UserAction** in the app, and is an extension of an ecogesture to which we add an _startDate_ and a _userActionState_, allowing user to manage the action state depending on user's progress.
```jsx
```ts
UserAction {
ecogesture: Ecogesture | null
state: UserActionState
......
......@@ -30,7 +30,7 @@ For EGL, the interval is **5 days**
## ConsumptionView
### Description
**Description:**
This view is the main view of the application. It displays an aggregation view of all connected fluids.
It is the entrypoint to several children components that each handles a particular feature :
......@@ -43,7 +43,7 @@ It is the entrypoint to several children components that each handles a particul
The submenu (FluidButtons), allows the user to switch between the different fluids and the multifluid view.
### Rules
**Rules:**
1. If no fluids are connected, this view will display the multifluid view with the _KonnectorViewerList_ component which shows buttons that allow user to connect its first fluids. These buttons redirects to the chosen fluid section with the connection form.
2. If at least one fluid is connected, the multi fluid view and the connected fluids views are shown (electricity, water, gas).
......@@ -54,11 +54,11 @@ The submenu (FluidButtons), allows the user to switch between the different flui
## DateNavigator
### Description
**Description:**
The component allows the user to navigate through the selected timestep (week by week, month by month, etc.)
### Rules
**Rules:**
1. If no fluid is connected, the navigation is locked
2. By default, the date is set to the lastDataDate.
......@@ -66,11 +66,11 @@ The component allows the user to navigate through the selected timestep (week by
## FluidButtons
### Description
**Description:**
The component allows the user to navigate through the different fluid views (multifluid, electricity, water, gas)
### Rules
**Rules:**
1. If a Konnector is on error or its data is outdated, we show a red cross on the fluid icon
2. If the fluid is not connected we show a "turn on" icon
......@@ -78,7 +78,7 @@ The component allows the user to navigate through the different fluid views (mul
## FluidChart
### Description
**Description:**
This component is the one that shows the user its consumption, according to the selected fluid, timestep and date.
It is split in 3 distinct parts:
......@@ -87,7 +87,7 @@ It is split in 3 distinct parts:
- The FluidSlides
- The TimeStep Navigator
### Rules
**Rules:**
| Component | Rules |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
......@@ -97,12 +97,12 @@ It is split in 3 distinct parts:
## DataLoad Consumption Visualizer
### Description
**Description:**
This view displays the load of a specified fluid (electricity, water, gas) or the total consumption on the multifluid screen.
The display will be done in function of the data state.
### Rules to define data state
**Rules to define data state:**
The data state is define in the "ConsumptionFormatter" service following theses rules :
......@@ -202,7 +202,7 @@ The chart scale will adapt to the max load displayed between the _actualData_ an
This component shows the konnector state and allows the user to connect, delete, or update a konnector
### Rules
**Rules:**
- If the fluid is connected, this component will shows the konnector state at the end of the consumption page
- If the fluid is not connected, it will show the connection form
......
......@@ -23,7 +23,6 @@ This section explains how the application is tracking usage events. Here are the
- All events are stored during the use of the application in the doctype **com.grandlyon.ecolyo.usageevents**
- A service is responsible of the aggregation of these events to create ANONYMIZED indicators. These indicators are then sent to a remote docType.
| Title | Tech name | target | context | startDate | result | trigger | Cozy Dacc Name |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Changement d'action dans un challenge | ActionChangeEvent | Id de l'action | Id du challenge en cours | --- | --- | Chaque appui sur le bouton `selectEcogesture` dans le `ActionCard` | navigation-action-daily |
......@@ -48,8 +47,6 @@ This section explains how the application is tracking usage events. Here are the
| Consultation du nouveau bilan mensuel | ReportFromEvent | --- | 'analysis' | --- | 1 | Lorsque l'utilisateur consulte sa page analyse quand la notification est activée | summary-subscription-monthly |
| Tentatitve de connexion à un connecteur (initialisation)| KonnectorAttemptEvent | Slug du connecteur | --- | --- | 'success or error' | Lorsque l'utilisateur clique sur le bouton de connexion. Lorsque la connexion est réussie, et que l'utilisateur clique sur OK dans la modale le *result* est passé à 'success' | konnector-attempts-monthly |
1. Nom de la page, différents cas existant
| Page | target | Trigger |
......@@ -61,11 +58,13 @@ This section explains how the application is tracking usage events. Here are the
## Indicators
!!! warning "note"
!!! warning "note"
All indicators are only sent if a user validate first version of CGU, the one containing dacc validation
### Monthly Indicators
All monthly indicators call can be found after this comment on the code
```js
// Monthly events
```
......@@ -79,7 +78,6 @@ All monthly indicators call can be found after this comment on the code
| profile-count-monthly | Tous les mois si le profil a été complété au moins une fois | Le nombre de fois ou le profile a été complété |
| konnector-attempts-monthly | Tous les mois, le nombre de tentative de connexion pour connecter un connecteur la première fois. Une fois la connexion réussie, l'indicateur remonte true dans le groupe "success". L'indicateur ne remonte ensuite plus pour cet utilisateur car il aura déjà réussi à se connecter une première fois. | Le nombre total de tentatives |
### Daily Indicators
The daily process get all events of previous day and process them in the following indicators
......@@ -104,7 +102,7 @@ The daily process get all events of previous day and process them in the followi
All indicator are post to a remote doctype, which will allow the application to read a defined external API. This doctype is created by Cozy itself.
The structure to send is the following :
```
```ts
{
createdBy: string
measureName: string
......@@ -122,7 +120,7 @@ with:
- *startDate*: used to defined the start date of the indicator
- *value*: contains a value relevant to the defined indicator (example: number of page viewed on a day).
- *groups*: contains all attributes defining a indicator. Please refer to [indicators definition](https://stats.cozycloud.cc/question#eyJkYXRhc2V0X3F1ZXJ5Ijp7ImRhdGFiYXNlIjo0LCJxdWVyeSI6eyJzb3VyY2UtdGFibGUiOjh9LCJ0eXBlIjoicXVlcnkifSwiZGlzcGxheSI6InRhYmxlIiwidmlzdWFsaXphdGlvbl9zZXR0aW5ncyI6e319)
- *mesureName*: contains one of the following value
- *mesureName*: contains one of the following value
| ENUM | value |
| --- | --- |
......@@ -142,7 +140,7 @@ with:
| PROFILE_COUNT_MONTHLY | profile-count-monthly |
| KONNECTOR_ATTEMPTS_MONTHLY | konnector-attempts-monthly |
### Environments
### Environments
There is two remote doctypes pointing to two different mode. `dacc-dev` is used on alpha.
......@@ -162,11 +160,13 @@ There is two remote doctypes pointing to two different mode. `dacc-dev` is used
First you need to modify the service in order to be able to see data in local :
- Run a local server that will listen and log events.
```sh
node srcipts/server.js
```
- Edit dacc URL (line 67) to send requests to your local server at `http://localhost:8081`
```js
await client
.getStackClient()
......@@ -180,7 +180,9 @@ node srcipts/server.js
}
)
```
- For **monthly indicators**, remove date protection (ligne 1100)
```js
if (
profile
......@@ -199,14 +201,16 @@ You will be able to see previous events and freshly generated events in the db `
:warning: because the cron run every day at 2am, it will take events from the day before. So if you want to test specific usage, you will have to edit the `eventDate` of events you want to send.
- Then you are finally ready to test ! Just run the following :
*If aggregatorUsageEvents changed*
*If aggregatorUsageEvents changed:*
```sh
yarn build-dev:browser && yarn run cozy-konnector-dev -m ./manifest.webapp ./build/services/aggregatorUsageEvents/ecolyo.js
```
*To save time, when running multiple times and if aggregatorUsageEvents didn't change, you don't have to build.*
```sh
yarn run cozy-konnector-dev -m ./manifest.webapp ./build/services/aggregatorUsageEvents/ecolyo.js
```
......@@ -215,25 +219,27 @@ yarn run cozy-konnector-dev -m ./manifest.webapp ./build/services/aggregatorUsag
```json
{
data: '{"createdBy":"ecolyo","measureName":"connection-count-monthly","startDate":"2021-12-09","value":3}'
"data": {"createdBy":"ecolyo","measureName":"connection-count-monthly","startDate":"2021-12-09","value":3}
}
{
data: '{"createdBy":"ecolyo","measureName":"connection-count-monthly","startDate":"2021-12-09","value":3}'
"data": {"createdBy":"ecolyo","measureName":"connection-count-monthly","startDate":"2021-12-09","value":3}
}
```
## How to add new indicator ?
## How to add new indicator ?
You have to reach cozy and discuss with them about new indicators. They will implement it for `dacc-dev` and `dacc` and you will be able to test it on alpha env. Remember you will need **at least 5 data** of each type to see it in metabase.
## Visualisation
## Visualisation
All the data aggregated in the dacc can be visualized with a *Metabase* website hosted by [cozy](https://stats.cozycloud.cc/).
## Errors
More here in [DJU](https://doc.self-data.alpha.grandlyon.com/ecolyo/functionalities/profile_type/).
If there is an authentication error, the api will returns an error in html format to cozy, so you'll get from cozy an error 502 as following, because cozy expects a json response :
```json
{
"status": "502",
......
......@@ -10,7 +10,7 @@ Also, an ecogesture can be used for an action challenge.
### Model
```
```ts
Ecogesture {
id: string
shortName: string
......@@ -35,9 +35,11 @@ Ecogesture {
viewedInSelection: boolean
}
```
## Ecogestures screen
This screen is divided in 3 tabs :
This screen is divided in 3 tabs :
- *ALL*: display the full list of ecogestures. User can filter ecogesture by usage.
- *DOING*: display the list of doing ecogestures. User can filter ecogesture by usage.
- *OBJECTIVES*: display the list of objectives ecogestures. User can filter ecogesture by usage.
......@@ -55,12 +57,13 @@ An ecogesture can have a status according the user's choice, it can be *doing* a
## Profile Ecogesture
The first time the user consults the ecogesture page, he will be prompted to start selecting his custom ecogestures.
- If he refuses, I will still be able to access this functionality by clicking on the "Select" button on the tabs 'Doing' and 'Objectives' while they are still empty.
- If he starts select ecogestures on his own by the tab 'All' and fill both 'objective' and 'doing' sections, he won't be able to access the form and selection as described in the next parts.
### Model
```
```ts
ProfileEcogesture {
heating: IndividualOrCollective
warmingFluid: WarmingType | null
......@@ -70,19 +73,21 @@ ProfileEcogesture {
```
### Ecogesture Form
The form is compose in 2 parts :
- The first is made of question concerning his heating fluid and type (individual or collective), and his hotWater type.
- The second part asks the user to pick the equipment he has.
*If the user has completed his profileType, he won't see the first part as it is automatically completed with the information he filled in his profileType*
*If the user has completed his profileType, he won't see the first part as it is automatically completed with the information he filled in his profileType:*
- The first part filters his custom list by Usages ECS and HEATING
- The second part filters his custom list by Equipments
## Ecogesture Selection
Once user has completed his profile ecogesture through the form, he has the possibility to enter the ecogesture selection (tinder-like)
- A list of custom ecogesture is made according to his profile
- User will cross this list 10 by 10, and has to choose if it is 'doing' 'objective' or 'not interested
......
# Inisitaliaztion
This section explains how to handle data storage.
We handle data storage according to the following process :
......@@ -46,12 +48,9 @@ Functions used to init or update the hash :
| initQuizEntity(hash: string) |
| initExplorationEntity(hash: string) |
!!! info "Exception for ecogestures"
When we update the ecogesture list in **ecogestureData.json**, we also get the previous existing list to transfer the ecogesture status (doing and/or objective) to the updated list.
### dataEntity vs userData
In the project, you'll see two versions for the same data. The dataEntity (quizEntity, challengeEntity, ...) is the data stored in the db folder and in the CouchDB. These data are only edited in the CouchDB when we update a challenge/quiz/duel or add a new one.
......@@ -93,7 +92,7 @@ We create a userData and store it in the CouchDB under the doctype userData name
To illustrate this, let's show an example of the conversion of duelEntity to UserDuel :
```jsx
```ts
DuelEntity {
id: string
title: string
......@@ -104,12 +103,12 @@ DuelEntity {
Becomes :
```jsx
```ts
UserDuel {
id: string
title: string
description: string
duration: Duration
duration: Duration
threshold: number
state: UserDuelState
startDate: DateTime | null
......@@ -127,7 +126,7 @@ UserDuelEntity {
id: string
title: string
description: string
duration: Duration
duration: Duration
threshold: number
state: UserDuelState
startDate: string | null
......@@ -146,7 +145,7 @@ The initialization process displays progression steps in the splash screen so th
Available loading steps are the followings :
````
```ts
MIGRATION = 0,
CONSENT = 1,
PROFILE = 2,
......@@ -154,12 +153,11 @@ Available loading steps are the followings :
CHALLENGES = 4,
PRICES = 5,
CONSOS = 6,
```
Possible errors are the followings :
```
```ts
MIGRATION_ERROR = 'migration_error',
CONSENT_ERROR = 'consent_error',
PROFILE_ERROR = 'profile_error',
......
......@@ -15,7 +15,7 @@ Matomo is hosted on [statweb.com](https://statweb.grandlyon.com/) where two proj
_For our development, every alpha instance points to the REC project. That way, we work in an environment that is close to our production one._
## Local testing
## Local testing
### Matomo server
......@@ -39,7 +39,8 @@ On step 5, create a super user with the credentials you want, for example
On step6, enter dummy values and select a time zone.
Once you finish the setup and access the server, you should see a warning telling you that matomo has not been configured with the correct port. To fix this problem follow these instructions.
```
```sh
docker ps
# copy container id of matomo
......@@ -54,16 +55,19 @@ vi config/config.ini.php
```
and under "[General]" add the port **9800** to the following line :
```
```sh
trusted_hosts[] = "localhost:9800"
```
After reloading, you should be able to login. We need to make one last change for our app to send data to our matomo server.
### Ecolyo app
In the file
In the file
src/targets/browser/**index.tsx** at line 66 comment the dev condition that is preventing the tracker from being initialized.
```jsx
```js
if (
window.Piwik
// && !isDev
......
# Onboarding
This section explains the way we handle onboarding the application.
## Description
When the user connects for the first time to Ecolyo, onboarding screens will be displayed.
!!! note "First connection"
!!! note "First connection"
The first connection is define by the **isFirstConnection** boolean contains in the **profile** doctype.
### GCU screen
First of all, we display the GCU screen, which allows user to read the General Condition of Use and the Legal Notice. The user should consent to all the terms to go further in the application.
!!! note "About terms"
More details are available on the (term section)[/ecolyo/functionalities/terms.md].
!!! note "About terms"
More details are available on the [term section](/ecolyo/functionalities/terms.md).
### Welcome modal
......
......@@ -5,7 +5,8 @@ This section explains the price calculation process.
## Description
Since version `1.6.0` of the app, we have a database storing fluid prices evolution since 2012 for the following fluids :
* Electricity
* Electricity
* Gas
Before this version, the app was applying a hard coded price for each fluid without taking care of the time period. Now, there is a service running every night that process fresh data in order to apply the current price to this data, but also apply the most relevant price for a fluid doctype.
......@@ -83,15 +84,16 @@ stop
This service is running every night at 02:00 AM.
!!! warning "note"
You might observe some price miscalculation if data from konnector is collect after the service runtime. Because of the hard code price, which is the current price, the user should not see any difference.
You might observe some price miscalculation if data from konnector is collect after the service runtime. Because of the hard code price, which is the current price, the user should not see any difference.
### Init
### Init
A migration job has been setup to init the database with json data store inside the app. This job should be run once and will init electricity and gas prices.
### New price
In case of price update the following procedure must be done :
* Create a migration for adding new prices
* Update hard coded price inside app in order to maintain fallback calculation
* Verify full service calculation with new data
......@@ -102,6 +104,7 @@ In case of price update the following procedure must be done :
### Prices Data
We store in database a collection of prices with the following info :
* StartDate
* EndDate
......@@ -110,7 +113,6 @@ We store in database a collection of prices with the following info :
The EndDate is set to null if it's the current fluid price.
## App Price display
The app can handle the new price calculation and also keep the old calculation system.
......@@ -123,7 +125,7 @@ If there is a price on the doctype we want to process, it will be use for displa
The app take the hard code price for a given fluid and apply it to a load. This allow the app to handle prices in any case.
### How to test service ?
### How to test service ?
In a shell run a build and test service with le following command line :
......@@ -134,6 +136,7 @@ yarn build-dev:browser; yarn run cozy-konnector-dev -m .\manifest.webapp .\build
### Future Changes
We might consider a more dynamic process for fallback price calculation in the future:
* Get last price for a given price in database
* Use it to calculate value instead of the hard coded one
* Use it in all info pop-in for user information
# Profile type
This section explains the profileType creation process in order to make different comparisons between the actual user's consumption and its profile type.
## Profile type data
The profileType data are stored in the profile doctype and includes the following information :
```jsx
```ts
{
housingType: HousingType
constructionYear: ConstructionYear
......@@ -35,22 +37,22 @@ Here is the flow of questions:
![ProfileTypeForm](/img/profile_type/profile_type_form.png)
## Profile types handling over time
A user can have many profileTypes, Ecolyo takes into account that one can move from his home, have more occupants, start renovating works and so on.
That's why a profileType is only active for a given time period, this is how its time logic works.
#### No filled profileType
### No filled profileType
A default profileType is loaded in redux to operate basic operations. When the user looks at its analysis or options, ecolyo suggest user to fill a more accurate profileType.
#### First profileType
### First profileType
The profileType will follow the form logic above (see ProfileType form section). *updateDate* field will be the current month and year.
Since this profileType will be the only one in database, *getProfileType()* method will always return it, therefore it will be used for all past time period on analysis.
#### Following profileTypes
### Following profileTypes
Each new profileType form will show a calendar picking section at the end of the form.
By default, current month and year will be selected.
......@@ -58,6 +60,7 @@ By default, current month and year will be selected.
If current year is not yet completed (december not reached), month dropdown menu will only propose past and present months for this year.
When finishing, before the new profileType is saved. Checks if other profileTypes exist on the period between selected month/year and present day.
- If profileTypes are found, they are deleted (newest profileType always prevails on older ones, so that user had forgotten to fill some information before, this new profiletype will be more accurate). Then save profileType on given month/year.
- If no other profileTypes are found, save profileType on given month/year.
......@@ -97,7 +100,7 @@ Here you can see the different methods provided by the profileType service. Thes
Here is an example of a MonthlyForecast, which is the only function directly called by the analysis component :
```jsx
```ts
{
fluidForecast: [
{
......@@ -148,14 +151,15 @@ Also, we consider that if the heating or the hotwater are collective, we don't c
## DJU
The method **fetchDJU(month:number)** tries to fetch the daily dju from the datagrandlyon API trough a remote doctype named _org.ecolyo.dju_.
The method **fetchDJU(month:number)** tries to fetch the daily dju from the datagrandlyon API trough a remote doctype named *org.ecolyo.dju*.
The data returned by this API are gathered by the lyon-bron-station The API returns dju by day for a given month, so we add them to return a monthly dju. If remote doctype fails or return a null value, we returns instead the default dju stored in _heating.json_
Useful tips while working with this API :
- Do not pass a Content-Type while requesting, it will returns error
- While requesting from a cozy instance, if you get errors, you will get errors from the cozy stack and not directly from the API, which leads to weird cases :
- If there is an authentication error, the api will returns an error in _html_ format to cozy, so you'll get from cozy an error 502 as following, because cozy expects a json response :
- If there is an authentication error, the api will returns an error in *html* format to cozy, so you'll get from cozy an error 502 as following, because cozy expects a json response :
```json
{
"status": "502",
......@@ -164,4 +168,5 @@ Useful tips while working with this API :
"source": {}
}
```
- In case of bad request (wrong parameters for example), the API will return an error in _xml_ format so you'll get exactly the same error as above in your cozy instance.
- In case of bad request (wrong parameters for example), the API will return an error in *xml* format so you'll get exactly the same error as above in your cozy instance.
# Terms
This section explains the way we handle terms in the application.
## Description
......@@ -13,7 +15,6 @@ The only public routes are :
- _/cgu_ : shows the CGU public page, accessible by the terms page
- _/legal_ : shows the Legal Notice public page, accessible by the terms page
### Terms management
We check the terms acceptation in the **splash screen** while the application is initializing, if there is no consent (first connection), or the consent is outdated (update of terms), the user will be redirected to the terms acceptation page.
......@@ -21,7 +22,8 @@ We check the terms acceptation in the **splash screen** while the application is
For the full terms acceptation process, the user has to check the two checkboxes (one for Data share consent, and one for CGU and Legal Notice) to unlock the terms acceptation button. Once he has accepted it, a new term doctype is created with the value _accepted_ to true. So he can access now the entire application.
We store in user's profile a boolean _showConsentModal_ that allows the app to know about the consent status.
If there is a consent update, two cases are possible :
If there is a consent update, two cases are possible :
- It's a major update, ex: from 1.X.X to 2.X.X, the user has to go through the entire term validation process as explained above
- It's a minor update, ex: from 1.1.X to 1.3.X or from 1.2.1 to 1.2.3, the user is just prompted with a modal with some text about the update, and a link to the legal notice, but there is no blocking acceptation input for the user.
......@@ -35,7 +37,7 @@ Once the verification done in the **splash screen**, the last term state is stor
The model is the following :
```
```ts
termsStatus: {
accepted: boolean,
versionType: 'major' | 'minor' | 'init',
......
......@@ -59,7 +59,7 @@ More technical information are available [here](/ecolyo/services/aggregator_usag
All indicator are post to a remote doctype, which will allow the application to read a defined external API. This doctype is created by Cozy itself.
Here are the actual structure of this remote doctype:
```
```ts
{
source: string
name: string
......
# Launch the application on local
This section will allow you to launch a proper local environment of the Ecolyo application
## Initialisation of the project
### Clone the project repository
Use following command in your favorite terminal to clone the project:
Clone the project repository using the following command
```
```sh
git clone https://forge.grandlyon.com/web-et-numerique/llle_project/ecolyo.git
```
## Installation of the project
### Installation of node modules
### Start the app
To install required node module, open a terminal on the root folder of the project and type the following command:
Install required node modules, open a terminal on the root folder of the project and type the following command:
```
```sh
yarn install
```
### Start Ecolyo application
Start ecolyo application just launch the command:
To start ecolyo application just launch the command:
```
```sh
yarn start
```
If the application starts successfully you should obtain the following message:
> App successfully compiled!
> Dev assets:http://localhost:8888
> App successfully compiled!
> Dev assets: 'http://localhost:8888'
Once the application is started, run the easy-cozy stack with docker.
#### On windows and linux
### Start cozy stack
Launch the stack with the following command:
```
```sh
docker-compose up
```
If you have an access denied issue, try to docker login
```
docker login registry.forge.grandlyon.com
```
!!! note "If you have an access denied issue, try to docker login"
```sh
docker login registry.forge.grandlyon.com
```
A Powershell window will open. Wait until the success message:
Wait until the success message:
> Everything is setup. Go to http://ecolyo.cozy.tools:8080/
> Everything is setup. Go to http://ecolyo.cozy.tools:8080/
> To exit, press ^C
Once successful you can launch your local cozy with following url: [Cozy local url](http://cozy.tools:8080/)
......@@ -62,13 +58,14 @@ Local database can also be consulted at the following url: [Cozy local DB](http:
## Use local konnectors
In most case you will use mocked konnectors with mock data, but for some testing goals you will need real accounts.
In local, it is possible to run EGL en SGE-Enedis konnectors, with real accounts, but it needs some specific manipulation as well as you'll need to use api secrets that are, of course, basically not available in the project. If you need to use konnectors with real accounts in testing goals, please follow the following steps. Otherwise, refer to the next two sections 'Import Mock Data' et 'Simulate konnector connections'.
In local, it is possible to run EGL en SGE-Enedis konnectors, with real accounts, but it needs some specific manipulation as well as you'll need to use api secrets that are, of course, basically not available in the project. If you need to use konnectors with real accounts in testing goals, please follow the following steps. Otherwise, refer to the next two sections 'Import Mock Data' et 'Simulate konnector connections'.
First step, make sure your stack is running. Then open your [CouchDB](http://localhost:5984/_utils/) and look for the ```secrets/io-cozy-account_types``` entry.
Then add a new document like this :
EGL Example
```
```json
{
"_id": "eglgrandlyon",
"grant_mode": "secret",
......@@ -79,8 +76,10 @@ EGL Example
}
}
```
SGE Enedis example
```
```json
{
"_id": "enedis-sge-grandlyon",
"grant_mode": "secret",
......@@ -93,6 +92,7 @@ SGE Enedis example
}
}
```
!!! info ""
You'll need to use konnector slug as is to make it work properly
......@@ -104,11 +104,11 @@ Once it is done, you will be able to use these 2 Konnectors with real accounts.
## Import mock data
!!! info "Requirement"
!!! info "Requirement"
Your dev stack should be running to import the mock data
First install ACH using yarn :
```
```sh
yarn global add cozy-ach
```
......@@ -117,7 +117,7 @@ Next create the "config.js" file base on the "config.template.js"
!!! info ""
You can change the period of data generated by changing the following lines:
```
```js
const startingdate = DateTime.local()
.plus({ days: -120 })
.startOf('day')
......@@ -128,25 +128,24 @@ Next create the "config.js" file base on the "config.template.js"
Just replace -120 by the value needed
Next launch the script **createDayDataFiles.js** available into the **scripts** folder
Next launch the script `createDayDataFiles.js` available into the `scripts` folder
```
cd scripts
node createDayDataFiles.js
```sh
node scripts/createDayDataFiles.js
```
Json files with data will be created into **scripts/data** folder.
ACH script "importData.bat" will load the content of the file into your CouchDB (database of your dev stack). Launch it using following commands:
Json files with data will be created into `scripts/data` folder.
ACH script `importData.bat` will load the content of the file into your CouchDB (database of your dev stack). Launch it using following commands:
```
```sh
cd scripts
./importData.bat
```
!!! info ""
If you cannot execute ```ACH``` after this command, it may be because you do not have the directory where yarn stores its symbolic links in your ```PATH```. Edit it to append the result of ```yarn global bin```.
If you cannot execute `ACH` after this command, it may be because you do not have the directory where yarn stores its symbolic links in your `PATH`. Edit it to append the result of `yarn global bin`.
You'll be prompted for a cozysessid, you can get it in the web console ; in the `application` tab, look for the cookies and just copy the cozysessid value.
You'll be prompted for a **cozysessid**, you can get it in the web console : in the `application` tab, look for the cookies and just copy the cozysessid value.
A new browser windows will open and asking you approval to import data. Just click on **Approve**
......@@ -162,22 +161,21 @@ To simulate the connection you can use the script **createConnection.js** availa
First update the authorization and cookie information from the "config.js" file (if not created just create it from the "config.template.js" file):
```
```js
const authorization =
'Bearer xxxxxxxxxxx'
const cookie =
'cozysessid=xxxxxxxxxxx'
```
To obtain your own Bearer and cozysessid you need to have the application launched and display the web console (F12) in your navigator and select the Network tab. Just select one request and retrieve information for Request Header:
To obtain your own Bearer and cozysessid you need to have the application launched and display the web console (F12) in your navigator and select the **Network tab**. Just select one request and retrieve information for Request Header:
![Bearer&cozysessid](/img/bearer_cozysessid.png)
Next launch the script :
```
cd scripts
node createConnections.js
```sh
node scripts/createConnections.js
```
Your data is now loaded and you can refresh the application to see your konnector connected.
# Launch a konnector on local
## Cozy resources
Please see also the [official cozy documentation](https://docs.cozy.io/en/cozy-konnector-libs/).
......@@ -22,4 +24,3 @@ This file needs to hold all the information transmitted by the cozy stack when t
Type them all in the *fields* object.
All data recovered by the standalone konnector will be stored in the *data* folder.
# Ecolyo
![ecolyo](../img/ecolyo.png){: .center}
Ecolyo is a multi-fluid application solution towards users of the grand lyon metropolis to monitor and optimize their energy consumption.
This is a [Cozy](https://docs.cozy.io/en/) application that allows users to connect their energy accounts such as **EGL**, **ENEDIS** and **GRDF**, using cozy [konnectors](https://docs.cozy.io/en/cozy-stack/konnectors/).
!!! danger "Reminder"
If you're a new developer tasked to work on this project, please get acquainted with the team [processes](https://forge.grandlyon.com/web-et-numerique/wiki_web_num) and read the advised [dev environment](https://forge.grandlyon.com/web-et-numerique/wiki_web_num) documentation and the self-data [prerequisites](../index.md#installing-prerequisites).
## ![gitlab](../img/gitlab-logo.svg) Repositories
- [ecolyo](https://forge.grandlyon.com/web-et-numerique/llle_project/ecolyo)
- [ecolyo-agent server](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-server)
- [ecolyo-agent client](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-client)
\ No newline at end of file
- [Ecolyo](https://forge.grandlyon.com/web-et-numerique/llle_project/ecolyo)
- [Ecolyo.com](https://forge.grandlyon.com/web-et-numerique/llle_project/ecolyo_landing_page)
- Ecolyo Agent
- [Ecolyo-agent server](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-server)
- [Ecolyo-agent client](https://forge.grandlyon.com/web-et-numerique/llle_project/backoffice-client)
## Konnectors
Ecolyo heavily rely on konnectors to work, check our [konnector documentation](../konnectors/index.md).