# **Микросервис "Marquiz Metrica Connector"**

## **1. Введение**

**Marquiz Metrica Connector** — это stateless-микросервис на FastAPI, предназначенный для полной автоматизации процесса настройки Яндекс.Метрики для квизов, созданных на платформе Marquiz.

Сервис выступает в роли безопасного бэкенд-посредника ("половинки" приложения) между frontend-частью личного кабинета Marquiz и Management API Яндекс.Метрики.

### **Ключевые возможности**
*   Безопасная авторизация пользователей через протокол Яндекс.OAuth 2.0.
*   Получение списка счетчиков пользователя.
*   Создание новых счетчиков с настройками по умолчанию.
*   Автоматическое создание стандартного набора целей типа "JavaScript-событие" для квизов Marquiz.

---

## **2. Стек технологий**

*   **Язык:** Python 3.11
*   **Фреймворк:** FastAPI
*   **Сервер:** Uvicorn
*   **HTTP-клиент:** HTTPX (для асинхронных запросов)
*   **Валидация:** Pydantic
*   **Логирование:** Loguru
*   **Окружение:** Docker (образ `python:3.11-slim`)
*   **Управление:** Docker Compose

---

## **3. Быстрый старт (для локального тестирования)**

1.  **Клонируйте репозиторий:**
    ```bash
    git clone [адрес_вашего_репозитория]
    cd marquiz-metrics
    ```
2.  **Настройте переменные окружения:**
    Проверьте файл .env и вернитесь к нему  с реальными данными после шага 4 - Регистрация приложения.

3.  **Соберите и запустите контейнер:**
    ```bash
    docker compose up -d --build
    ```
4.  **Проверьте работоспособность:**
    *   Сервис будет доступен по адресу, настроенному в вашем прокси-менеджере (например, `http://localhost:8000`).
    *   Интерактивная документация API (Swagger UI) доступна по адресу: `http://localhost:8000/docs`.

---

## **4. Руководство по интеграции для Frontend-разработчиков Marquiz**

### **Шаг 1: Настройка приложения в Яндекс.OAuth**

Для работы интеграции необходимо зарегистрировать приложение на стороне Яндекса.

*   **Адрес для регистрации:** [https://oauth.yandex.ru/](https://oauth.yandex.ru/)
*   **Тип приложения:** "Веб-сервисы".

#### **Ключевые параметры при регистрации:**

1.  **Redirect URI:** Это самый важный параметр. Это URL на стороне Marquiz, куда Яндекс вернет пользователя после авторизации.
    *   Для **тестирования** можно использовать: `https://oauth.yandex.ru/verification_code`
    *   Для **рабочей версии** это должен быть специальный роут в приложении Marquiz, например: `https://marquiz.ru/integration/yandex/callback`

2.  **Права доступа (Scopes):** Приложению необходимы следующие права. Чтобы их найти, начните вводить "metrika" в пустой строке выбора прав:
    *   `metrika:read` - Получение статистики, чтение параметров своих и доверенных счётчиков.
    *   `metrika:write` - Создание счётчиков, изменение параметров своих и доверенных счётчиков.

После регистрации вы получите **`ClientID`** и **`Client secret`**. Их необходимо будет передать backend-разработчику для внесения в `.env` файл на сервере.

### **Шаг 2: Процесс авторизации пользователя (OAuth 2.0 Flow)**

Процесс полностью интерактивный и инициируется на стороне frontend.

1.  **Инициация:** Пользователь нажимает кнопку "Подключить Яндекс.Метрику".
2.  **Редирект на Яндекс:** Frontend Marquiz формирует ссылку и перенаправляет браузер пользователя на страницу авторизации Яндекса.
    ```
    https://oauth.yandex.ru/authorize?response_type=code&client_id=ВАШ_CLIENT_ID&redirect_uri=ВАШ_REDIRECT_URI
    ```
3.  **Согласие пользователя:** Пользователь на сайте Яндекса входит в свой аккаунт и разрешает приложению Marquiz доступ к данным Метрики.
4.  **Возврат в Marquiz:** Яндекс перенаправляет пользователя обратно на `redirect_uri` с временным `code` в параметрах URL:
    ```
    https://marquiz.ru/integration/yandex/callback?code=A1B2C3D4...
    ```
5.  **Обмен `code` на `access_token`:** JavaScript-код на странице `/callback` извлекает `code` из URL и немедленно отправляет его на наш backend-сервис:

    *   **Эндпоинт:** `POST /api/v1/auth/token`
    *   **Тело запроса:** `{"code": "A1B2C3D4..."}`

6.  **Получение и сохранение токена:** Наш сервис в ответ возвращает `access_token`. Frontend **обязан сохранить этот токен** (например, в `localStorage` или в сессии пользователя) для всех последующих запросов к API.

### **Шаг 3: Справка по API эндпоинтам**

Для всех запросов, кроме `/auth/token`, требуется заголовок `Authorization: Bearer <access_token>`.

#### **1. Получение списка счетчиков**
*   **Метод:** `GET`
*   **URL:** `/api/v1/counters/`
*   **Описание:** Возвращает список всех счетчиков, доступных пользователю.
*   **Успешный ответ (200 OK):**
    ```json
    {
      "counters": [
        {
          "id": 123456,
          "name": "Мой сайт",
          "site": "example.com"
        }
      ]
    }
    ```

#### **2. Создание нового счетчика**
*   **Метод:** `POST`
*   **URL:** `/api/v1/counters/`
*   **Описание:** Создает новый счетчик для указанного сайта.
*   **Тело запроса:**
    ```json
    {
      "site_url": "https://new-quiz.com"
    }
    ```
*   **Успешный ответ (201 Created):**
    ```json
    {
      "id": 98765432,
      "name": "new-quiz.com",
      "code_status": "CS_NOT_FOUND"
    }
    ```

#### **3. Создание стандартных целей**
*   **Метод:** `POST`
*   **URL:** `/api/v1/counters/{counter_id}/goals`
*   **Описание:** Создает стандартный набор целей Marquiz в указанном счетчике.
*   **Параметр пути `counter_id`:** ID счетчика, в котором нужно создать цели.
*   **Тело запроса:**
    ```json
    {
      "goal_identifiers": [
        "Marquiz-start",
        "Marquiz-startquiz",
        "Marquiz-form",
        "Marquiz-result",
        "Marquiz-contacts1"
      ]
    }
    ```
*   **Успешный ответ (201 Created):**
    ```json
    {
      "created_goals": [
        {
          "id": 460587013,
          "name": "Посетитель открыл квиз"
        },
        {
          "id": 460587014,
          "name": "Посетитель нажал на кнопку стартовой страницы"
        }
      ]
    }
    ```
---