feat(userReports): add last_updated to API response DEV-1267 (#6460)

### 📣 Summary
This PR exposes the latest snapshot update timestamp
(`BillingAndUsageSnapshot.date_modified`) as `last_updated` in the
`/api/v2/user-reports/` endpoint.

Author: rajpatel24

jsapp/js/api/react-query/server-logs-superusers.ts

@@ -940,6 +940,7 @@ Supports exact matching and range operators (e.g., gte, lte)
 
 - date_joined
 - last_login
+- last_updated (Represents the last modified timestamp of the materialized view)
 - extra_details__date_removal_requested
 - extra_details__date_removed
 - extra_details_password_date_changed

kobo/apps/user_reports/migrations/0002_create_user_reports_mv.py

@@ -54,7 +54,8 @@
             bus.mt_characters_limit,
             COALESCE(bus.total_storage_bytes, 0) as total_storage_bytes,
             COALESCE(bus.total_submission_count_all_time, 0) as total_submission_count_all_time,
-            COALESCE(bus.total_submission_count_current_period, 0) as total_submission_count_current_period
+            COALESCE(bus.total_submission_count_current_period, 0) as total_submission_count_current_period,
+            bus.date_modified
         FROM auth_user au
         LEFT JOIN organizations_organizationuser ou ON au.id = ou.user_id
         LEFT JOIN user_reports_billingandusagesnapshot bus ON ou.organization_id = bus.organization_id
@@ -98,6 +99,7 @@
         au.is_staff,
         au.is_active,
         TO_CHAR(au.date_joined AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS date_joined,
+        TO_CHAR(ubau.date_modified AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS last_updated,
         CASE
             WHEN au.last_login IS NOT NULL THEN TO_CHAR(au.last_login AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
             ELSE NULL
@@ -281,7 +283,8 @@
         ubau.mt_characters_limit,
         ubau.total_storage_bytes,
         ubau.total_submission_count_all_time,
-        ubau.total_submission_count_current_period;
+        ubau.total_submission_count_current_period,
+        ubau.date_modified;
     """
 
 STRIPE_SUBSCRIPTIONS = """

kobo/apps/user_reports/models.py

@@ -122,6 +122,8 @@ class UserReports(models.Model):
     current_period_end = models.DateTimeField(null=True, blank=True)
     service_usage = models.JSONField(null=True, blank=True)
 
+    last_updated = models.CharField()
+
     class Meta:
         managed = False
         db_table = 'user_reports_userreportsmv'

kobo/apps/user_reports/seralizers.py

@@ -41,6 +41,7 @@ class Meta:
             'account_restricted',
             'asset_count',
             'deployed_asset_count',
+            'last_updated',
         ]
 
     def get_account_restricted(self, obj) -> bool:

kobo/apps/user_reports/utils/snapshot_refresh_helpers.py

@@ -3,6 +3,7 @@
 from django.db import connection
 from django.db.models import Q
 from django.db.models.query import QuerySet
+from django.utils import timezone
 
 from kobo.apps.organizations.models import Organization
 from kobo.apps.user_reports.models import (
@@ -94,6 +95,7 @@ def process_chunk(
                 mt_characters_limit=_normalize_limit(
                     org_limits.get('mt_characters_limit')
                 ),
+                date_modified=timezone.now(),
             )
         )
 
@@ -113,6 +115,7 @@ def process_chunk(
                 'storage_bytes_limit',
                 'asr_seconds_limit',
                 'mt_characters_limit',
+                'date_modified',
             ],
             unique_fields=['organization_id'],
         )

kpi/docs/api/v2/user_reports/list.md

@@ -57,6 +57,7 @@ Supports exact matching and range operators (e.g., gte, lte)
 
 - date_joined
 - last_login
+- last_updated (Represents the last modified timestamp of the materialized view)
 - extra_details__date_removal_requested
 - extra_details__date_removed
 - extra_details_password_date_changed

static/openapi/schema_v2.json

@@ -11647,7 +11647,7 @@
         "/api/v2/user-reports/": {
             "get": {
                 "operationId": "api_v2_user_reports_list",
-                "description": "# List user reports\n\n⚠️ _Only available to superusers_\n\n## Filterable fields by string:\n\nSupports partial filtering\n- username\n- first_name\n- last_name\n- email\n- user_uid\n- organization__name\n- organization__role (e.g., admin, member, owner)\n- organization__website\n- extra_details__data__organization_type\n- `extra_details__data__<field>` (other string fields, e.g., name, sector, country...)\n\n## Filterable fields by int:\n\nSupports exact matching and range operators (e.g., gte, lte)\n\n**Total NLP Usage**\n- service_usage__total_nlp_usage__asr_seconds_all_time\n- service_usage__total_nlp_usage__mt_characters_all_time\n- service_usage__total_nlp_usage__asr_seconds_current_period\n- service_usage__total_nlp_usage__mt_characters_current_period\n\n**Total Storage/Submissions**\n- service_usage__total_storage_bytes\n- service_usage__total_submission_count__all_time\n- service_usage__total_submission_count__current_period\n\n**Service Usage Balances**\n\nPrefix: `service_usage__balances__<metric>__<value>`\n\nMetric:\n- submission\n- asr_seconds\n- mt_characters\n- storage_bytes\n\nValue:\n- balance_value\n- balance_percent\n- effective_limit\n\nEx: `service_usage__balances__submission__balance_value`\n\n**Asset Count**\n- asset_count\n- deployed_asset_count\n\n## Filterable fields by date:\nSupports exact matching and range operators (e.g., gte, lte)\n\n- date_joined\n- last_login\n- extra_details__date_removal_requested\n- extra_details__date_removed\n- extra_details_password_date_changed\n\n## Filterable fields by boolean:\n\n- is_superuser\n- is_staff\n- is_active\n- validated_email\n- extra_details__validated_password\n- mfa_is_active\n- sso_is_active\n- accepted_tos\n- extra_details__data__newsletter_subscription\n- service_usage__balances__*metric*__exceeded (metric: submission, asr_seconds, mt_characters, storage_bytes)\n- account_restricted\n\n## Filterable fields by list:\n\nSubscription filtering:\n\nHas subscriptions\n\n`?q=subscriptions__0__id__isnull:False`\n\nNo subscriptions\n\n`?q=subscriptions__0__id__isnull:True`\n\nSubscription id\n\n`?q=subscriptions[]__id:sub_1QwPItAR39rDI89stzLJ040p`\n\nActive subscriptions\n\n`?q=subscriptions[]__status:active`\n",
+                "description": "# List user reports\n\n⚠️ _Only available to superusers_\n\n## Filterable fields by string:\n\nSupports partial filtering\n- username\n- first_name\n- last_name\n- email\n- user_uid\n- organization__name\n- organization__role (e.g., admin, member, owner)\n- organization__website\n- extra_details__data__organization_type\n- `extra_details__data__<field>` (other string fields, e.g., name, sector, country...)\n\n## Filterable fields by int:\n\nSupports exact matching and range operators (e.g., gte, lte)\n\n**Total NLP Usage**\n- service_usage__total_nlp_usage__asr_seconds_all_time\n- service_usage__total_nlp_usage__mt_characters_all_time\n- service_usage__total_nlp_usage__asr_seconds_current_period\n- service_usage__total_nlp_usage__mt_characters_current_period\n\n**Total Storage/Submissions**\n- service_usage__total_storage_bytes\n- service_usage__total_submission_count__all_time\n- service_usage__total_submission_count__current_period\n\n**Service Usage Balances**\n\nPrefix: `service_usage__balances__<metric>__<value>`\n\nMetric:\n- submission\n- asr_seconds\n- mt_characters\n- storage_bytes\n\nValue:\n- balance_value\n- balance_percent\n- effective_limit\n\nEx: `service_usage__balances__submission__balance_value`\n\n**Asset Count**\n- asset_count\n- deployed_asset_count\n\n## Filterable fields by date:\nSupports exact matching and range operators (e.g., gte, lte)\n\n- date_joined\n- last_login\n- last_updated (Represents the last modified timestamp of the materialized view)\n- extra_details__date_removal_requested\n- extra_details__date_removed\n- extra_details_password_date_changed\n\n## Filterable fields by boolean:\n\n- is_superuser\n- is_staff\n- is_active\n- validated_email\n- extra_details__validated_password\n- mfa_is_active\n- sso_is_active\n- accepted_tos\n- extra_details__data__newsletter_subscription\n- service_usage__balances__*metric*__exceeded (metric: submission, asr_seconds, mt_characters, storage_bytes)\n- account_restricted\n\n## Filterable fields by list:\n\nSubscription filtering:\n\nHas subscriptions\n\n`?q=subscriptions__0__id__isnull:False`\n\nNo subscriptions\n\n`?q=subscriptions__0__id__isnull:True`\n\nSubscription id\n\n`?q=subscriptions[]__id:sub_1QwPItAR39rDI89stzLJ040p`\n\nActive subscriptions\n\n`?q=subscriptions[]__status:active`\n",
                 "parameters": [
                     {
                         "name": "limit",

static/openapi/schema_v2.yaml

@@ -8484,6 +8484,7 @@ paths:
 
         - date_joined
         - last_login
+        - last_updated (Represents the last modified timestamp of the materialized view)
         - extra_details__date_removal_requested
         - extra_details__date_removed
         - extra_details_password_date_changed