143 lines
11 KiB
Markdown
143 lines
11 KiB
Markdown
# 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 с таймкодом](https://youtu.be/RmEsC2T8dwE?t=509)).
|
||
|
||
### Шаги по Настройке и Запуску
|
||
|
||
1. **Клонирование Репозитория**
|
||
|
||
Если проект находится в Git репозитории, клонируйте его:
|
||
```bash
|
||
git clone <URL вашего репозитория>
|
||
cd <папка проекта>
|
||
```
|
||
|
||
2. **Настройка Миграций Базы Данных (Выполнить ОДИН РАЗ локально)**
|
||
|
||
Прежде чем собирать Docker образ, необходимо инициализировать репозиторий миграций Alembic. Это нужно сделать **локально** в вашем окружении разработки.
|
||
Убедитесь, что у вас установлен Flask-Migrate (`pip install Flask-Migrate`) и активировано виртуальное окружение.
|
||
|
||
```bash
|
||
# Убедитесь, что вы находитесь в корневой директории проекта
|
||
# Активируйте ваше виртуальное окружение
|
||
# 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 скрипта:
|
||
```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` находятся в корне проекта.
|
||
|
||
```bash
|
||
docker build -t mholaper .
|
||
```
|
||
|
||
5. **Запуск Docker Контейнера**
|
||
|
||
При запуске контейнера необходимо передать сгенерированные секретные ключи как переменные окружения (`-e`) и пробросить порт (`-p`).
|
||
|
||
**Настоятельно рекомендуется использовать Docker Volume** для сохранения данных (база данных SQLite, загруженные учетные данные Google) между перезапусками или обновлениями контейнера.
|
||
|
||
```bash
|
||
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` автоматически применит новые миграции при запуске.
|