metrics.md in decidim-0.18.0

- old
+ new
@@ -19,36 +19,98 @@
   ```ruby
   bundle exec rake decidim:metrics:all["YYYY-MM-DD"]
   bundle exec rake decidim:metrics:one["<metric name>","YYYY-MM-DD"]
   ```
 
-## Current available metric names
+- It is possible to rebuild one or all metrics since some specific day. This is useful in case current metrics are no generated or corrupt. **Depending on the size of the database this can take a long time!**. The command will execute the same calculations as the commands above for **each** day between *today* and the date specified.
 
-- *users*, created `Users`
-- *proposals*, published, not withdrawn and not *hidden* `Proposals`
-- *accepted_proposals*, accepted `Proposals`
-- *supports*, supports in `Proposals`
-- *assemblies*, published `Assemblies`
-- *participatory_processes*, published `ParticipatoryProcesses`
-- *results*, `Results` in `Accountability`
-- *comment*, `Comments` generated by users, related to public elements and not *hidden*
-- *meetings*, public `Meetings`
+- To rebuild metrics since a given date (all or an specific one)
 
+  ```ruby
+  bundle exec rake decidim:metrics:rebuild["YYYY-MM-DD"]
+  bundle exec rake decidim:metrics:rebuild["<metric name>","YYYY-MM-DD"]
+  ```
+
+## Available metrics
+
+- Use the command `decidim:metrics:list` to list all available metrics using the console:
+
+```ruby
+bundle exec rake decidim:metrics:list
+```
+Currently, available metrics are:
+
+- **users**, created `Users`
+- **proposals**, published, not withdrawn and not *hidden* `Proposals`
+- **accepted_proposals**, accepted `Proposals`
+- **supports**, supports given to `Proposals`
+- **assemblies**, published `Assemblies`
+- **participatory_processes**, published `ParticipatoryProcesses`
+- **results**, `Results` in `Accountability`
+- **comments**, `Comments` generated by users, related to public elements and not *hidden*
+- **meetings**, public `Meetings`
+
 Only available for `ParticipatorySpaces` (restricted to `ParticipatoryProcesses`)
 
-- *participants*: unique users who make at least one of the following actions
-  - Create a proposal
-  - Create a debate
+- **participants**, unique users who make at least one of the following actions:
   - Answer a survey
+  - Create a debate
+  - Create a proposal
+  - Endorse a proposal
   - Leave a comment
-  - Give support to a proposal
-  - Endorse
+  - Support a proposal
   - Vote a participatory budgeting project
-- *followers*: unique users who follow any participatory element in a `ParticipatorySpace`
-- *endorsements*: number of `Endorsements` in `Proposals`, within a `ParticipatorySpace`
-- *debates*: number of `Debates` within a `ParticipatorySpace`
-- *survey_answers*: number of answered `Surveys` by users within a `ParticipatorySpace`
+- **followers**, unique users who follow any participatory element in a `ParticipatorySpace`
+- **endorsements**, number of `Endorsements` in `Proposals`, within a `ParticipatorySpace`
+- **debates**, number of `Debates` within a `ParticipatorySpace`
+- **survey_answers**, number of answered `Surveys` by users within a `ParticipatorySpace`
 
-## To configure it correctly
+## Configuration
 
 - A **crontab** line must be added to your server to maintain them updated daily. You could use [Whenever](https://github.com/javan/whenever) to manage it directly from the APP
 - An **ActiveJob** queue, like [Sidekiq](https://github.com/mperham/sidekiq) or [DelayedJob](https://github.com/collectiveidea/delayed_job/)
+
+## Persistence
+
+The metrics module percomutes calculations and persists them into
+`decidim_metrics` database table. So this module only uses one single table to
+persist metrics from all times and types.
+
+The `decidim_metrics` table has the following fields:
+
+- `day`: the day for which the metric has been computed.
+- `metric_type`: the type of the metric. One of: users, proposals,
+accepted_proposals, supports, assemblies.
+- `cumulative`: quantity accumulated to day ”day”.
+- `quantity`:  quantity for the current day, ”day”.
+- `decidim_organization_id`: the FK to the organization to which this Metric
+belongs to.
+- `participatory_space_type` + `participatory_space_id`: the FK to the
+participatory space to which this Metric belongs to, if any.
+- `related_object_type` + `related_object_id`: the FK to the object to which
+this Metric belongs to, if any.
+- `decidim_category_id`: the FK to the category for this Metric, if any.
+
+Relations around `decidim_metrics` table:
+```
+                                                    +------------------------+
++--------------+                                    | ParticipatoryProcesses |
+| Organization |                               +----+------------------------+
++------+-------+                               |
+       |            +--------------------+     |    +------------+
+       |            |                    |     +----+ Assemblies |
+       |     +----->+ ParticipatorySpace +<----+    +------------+
+       |     |      |                    |     |    +-------------+
+       |     |      +--------------------+     +----+ Initiatives |
+       |     |                                 |    +-------------+
+       |     |                                 |
+       |     |                                 |    +---------------+
+ +-----+-------+---+                           +----+ Consultations |
+ |                 |                                +---------------+
+ | decidim_metrics |
+ |                 |
+ +--------+--------+       +----------------+
+          |                | related_object |
+          +--------------->+                |
+                           | [polymorphic]  |
+                           +----------------+
+```