Skip to content

Commit 8773aa5

Browse files
emjay0921emjay0921
committed
docs(spp_aggregation,spp_metrics_core,spp_metrics_services): add README files
1 parent 4612b0d commit 8773aa5

6 files changed

Lines changed: 481 additions & 0 deletions

File tree

‎spp_aggregation/README.rst‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
==========================
2+
OpenSPP Aggregation Engine
3+
==========================
4+
5+
..
6+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7+
!! This file is generated by oca-gen-addon-readme !!
8+
!! changes will be overwritten. !!
9+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
10+
!! source digest: sha256:9951d094574dd68b1d86ae2167e53c5ccea5240188acf11a2b7f619ede6c5b54
11+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
12+
13+
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
14+
:target: https://odoo-community.org/page/development-status
15+
:alt: Beta
16+
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
17+
:target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
18+
:alt: License: LGPL-3
19+
.. |badge3| image:: https://img.shields.io/badge/github-OpenSPP%2FOpenSPP2-lightgray.png?logo=github
20+
:target: https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_aggregation
21+
:alt: OpenSPP/OpenSPP2
22+
23+
|badge1| |badge2| |badge3|
24+
25+
Unified aggregation engine for computing statistics, breakdowns, and
26+
fairness metrics over scoped registrant populations. Supports multiple
27+
scope types (CEL expressions, areas, spatial queries, explicit IDs) with
28+
access control, caching, and privacy enforcement.
29+
30+
Key Capabilities
31+
~~~~~~~~~~~~~~~~
32+
33+
- Define reusable aggregation scopes: CEL expression, area, area tag,
34+
spatial polygon/buffer, or explicit registrant IDs
35+
- Resolve scopes to registrant sets with union and intersection
36+
operations
37+
- Compute statistics (count, Gini) with extensible statistic registry
38+
supporting CEL variables
39+
- Role-based access control with per-user scope type restrictions,
40+
dimension limits, and area constraints
41+
- Result caching with configurable TTL per scope type and automatic
42+
cleanup
43+
- Privacy enforcement via k-anonymity suppression on computed results
44+
- Convenience methods for area-based, expression-based, fairness, and
45+
distribution queries
46+
47+
Key Models
48+
~~~~~~~~~~
49+
50+
+----------------------------+----------+----------------------------+
51+
| Model | Type | Description |
52+
+============================+==========+============================+
53+
| ``spp.aggregation.scope`` | Concrete | Configurable aggregation |
54+
| | | scope definitions |
55+
+----------------------------+----------+----------------------------+
56+
| ``spp | Concrete | Per-user/group access |
57+
| .aggregation.access.rule`` | | control rules |
58+
+----------------------------+----------+----------------------------+
59+
| ``spp | Concrete | Persistent cache entries |
60+
| .aggregation.cache.entry`` | | with TTL |
61+
+----------------------------+----------+----------------------------+
62+
| ``spp.ag | Abstract | Strategy-based scope |
63+
| gregation.scope.resolver`` | | resolution service |
64+
+----------------------------+----------+----------------------------+
65+
| ``spp.aggregation.cache`` | Abstract | Cache service with TTL and |
66+
| | | cleanup |
67+
+----------------------------+----------+----------------------------+
68+
| ``spp.aggreg | Abstract | Statistic computation |
69+
| ation.statistic.registry`` | | registry (builtins + CEL) |
70+
+----------------------------+----------+----------------------------+
71+
| ` | Abstract | Main aggregation entry |
72+
| `spp.aggregation.service`` | | point |
73+
+----------------------------+----------+----------------------------+
74+
75+
Configuration
76+
~~~~~~~~~~~~~
77+
78+
- Aggregation scopes: **Settings > Aggregation > Aggregation Scopes**
79+
- Access rules: **Settings > Aggregation > Access Rules**
80+
- Cache cleanup runs daily via scheduled action
81+
82+
Security
83+
~~~~~~~~
84+
85+
+----------------------------------+----------------------------------+
86+
| Group | Access |
87+
+==================================+==================================+
88+
| ``spp_aggr | Read-only access to scopes and |
89+
| egation.group_aggregation_read`` | cache |
90+
+----------------------------------+----------------------------------+
91+
| ``spp_aggre | Read/write scopes and access |
92+
| gation.group_aggregation_write`` | rules |
93+
+----------------------------------+----------------------------------+
94+
| ``spp_aggreg | Implied by write group |
95+
| ation.group_aggregation_viewer`` | |
96+
+----------------------------------+----------------------------------+
97+
| ``spp_aggrega | Implied by viewer group |
98+
| tion.group_aggregation_officer`` | |
99+
+----------------------------------+----------------------------------+
100+
| ``spp_aggrega | Full access, implied by admin |
101+
| tion.group_aggregation_manager`` | |
102+
+----------------------------------+----------------------------------+
103+
104+
Dependencies
105+
~~~~~~~~~~~~
106+
107+
``base``, ``spp_cel_domain``, ``spp_area``, ``spp_registry``,
108+
``spp_security``, ``spp_metrics_services``
109+
110+
**Table of contents**
111+
112+
.. contents::
113+
:local:
114+
115+
Bug Tracker
116+
===========
117+
118+
Bugs are tracked on `GitHub Issues <https://github.com/OpenSPP/OpenSPP2/issues>`_.
119+
In case of trouble, please check there if your issue has already been reported.
120+
If you spotted it first, help us to smash it by providing a detailed and welcomed
121+
`feedback <https://github.com/OpenSPP/OpenSPP2/issues/new?body=module:%20spp_aggregation%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
122+
123+
Do not contact contributors directly about support or help with technical issues.
124+
125+
Credits
126+
=======
127+
128+
Authors
129+
-------
130+
131+
* OpenSPP.org
132+
133+
Maintainers
134+
-----------
135+
136+
.. |maintainer-jeremi| image:: https://github.com/jeremi.png?size=40px
137+
:target: https://github.com/jeremi
138+
:alt: jeremi
139+
140+
Current maintainer:
141+
142+
|maintainer-jeremi|
143+
144+
This module is part of the `OpenSPP/OpenSPP2 <https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_aggregation>`_ project on GitHub.
145+
146+
You are welcome to contribute.

‎spp_aggregation/readme/DESCRIPTION.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
Unified aggregation engine for computing statistics, breakdowns, and fairness metrics over scoped registrant populations. Supports multiple scope types (CEL expressions, areas, spatial queries, explicit IDs) with access control, caching, and privacy enforcement.
2+
3+
### Key Capabilities
4+
5+
- Define reusable aggregation scopes: CEL expression, area, area tag, spatial polygon/buffer, or explicit registrant IDs
6+
- Resolve scopes to registrant sets with union and intersection operations
7+
- Compute statistics (count, Gini) with extensible statistic registry supporting CEL variables
8+
- Role-based access control with per-user scope type restrictions, dimension limits, and area constraints
9+
- Result caching with configurable TTL per scope type and automatic cleanup
10+
- Privacy enforcement via k-anonymity suppression on computed results
11+
- Convenience methods for area-based, expression-based, fairness, and distribution queries
12+
13+
### Key Models
14+
15+
| Model | Type | Description |
16+
| ---------------------------------- | -------- | ------------------------------------------------- |
17+
| `spp.aggregation.scope` | Concrete | Configurable aggregation scope definitions |
18+
| `spp.aggregation.access.rule` | Concrete | Per-user/group access control rules |
19+
| `spp.aggregation.cache.entry` | Concrete | Persistent cache entries with TTL |
20+
| `spp.aggregation.scope.resolver` | Abstract | Strategy-based scope resolution service |
21+
| `spp.aggregation.cache` | Abstract | Cache service with TTL and cleanup |
22+
| `spp.aggregation.statistic.registry` | Abstract | Statistic computation registry (builtins + CEL) |
23+
| `spp.aggregation.service` | Abstract | Main aggregation entry point |
24+
25+
### Configuration
26+
27+
- Aggregation scopes: **Settings > Aggregation > Aggregation Scopes**
28+
- Access rules: **Settings > Aggregation > Access Rules**
29+
- Cache cleanup runs daily via scheduled action
30+
31+
### Security
32+
33+
| Group | Access |
34+
| --------------------------------------- | ----------------------------------------- |
35+
| `spp_aggregation.group_aggregation_read` | Read-only access to scopes and cache |
36+
| `spp_aggregation.group_aggregation_write` | Read/write scopes and access rules |
37+
| `spp_aggregation.group_aggregation_viewer` | Implied by write group |
38+
| `spp_aggregation.group_aggregation_officer` | Implied by viewer group |
39+
| `spp_aggregation.group_aggregation_manager` | Full access, implied by admin |
40+
41+
### Dependencies
42+
43+
`base`, `spp_cel_domain`, `spp_area`, `spp_registry`, `spp_security`, `spp_metrics_services`

‎spp_metrics_core/README.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
====================
2+
OpenSPP Metrics Core
3+
====================
4+
5+
..
6+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7+
!! This file is generated by oca-gen-addon-readme !!
8+
!! changes will be overwritten. !!
9+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
10+
!! source digest: sha256:081ca8abe85eada71f0faa5c94d74dedc85e51f41225ae0969a971fc99230833
11+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
12+
13+
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
14+
:target: https://odoo-community.org/page/development-status
15+
:alt: Beta
16+
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
17+
:target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
18+
:alt: License: LGPL-3
19+
.. |badge3| image:: https://img.shields.io/badge/github-OpenSPP%2FOpenSPP2-lightgray.png?logo=github
20+
:target: https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_metrics_core
21+
:alt: OpenSPP/OpenSPP2
22+
23+
|badge1| |badge2| |badge3|
24+
25+
Unified metric foundation providing abstract base models for statistics,
26+
simulations, and reporting across OpenSPP modules.
27+
28+
Key Capabilities
29+
~~~~~~~~~~~~~~~~
30+
31+
- Abstract base model for defining reusable metrics with label, unit,
32+
and decimal precision
33+
- Hierarchical metric categories with unique code constraints
34+
- Category tree with parent-child recursion prevention
35+
- Default metric categories for population, coverage, targeting, and
36+
distribution
37+
38+
Key Models
39+
~~~~~~~~~~
40+
41+
+-------------------------+----------+----------------------------+
42+
| Model | Type | Description |
43+
+=========================+==========+============================+
44+
| ``spp.metric.base`` | Abstract | Base fields and logic |
45+
| | | inherited by concrete |
46+
| | | metrics |
47+
+-------------------------+----------+----------------------------+
48+
| ``spp.metric.category`` | Concrete | Hierarchical grouping of |
49+
| | | metrics by domain |
50+
+-------------------------+----------+----------------------------+
51+
52+
Configuration
53+
~~~~~~~~~~~~~
54+
55+
No configuration required. Default categories are created via data files
56+
on install.
57+
58+
Dependencies
59+
~~~~~~~~~~~~
60+
61+
``base``
62+
63+
**Table of contents**
64+
65+
.. contents::
66+
:local:
67+
68+
Bug Tracker
69+
===========
70+
71+
Bugs are tracked on `GitHub Issues <https://github.com/OpenSPP/OpenSPP2/issues>`_.
72+
In case of trouble, please check there if your issue has already been reported.
73+
If you spotted it first, help us to smash it by providing a detailed and welcomed
74+
`feedback <https://github.com/OpenSPP/OpenSPP2/issues/new?body=module:%20spp_metrics_core%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
75+
76+
Do not contact contributors directly about support or help with technical issues.
77+
78+
Credits
79+
=======
80+
81+
Authors
82+
-------
83+
84+
* OpenSPP.org
85+
86+
Maintainers
87+
-----------
88+
89+
.. |maintainer-jeremi| image:: https://github.com/jeremi.png?size=40px
90+
:target: https://github.com/jeremi
91+
:alt: jeremi
92+
.. |maintainer-gonzalesedwin1123| image:: https://github.com/gonzalesedwin1123.png?size=40px
93+
:target: https://github.com/gonzalesedwin1123
94+
:alt: gonzalesedwin1123
95+
96+
Current maintainers:
97+
98+
|maintainer-jeremi| |maintainer-gonzalesedwin1123|
99+
100+
This module is part of the `OpenSPP/OpenSPP2 <https://github.com/OpenSPP/OpenSPP2/tree/19.0/spp_metrics_core>`_ project on GitHub.
101+
102+
You are welcome to contribute.

‎spp_metrics_core/readme/DESCRIPTION.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Unified metric foundation providing abstract base models for statistics, simulations, and reporting across OpenSPP modules.
2+
3+
### Key Capabilities
4+
5+
- Abstract base model for defining reusable metrics with label, unit, and decimal precision
6+
- Hierarchical metric categories with unique code constraints
7+
- Category tree with parent-child recursion prevention
8+
- Default metric categories for population, coverage, targeting, and distribution
9+
10+
### Key Models
11+
12+
| Model | Type | Description |
13+
| --------------------- | -------- | ------------------------------------------------ |
14+
| `spp.metric.base` | Abstract | Base fields and logic inherited by concrete metrics |
15+
| `spp.metric.category` | Concrete | Hierarchical grouping of metrics by domain |
16+
17+
### Configuration
18+
19+
No configuration required. Default categories are created via data files on install.
20+
21+
### Dependencies
22+
23+
`base`

0 commit comments

Comments
 (0)