feat(user-usage): add clean chart data option for user data resets

x0sina · x0sina · commit 4e56e3839b6a · 2026-05-08T20:06:45.000+03:30
- Introduced `clean_chart_data` parameter in user data reset functions to conditionally delete historical chart rows.
- Updated relevant CRUD operations and job functions to utilize the new parameter.
- Enhanced environment configuration with `RESET_USER_USAGE_CLEAN_CHART_DATA` option for controlling chart data cleanup.
- Modified user count chart accuracy notes in multiple languages to reflect the new behavior regarding chart data retention.
diff --git a/.env.example b/.env.example
@@ -100,6 +100,7 @@ UVICORN_PORT = 8000
 
 # DISABLE_RECORDING_NODE_USAGE = False
 # ENABLE_RECORDING_NODES_STATS = False  # Only available for postgresql and timescaledb
+# RESET_USER_USAGE_CLEAN_CHART_DATA = False  # When true, reset user usage also deletes historical user chart rows.
 
 # ALLOWED_ORIGINS = "*"
 
diff --git a/app/db/crud/bulk.py b/app/db/crud/bulk.py
@@ -23,7 +23,12 @@
 from .user import load_user_attrs
 
 
-async def reset_all_users_data_usage(db: AsyncSession, admin: Optional[Admin] = None):
+async def reset_all_users_data_usage(
+    db: AsyncSession,
+    admin: Optional[Admin] = None,
+    *,
+    clean_chart_data: bool = False,
+):
     """
     Efficiently resets data usage for all users, or users under a specific admin if provided.
 
@@ -33,7 +38,8 @@ async def reset_all_users_data_usage(db: AsyncSession, admin: Optional[Admin] =
     Operations performed:
         - Sets `used_traffic` to 0 for all target users.
         - Sets `status` to `active` for all users, unless filtered by admin.
-        - Deletes all related `UserUsageResetLogs`, `NodeUserUsage`, and `NextPlan` entries.
+        - Deletes all related `UserUsageResetLogs` and `NextPlan` entries.
+        - Deletes `NodeUserUsage` chart rows when `clean_chart_data` is enabled.
 
     Args:
         db (AsyncSession): The SQLAlchemy async session used for database operations.
@@ -54,7 +60,8 @@ async def reset_all_users_data_usage(db: AsyncSession, admin: Optional[Admin] =
     await db.execute(update(User).where(User.id.in_(user_ids)).values(used_traffic=0, status=UserStatus.active))
 
     await db.execute(delete(UserUsageResetLogs).where(UserUsageResetLogs.user_id.in_(user_ids)))
-    await db.execute(delete(NodeUserUsage).where(NodeUserUsage.user_id.in_(user_ids)))
+    if clean_chart_data:
+        await db.execute(delete(NodeUserUsage).where(NodeUserUsage.user_id.in_(user_ids)))
     await db.execute(delete(NextPlan).where(NextPlan.user_id.in_(user_ids)))
 
     await db.commit()
diff --git a/app/db/crud/user.py b/app/db/crud/user.py
@@ -1032,7 +1032,7 @@ async def clear_user_node_usages(db: AsyncSession, user_id: int, *, before: date
     await db.execute(stmt)
 
 
-async def reset_user_data_usage(db: AsyncSession, db_user: User) -> User:
+async def reset_user_data_usage(db: AsyncSession, db_user: User, *, clean_chart_data: bool = False) -> User:
     """
     Resets the data usage of a user and logs the reset.
 
@@ -1044,7 +1044,8 @@ async def reset_user_data_usage(db: AsyncSession, db_user: User) -> User:
         User: The updated user object.
     """
     await _reset_user_traffic_and_log(db, db_user)
-    await clear_user_node_usages(db, db_user.id)
+    if clean_chart_data:
+        await clear_user_node_usages(db, db_user.id)
 
     if db_user.status not in [UserStatus.expired, UserStatus.disabled]:
         db_user.status = UserStatus.active
@@ -1054,7 +1055,9 @@ async def reset_user_data_usage(db: AsyncSession, db_user: User) -> User:
     return db_user
 
 
-async def bulk_reset_user_data_usage(db: AsyncSession, users: list[User]) -> list[User]:
+async def bulk_reset_user_data_usage(
+    db: AsyncSession, users: list[User], *, clean_chart_data: bool = False
+) -> list[User]:
     """
     Resets the data usage for a list of users and logs the reset.
 
