Release 1.7.0: Grafana catalog, ingress/IRM, tests

docs/GRAFANA_TOPOLOGY.md

@@ -0,0 +1,54 @@
+# Каталог Grafana в onGuard24
+
+Иерархия **инстанс → организация → папки → правила алертинга** подтягивается **по HTTP API** Grafana и сохраняется в PostgreSQL. Вебхук при этом не заменяет синхронизацию: вебхук даёт события, каталог — актуальную структуру правил.
+
+## Что нужно
+
+1. Миграция **`004_grafana_catalog`** (выполняется при старте контейнера через `alembic upgrade head`).
+2. В `.env` у источника Grafana заданы **`api_url`** и **`api_token`** (service account с правами читать папки и alert rules — обычно роль Viewer/Editor и доступ к Alerting).
+3. Источник попадает в **`iter_grafana_sources`**: `GRAFANA_SOURCES_JSON` или пара `GRAFANA_URL` + `GRAFANA_SERVICE_ACCOUNT_TOKEN` (slug `default`).
+
+## API
+
+| Метод | Путь | Назначение |
+|--------|------|------------|
+| POST | `/api/v1/modules/grafana-catalog/sync` | Синхронизация. Тело: `{}` — все источники с токеном; `{"instance_slug":"default"}` — один slug. |
+| GET | `/api/v1/modules/grafana-catalog/meta` | Последние метаданные синхронизации по всем slug. |
+| GET | `/api/v1/modules/grafana-catalog/tree?instance_slug=default` | Дерево: папки и правила, сгруппированные по `namespace_uid` (обычно UID папки правил). |
+
+## Проверка на https://onguard24.pvenode.ru/
+
+1. Убедитесь, что задеплоена версия с модулем **Каталог Grafana** (пункт в боковом меню).
+2. Выполните синхронизацию (с сервера или с машины с доступом к API):
+
+```bash
+curl -sS -X POST "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/sync" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Ответ: `results[]` с полями `ok`, `folders`, `rules`, при ошибке — `error`.
+
+3. Посмотреть дерево:
+
+```bash
+curl -sS "https://onguard24.pvenode.ru/api/v1/modules/grafana-catalog/tree?instance_slug=default" | python3 -m json.tool
+```
+
+(Если используете только `GRAFANA_URL`, slug источника — **`default`**.)
+
+4. В UI: **Каталог Grafana** — таблица последних синхронизаций.
+
+## Связь с вебхуком
+
+- В инцидентах по-прежнему используется **`externalURL` / лейблы** из тела вебхука.
+- Каталог позволяет в UI/API сопоставлять **`rule_uid`** и папку с сохранённым снимком (после доработок привязки).
+
+## Ограничения
+
+- Один токен = **одна Grafana-организация** (контекст `GET /api/org`). Обход нескольких org на одном инстансе — отдельные токены или админ-API (не в этой версии).
+- Эндпоинты Ruler: пробуются `/api/ruler/grafana/api/v1/rules` и `/api/ruler/Grafana/api/v1/rules` (зависит от версии Grafana).
+
+## Автоматический cron
+
+Периодический `POST .../sync` пока не встроен: можно повесить **системный cron**, **Forgejo scheduled workflow** или внешний оркестратор.