klg-asutk-app/docs/АРХИТЕКТУРА_ТЕХНОЛОГИЙ.md

Архитектура технологий системы

Обзор

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

Компоненты

1. PostgreSQL - CRUD и авторизация

Назначение: Основная база данных для операционных данных и авторизации

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

• Хранение пользователей и ролей
• CRUD операции для воздушных судов, аудитов, рисков
• Транзакционные данные
• Связи между сущностями

Конфигурация:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=klg
DB_USER=klg
DB_PASSWORD=klg

Файлы:

• lib/database/connection.ts - подключение
• lib/database/schema.sql - схема БД

---

2. S3/MinIO + Parquet - Хранение данных

Назначение: Объектное хранилище для больших объёмов данных в формате Parquet

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

• Хранение исторических данных
• Экспорт/импорт больших объёмов
• Архивные копии
• Данные для аналитики

Конфигурация:

MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=klg-data

Файлы:

• lib/storage/s3-client.ts - клиент S3/MinIO
• lib/parquet/polars-utils.ts - утилиты для Parquet

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

import { uploadParquetFile, getParquetFile } from '@/lib/storage/s3-client';

// Загрузка Parquet файла
await uploadParquetFile('aircraft/data.parquet', buffer);

// Получение файла
const data = await getParquetFile('aircraft/data.parquet');

---

3. ClickHouse - Аналитика и тяжёлые списки

Назначение: Колоночная БД для аналитических запросов и больших объёмов данных

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

• Аналитические запросы
• Агрегации по большим объёмам данных
• Отчёты и дашборды
• Исторические данные

Конфигурация:

CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_DB=klg_analytics
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

Файлы:

• lib/analytics/clickhouse-client.ts - клиент ClickHouse
• scripts/clickhouse-init/init.sql - инициализация схемы

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

import { queryClickHouse, insertClickHouse } from '@/lib/analytics/clickhouse-client';

// Аналитический запрос
const analytics = await queryClickHouse(`
  SELECT operator, COUNT(*) as total
  FROM aircraft_analytics
  GROUP BY operator
`);

// Вставка данных
await insertClickHouse('aircraft_analytics', data);

---

4. OpenSearch - Полнотекстовый поиск

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

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

• Поиск воздушных судов
• Поиск в документах
• Поиск в аудитах и рисках
• Нечёткий поиск (fuzzy search)

Конфигурация:

OPENSEARCH_URL=http://localhost:9200
OPENSEARCH_USERNAME=
OPENSEARCH_PASSWORD=

Файлы:

• lib/search/opensearch-client.ts - клиент OpenSearch

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

import { searchAircraft, indexDocument } from '@/lib/search/opensearch-client';

// Индексация документа
await indexDocument('aircraft', aircraftId, aircraftData);

// Поиск
const results = await searchAircraft('RA-12345', {
  operator: 'Аэрофлот',
  status: 'Активен'
});

---

5. Airflow/Prefect + Python (Polars/DuckDB) - Пайплайны

Назначение: Оркестрация ETL пайплайнов для обработки данных

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

• Импорт данных из ФАВТ
• Обработка больших объёмов данных
• Конвертация форматов (CSV → Parquet)
• Загрузка данных в аналитические хранилища

Конфигурация:

PREFECT_API_URL=http://localhost:4200/api
MINIO_ENDPOINT=http://localhost:9000
CLICKHOUSE_URL=http://localhost:8123

Файлы:

• scripts/pipelines/aircraft_pipeline.py - пайплайн обработки ВС
• scripts/pipelines/favt_import_pipeline.py - пайплайн импорта ФАВТ
• scripts/pipelines/requirements.txt - Python зависимости

Установка:

pip install -r scripts/pipelines/requirements.txt

Запуск пайплайна:

# Через Prefect CLI
prefect deployment run aircraft-data-pipeline

# Или напрямую
python scripts/pipelines/aircraft_pipeline.py

---

6. OpenAPI → Генерация типов на фронт

Назначение: Автоматическая генерация TypeScript типов из OpenAPI схемы

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

• Типобезопасность API
• Автодополнение в IDE
• Валидация запросов/ответов
• Документация API

Файлы:

• openapi.json - OpenAPI схема
• scripts/openapi-generate.ts - генератор типов

Генерация типов:

npm run generate:types

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

import { Aircraft, APIEndpoints } from '@/lib/api/generated-types';

// Типизированный запрос
const aircraft: Aircraft = await fetch('/api/aircraft/123').then(r => r.json());

---

Docker Compose

Все сервисы запускаются через Docker Compose:

docker-compose up -d

Сервисы:

• db - PostgreSQL (5432)
• minio - MinIO S3 (9000, 9001)
• clickhouse - ClickHouse (8123, 9000)
• opensearch - OpenSearch (9200)
• opensearch-dashboards - Dashboards (5601)
• redis - Redis (6379)
• prefect - Prefect UI (4200)
• backend - FastAPI (8000)
• frontend - Next.js (3000)

---

Поток данных

Импорт данных из ФАВТ

1. Python скрипт (fetch_favt_registry.py) загружает CSV с сайта ФАВТ
2. Prefect пайплайн (favt_import_pipeline.py):
   • Читает CSV
   • Конвертирует в Parquet через Polars
   • Сохраняет в S3/MinIO
   • Импортирует в PostgreSQL
3. Данные синхронизируются:
   • PostgreSQL - для операционных запросов
   • ClickHouse - для аналитики
   • OpenSearch - для поиска

Обработка данных

1. Пайплайн (aircraft_pipeline.py):
   • Загружает данные из PostgreSQL
   • Обрабатывает через Polars/DuckDB
   • Сохраняет в Parquet
   • Загружает в S3 и ClickHouse

Поиск

1. При создании/обновлении записи:
   • Данные сохраняются в PostgreSQL
   • Индексируются в OpenSearch
2. При поиске:
   • Запрос идёт в OpenSearch
   • Результаты возвращаются с релевантностью

---

Переменные окружения

Создайте файл .env.local:

# PostgreSQL
DB_HOST=localhost
DB_PORT=5432
DB_NAME=klg
DB_USER=klg
DB_PASSWORD=klg

# MinIO/S3
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=klg-data

# ClickHouse
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_DB=klg_analytics
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

# OpenSearch
OPENSEARCH_URL=http://localhost:9200

# Prefect
PREFECT_API_URL=http://localhost:4200/api

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

---

Запуск системы

1. Запуск всех сервисов:

   docker-compose up -d
   

2. Инициализация ClickHouse:

   docker-compose exec clickhouse clickhouse-client < scripts/clickhouse-init/init.sql
   

3. Создание bucket в MinIO:

   • Откройте http://localhost:9001
   • Логин: minioadmin / minioadmin
   • Создайте bucket klg-data

4. Генерация типов из OpenAPI:

   npm run generate:types
   

5. Запуск пайплайнов:

   # Установка зависимостей
   pip install -r scripts/pipelines/requirements.txt
   
   # Запуск Prefect сервера (уже в Docker)
   # Запуск пайплайна
   prefect deployment run aircraft-data-pipeline
   

---

Мониторинг

• Prefect UI: http://localhost:4200
• MinIO Console: http://localhost:9001
• OpenSearch Dashboards: http://localhost:5601
• ClickHouse: http://localhost:8123/play

---

Дополнительная информация

См. также:

• docs/MASHTABIRUEMOST.md - масштабируемость
• docs/DEPLOYMENT.md - развёртывание
• scripts/pipelines/ - примеры пайплайнов