add spreadsheet_dashboard_pos_cooperative & pos_dashboard_cooperative

spreadsheet_dashboard_pos_cooperative/readme/USAGE.rst

@@ -0,0 +1,149 @@
+Open *Dashboards → Cooperative* in the Odoo backend. Four dashboards
+are published:
+
+The workbook content (titles, KPI labels, table headers, scorecard
+descriptions) is available in **English (source) and Spanish** out of
+the box. Users with ``lang = es_ES`` will see all in-cell texts in
+Spanish; the rest of the locales can be added by translating the
+``i18n/spreadsheet_dashboard_pos_cooperative.pot`` template.
+
+Note: the dashboard names shown in the *Dashboards* menu sidebar
+(*POS Overview*, *POS Members*, *POS Categories*, *POS Sales by
+Time*) are not translatable because ``spreadsheet.dashboard.name`` is
+not declared as a translatable field in Odoo core.
+
+POS Overview
+============
+
+Headline KPIs and monthly evolution for the whole store.
+
+* **Sales (€)** — sum of ``price_total`` over orders in the period.
+* **Orders** — count of distinct ``order_id``.
+* **Average ticket (€)** — ``Sales / Orders``.
+* **Gross margin (€)** — sum of ``margin``.
+* A line chart with monthly sales evolution.
+
+POS Members
+===========
+
+Detailed comparison between cooperative members and non-members. For
+each group the dashboard shows:
+
+* Sales (€), Orders, Average ticket (€), UPT, Distinct buyers, and
+  (members only) Frequency.
+* Monthly evolution chart with one line per group.
+* TOP 50 buying members (ranked by sales), with sales, orders, units,
+  average ticket and UPT.
+
+POS Categories
+==============
+
+Members contribution KPIs and the top product breakdowns.
+
+* **Members sales (€)** — sales from orders where the customer was a
+  cooperative member at the order date.
+* **Purchase share** — ``members sales / total sales``.
+* **Members penetration** — ``distinct members buyers / distinct total
+  buyers`` (see "Metric definitions" below for the caveat).
+* TOP 10 product families (root categories) with sales, orders, share %.
+* TOP 10 product subfamilies (parent categories) with the same columns.
+* TOP 10 products with sales, units, share %.
+
+POS Sales by Time
+=================
+
+* Line chart of sales by ISO day of the week (1 = Monday, 7 = Sunday).
+* Line chart of sales by hour of the day (0..23).
+
+Global filters
+==============
+
+Every dashboard ships a ``Period`` date filter. Members, Categories
+and Sales by Time also ship ``Product Category``, ``Product`` and
+(Members only) ``Member`` relation filters. Each filter is wired to
+every pivot and chart on the dashboard, so changing one selection
+updates the whole view.
+
+* **Period** — year picker plus a month dropdown
+  (January..December). Pick a year only to look at the full year
+  (e.g. *2026*, *2025*), or add a month to narrow the range (e.g.
+  *March 2026*). Defaults to the current month.
+* **Product Category** — relation picker over ``product.category``.
+  Choose one or more categories to restrict every metric to products
+  of those categories. Empty = no restriction.
+* **Product** — relation picker over ``product.product``. Useful to
+  audit a specific reference.
+* **Member** — relation picker over ``res.partner``. Available only
+  on the Members dashboard; restricts the comparison and the TOP 50
+  to the selected partners.
+
+Note: the o-spreadsheet date filter in Odoo 16 only accepts a single
+``rangeType`` per filter (year, quarter or month). We chose ``month``
+because it is the finest granularity the customer requested; for
+year-only views, just pick a year and leave the month dropdown
+unset. Rolling ranges (*Last 30 / 90 / 180 days*) and quarter
+selection (*Q1..Q4*) are not available on the spreadsheet filters;
+both are handled in ``pos_dashboard_cooperative`` through the
+standard search view on *Point of Sale → Reporting → Cooperative
+Dashboards*, which exposes the usual Odoo date filters.
+
+Metric definitions
+==================
+
+The BI brief from the customer left several KPIs without a precise
+formulation. The dashboards use the following standard retail
+definitions; revise them in the JSON if your cooperative prefers a
+different convention.
+
+* **UPT** (Units per Ticket) = ``total units sold / number of
+  orders``. ``product_qty`` summed and divided by distinct
+  ``order_id``.
+* **Frequency** = ``number of orders / number of distinct buyers``.
+  Measures how many tickets the average member buyer made in the
+  period.
+* **Average ticket (€)** = ``total sales / number of orders``. POS has
+  no separate "average ticket value", so this metric matches the
+  "Ticket medio" and "Valor medio del ticket" rows in the BI brief.
+* **Purchase share %** = ``members sales / total sales``. Share of
+  total revenue contributed by member-driven orders.
+* **Members penetration %** = ``distinct member buyers / distinct
+  total buyers`` *in the selected period*. Note: a stricter definition
+  would be ``distinct member buyers / total members in the
+  cooperative`` (regardless of whether they bought). That denominator
+  is not exposed by ``report.pos.order``; a future iteration may add a
+  separate KPI sourced from ``share.line``.
+* **Sales concentration** (not yet rendered) would be the share of
+  sales captured by the top X% of buying members, typically X = 20.
+  Easy to add later from the same ``Top buyers`` pivot.
+
+Iterating on the layouts
+========================
+
+Each dashboard is a ``data/files/*.json`` file shipped as a base64
+binary on a ``spreadsheet.dashboard`` record. They are intentionally
+small and hand-authored to be diff-friendly.
+
+To redesign one of them visually:
+
+1. Install ``spreadsheet_oca`` (from OCA's ``spreadsheet`` repository)
+   on top of this module. It provides full o-spreadsheet editing in
+   the backend, including saving back to ``spreadsheet.dashboard``.
+2. Open the dashboard in *Dashboards → Cooperative*.
+3. Edit pivots, charts, styles and global filters from the
+   o-spreadsheet UI. The data sources are pre-wired against
+   ``report.pos.order`` and consume the dimensions exposed by
+   ``pos_dashboard_cooperative``:
+
+   * ``is_member_at_date`` (boolean) — cooperative member flag at the
+     order date.
+   * ``categ_root_id`` / ``categ_parent_id`` — product family /
+     subfamily.
+   * ``hour_of_day`` / ``day_of_week`` — time distributions.
+
+4. Export the workbook to JSON.
+5. Replace the matching ``data/files/<name>.json`` and reinstall (or
+   upgrade) the module.
+
+Reference: the same workflow is used by Odoo core's
+``spreadsheet_dashboard_sale``, ``spreadsheet_dashboard_purchase`` and
+similar modules.