Admin Dashboard & Reporting Endpoints¶

Аудитория: разработчики, разработчики админских панелей Последнее обновление: 2025-11-17 Краткое содержание: Детальная документация Admin Dashboard endpoints — статистика платформы, метрики доходов, отчёты роста пользователей. Полное руководство по интеграции для админских аналитических панелей.

Обзор Endpoints¶

Метод	Endpoint	Описание	Auth Required	Permission
GET	`/api/admin/dashboard/stats`	Статистика платформы	✅ Admin	`dashboard:read`
GET	`/api/admin/dashboard/revenue`	Метрики доходов	✅ Admin	`dashboard:read`
GET	`/api/admin/reports/users`	Отчёт роста пользователей	✅ Admin	`reports:read`
GET	`/api/admin/reports/investments`	Отчёт инвестиций	✅ Admin	`reports:read`

GET /api/admin/dashboard/stats¶

Получить комплексную статистику платформы.

Запрос¶

GET /api/admin/dashboard/stats?period=30d
Authorization: Bearer <admin_jwt_token>

Query параметры:

Параметр	Тип	Обязательно	Описание	По умолчанию
`period`	string	❌ Нет	Временной период: `24h`, `7d`, `30d`, `90d`, `1y`, `all`	`30d`

Ответ¶

Успех (200 OK):

