ch
This commit is contained in:
182
README.md
Normal file
182
README.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 🚀 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=.
|
||||
```
|
||||
|
||||
## 📝 Лицензия
|
||||
|
||||
Проект разработан для внутреннего использования НИН.
|
||||
Reference in New Issue
Block a user