Skip to content

ACTIVITY_LOG.md

Latest commit

 

History

History
320 lines (259 loc) · 11.2 KB

ACTIVITY_LOG.md

File metadata and controls

320 lines (259 loc) · 11.2 KB
Raw

📋 Лог активности пользователей

Обзор

Система логирования активности автоматически записывает все действия пользователей в системе, предоставляя полный аудит всех операций для администраторов.

Возможности

  • ✅ Автоматическое логирование всех CRUD операций
  • ✅ Логирование изменений настроек системы
  • ✅ Запись IP адресов пользователей
  • ✅ Детали изменений (до/после) для UPDATE операций
  • ✅ Отслеживание результатов (успех/ошибка)
  • ✅ Фильтрация и поиск по множеству параметров
  • ✅ Пагинация для больших объемов данных
  • ✅ Детальный просмотр изменений в модальном окне

Типы логируемых действий

CRUD операции

  • CREATE - создание новых сущностей

    • Пользователи
    • Группы
    • Предметы
    • Расписание
    • Домашние задания

  • UPDATE - обновление существующих сущностей

    • Все изменения с сохранением состояния до и после
    • Автоматическое вычисление измененных полей

  • DELETE - удаление сущностей (мягкое удаление)

    • Сохранение состояния перед удалением

Изменения настроек

  • SETTINGS_CHANGE - изменения конфигурации системы
    • Настройки Telegram бота
    • Параметры уведомлений
    • Конфигурация системы

Структура лога

Поля записи

interface ActivityLog {
  id: string                    // Уникальный идентификатор
  userId: string                // ID пользователя, выполнившего действие
  action: string                // Тип действия (CREATE, UPDATE, DELETE, SETTINGS_CHANGE)
  entityType: string | null     // Тип сущности (User, Group, Subject, Schedule, Homework, BotSettings)
  entityId: string | null       // ID затронутой сущности
  ipAddress: string | null      // IP адрес пользователя
  details: {                    // Детали изменений
    before?: Record<string, any> // Состояние до изменения
    after?: Record<string, any>  // Состояние после изменения
    changes?: Array<{           // Список измененных полей
      field: string
      oldValue: any
      newValue: any
    }>
    error?: string              // Сообщение об ошибке (если result = FAILURE)
  }
  result: 'SUCCESS' | 'FAILURE'  // Результат операции
  createdAt: DateTime           // Время выполнения действия
}

Пример записи

{
  "id": "clx123...",
  "userId": "user456",
  "action": "UPDATE",
  "entityType": "User",
  "entityId": "user789",
  "ipAddress": "192.168.1.100",
  "details": {
    "before": {
      "id": "user789",
      "name": "Иван Иванов",
      "email": "ivan@example.com",
      "role": "student",
      "groupId": "group1"
    },
    "after": {
      "id": "user789",
      "name": "Иван Петров",
      "email": "ivan@example.com",
      "role": "student",
      "groupId": "group2"
    },
    "changes": [
      {
        "field": "name",
        "oldValue": "Иван Иванов",
        "newValue": "Иван Петров"
      },
      {
        "field": "groupId",
        "oldValue": "group1",
        "newValue": "group2"
      }
    ]
  },
  "result": "SUCCESS",
  "createdAt": "2025-11-03T20:10:57Z"
}

Использование

Просмотр логов

  1. Войдите как администратор
  2. Перейдите в раздел "Лог активности" (/admin/activity-log)
  3. Используйте фильтры для поиска нужных записей

Фильтры

  • По пользователю - введите ID пользователя
  • По действию - выберите тип действия (CREATE, UPDATE, DELETE, SETTINGS_CHANGE)
  • По типу сущности - выберите тип (User, Group, Subject, Schedule, Homework, BotSettings)
  • По дате - укажите период (начало и конец)

Просмотр деталей

  1. Нажмите на кнопку "Просмотр" у нужной записи
  2. Откроется модальное окно с полными деталями
  3. Просмотрите изменения в формате JSON

API

GET /api/activity-logs

Получить список логов активности с фильтрацией и пагинацией.

Права: admin

