# Микросервис "Marquiz Metrica Connector" (v2.0)

**Версия:** 2.0  
**Статус:** Staging-окружение развернуто и готово к интеграции.

---

## 1. Назначение проекта

**Marquiz Metrica Connector** — это backend-микросервис, который предоставляет безопасный, стабильный и гибкий API для управления счетчиками и целями в Яндекс.Метрике. Он служит "мостом" между frontend-частью Marquiz и сложным Management API Яндекса.

**Ключевые функции:**
*   🔐 **Безопасная OAuth 2.0 авторизация** пользователей.
*   📊 **Управление счетчиками:** получение списка, создание.
*   🎯 **Управление целями:** получение списка, создание кастомных целей, массовое удаление.

---

## 2. Стек и архитектура

| Компонент | Технология |
| :--- | :--- |
| **Язык** | Python 3.11+ |
| **Фреймворк** | FastAPI (асинхронный) |
| **Сервер** | Gunicorn + Uvicorn (production-ready) |
| **Зависимости** | Poetry |
| **Тестирование** | Pytest |
| **Контейнеризация** | Docker (multi-stage build) |
| **CI/CD** | Gitea + Drone |
| **Управление секретами** | **git-crypt** |

---

## 3. Локальная разработка

### 3.1. Первоначальная настройка

1.  **Установите необходимое ПО:**
    ```bash
    # Для Debian/Ubuntu
    sudo apt-get update && sudo apt-get install -y git-crypt poetry
    ```

2.  **Получите мастер-ключ проекта** (`marquiz-metrics.key`) от администратора репозитория.

3.  **Клонируйте репозиторий:**
    ```bash
    git clone [ssh_url_репозитория] marquiz-metrics
    cd marquiz-metrics
    ```

4.  **"Отомкните" репозиторий**, чтобы расшифровать секретные файлы:
    ```bash
    git-crypt unlock /путь/к/вашему/marquiz-metrics.key
    ```

5.  **Создайте локальные файлы конфигурации** из шаблонов.
    ```bash
    # Создаем .env с вашими тестовыми секретами
    cp envs/staging.env .env 
    
    # Создаем docker-compose.yml для локального запуска
    cp docker-compose.base.yml docker-compose.yml
    ```
    > **Примечание:** Файлы `.env` и `docker-compose.yml` находятся в `.gitignore` и не попадут в репозиторий.

6.  **Установите зависимости проекта:**
    ```bash
    make install
    ```

### 3.2. Полезные команды (`Makefile`)

Для удобства все рутинные операции вынесены в `Makefile`.

*   **Запустить сервис локально:**
    ```bash
    make dev-up
    ```
*   **Остановить сервис:**
    ```bash
    make dev-down
    ```
*   **Смотреть логи:**
    ```bash
    make dev-logs
    ```
*   **Запустить автотесты:**
    ```bash
    make test
    ```
*   **Сделать коммит и push в текущую ветку:**
    ```bash
    make save msg="feat: Описание ваших изменений"
    ```

---

## 4. Процесс CI/CD (Gitea + Drone)

Проект использует CI/CD для автоматического тестирования и развертывания на Staging-окружение.

*   **Триггер:** `git push` в ветку `staging`.
*   **Пайплайн (`.drone.yml`):**
    1.  **Login:** Drone логинится в Docker Hub для скачивания образов-инструментов.
    2.  **Test:** Запускаются автотесты `pytest`. В случае ошибки пайплайн останавливается.
    3.  **Deploy:** Если тесты прошли, Drone подключается к Staging VDS по SSH и запускает скрипт `scripts/deploy.sh`.
*   **Скрипт `deploy.sh` (на VDS):**
    1.  `git pull`: Скачивает последнюю версию кода. `git-crypt` на сервере **автоматически расшифровывает** секреты.
    2.  `cat ... > .env.staging`: Собирает финальный файл с переменными окружения.
    3.  `make staging-up`: Пересобирает и перезапускает Docker-контейнер с новым кодом и конфигурацией.

---

## 5. Управление секретами (git-crypt)

*   Секреты для каждого окружения (`staging`, `prod`) хранятся в папке `envs/` в **зашифрованном** виде прямо в Git.
*   Файл `.gitattributes` в корне проекта указывает `git-crypt`, какие именно файлы (`envs/*.env`) подлежат шифрованию.
*   Шифрование/расшифровка происходят **прозрачно и автоматически** при выполнении команд `git commit` / `git pull` на "отпертом" репозитории.
*   Доступ к секретам получают только те разработчики и серверы, у которых есть **мастер-ключ**. Ключ **никогда не хранится в Git**.