reference: stats: add document for order and document request stats

Author: JakobMiesner

docs/customize/configure.md

@@ -166,6 +166,16 @@ EXTEND_LOANS_SCHEDULE_TIME = datetime.time(2)
 
 Enable or disable Self-Checkout feature.
 
+### ILS_EXTEND_INDICES_WITH_STATS_ENABLED (True/False)
+
+Enable or disable extended statistics fields in record indices. When enabled, additional computed fields are indexed for loans, acquisition orders, and document requests to support KPI reporting.
+
+```python
+ILS_EXTEND_INDICES_WITH_STATS_ENABLED = True
+```
+
+See the statistics reference for available fields: [Loans](../reference/stats/loan_stats.md#stats-fields), [Acquisition Orders](../reference/stats/acquisition_orders.md#stats-fields), [Document Requests](../reference/stats/document_requests.md#stats-fields). See the [v7 upgrade guide](../releases/version7/upgrade.md) for setup instructions.
+
 ## JSONSchemas Configuration
 
 ### JSONSCHEMAS_HOST

docs/reference/stats/acquisition_orders.md

@@ -0,0 +1,28 @@
+# Acquisition Order Statistics
+
+See [Histogram Endpoints](histogram.md) for general parameter documentation.
+
+```
+GET /api/acquisition/stats
+```
+
+## Stats Fields
+
+The following fields are added to acquisition orders specifically for statistics. They require [`ILS_EXTEND_INDICES_WITH_STATS_ENABLED`](../../customize/configure.md#ils_extend_indices_with_stats_enabled-truefalse) to be enabled.
+
+| Field                                 | Description                                                               |
+| ------------------------------------- | ------------------------------------------------------------------------- |
+| `stats.document_request_waiting_time` | Days between related literature request creation and order received date. |
+| `stats.order_processing_time`         | Days between order creation and received date.                            |
+
+## Example
+
+Average order processing time by month:
+
+```shell
+curl --get \
+  --url 'https://127.0.0.1:5000/api/acquisition/stats' \
+  --data-urlencode 'group_by=[{"field":"_created","interval":"1M"}]' \
+  --data-urlencode 'metrics=[{"field":"stats.order_processing_time","aggregation":"avg"}]' \
+  --header 'authorization: Bearer <auth token>'
+```

docs/reference/stats/document_requests.md

@@ -0,0 +1,27 @@
+# Document Request Statistics
+
+See [Histogram Endpoints](histogram.md) for general parameter documentation.
+
+```
+GET /api/document-requests/stats
+```
+
+## Stats Fields
+
+The following fields are added to document requests specifically for statistics. They require [`ILS_EXTEND_INDICES_WITH_STATS_ENABLED`](../../customize/configure.md#ils_extend_indices_with_stats_enabled-truefalse) to be enabled.
+
+| Field                           | Description                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------ |
+| `stats.provider_creation_delay` | Days between document request creation and associated order/borrowing request creation. |
+
+## Example
+
+Average time to create purchase order or borrowing request:
+
+```shell
+curl --get \
+  --url 'https://127.0.0.1:5000/api/document-requests/stats' \
+  --data-urlencode 'group_by=[{"field":"_created","interval":"1M"}]' \
+  --data-urlencode 'metrics=[{"field":"stats.provider_creation_delay","aggregation":"avg"}]' \
+  --header 'authorization: Bearer <auth token>'
+```

docs/reference/stats/histogram.md

@@ -0,0 +1,49 @@
+# Histogram Endpoints
+
+Several record types in InvenioILS expose a `/stats` endpoint for flexible aggregation queries. These endpoints provide real-time aggregation of records from their respective indices, allowing flexible grouping by any field and computation of statistical metrics on numeric fields.
+
+Each response returns the count for the records matching the filter and grouping criteria under the field `doc_count` and the requested aggregated metrics.
+
+## Available Endpoints
+
+| Endpoint                         | Description                     |
+| -------------------------------- | ------------------------------- |
+| `/api/circulation/loans/stats`   | Loan aggregations               |
+| `/api/acquisition/stats`         | Purchase order aggregations     |
+| `/api/document-requests/stats`   | Literature request aggregations |
+
+## Parameters
+
+| Name       | Type       | Location | Required | Description                                                                                                                                                                   |
+| ---------- | ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `group_by` | JSON array | query    | ✓        | Array of grouping definitions. Each item is an object with `field` (required) and `interval` (required for date fields). See [format details below](#group_by-field-format). |
+| `metrics`  | JSON array | query    | ✗        | Array of metric definitions. Each item is an object with `field` (required) and `aggregation` (required). See [format details below](#metrics-field-format).                  |
+| `q`        | string     | query    | ✗        | Search query string for filtering records (uses standard search syntax).                                                                                                      |
+
+### `group_by` Field Format
+
+Each grouping object can be:
+
+- **Term field**: `{"field": "field_name"}` - Groups by exact values (e.g., `state`, `patron_pid`)
+- **Date field**: `{"field": "date_field", "interval": "time_interval"}` - Groups by time intervals
+    - Available intervals for date fields: `1d` (day), `1w` (week), `1M` (month), `1q` (quarter), `1y` (year)
+
+### `metrics` Field Format
+
+Each metrics object is:
+
+- `{"field": "field_name", "aggregation": "aggregation_type"}`
+    - Available aggregation types: `avg` (average), `sum` (total), `min` (minimum), `max` (maximum), `median` (50th percentile)
+
+## Example
+
+Group by month with an average metric:
+
+```shell
+curl --get \
+  --url 'https://127.0.0.1:5000/api/circulation/loans/stats' \
+  --data-urlencode 'group_by=[{"field":"start_date","interval":"1M"}]' \
+  --data-urlencode 'metrics=[{"field":"extension_count","aggregation":"avg"}]' \
+  --header 'content-type: application/json' \
+  --header 'authorization: Bearer <auth token>'
+```

docs/reference/stats/index.md

@@ -2,7 +2,12 @@
 
 InvenioILS exposes statistics through REST API endpoints for analyzing library operations.
 
+Several record types (loans, acquisition orders, document requests) share a common [histogram endpoint](histogram.md) pattern for flexible aggregation queries.
+
 ## Available Statistics
 
+- [Histogram Endpoints](histogram.md) - Flexible aggregation queries for loans, orders, and document requests
 - [Loan Statistics](loan_stats.md) - Loan histogram aggregations and transition tracking
+- [Acquisition Order Statistics](acquisition_orders.md) - Purchase order timing and workflow metrics
+- [Document Request Statistics](document_requests.md) - Literature request fulfillment metrics
 - [Record Changes](record_changes.md) - Track insertions, updates, and deletions per record type

docs/reference/stats/loan_stats.md

@@ -8,45 +8,21 @@ InvenioILS provides two complementary endpoints for analyzing loan data:
 
 ## Loan Histogram
 
-The Loan Histogram endpoint provides real-time aggregation of loan records from the loans index.
-It allows flexible grouping by any field and computation of statistical metrics on numeric fields.
-Each response returns the count for the loans matching the filter and grouping criteria under the field `doc_count` and the requested aggregated metrics.
-
-
-### Endpoint
+See [Histogram Endpoints](histogram.md) for general parameter documentation.
 
 ```
 GET /api/circulation/loans/stats
 ```
 
-### Parameters
-
-| Name       | Type       | Location | Required | Description                                                                                                                                                                  |
-| ---------- | ---------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `group_by` | JSON array | query    | ✓        | Array of grouping definitions. Each item is an object with `field` (required) and `interval` (required for date fields). See [format details below](#group_by-field-format). |
-| `metrics`  | JSON array | query    | ✗        | Array of metric definitions. Each item is an object with `field` (required) and `aggregation` (required). See [format details below](#metrics-field-format).                 |
-| `q`        | string     | query    | ✗        | Search query string for filtering loans (uses standard search syntax).                                                                                                       |
-
-#### `group_by` Field Format
-
-Each grouping object can be:
-
-- **Term field**: `{"field": "field_name"}` - Groups by exact values (e.g., `state`, `patron_pid`)
-- **Date field**: `{"field": "date_field", "interval": "time_interval"}` - Groups by time intervals
-    - Available intervals for date fields: `1d` (day), `1w` (week), `1M` (month), `1q` (quarter), `1y` (year)
-
-#### `metrics` Field Format
-
-Each metrics object is:
+### Stats Fields
 
-- `{"field": "field_name", "aggregation": "aggregation_type"}`
-    - Available aggregation types: `avg` (average), `sum` (total), `min` (minimum), `max` (maximum), `median` (50th percentile)
+The following fields are added to loans specifically for statistics. They require [`ILS_EXTEND_INDICES_WITH_STATS_ENABLED`](../../customize/configure.md#ils_extend_indices_with_stats_enabled-truefalse) to be enabled.
 
-!!! tip "Discovering available fields"
-    To see all available loan fields for grouping and metrics, query the loans endpoint:
-    ```
-    GET /api/circulation/loans
-    ```
+| Field                                            | Description                                                     |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| `extra_data.stats.available_items_during_request` | Whether loanable items were available when the loan was requested. |
+| `extra_data.stats.loan_duration`                  | Duration of the loan in days (for completed loans).             |
+| `extra_data.stats.waiting_time`                   | Days between request creation and checkout.                     |
 
 ### Examples
 

mkdocs.yml

@@ -74,8 +74,11 @@ nav:
       - Provider API: reference/api/provider.md
     - Statistics:
       - Overview: reference/stats/index.md
-      - Record Changes: reference/stats/record_changes.md
+      - Histogram Endpoints: reference/stats/histogram.md
       - Loan Statistics: reference/stats/loan_stats.md
+      - Acquisition Orders: reference/stats/acquisition_orders.md
+      - Document Requests: reference/stats/document_requests.md
+      - Record Changes: reference/stats/record_changes.md
   - Features:
     - Fast, Responsive User Interface: features/user_interface.md
     - Scalable, Optimised. Fast Search: features/search.md