marquiz-metrics/README.md

Микросервис "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. Первоначальная настройка Установите git-crypt на вашу машину (sudo apt install git-crypt). Получите "мастер-ключ" проекта (marquiz-metrics.key) от тимлида/DevOps. Клонируйте репозиторий. "Отомкните" репозиторий, чтобы расшифровать секреты: git-crypt unlock /путь/к/marquiz-metrics.key. Создайте локальные файлы .env и docker-compose.yml из шаблонов. Выполните make install для установки зависимостей. 3.2. Полезные команды (Makefile) make dev-up: Запустить сервис локально. make dev-down: Остановить сервис. make test: Запустить автотесты. make save msg="...": Сделать коммит и push. При коммите git-crypt автоматически зашифрует секретные файлы.
4. Процесс CI/CD (Gitea + Drone) Проект использует CI/CD для автоматического тестирования и развертывания на Staging. Триггер: git push в ветку staging. Пайплайн (.drone.yml): Login: Drone логинится в Docker Hub. Test: Запускаются автотесты pytest. Deploy: Drone подключается к Staging VDS по SSH и запускает скрипт scripts/deploy.sh. Скрипт deploy.sh (на VDS): git pull: Скачивает последнюю версию кода. git-crypt автоматически расшифровывает секретные файлы, так как репозиторий на VDS был "отперт" мастер-ключом. cat ... > .env.staging: Собирает финальный файл с переменными. make staging-up: Пересобирает и перезапускает Docker-контейнер.
5. Управление секретами (git-crypt) Секреты для каждого окружения (staging, prod) хранятся в папке envs/. Файл .gitattributes в корне проекта указывает git-crypt, какие файлы (envs/*.env) нужно шифровать. Шифрование и расшифровка происходят прозрачно и автоматически при выполнении команд git commit / git pull. Доступ к секретам получают только те, у кого есть мастер-ключ (marquiz-metrics.key). Этот ключ никогда не хранится в Git.