Параметры запроса:

  • userId - Фильтр по ID пользователя
  • action - Фильтр по типу действия (CREATE, UPDATE, DELETE, SETTINGS_CHANGE)
  • entityType - Фильтр по типу сущности
  • startDate - Дата начала периода (YYYY-MM-DD)
  • endDate - Дата окончания периода (YYYY-MM-DD)
  • page - Номер страницы (по умолчанию 1)
  • limit - Количество записей на странице (по умолчанию 50)

Пример запроса:

GET /api/activity-logs?action=UPDATE&entityType=User&startDate=2025-11-01&page=1&limit=50

Ответ:

{
  "logs": [
    {
      "id": "clx123...",
      "userId": "user456",
      "action": "UPDATE",
      "entityType": "User",
      "entityId": "user789",
      "ipAddress": "192.168.1.100",
      "details": { ... },
      "result": "SUCCESS",
      "createdAt": "2025-11-03T20:10:57Z",
      "user": {
        "id": "user456",
        "name": "Администратор",
        "email": "admin@example.com",
        "role": "admin"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Интеграция

Автоматическое логирование

Система автоматически логирует все действия в следующих API endpoints:

  • POST /api/users - создание пользователя
  • PUT /api/users - обновление пользователя
  • DELETE /api/users - удаление пользователя
  • POST /api/groups - создание группы
  • PUT /api/groups - обновление группы
  • DELETE /api/groups - удаление группы
  • POST /api/subjects - создание предмета
  • PUT /api/subjects - обновление предмета
  • DELETE /api/subjects - удаление предмета
  • POST /api/schedules - создание расписания
  • PUT /api/schedules - обновление расписания
  • DELETE /api/schedules - удаление расписания
  • POST /api/homework - создание домашнего задания
  • POST /api/telegram/config - изменение настроек Telegram бота

Утилита логирования

import { logActivity } from '@/lib/activity-log'

// Логирование успешной операции
await logActivity({
  userId: session.user.id,
  action: 'CREATE',
  entityType: 'User',
  entityId: newUser.id,
  request,
  details: {
    after: {
      id: newUser.id,
      email: newUser.email,
      role: newUser.role
    }
  },
  result: 'SUCCESS'
})

// Логирование ошибки
await logActivity({
  userId: session.user.id,
  action: 'CREATE',
  entityType: 'User',
  request,
  details: {
    error: error.message
  },
  result: 'FAILURE'
})

Безопасность

Защита данных

  • Пароли не логируются - автоматически удаляются из логов
  • Чувствительные данные фильтруются перед сохранением
  • Только администраторы имеют доступ к логам
  • IP адреса записываются для аудита безопасности

Производительность

  • Индексы на часто используемых полях (userId, action, entityType, createdAt)
  • Пагинация для больших объемов данных
  • Асинхронное логирование - не блокирует основную операцию
  • Обработка ошибок - сбои логирования не прерывают основную операцию

База данных

Модель Prisma

model ActivityLog {
  id          String   @id @default(cuid())
  userId      String
  action      String   // CREATE, UPDATE, DELETE, LOGIN, LOGOUT, SETTINGS_CHANGE
  entityType  String?  // User, Group, Subject, Schedule, Homework, Settings
  entityId    String?  // ID затронутой сущности
  ipAddress   String?
  details     Json?    // { before: {...}, after: {...}, changes: [...] }
  result      String   @default("SUCCESS") // SUCCESS, FAILURE
  createdAt   DateTime @default(now())
  
  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  
  @@index([userId])
  @@index([action])
  @@index([entityType])
  @@index([createdAt])
  @@map("activity_logs")
}

Миграция

npx prisma migrate dev --name add_activity_log

Ограничения

  • Только администраторы могут просматривать логи
  • Логи не удаляются автоматически (нужно периодически очищать старые записи)
  • IP адрес может быть недоступен за прокси-сервером
  • Детали изменений хранятся в JSON формате

Рекомендации

Очистка старых логов

Рекомендуется периодически очищать старые логи (старше 90 дней) для оптимизации производительности:

DELETE FROM activity_logs 
WHERE created_at < NOW() - INTERVAL '90 days';

Мониторинг

  • Регулярно проверяйте логи на наличие ошибок
  • Анализируйте активность пользователей
  • Отслеживайте подозрительные действия
  • Используйте фильтры для быстрого поиска

Документация обновлена: 19 ноября 2025
Версия системы: 0.4.0-alpha