klg-asutk-app/docs/AUDIT_AND_ANALYTICS.md

Система аудита и аналитики

Обзор

Реализована комплексная система аудита, логирования действий пользователей и расширенной аналитики для дашборда.

Компоненты системы

1. Система аудита (lib/audit/)

audit-service.ts

• Создание записей аудита - логирование всех изменений данных
• История изменений - получение истории для конкретного ресурса
• Поиск записей - фильтрация по пользователю, действию, типу ресурса, датам, IP адресу
• Откат изменений - восстановление предыдущего состояния
• Экспорт логов - экспорт в JSON или CSV

user-activity-logger.ts

• Логирование действий пользователей:
  • Просмотр данных (logView)
  • Создание записей (logCreate)
  • Изменение записей (logUpdate)
  • Удаление записей (logDelete)
  • Экспорт данных (logExport)
  • Использование ИИ агента (logAIAgentUsage)

2. API Endpoints

/api/audit

• GET /api/audit - поиск записей аудита с фильтрами
• GET /api/audit?format=json|csv - экспорт логов
• GET /api/audit/[resourceType]/[resourceId] - история изменений ресурса
• POST /api/audit/rollback - откат изменений

/api/analytics

• GET /api/analytics?type=timeseries - данные для графиков по времени
• GET /api/analytics?type=compare - сравнение периодов
• GET /api/analytics?type=forecast - прогнозирование
• GET /api/analytics?type=activity - статистика активности пользователей

/api/logs/search

• GET /api/logs/search - поиск по всем логам (файловым и БД)

3. Страница истории изменений

Путь: /audit-history

Функционал:

• Просмотр всех записей аудита
• Фильтрация по действию, типу ресурса, датам, поиск
• Просмотр деталей изменений (старые/новые значения)
• Откат изменений (для UPDATE операций)
• Экспорт в CSV или JSON

4. Система логирования

Ротация логов (lib/logs/log-rotation.ts)

• По размеру - удаление файлов, превышающих лимит
• По времени - удаление старых файлов (настраиваемый retention)
• Очистка БД - удаление старых записей из audit_log

Команда: npm run logs:rotate

Поиск по логам (lib/logs/log-search.ts)

• Поиск в файловых логах (JSON формат)
• Поиск в базе данных (audit_log)
• Комплексный поиск по всем источникам

5. Аналитика (lib/analytics/analytics-service.ts)

Временные ряды

• Группировка по дням, неделям, месяцам
• Поддержка различных типов ресурсов (aircraft, risks, audits)

Сравнение периодов

• Текущий период vs предыдущий период
• Расчет изменений в процентах
• Определение тренда (рост/падение/стабильно)

Прогнозирование

• Простое линейное прогнозирование на основе исторических данных
• Настраиваемый период прогноза

Статистика активности

• Общее количество действий
• Распределение по типам действий
• Топ пользователей по активности

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

Интеграция логирования в API endpoints

import { logCreate, logUpdate, logDelete, getClientIP, getUserAgent } from '@/lib/audit/user-activity-logger';

// При создании записи
await logCreate('aircraft', newAircraftId, newValues, userId, ipAddress, userAgent);

// При изменении записи
await logUpdate('aircraft', aircraftId, oldValues, newValues, userId, ipAddress, userAgent);

// При удалении записи
await logDelete('aircraft', aircraftId, oldValues, userId, ipAddress, userAgent);

Получение истории изменений

import { getAuditHistory } from '@/lib/audit/audit-service';

const history = await getAuditHistory('aircraft', aircraftId, 50);

Поиск записей аудита

import { searchAuditLogs } from '@/lib/audit/audit-service';

const { logs, total } = await searchAuditLogs({
  userId: 'user-id',
  action: 'UPDATE',
  resourceType: 'aircraft',
  startDate: new Date('2025-01-01'),
  endDate: new Date('2025-01-31'),
}, 100, 0);

Откат изменений

import { rollbackChange } from '@/lib/audit/audit-service';

const success = await rollbackChange(auditLogId);

Настройка

Ротация логов

Создайте cron job для автоматической ротации:

# Ежедневно в 2:00
0 2 * * * cd /path/to/project && npm run logs:rotate

Или используйте системный таймер (systemd):

[Unit]
Description=Rotate KLG logs
After=network.target

[Service]
Type=oneshot
WorkingDirectory=/path/to/project
ExecStart=/usr/bin/npm run logs:rotate

[Timer]
OnCalendar=daily
OnCalendar=02:00

[Install]
WantedBy=timers.target

Retention период

Настройте в .env.local:

AUDIT_LOG_RETENTION_DAYS=90
LOG_RETENTION_DAYS=30
LOG_MAX_SIZE=10485760  # 10MB
LOG_MAX_FILES=10

Структура данных

Таблица audit_log

CREATE TABLE audit_log (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    action VARCHAR(100) NOT NULL,
    resource_type VARCHAR(100) NOT NULL,
    resource_id UUID NOT NULL,
    old_values JSONB,
    new_values JSONB,
    ip_address VARCHAR(45),
    user_agent TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Партиционирование

Таблица audit_log партиционирована по месяцам для оптимизации производительности при больших объемах данных.

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

• Все действия пользователей логируются
• IP адреса и User-Agent сохраняются для аудита безопасности
• Откат изменений требует подтверждения
• Экспорт логов доступен только авторизованным пользователям
• Rate limiting на всех API endpoints

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

• Индексы на часто используемых полях
• Партиционирование таблицы audit_log
• Пагинация результатов поиска
• Кэширование статистики (опционально через Redis)

Мониторинг

• Логи аудита доступны через страницу /audit-history
• Статистика активности через /api/analytics?type=activity
• Автоматическая ротация предотвращает переполнение диска