Сервис для взаимодействия со статистикой

Описание:

Данный проект представляет из себя отдельный сервис, который взаимодействует с монолитным веб-приложением для управления абитуриентами в рамках образовательной организации. Сервис взаимодействует с монолитной реляционной базой данных (PostgreSQL) посредством сырых SQL запросов, которые экранируются встроенной в библиотеку sqlalchemy функцией text() с передачей необходимых данных из запросов.

Сервис описан в соответствии с луковой архитектурой, представляющей из себя три базовых уровня:

1. Domain Layer (Repositories) - Взаимодействие с данными (получение, удаление и т.д.);
2. Application Layer (Services) - Описание бизнес-логики
3. Presentation Layer (Routers) - Контракты в виде API для взаимодействия с приложением.

Важно:

• Используется для hidden (внешний сервис);
• При изменении схемы базы данных приемной кампании, необходимо так же пересмотреть и актуализировать .sql файлы в рабочей директории;
• Сервис создан в целях снизить нагрузку с ключевого веб-приложения;
• В сервисе используется пакетный менеджер uv - для корректного использования необходимо использовать именно его;
• Далее в данном README будет описан процесс установки зависимостей и запуска для локальной разработки.

Стэк:

• Python 3.12
• FastAPI >=0.135.2
• SQLAlchemy[asyncio, ascynpg] >=2.0.48

Полный список

Структура проекта:

statistic
├─ .env.example               # Пример необходимых переменных окружения
├─ .python-version            # Используемая версия питона
├─ config                     # Хранение всех конфигураций и настроек проекта 
│  ├─ database.py             # Настройка подключения к БД
│  ├─ paths.py                # Необходимые пути внутри сервиса
│  ├─ settings.py             # Настройка самого веб-сервера
│  └─ __init__.py 
├─ enums                      # Хранение всех перечисляемых типов
│  ├─ education.py
│  └─ __init__.py
├─ main.py                    # Основной файл веб-сервиса. Точка входа
├─ pyproject.toml             # Список зависимостей и описание проекта
├─ README.md                  # ---> Вы находитесь тут <---
├─ repositories               # Слой для работы с базой данных
│  ├─ enrolled.py
│  ├─ helper.py               # Вспомогательные методы для взаимодействия с БД
│  └─ __init__.py
├─ routers                    # Слой представления (эндпоинты)
│  ├─ application.py
│  ├─ enrolled.py
│  └─ __init__.py
├─ schemas                    # Сериализация объектов данных
│  ├─ application_consent.py
│  ├─ application_dynamic.py
│  ├─ application_quota.py
│  ├─ enrolled_basic.py
│  ├─ enrolled_ege.py
│  ├─ enrolled_location.py
│  └─ __init__.py
├─ services                   # Сервисный слой для изоляции бизнес логики
│  ├─ application_selector.py
│  ├─ enrolled_selector.py
│  └─ __init__.py
├─ sql                        # Директория для хранения SQL запросов
│  ├─ enrolled
│  │  ├─ get_basic_stats_commercial_plan.sql
│  │  ├─ get_basic_stats_enrolled_students_budget.sql
│  │  ├─ get_basic_stats_enrolled_students_commercial.sql
│  │  ├─ get_basic_stats_kcp.sql
│  │  ├─ get_ege_stat.sql
│  │  ├─ get_enrolled_geo_enrolled_from_rostov.sql
│  │  ├─ get_enrolled_geo_enrolled_from_russia.sql
│  │  ├─ get_enrolled_geo_enrolled_other_citizenship.sql
│  │  ├─ get_enrolled_geo_enrolled_other_regions.sql
│  │  ├─ get_enrolled_geo_involved_countries.sql
│  │  ├─ get_enrolled_geo_involved_regions.sql
│  │  ├─ get_geo_by_level_country.sql
│  │  ├─ get_geo_by_level_region.sql
│  │  └─ get_level_stats.sql
│  └─ README.md               # ВАЖНО. Изучить перед работой с запросами
├─ src                        # Директория для корректной инициализации сервиса
│  └─ statistic
│     └─ __init__.py
├─ uv.lock                    # Актуальные версии зависимостей
└─ __init__.py

Запуск проекта

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

1. Создание .env файла. Необходимо скопировать .env.example и заполнить реальными данными;
2. Произвести установку зависимостей или обновить их:

$ uv venv
$ uv sync

3. Запустить проект. При необходимости добавьте параметр --workers 2

$ uv run uvicorn main:app --host 0.0.0.0 --port 8008 --reload