MyHoreca OLAP-to-GoogleSheets

Описание Проекта

MyHoreca OLAP-to-GoogleSheets - это веб-приложение на базе Flask, предназначенное для автоматической выгрузки OLAP-отчетов из сервера RMS (iiko или Syrve) в Google Таблицы. Приложение позволяет пользователям настраивать подключение к RMS, указывать целевую Google Таблицу, сопоставлять листы Google Таблицы с определенными OLAP-отчетами RMS и запускать отрисовку данных за выбранный период.

Приложение использует:

• Flask и Flask-Login для веб-интерфейса и управления пользователями.
• Flask-SQLAlchemy и Flask-Migrate для работы с базой данных SQLite (по умолчанию) и управления миграциями.
• requests для взаимодействия с RMS API.
• gspread для взаимодействия с Google Sheets API.
• cryptography для безопасного хранения паролей RMS в зашифрованном виде.
• Gunicorn как WSGI-сервер для продакшена.

Развертывание с Использованием Docker

Наиболее рекомендуемый способ развертывания приложения - использование Docker.

Предварительные требования

• Установленный Docker
• Доступ к RMS API с логином и паролем.
• Аккаунт Google Cloud и понимание, как получить учетные данные сервисного аккаунта для Google Sheets API и Google Drive API (см. Youtube с таймкодом).

Шаги по Настройке и Запуску

1. Клонирование Репозитория

   Если проект находится в Git репозитории, клонируйте его:

   git clone <URL вашего репозитория>
   cd <папка проекта>
   

2. Настройка Миграций Базы Данных (Выполнить ОДИН РАЗ локально)

   Прежде чем собирать Docker образ, необходимо инициализировать репозиторий миграций Alembic. Это нужно сделать локально в вашем окружении разработки. Убедитесь, что у вас установлен Flask-Migrate (pip install Flask-Migrate) и активировано виртуальное окружение.

   # Убедитесь, что вы находитесь в корневой директории проекта
   # Активируйте ваше виртуальное окружение
   # source .venv/bin/activate # Linux/macOS
   # .venv\Scripts\activate   # Windows CMD/PowerShell
   
   # Установите переменную окружения, чтобы Flask CLI мог найти ваше приложение
   export FLASK_APP=app.py # Linux/macOS
   # set FLASK_APP=app.py   # Windows CMD
   # $env:FLASK_APP="app.py" # Windows PowerShell
   
   # Инициализируйте репозиторий миграций (создаст папку 'migrations')
   flask db init
   
   # Создайте первую миграцию на основе текущих моделей
   flask db migrate -m "Initial database schema"
   
   # Деактивируйте виртуальное окружение, если нужно
   # deactivate
   

   После выполнения этих команд в корне вашего проекта появится папка migrations. Убедитесь, что она не игнорируется в .dockerignore и будет скопирована в Docker образ.

3. Генерация Секретных Ключей

   Приложению требуются два секретных ключа:

   • SECRET_KEY: Секретный ключ Flask для сессий и безопасности.
   • ENCRYPTION_KEY: Ключ для шифрования паролей RMS в базе данных. Этот ключ должен быть постоянным!

   Вы можете сгенерировать надежные ключи с помощью простого Python скрипта:

   # generate_keys.py
   import os
   import base64
   from cryptography.fernet import Fernet
   
   # Generate a strong SECRET_KEY for Flask (e.g., 24 random bytes in hex)
   flask_secret_key = os.urandom(24).hex()
   
   # Generate a strong ENCRYPTION_KEY for Fernet (correct format)
   fernet_encryption_key = Fernet.generate_key().decode()
   
   print("Generated SECRET_KEY (for Flask):")
   print(flask_secret_key)
   print("\nGenerated ENCRYPTION_KEY (for RMS password encryption):")
   print(fernet_encryption_key)
   print("\nIMPORTANT: Keep these keys secret and use them as environment variables!")
   

   Запустите этот скрипт (python generate_keys.py), скопируйте сгенерированные ключи и сохраните их в безопасном месте.

4. Сборка Docker Образа

   Убедитесь, что файлы Dockerfile, requirements.txt, start.sh и папка migrations находятся в корне проекта.

   docker build -t mholaper .
   

5. Запуск Docker Контейнера

   При запуске контейнера необходимо передать сгенерированные секретные ключи как переменные окружения (-e) и пробросить порт (-p).

   Настоятельно рекомендуется использовать Docker Volume для сохранения данных (база данных SQLite, загруженные учетные данные Google) между перезапусками или обновлениями контейнера.

   docker run -d \
     -p 5005:5005 \
     -e SECRET_KEY="<СЮДА_ВАШ_SECRET_KEY>" \
     -e ENCRYPTION_KEY="<СЮДА_ВАШ_ENCRYPTION_KEY>" \
     -v mholaper_data:/app/data \
     mholaper
   

   • -d: Запуск в фоновом режиме.
   • -p 5005:5005: Проброс порта 5005 контейнера на порт 5005 хост-машины.
   • -e SECRET_KEY="...": Установка переменной окружения SECRET_KEY.
   • -e ENCRYPTION_KEY="...": Установка переменной окружения ENCRYPTION_KEY. Ключ должен быть тем же, что использовался для шифрования ранее!
   • -v mholaper_data:/app/data: Монтирование Docker Volume с именем mholaper_data к папке /app/data внутри контейнера. Это обеспечит сохранность данных.

   Внимание: Если вы не используете -v для /app/data, все пользовательские данные будут храниться внутри файловой системы контейнера и будут потеряны при его удалении.

Доступ к Приложению

После успешного запуска контейнера, приложение будет доступно по адресу http://localhost:5005 (или IP-адресу вашей хост-машины, если вы разворачиваете на удаленном сервере).

Использование Сервиса (Веб-интерфейс)

После запуска приложения и перехода по его адресу в браузере:

1. Регистрация / Вход: Зарегистрируйте нового пользователя или войдите, если у вас уже есть учетная запись.
2. 1. Connection to RMS-server: Настройте параметры подключения к вашему RMS API (хост, логин, пароль). При сохранении приложение попытается подключиться и загрузить список доступных OLAP-отчетов (пресетов).
3. 2. Google Sheets Configuration:
   • Загрузите JSON-файл учетных данных сервисного аккаунта Google. Приложение покажет email сервисного аккаунта.
   • Важно: Предоставьте этому сервисному аккаунту права на редактирование вашей целевой Google Таблицы.
   • Укажите URL Google Таблицы и нажмите "Connect Google Sheets". Приложение загрузит список листов (вкладок) из этой таблицы.
4. 3. Mapping Sheets to OLAP Reports: Сопоставьте листы Google Таблицы с загруженными OLAP-отчетами из RMS. Выберите, какой отчет должен отрисовываться на каком листе. Сохраните сопоставления.
5. 4. Render Reports to Sheets: Выберите период (даты From/To) и нажмите кнопку "Render to sheet" напротив каждого сопоставления, которое вы хотите выполнить. Приложение получит данные отчета из RMS за указанный период, очистит соответствующий лист в Google Таблице и запишет туда новые данные.

Разработка и Вклад

Если вы хотите внести изменения в код:

• Разрабатывайте локально в виртуальном окружении.
• При изменении моделей SQLAlchemy используйте Flask-Migrate (flask db migrate, flask db upgrade) для создания новых миграций.
• После внесения изменений и создания миграций, пересоберите Docker образ и запустите контейнер. Скрипт start.sh автоматически применит новые миграции при запуске.