Микросервис "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. Первоначальная настройка

Установите необходимое ПО:

# Для Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y git-crypt poetry

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

Клонируйте репозиторий:

git clone [ssh_url_репозитория] marquiz-metrics
cd marquiz-metrics

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

Создайте локальные файлы конфигурации из шаблонов.

# Создаем .env с вашими тестовыми секретами
cp envs/staging.env .env 

# Создаем docker-compose.yml для локального запуска
cp docker-compose.base.yml docker-compose.yml

Примечание: Файлы .env и docker-compose.yml находятся в .gitignore и не попадут в репозиторий.

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

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

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

Запустить сервис локально:
```
make dev-up
```
Остановить сервис:
```
make dev-down
```
Смотреть логи:
```
make dev-logs
```
Запустить автотесты:
```
make test
```

Сделать коммит и push в текущую ветку:

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.

5.7 KiB Raw Blame History Unescape Escape