182 lines
7.0 KiB
Markdown
182 lines
7.0 KiB
Markdown
# 🚀 NIN Excel Parsers API - Полная система
|
||
|
||
Полноценная система для парсинга Excel отчетов нефтеперерабатывающих заводов (НПЗ) с использованием FastAPI, MinIO и Streamlit.
|
||
|
||
## 🏗️ Архитектура проекта
|
||
|
||
Проект состоит из **двух изолированных пакетов**:
|
||
|
||
- **`python_parser/`** - FastAPI сервер + парсеры Excel
|
||
- **`streamlit_app/`** - Веб-интерфейс для демонстрации API
|
||
|
||
## 🚀 Быстрый запуск
|
||
|
||
### **Вариант 1: Все сервисы в Docker (рекомендуется)**
|
||
```bash
|
||
# Запуск всех сервисов: 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 + сервисы локально**
|
||
```bash
|
||
# Запуск 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**
|
||
```bash
|
||
# Запуск только 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
|
||
|
||
### Сборка образов:
|
||
```bash
|
||
# FastAPI
|
||
docker build -t nin-fastapi ./python_parser
|
||
|
||
# Streamlit
|
||
docker build -t nin-streamlit ./streamlit_app
|
||
```
|
||
|
||
### Запуск отдельных сервисов:
|
||
```bash
|
||
# Только MinIO
|
||
docker-compose up -d minio
|
||
|
||
# MinIO + FastAPI
|
||
docker-compose up -d minio fastapi
|
||
|
||
# Все сервисы
|
||
docker-compose up -d
|
||
```
|
||
|
||
## 🛑 Остановка
|
||
|
||
### Остановка Docker сервисов:
|
||
```bash
|
||
# Все сервисы
|
||
docker-compose down
|
||
|
||
# Только MinIO
|
||
docker-compose stop minio
|
||
```
|
||
|
||
### Остановка локальных сервисов:
|
||
```bash
|
||
# Нажмите 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`
|
||
|
||
### Тестирование:
|
||
|
||
```bash
|
||
# Запуск тестов
|
||
cd python_parser
|
||
pytest
|
||
|
||
# Запуск с покрытием
|
||
pytest --cov=.
|
||
```
|
||
|
||
## 📝 Лицензия
|
||
|
||
Проект разработан для внутреннего использования НИН. |