@@ -1067,7 +1070,8 @@ async def bulk_reset_user_data_usage(db: AsyncSession, users: list[User]) -> lis
     """
     for db_user in users:
         await _reset_user_traffic_and_log(db, db_user)
-        await clear_user_node_usages(db, db_user.id)
+        if clean_chart_data:
+            await clear_user_node_usages(db, db_user.id)
         if db_user.status not in [UserStatus.expired, UserStatus.disabled]:
             db_user.status = UserStatus.active
     await db.commit()
@@ -1086,7 +1090,7 @@ def _build_revoked_proxy_settings(db_user: User) -> dict:
     return proxy_settings.dict()
 
 
-async def reset_user_by_next(db: AsyncSession, db_user: User) -> User:
+async def reset_user_by_next(db: AsyncSession, db_user: User, *, clean_chart_data: bool = False) -> User:
     """
     Resets the data usage of a user based on next user.
 
@@ -1140,7 +1144,8 @@ async def reset_user_by_next(db: AsyncSession, db_user: User) -> User:
         db_user.data_limit_reset_strategy = db_user.next_plan.user_template.data_limit_reset_strategy
 
     await _reset_user_traffic_and_log(db, db_user)
-    await clear_user_node_usages(db, db_user.id)
+    if clean_chart_data:
+        await clear_user_node_usages(db, db_user.id)
     db_user.status = UserStatus.active
 
     await db.commit()
diff --git a/app/jobs/reset_user_data_usage.py b/app/jobs/reset_user_data_usage.py
@@ -9,7 +9,7 @@
 from app import notification
 from app.jobs.dependencies import SYSTEM_ADMIN
 from app.utils.logger import get_logger
-from config import job_settings, runtime_settings
+from config import job_settings, runtime_settings, usage_settings
 
 logger = get_logger("jobs")
 user_operator = UserOperation(operator_type=OperatorType.SYSTEM)
@@ -20,7 +20,11 @@ async def reset_data_usage():
         users = await get_users_to_reset_data_usage(db)
         old_statuses = {user.id: user.status for user in users}
 
-        updated_users = await bulk_reset_user_data_usage(db, users)
+        updated_users = await bulk_reset_user_data_usage(
+            db,
+            users,
+            clean_chart_data=usage_settings.reset_user_usage_clean_chart_data,
+        )
 
         for db_user in updated_users:
             user = await user_operator.update_user(db_user)
diff --git a/app/jobs/review_users.py b/app/jobs/review_users.py
@@ -25,7 +25,7 @@
 from app.node import node_manager as node_manager
 from app.settings import webhook_settings
 from app.utils.logger import get_logger
-from config import job_settings, runtime_settings
+from config import job_settings, runtime_settings, usage_settings
 
 logger = get_logger("review-users")
 user_operator = UserOperation(operator_type=OperatorType.SYSTEM)
@@ -34,7 +34,11 @@
 async def change_status(db: AsyncSession, db_user: User, status: UserStatus):
     next_plan_activated = bool(db_user.next_plan) and status != UserStatus.active
     if next_plan_activated:
-        db_user = await reset_user_by_next(db, db_user)
+        db_user = await reset_user_by_next(
+            db,
+            db_user,
+            clean_chart_data=usage_settings.reset_user_usage_clean_chart_data,
+        )
 
     user = await user_operator.update_user(db_user)
 
diff --git a/app/operation/user.py b/app/operation/user.py
@@ -10,6 +10,7 @@
 from pydantic import ValidationError
 from sqlalchemy.exc import IntegrityError
 
+from config import usage_settings
 from app import notification
 from app.db import AsyncSession
 from app.db.crud.admin import get_admin
@@ -461,11 +462,15 @@ async def _reset_user_data_usage(
         db_user: User,
         admin: AdminDetails,
         *,
+        clean_chart_data: bool | None = None,
         emit_status_change_notification: bool = True,
     ):
         old_status = db_user.status
 
-        db_user = await reset_user_data_usage(db=db, db_user=db_user)
+        if clean_chart_data is None:
+            clean_chart_data = usage_settings.reset_user_usage_clean_chart_data
+
+        db_user = await reset_user_data_usage(db=db, db_user=db_user, clean_chart_data=clean_chart_data)
         user = await self.update_user(db_user)
 
         if emit_status_change_notification and user.status != old_status:
