🚀 NIN Excel Parsers API - Полная система

Полноценная система для парсинга Excel отчетов нефтеперерабатывающих заводов (НПЗ) с использованием FastAPI, MinIO и Streamlit.

🏗️ Архитектура проекта

Проект состоит из двух изолированных пакетов:

• python_parser/ - FastAPI сервер + парсеры Excel
• streamlit_app/ - Веб-интерфейс для демонстрации API

🚀 Быстрый запуск

Вариант 1: Все сервисы в Docker (рекомендуется)

# Запуск всех сервисов: MinIO + FastAPI + Streamlit
docker-compose up -d

# Доступ:
# - MinIO Console: http://localhost:9001
# - FastAPI: http://localhost:8000
# - Streamlit: http://localhost:8501
# - API Docs: http://localhost:8000/docs

Вариант 2: Только MinIO в Docker + сервисы локально

# Запуск MinIO в Docker
docker-compose up -d minio

# Запуск FastAPI локально
cd python_parser
python run_dev.py

# В отдельном терминале - Streamlit
cd streamlit_app
streamlit run app.py

Вариант 3: Только MinIO в Docker

# Запуск только MinIO
docker-compose up -d minio

📋 Описание сервисов

• MinIO (порт 9000-9001): S3-совместимое хранилище для данных
• FastAPI (порт 8000): API сервер для парсинга Excel файлов
• Streamlit (порт 8501): Веб-интерфейс для демонстрации API

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

python_parser_cf/                    # Корень проекта
├── python_parser/                   # Пакет FastAPI + парсеры
│   ├── app/                        # FastAPI приложение
│   │   ├── main.py                # Основной файл приложения
│   │   └── schemas/               # Pydantic схемы
│   ├── core/                      # Бизнес-логика
│   │   ├── models.py             # Модели данных
│   │   ├── ports.py              # Интерфейсы (порты)
│   │   └── services.py           # Сервисы
│   ├── adapters/                  # Адаптеры для внешних систем
│   │   ├── storage.py            # MinIO адаптер
│   │   └── parsers/              # Парсеры Excel файлов
│   ├── data/                     # Тестовые данные
│   ├── Dockerfile                # Docker образ для FastAPI
│   ├── requirements.txt          # Зависимости FastAPI
│   └── run_dev.py               # Запуск FastAPI локально
├── streamlit_app/                 # Пакет Streamlit
│   ├── app.py                    # Основное Streamlit приложение
│   ├── requirements.txt          # Зависимости Streamlit
│   ├── Dockerfile                # Docker образ для Streamlit
│   ├── .streamlit/               # Конфигурация Streamlit
│   │   └── config.toml          # Настройки
│   └── README.md                 # Документация Streamlit
├── docker-compose.yml             # Docker Compose конфигурация
├── .gitignore                     # Git исключения
└── README.md                      # Общая документация

🔍 Доступные эндпоинты

• GET / - Информация об API
• GET /docs - Swagger документация
• GET /parsers - Список доступных парсеров
• GET /parsers/{parser_name}/getters - Информация о геттерах парсера
• POST /svodka_pm/upload-zip - Загрузка сводок ПМ
• POST /svodka_ca/upload - Загрузка сводок ЦА
• POST /monitoring_fuel/upload-zip - Загрузка мониторинга топлива
• POST /svodka_pm/get_data - Получение данных сводок ПМ
• POST /svodka_ca/get_data - Получение данных сводок ЦА
• POST /monitoring_fuel/get_data - Получение данных мониторинга топлива

📊 Поддерживаемые типы отчетов

1. svodka_pm - Сводки по переработке нефти (ПМ)
   • Геттеры: single_og, total_ogs
2. svodka_ca - Сводки по переработке нефти (ЦА)
   • Геттеры: get_data
3. monitoring_fuel - Мониторинг топлива
   • Геттеры: total_by_columns, month_by_code

🏗️ Архитектура

Проект использует Hexagonal Architecture (Ports and Adapters):

• Порты (Ports): Интерфейсы для бизнес-логики
• Адаптеры (Adapters): Реализации для внешних систем
• Сервисы (Services): Бизнес-логика приложения

Система геттеров парсеров

Каждый парсер может иметь несколько методов получения данных (геттеров):

• Регистрация геттеров в словаре с метаданными
• Валидация параметров для каждого геттера
• Единый интерфейс get_value(getter_name, params)

🐳 Docker

Сборка образов:

# FastAPI
docker build -t nin-fastapi ./python_parser

# Streamlit
docker build -t nin-streamlit ./streamlit_app

Запуск отдельных сервисов:

# Только MinIO
docker-compose up -d minio

# MinIO + FastAPI
docker-compose up -d minio fastapi

# Все сервисы
docker-compose up -d

🛑 Остановка

Остановка Docker сервисов:

# Все сервисы
docker-compose down

# Только MinIO
docker-compose stop minio

Остановка локальных сервисов:

# Нажмите Ctrl+C в терминале с FastAPI/Streamlit

🔧 Разработка

Добавление нового парсера:

1. Создайте файл в python_parser/adapters/parsers/
2. Реализуйте интерфейс ParserPort
3. Добавьте в python_parser/core/services.py
4. Создайте схемы в python_parser/app/schemas/
5. Добавьте эндпоинты в python_parser/app/main.py

Тестирование:

# Запуск тестов
cd python_parser
pytest

# Запуск с покрытием
pytest --cov=.

📝 Лицензия

Проект разработан для внутреннего использования НИН.