This commit is contained in:
142
README.md
Normal file
142
README.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 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` автоматически применит новые миграции при запуске.
|
||||
Reference in New Issue
Block a user