docs: Revamp and format README.md

README.md

@@ -1,47 +1,120 @@
-Микросервис "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.
+# Микросервис "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**.