{
  "success": true,
  "data": {
    "users": {
      "total": 523,
      "active": 480,
      "new": 45,
      "growth": 9.4
    },
    "investments": {
      "total": 1250,
      "active": 1100,
      "pending": 15,
      "totalValue": "8500000.00"
    },
    "revenue": {
      "managementFees": "21250.00",
      "platformRevenue": "21250.00",
      "projectedAnnual": "255000.00"
    },
    "protocols": {
      "pendle": {
        "tvl": "2550000.00",
        "allocation": 30
      },
      "curve": {
        "tvl": "3400000.00",
        "allocation": 40
      },
      "convex": {
        "tvl": "2550000.00",
        "allocation": 30
      }
    },
    "performance": {
      "averageAPY": 10.2,
      "platformUptime": 99.95,
      "avgTransactionTime": 125
    }
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
`data.users.total`	number	Общее количество пользователей
`data.users.active`	number	Активных пользователей (с балансом > 0)
`data.users.new`	number	Новых пользователей за период
`data.users.growth`	number	Процент роста пользовательской базы
`data.investments.total`	number	Общее количество инвестиций
`data.investments.active`	number	Активных инвестиций
`data.investments.totalValue`	string	Общая стоимость всех инвестиций (SafeDecimal)
`data.revenue.managementFees`	string	Комиссии за управление (SafeDecimal)
`data.revenue.platformRevenue`	string	Общий доход платформы (SafeDecimal)
`data.revenue.projectedAnnual`	string	Прогнозируемый годовой доход (SafeDecimal)
`data.protocols[].tvl`	string	Total Value Locked в протоколе (SafeDecimal)
`data.protocols[].allocation`	number	Процент распределения капитала
`data.performance.averageAPY`	number	Средняя APY по всем стратегиям
`data.performance.platformUptime`	number	Uptime платформы в процентах
`data.performance.avgTransactionTime`	number	Среднее время обработки транзакции (миллисекунды)

Пример cURL¶

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET "https://app.saga.surf/api/admin/dashboard/stats?period=30d" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Пример TypeScript¶

const getPlatformStats = async (period: string = '30d') => {
  const token = localStorage.getItem('saga_admin_token');

  const response = await fetch(`/api/admin/dashboard/stats?period=${period}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  const { data } = await response.json();

  console.log('Total Users:', data.users.total);
  console.log('Active Investments:', data.investments.active);
  console.log('Platform Revenue:', data.revenue.platformRevenue);
  console.log('Average APY:', data.performance.averageAPY);

  return data;
};

// Использование
const stats = await getPlatformStats('30d');

GET /api/admin/dashboard/revenue¶

Получить детальные метрики доходов.

Запрос¶

GET /api/admin/dashboard/revenue?period=30d&breakdown=true
Authorization: Bearer <admin_jwt_token>

Query параметры:

Параметр	Тип	Обязательно	Описание	По умолчанию
`period`	string	❌ Нет	Временной период	`30d`
`breakdown`	boolean	❌ Нет	Включить детализацию по дням	`false`

Ответ¶

Успех (200 OK):

{
  "success": true,
  "data": {
    "summary": {
      "totalRevenue": "21250.00",
      "managementFees": "21250.00",
      "performanceFees": "0.00",
      "projectedAnnual": "255000.00",
      "revenueGrowth": 12.5
    },
    "breakdown": [
      {
        "date": "2025-10-03",
        "revenue": "708.33",
        "managementFees": "708.33",
        "userCount": 480
      }
    ],
    "byStrategy": [
      {
        "strategyId": "balanced-10",
        "revenue": "12750.00",
        "percentage": 60
      },
      {
        "strategyId": "conservative-5",
        "revenue": "6375.00",
        "percentage": 30
      },
      {
        "strategyId": "aggressive-20",
        "revenue": "2125.00",
        "percentage": 10
      }
    ]
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
`data.summary.totalRevenue`	string	Общий доход за период (SafeDecimal)
`data.summary.managementFees`	string	Комиссии за управление (SafeDecimal)
`data.summary.performanceFees`	string	Комиссии за производительность (SafeDecimal)
`data.summary.projectedAnnual`	string	Прогнозируемый годовой доход (SafeDecimal)
`data.summary.revenueGrowth`	number	Процент роста доходов
`data.breakdown[]`	array	Детализация по дням (если `breakdown=true`)
`data.breakdown[].date`	string	Дата (ISO 8601)
`data.breakdown[].revenue`	string	Доход за день (SafeDecimal)
`data.breakdown[].userCount`	number	Количество активных пользователей в этот день
`data.byStrategy[]`	array	Доход по стратегиям
`data.byStrategy[].strategyId`	string	Идентификатор стратегии
`data.byStrategy[].revenue`	string	Доход от стратегии (SafeDecimal)
`data.byStrategy[].percentage`	number	Процент от общего дохода

Пример cURL¶

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET "https://app.saga.surf/api/admin/dashboard/revenue?period=30d&breakdown=true" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Пример TypeScript¶

const getRevenueMetrics = async (period: string = '30d', breakdown: boolean = false) => {
  const token = localStorage.getItem('saga_admin_token');

  const response = await fetch(
    `/api/admin/dashboard/revenue?period=${period}&breakdown=${breakdown}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const { data } = await response.json();

  console.log('Total Revenue:', data.summary.totalRevenue);
  console.log('Projected Annual:', data.summary.projectedAnnual);
  console.log('Revenue Growth:', data.summary.revenueGrowth, '%');

  // Вывести доход по стратегиям
  data.byStrategy.forEach(strategy => {
    console.log(`${strategy.strategyId}: ${strategy.revenue} (${strategy.percentage}%)`);
  });

  return data;
};

// Использование
const revenue = await getRevenueMetrics('30d', true);

GET /api/admin/reports/users¶

Сгенерировать отчёт роста пользователей.

Запрос¶

GET /api/admin/reports/users?startDate=2025-09-01&endDate=2025-10-03&interval=daily
Authorization: Bearer <admin_jwt_token>

Query параметры:

Параметр	Тип	Обязательно	Описание	По умолчанию
`startDate`	string	❌ Нет	Дата начала отчёта (ISO 8601)	30 дней назад
`endDate`	string	❌ Нет	Дата окончания отчёта (ISO 8601)	Сегодня
`interval`	string	❌ Нет	Интервал данных: `hourly`, `daily`, `weekly`, `monthly`	`daily`

Ответ¶

Успех (200 OK):

{
  "success": true,
  "data": {
    "period": {
      "startDate": "2025-09-01T00:00:00Z",
      "endDate": "2025-10-03T23:59:59Z",
      "interval": "daily"
    },
    "summary": {
      "totalUsers": 523,
      "newUsers": 145,
      "activeUsers": 480,
      "retentionRate": 91.8,
      "averageInvestmentPerUser": "16284.80"
    },
    "dataPoints": [
      {
        "date": "2025-09-01",
        "totalUsers": 378,
        "newUsers": 5,
        "activeUsers": 350,
        "churnRate": 2.1
      },
      {
        "date": "2025-10-03",
        "totalUsers": 523,
        "newUsers": 8,
        "activeUsers": 480,
        "churnRate": 1.5
      }
    ]
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
`data.period`	object	Временной период отчёта
`data.summary.totalUsers`	number	Общее количество пользователей на конец периода
`data.summary.newUsers`	number	Новых пользователей за период
`data.summary.activeUsers`	number	Активных пользователей (с балансом > 0)
`data.summary.retentionRate`	number	Процент удержания пользователей
`data.summary.averageInvestmentPerUser`	string	Средняя инвестиция на пользователя (SafeDecimal)
`data.dataPoints[]`	array	Данные по интервалам
`data.dataPoints[].date`	string	Дата точки данных (ISO 8601)
`data.dataPoints[].totalUsers`	number	Общее количество пользователей на эту дату
`data.dataPoints[].newUsers`	number	Новых пользователей в этот интервал
`data.dataPoints[].activeUsers`	number	Активных пользователей на эту дату
`data.dataPoints[].churnRate`	number	Процент оттока пользователей

Пример cURL¶

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET "https://app.saga.surf/api/admin/reports/users?startDate=2025-09-01&endDate=2025-10-03&interval=daily" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Пример TypeScript¶

const getUserGrowthReport = async (
  startDate: string,
  endDate: string,
  interval: 'hourly' | 'daily' | 'weekly' | 'monthly' = 'daily'
) => {
  const token = localStorage.getItem('saga_admin_token');

  const response = await fetch(
    `/api/admin/reports/users?startDate=${startDate}&endDate=${endDate}&interval=${interval}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const { data } = await response.json();

  console.log('Total Users:', data.summary.totalUsers);
  console.log('New Users:', data.summary.newUsers);
  console.log('Retention Rate:', data.summary.retentionRate, '%');
  console.log('Avg Investment per User:', data.summary.averageInvestmentPerUser);

  // Построить график данных
  data.dataPoints.forEach(point => {
    console.log(`${point.date}: ${point.totalUsers} users (${point.newUsers} new, ${point.churnRate}% churn)`);
  });

  return data;
};

// Использование
const report = await getUserGrowthReport('2025-09-01', '2025-10-03', 'daily');

GET /api/admin/reports/investments¶

Сгенерировать отчёт активности инвестиций.

Запрос¶

GET /api/admin/reports/investments?startDate=2025-09-01&endDate=2025-10-03
Authorization: Bearer <admin_jwt_token>

Query параметры:

Параметр	Тип	Обязательно	Описание	По умолчанию
`startDate`	string	❌ Нет	Дата начала отчёта (ISO 8601)	30 дней назад
`endDate`	string	❌ Нет	Дата окончания отчёта (ISO 8601)	Сегодня

Ответ¶

Успех (200 OK):

{
  "success": true,
  "data": {
    "summary": {
      "totalInvestments": 1250,
      "totalValue": "8500000.00",
      "averageInvestment": "6800.00",
      "topStrategy": "balanced-10"
    },
    "byStrategy": [
      {
        "strategyId": "balanced-10",
        "count": 750,
        "tvl": "5100000.00",
        "averageAPY": 10.2
      },
      {
        "strategyId": "conservative-5",
        "count": 375,
        "tvl": "2550000.00",
        "averageAPY": 5.1
      },
      {
        "strategyId": "aggressive-20",
        "count": 125,
        "tvl": "850000.00",
        "averageAPY": 20.5
      }
    ],
    "trends": {
      "weekOverWeek": 8.5,
      "monthOverMonth": 12.3
    }
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
`data.summary.totalInvestments`	number	Общее количество инвестиций
`data.summary.totalValue`	string	Общая стоимость всех инвестиций (SafeDecimal)
`data.summary.averageInvestment`	string	Средняя сумма инвестиции (SafeDecimal)
`data.summary.topStrategy`	string	ID наиболее популярной стратегии
`data.byStrategy[]`	array	Статистика по стратегиям
`data.byStrategy[].strategyId`	string	Идентификатор стратегии
`data.byStrategy[].count`	number	Количество инвестиций в стратегию
`data.byStrategy[].tvl`	string	Total Value Locked в стратегии (SafeDecimal)
`data.byStrategy[].averageAPY`	number	Средняя APY стратегии
`data.trends.weekOverWeek`	number	Процент роста неделя к неделе
`data.trends.monthOverMonth`	number	Процент роста месяц к месяцу

Пример cURL¶

ADMIN_TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET "https://app.saga.surf/api/admin/reports/investments?startDate=2025-09-01&endDate=2025-10-03" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Пример TypeScript¶

const getInvestmentReport = async (startDate: string, endDate: string) => {
  const token = localStorage.getItem('saga_admin_token');

  const response = await fetch(
    `/api/admin/reports/investments?startDate=${startDate}&endDate=${endDate}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );

  const { data } = await response.json();

  console.log('Total Investments:', data.summary.totalInvestments);
  console.log('Total Value:', data.summary.totalValue);
  console.log('Average Investment:', data.summary.averageInvestment);
  console.log('Top Strategy:', data.summary.topStrategy);

  // Вывести статистику по стратегиям
  data.byStrategy.forEach(strategy => {
    console.log(`${strategy.strategyId}: ${strategy.count} investments, TVL: ${strategy.tvl}, APY: ${strategy.averageAPY}%`);
  });

  console.log('Week over Week Growth:', data.trends.weekOverWeek, '%');
  console.log('Month over Month Growth:', data.trends.monthOverMonth, '%');

  return data;
};

// Использование
const report = await getInvestmentReport('2025-09-01', '2025-10-03');

Связанная документация¶

Другие Admin Endpoints:

Admin Auth - Админская аутентификация
Admin Users - Управление пользователями

Архитектура:

📋 Метаданные¶

Версия: 2.6.268

Обновлено: 2025-10-21

Статус: Published