# 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` автоматически применит новые миграции при запуске.