@@ -498,7 +503,11 @@ async def bulk_reset_user_data_usage(
         db_users = await self._get_validated_users_by_ids(db, bulk_users.ids, admin, load_usage_logs=False)
         old_statuses = {user.id: user.status for user in db_users}
 
-        db_users = await bulk_reset_user_data_usage(db, db_users)
+        db_users = await bulk_reset_user_data_usage(
+            db,
+            db_users,
+            clean_chart_data=usage_settings.reset_user_usage_clean_chart_data,
+        )
         await sync_users(db_users)
 
         users = [await self.validate_user(db_user) for db_user in db_users]
@@ -577,14 +586,22 @@ async def bulk_enable_users(
     async def reset_users_data_usage(self, db: AsyncSession, admin: AdminDetails):
         """Reset all users data usage"""
         db_admin = await self.get_validated_admin(db, admin.username)
-        await reset_all_users_data_usage(db=db, admin=db_admin)
+        await reset_all_users_data_usage(
+            db=db,
+            admin=db_admin,
+            clean_chart_data=usage_settings.reset_user_usage_clean_chart_data,
+        )
 
     async def _active_next_plan(self, db: AsyncSession, db_user: User, admin: AdminDetails) -> UserResponse:
         if db_user is None or db_user.next_plan is None:
             await self.raise_error(message="User doesn't have next plan", code=404)
 
         old_status = db_user.status
-        db_user = await reset_user_by_next(db=db, db_user=db_user)
+        db_user = await reset_user_by_next(
+            db=db,
+            db_user=db_user,
+            clean_chart_data=usage_settings.reset_user_usage_clean_chart_data,
+        )
         user = await self.update_user(db_user)
 
         if user.status != old_status:
diff --git a/config.py b/config.py
@@ -164,6 +164,10 @@ def build_sudoers(self) -> "AuthSettings":
 class UsageSettings(EnvSettings):
     disable_recording_node_usage: bool = Field(default=False, validation_alias="DISABLE_RECORDING_NODE_USAGE")
     enable_recording_nodes_stats: bool = Field(default=False, validation_alias="ENABLE_RECORDING_NODES_STATS")
+    reset_user_usage_clean_chart_data: bool = Field(
+        default=False,
+        validation_alias="RESET_USER_USAGE_CLEAN_CHART_DATA",
+    )
 
 
 class JobSettings(EnvSettings):
diff --git a/dashboard/public/statics/locales/en.json b/dashboard/public/statics/locales/en.json
@@ -1936,7 +1936,7 @@
   "statistics.onlineUsers": "Online Users",
   "statistics.userCountChart": "User Count",
   "statistics.userCountChartDescription": "Online, expired, and limited user activity counts over time",
-  "statistics.userCountChartAccuracyNote": "Resetting user usage or changing user status can make this chart show inaccurate historical data.",
+  "statistics.userCountChartAccuracyNote": "Changing user status can make this chart show inaccurate historical data. Resetting usage only removes chart history when chart-data cleanup is enabled in the environment.",
   "workersHealth.title": "Workers Health",
   "workersHealth.subtitle": "Scheduler and node worker status",
   "workersHealth.live": "Live",
diff --git a/dashboard/public/statics/locales/fa.json b/dashboard/public/statics/locales/fa.json
@@ -1889,7 +1889,7 @@
   "statistics.onlineUsers": "کاربران آنلاین",
   "statistics.userCountChart": "تعداد کاربران",
   "statistics.userCountChartDescription": "تعداد کاربران آنلاین، منقضی‌شده و محدودشده در طول زمان",
-  "statistics.userCountChartAccuracyNote": "بازنشانی مصرف کاربر یا تغییر وضعیت کاربر می‌تواند باعث شود این نمودار داده‌های تاریخی نادقیق نشان دهد.",
+  "statistics.userCountChartAccuracyNote": "تغییر وضعیت کاربر می‌تواند باعث شود این نمودار داده‌های تاریخی نادقیق نشان دهد. بازنشانی مصرف فقط زمانی تاریخچه نمودار را حذف می‌کند که پاک‌سازی داده‌های نمودار در محیط فعال باشد.",
   "workersHealth.title": "سلامت پراسس ها",
   "workersHealth.subtitle": "وضعیت زمان‌بند و پراسس گره",
   "workersHealth.live": "زنده",
diff --git a/dashboard/public/statics/locales/ru.json b/dashboard/public/statics/locales/ru.json
@@ -1851,7 +1851,7 @@
   "statistics.onlineUsers": "Онлайн пользователи",
   "statistics.userCountChart": "Количество пользователей",
   "statistics.userCountChartDescription": "Количество онлайн, истекших и ограниченных пользователей во времени",
-  "statistics.userCountChartAccuracyNote": "Сброс использования пользователя или изменение статуса пользователя может сделать исторические данные на этом графике неточными.",
+  "statistics.userCountChartAccuracyNote": "Изменение статуса пользователя может сделать исторические данные на этом графике неточными. Сброс использования удаляет историю графиков только если очистка данных графиков включена в окружении.",
   "workersHealth.title": "Состояние воркеров",
   "workersHealth.subtitle": "Статус планировщика и воркера узла",
   "workersHealth.live": "В реальном времени",
diff --git a/dashboard/public/statics/locales/zh.json b/dashboard/public/statics/locales/zh.json
@@ -1902,7 +1902,7 @@
   "statistics.onlineUsers": "在线用户",
   "statistics.userCountChart": "用户数量",
   "statistics.userCountChartDescription": "在线、已过期和受限用户活动数量随时间变化",
-  "statistics.userCountChartAccuracyNote": "重置用户用量或更改用户状态可能会使此图表显示不准确的历史数据。",
+  "statistics.userCountChartAccuracyNote": "更改用户状态可能会使此图表显示不准确的历史数据。只有在环境中启用图表数据清理时，重置用量才会删除图表历史。",
   "workersHealth.title": "工作器健康",
   "workersHealth.subtitle": "调度器与节点工作器状态",
   "workersHealth.live": "实时",
diff --git a/dashboard/src/components/charts/user-counts-chart.tsx b/dashboard/src/components/charts/user-counts-chart.tsx
@@ -512,7 +512,8 @@ export function UserCountsChart({ nodeId, isSudo, nodesData = [] }: UserCountsCh
                 <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
                 <span>
                   {t('statistics.userCountChartAccuracyNote', {
-                    defaultValue: 'Resetting user usage or changing user status can make this chart show inaccurate historical data.',
+                    defaultValue:
+                      'Changing user status can make this chart show inaccurate historical data. Resetting usage only removes chart history when chart-data cleanup is enabled in the environment.',
                   })}
                 </span>
               </p>
diff --git a/tests/api/test_user.py b/tests/api/test_user.py
@@ -12,15 +12,16 @@
 from unittest.mock import AsyncMock, MagicMock
 
 from fastapi import status
-from sqlalchemy import update
+from sqlalchemy import func, select, update
 
-from app.db.models import User
+from app.db.models import NodeUserUsage, User
 from app.models.stats import Period, UserCountMetric, UserCountMetricStat, UserCountMetricStatsList
 from app.models.settings import ConfigFormat, SubRule, Subscription
 from app.operation.subscription import SubscriptionOperation
 from app.utils import jwt as jwt_utils
 from app.utils.crypto import generate_wireguard_keypair, get_wireguard_public_key
 from app.utils.jwt import create_subscription_token, get_secret_key, get_subscription_payload
+from config import usage_settings
 from tests.api import TestSession, client
 from tests.api.helpers import (
     auth_headers,
@@ -60,6 +61,17 @@ async def _set_online_at():
     asyncio.run(_set_online_at())
 
 
+def count_user_chart_rows(user_id: int) -> int:
+    async def _count_rows():
+        async with TestSession() as session:
+            result = await session.execute(
+                select(func.count()).select_from(NodeUserUsage).where(NodeUserUsage.user_id == user_id)
+            )
+            return result.scalar_one()
+
+    return asyncio.run(_count_rows())
+
+
 def extract_wireguard_config_bodies(response) -> list[str]:
     with zipfile.ZipFile(io.BytesIO(response.content)) as zip_file:
         config_files = [name for name in zip_file.namelist() if name.endswith(".conf")]
@@ -1601,6 +1613,53 @@ def test_reset_user_usage(access_token):
         cleanup_groups(access_token, core, groups)
 
 
+def test_reset_user_usage_only_cleans_chart_data_when_enabled(access_token):
+    """Test that user reset preserves chart data unless env cleanup is enabled."""
+    core, groups = setup_groups(access_token, 1)
+    user = create_user(
+        access_token,
+        group_ids=[groups[0]["id"]],
+        payload={"username": unique_name("test_user_reset_chart_data")},
+    )
+
+    async def _add_chart_row():
+        async with TestSession() as session:
+            session.add(
+                NodeUserUsage(
+                    user_id=user["id"],
+                    node_id=None,
+                    created_at=datetime.now(timezone.utc) - timedelta(minutes=10),
+                    used_traffic=123,
+                )
+            )
+            await session.commit()
+
+    previous_clean_chart_data = usage_settings.reset_user_usage_clean_chart_data
+    try:
+        usage_settings.reset_user_usage_clean_chart_data = False
+        asyncio.run(_add_chart_row())
+        assert count_user_chart_rows(user["id"]) == 1
+
+        response = client.post(
+            f"/api/user/by-id/{user['id']}/reset",
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+        assert response.status_code == status.HTTP_200_OK
+        assert count_user_chart_rows(user["id"]) == 1
+
+        usage_settings.reset_user_usage_clean_chart_data = True
+        response = client.post(
+            f"/api/user/by-id/{user['id']}/reset",
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+        assert response.status_code == status.HTTP_200_OK
+        assert count_user_chart_rows(user["id"]) == 0
+    finally:
+        usage_settings.reset_user_usage_clean_chart_data = previous_clean_chart_data
+        delete_user(access_token, user["username"])
+        cleanup_groups(access_token, core, groups)
+
+
 def test_user_update(access_token):
     """Test that the user update route is accessible."""
     core, groups = setup_groups(access_token, 2)
