chore: release v1.0.0 — каркас FastAPI, ingress Grafana, интеграции, документация

Made-with: Cursor
2026-04-03 08:30:56 +03:00
commit 4da9b13a86
34 changed files with 1049 additions and 0 deletions
--- a/.env.example
+++ b/.env.example
@ -0,0 +1,33 @@
 # Скопируй в .env и подставь значения (файл .env в git не коммитится)
 HTTP_ADDR=0.0.0.0:8080
 LOG_LEVEL=info
 # Опционально: если задан — POST /api/v1/ingress/grafana требует заголовок X-OnGuard-Secret
 # GRAFANA_WEBHOOK_SECRET=
 # --- Grafana HTTP API (service account, не пароль admin) ---
 # URL без завершающего слэша. Токен: Grafana → Administration → Service accounts → onguard24 → Add service account token
 GRAFANA_URL=https://grafana.pvenode.ru
 # GRAFANA_SERVICE_ACCOUNT_TOKEN=
 # --- PostgreSQL (onGuard24) ---
 DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/DBNAME?sslmode=disable
 # Альтернатива по отдельным полям (если приложение читает так)
 # PGHOST=
 # PGPORT=5432
 # PGUSER=
 # PGPASSWORD=
 # PGDATABASE=
 # PGSSLMODE=disable
 # --- HashiCorp Vault ---
 VAULT_ADDR=https://vault.pvenode.ru
 # Только для dev: предпочтительно AppRole / отдельный токен с ограниченными правами, не root
 VAULT_TOKEN=
 # --- Forgejo (Gitea API) — репозиторий, CI, тот же токен для git clone по HTTPS при необходимости ---
 # Токен: Forgejo → Settings → Applications → Generate New Token (или старый PAT)
 FORGEJO_URL=https://forgejo.pvenode.ru
 # FORGEJO_TOKEN=
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,16 @@
 .env
 .env.local
 *.pem
 dist/
 bin/
 .venv/
 __pycache__/
 *.py[cod]
 *.egg-info/
 .pytest_cache/
 web/node_modules/
 web/dist/
 .idea/
 onguard24/.idea/
 .vscode/
 .DS_Store
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -0,0 +1,25 @@
 # Changelog
 Формат: семантическое версионирование `MAJOR.MINOR.PATCH`. Git-теги `v1.0.0`, `v1.1.0` и т.д. — см. [docs/VERSIONING.md](docs/VERSIONING.md).
 ## [1.0.0] — 2026-04-03
 Первый зафиксированный релиз **каркаса** (scaffold).
 ### Что входит
 - **Backend:** FastAPI, uvicorn, конфиг из `.env` (путь к `.env` от корня репозитория).
 - **БД:** PostgreSQL через asyncpg, пул, миграция `ingress_events` (сырой SQL в `onguard24/db.py`).
 - **Ingress:** `POST /api/v1/ingress/grafana` — сохранение JSON алерта в БД; опционально `X-OnGuard-Secret` + `GRAFANA_WEBHOOK_SECRET`.
 - **Статус:** `GET /`, `GET /api/v1/status` — проверки database, Vault, Grafana (SA token), Forgejo (PAT + fallback без `read:user`).
 - **Модули-заглушки:** `schedules`, `contacts`, `statusboard` под префиксом `/api/v1/modules/...`.
 - **Фронт:** Vite + React в `web/` (прокси на API).
 - **Документация:** README, `.env.example`, `docs/ARCHITECTURE.md`.
 ### Не входит (следующие версии)
 - Alembic / полноценные миграции.
 - Авторизация публичных API (кроме секрета webhook).
 - Бизнес-логика IRM (эскалации, дежурства, светофор) — только заготовки модулей.
 Тег в репозитории: `v1.0.0`.
--- a/7
+++ b/7
@ -0,0 +1,7 @@
 .PHONY: run install lint
 install:
 	python3 -m venv .venv && . .venv/bin/activate && pip install -e .
 run:
 	. .venv/bin/activate && python -m uvicorn onguard24.main:app --reload --host 0.0.0.0 --port 8080
--- a/README.md
+++ b/README.md
@ -0,0 +1,75 @@
 # onGuard24
 **Версия: 1.0.0** · Модульный монолит на **Python (FastAPI)**: ядро, приём алертов из Grafana, заготовки модулей (дежурства, контакты, светофор), PostgreSQL, проверки Vault / Grafana / Forgejo.
 | Документ | Назначение |
 |----------|------------|
 | [CHANGELOG.md](CHANGELOG.md) | История версий |
 | [docs/VERSIONING.md](docs/VERSIONING.md) | Теги, откат к предыдущей версии |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Структура кода, куда что класть |
 | [docs/AI_CONTEXT.md](docs/AI_CONTEXT.md) | Краткий контекст для доработок |
 **Репозиторий:** [forgejo.pvenode.ru/admin/onGuard24](https://forgejo.pvenode.ru/admin/onGuard24)
 ---
 ## Что уже есть (функционал v1)
 - Запуск HTTP API (`uvicorn`), конфиг из `.env`.
 - **PostgreSQL:** пул asyncpg, таблица `ingress_events` для сырых тел webhook Grafana.
 - **POST `/api/v1/ingress/grafana`** — приём JSON алерта (опционально защита `X-OnGuard-Secret`).
 - **GET `/`**, **GET `/api/v1/status`** — проверки: БД, Vault, Grafana (service account), Forgejo (PAT).
 - **Модули-заглушки:** `/api/v1/modules/schedules|contacts|statusboard/`.
 - **Фронт (опционально):** `web/` — Vite + React, прокси на API.
 Чего **ещё нет** (следующие версии): Alembic, авторизация API, доменная модель инцидентов, эскалации, фоновые задачи.
 ## Быстрый старт
 ```bash
 cd onGuard24
 python3 -m venv .venv
 source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e .
 ```
 Скопируй `.env.example` в `.env` и заполни секреты (см. ниже).
 ```bash
 python -m uvicorn onguard24.main:app --reload --host 0.0.0.0 --port 8080
 ```
 Или: `python -m onguard24.main` (читает `HTTP_ADDR` из `.env`).
 ## API
 | Метод | Путь | Описание |
 |-------|------|----------|
 | GET | `/` | HTML: проверки **database / vault / grafana / forgejo** |
 | GET | `/?format=json` | Тот же статус + ссылки в JSON |
 | GET | `/health`, `/api/v1/health` | Liveness |
 | GET | `/api/v1/status` | JSON: интеграции + БД |
 | POST | `/api/v1/ingress/grafana` | Webhook Grafana (JSON), опционально `X-OnGuard-Secret` |
 | GET | `/api/v1/modules/schedules/` | Заглушка модуля дежурств |
 | GET | `/api/v1/modules/contacts/` | Заглушка контактов |
 | GET | `/api/v1/modules/statusboard/` | Заглушка «светофора» |
 ## Переменные окружения
 См. `.env.example`. Основные: `DATABASE_URL`, `HTTP_ADDR`, `VAULT_*`, `GRAFANA_*`, `FORGEJO_*`, опционально `GRAFANA_WEBHOOK_SECRET`.
 ### Grafana
 - **`GRAFANA_URL`**, **`GRAFANA_SERVICE_ACCOUNT_TOKEN`** — HTTP API (service account), не пароль пользователя.
 ### Forgejo (Gitea API)
 - **`FORGEJO_URL`**, **`FORGEJO_TOKEN`** — PAT; рекомендуется scope **`read:user`** для полного ответа `/api/v1/user` (см. README в предыдущих версиях и `integrations/forgejo_api.py`).
 ## Фронтенд (опционально)
 ```bash
 cd web && npm install && npm run dev
 ```
 Vite проксирует `/api` на `http://127.0.0.1:8080` (см. `web/vite.config.ts`).
--- a/docs/AI_CONTEXT.md
+++ b/docs/AI_CONTEXT.md
@ -0,0 +1,35 @@
 # Контекст для доработок (агент / разработчик)
 Кратко, что нужно знать перед изменениями в репозитории **onGuard24**.
 ## Продукт
 - **onGuard24** — сервис класса **IRM** (дежурства, эскалации, инциденты), модульный монолит.
 - **v1.0.0** — только каркас: API, БД, webhook Grafana, заглушки модулей, страница статусов.
 ## Стек
 - Python **≥3.11**, **FastAPI**, **asyncpg**, **httpx**, **pydantic-settings**.
 - Фронт опционально: **Vite + React** в `web/`.
 ## Правила
 1. **Секреты** — только `.env` (gitignore). В репо — `.env.example` без значений.
 2. **Версия** — синхронизировать: `pyproject.toml`, `onguard24/__init__.py`, тег git, `CHANGELOG.md`.
 3. **Новые модули** — пакет `onguard24/modules/`, роутер подключать в `main.py` с префиксом `/api/v1/modules/<имя>`.
 4. **Миграции БД** — пока правки в `onguard24/db.py` (константа SQL); не ломать таблицу `ingress_events` без миграционного плана.
 5. **Статус интеграций** — логика в `status_snapshot.py` и `integrations/*`.
 ## Точки входа в код
 | Задача | Файл |
 |--------|------|
 | Новый эндпоинт | `main.py` или `modules/*.py` |
 | Настройки | `config.py` |
 | Webhook Grafana | `ingress/grafana.py` |
 | Проверка Vault/Grafana/Forgejo | `status_snapshot.py`, `integrations/` |
 | HTML главной | `root_html.py` |
 ## Откат
 См. [VERSIONING.md](VERSIONING.md). Теги `v1.0.0`, `v1.1.0`, …
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@ -0,0 +1,55 @@
 # Архитектура onGuard24 (для разработки и доработок)
 Цель продукта: **модульный монолит** в духе IRM — ядро + подключаемые области (дежурства, контакты, «светофор» по сервисам). Текущая версия — **каркас v1**: HTTP, БД, ingress Grafana, проверки интеграций.
 ## Дерево пакетов
 ```
 onGuard24/
 ├── onguard24/
 │   ├── main.py              # FastAPI app, lifespan, маршруты верхнего уровня
 │   ├── config.py            # Settings: .env из корня репозитория (не от cwd)
 │   ├── db.py                # asyncpg pool, миграция ingress_events
 │   ├── status_snapshot.py   # Единый сборщик JSON для /api/v1/status
 │   ├── root_html.py         # HTML главной страницы со статусами
 │   ├── vaultcheck.py        # Vault /v1/sys/health
 │   ├── ingress/grafana.py   # POST webhook Grafana → INSERT ingress_events
 │   ├── integrations/
 │   │   ├── grafana_api.py   # Grafana HTTP API (Bearer SA)
 │   │   └── forgejo_api.py   # Forgejo/Gitea API (token + probe/fallback)
 │   └── modules/             # Заглушки: schedules, contacts, statusboard
 ├── web/                     # Vite + React (опционально)
 ├── pyproject.toml
 ├── CHANGELOG.md
 └── docs/
 ```
 ## Поток данных (сейчас)
 1. **Grafana** (отдельно настроенный contact point) шлёт **POST** на `/api/v1/ingress/grafana` → тело JSON пишется в **`ingress_events`**.
 2. **Параллельно** Grafana может слать в Mattermost — это вне этого репозитория (конфиг Grafana).
 3. **Статус страницы** не ходит в Grafana за алертами — только **проверка доступности API** (токен SA).
 ## Куда класть новый функционал
 | Задача | Место |
 |--------|--------|
 | Новый HTTP-роут модуля | `onguard24/modules/<name>.py` + `include_router` в `main.py` |
 | Общая логика инцидентов / событий | позже: `onguard24/core/` или сервисный слой + события из БД |
 | Новая таблица БД | пока: SQL в `db.py` (MIGRATION_00N); позже: Alembic |
 | Новая внешняя интеграция | `onguard24/integrations/<name>.py`, вызов из `status_snapshot` при необходимости |
 ## Конфигурация
 Все секреты только через **переменные окружения** / `.env` (файл **не в git**). Список ключей — `.env.example`.
 ## Зависимости между компонентами
 - `status_snapshot.build(request)` читает `request.app.state.pool` и `request.app.state.settings` (устанавливаются в `lifespan`).
 - Модули **не** зависят друг от друга; общий контракт позже можно ввести через **таблицы БД** и **внутренние события** (ещё не реализовано).
 ## Известные ограничения v1
 - Нет единой модели «инцидент» в БД — только сырой ingest в `ingress_events`.
 - Нет очереди/воркеров для эскалаций.
 - Нет auth на GET `/api/v1/status` (только для внутренней сети / за reverse proxy с ограничением).
--- a/docs/VERSIONING.md
+++ b/docs/VERSIONING.md
@ -0,0 +1,43 @@
 # Версии и откат
 ## Соглашение
 | Что | Как |
 |-----|-----|
 | Версия в коде | `pyproject.toml` → `[project] version`, `onguard24/__init__.py` → `__version__` |
 | Git-теги | Аннотированные: `v1.0.0`, `v1.1.0` (`git tag -a v1.0.0 -m "..."`) |
 | Ветка по умолчанию | `main` |
 Семвер ориентир:
 - **MAJOR** — несовместимые изменения API или схемы БД.
 - **MINOR** — новые фичи, обратная совместимость.
 - **PATCH** — исправления без смены контракта.
 ## Откат к предыдущей версии
 ```bash
 git fetch --tags
 git checkout v1.0.0   # или нужный тег
 # отладка / hotfix от тега
 ```
 Новая ветка от старого тега:
 ```bash
 git checkout -b hotfix/v1.0.1 v1.0.0
 ```
 Сравнение версий:
 ```bash
 git log v1.0.0..main --oneline
 git diff v1.0.0..main
 ```
 ## Выпуск новой версии (чеклист)
 1. Обновить `CHANGELOG.md`, `pyproject.toml`, `onguard24/__init__.py`.
 2. `git commit -m "chore: release vX.Y.Z"`.
 3. `git tag -a vX.Y.Z -m "Release vX.Y.Z"`.
 4. `git push origin main --tags`.
--- a/onguard24/init.py
+++ b/onguard24/init.py
@ -0,0 +1,3 @@
 """onGuard24 — модульный монолит (ядро + модули)."""
 __version__ = "1.0.0"
--- a/onguard24/config.py
+++ b/onguard24/config.py
@ -0,0 +1,37 @@
 from pathlib import Path
 from dotenv import load_dotenv
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 # .env рядом с корнём проекта (не зависит от текущей директории при запуске uvicorn)
 _PROJECT_ROOT = Path(__file__).resolve().parent.parent
 load_dotenv(_PROJECT_ROOT / ".env")
 class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=str(_PROJECT_ROOT / ".env"),
        env_file_encoding="utf-8",
        extra="ignore",
    )
    http_addr: str = Field(default="0.0.0.0:8080", validation_alias="HTTP_ADDR")
    database_url: str = Field(default="", validation_alias="DATABASE_URL")
    grafana_webhook_secret: str = Field(default="", validation_alias="GRAFANA_WEBHOOK_SECRET")
    # HTTP API (service account): Grafana → Administration → Service accounts → токен
    grafana_url: str = Field(default="", validation_alias="GRAFANA_URL")
    grafana_service_account_token: str = Field(
        default="",
        validation_alias="GRAFANA_SERVICE_ACCOUNT_TOKEN",
    )
    vault_addr: str = Field(default="", validation_alias="VAULT_ADDR")
    vault_token: str = Field(default="", validation_alias="VAULT_TOKEN")
    # Forgejo (Gitea-совместимый API): Settings → Applications → токен, или при создании PAT
    forgejo_url: str = Field(default="", validation_alias="FORGEJO_URL")
    forgejo_token: str = Field(default="", validation_alias="FORGEJO_TOKEN")
    log_level: str = Field(default="info", validation_alias="LOG_LEVEL")
 def get_settings() -> Settings:
    return Settings()
--- a/onguard24/db.py
+++ b/onguard24/db.py
@ -0,0 +1,32 @@
 import asyncpg
 from onguard24.config import Settings
 def normalize_dsn(url: str) -> str:
    if url.startswith("postgres://"):
        return url.replace("postgres://", "postgresql://", 1)
    return url
 async def create_pool(settings: Settings) -> asyncpg.Pool | None:
    if not settings.database_url.strip():
        return None
    dsn = normalize_dsn(settings.database_url.strip())
    return await asyncpg.create_pool(dsn=dsn, min_size=1, max_size=10)
 MIGRATION_001 = """
 CREATE TABLE IF NOT EXISTS ingress_events (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    source text NOT NULL,
    received_at timestamptz NOT NULL DEFAULT now(),
    body jsonb NOT NULL
 );
 CREATE INDEX IF NOT EXISTS ingress_events_received_at_idx ON ingress_events (received_at DESC);
 """
 async def migrate(pool: asyncpg.Pool) -> None:
    async with pool.acquire() as conn:
        await conn.execute(MIGRATION_001)
--- a/onguard24/ingress/init.py
+++ b/onguard24/ingress/init.py
@ -0,0 +1 @@
 """Входящие интеграции (Grafana и др.)."""
--- a/onguard24/ingress/grafana.py
+++ b/onguard24/ingress/grafana.py
@ -0,0 +1,43 @@
 import json
 import logging
 from fastapi import APIRouter, Depends, Header, HTTPException, Request
 from starlette.responses import Response
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["ingress"])
 async def get_pool(request: Request):
    return getattr(request.app.state, "pool", None)
@router.post("/ingress/grafana", status_code=202)
 async def grafana_webhook(
    request: Request,
    pool=Depends(get_pool),
    x_onguard_secret: str | None = Header(default=None, alias="X-OnGuard-Secret"),
 ):
    settings = request.app.state.settings
    if settings.grafana_webhook_secret and x_onguard_secret != settings.grafana_webhook_secret:
        raise HTTPException(status_code=401, detail="unauthorized")
    raw = await request.body()
    if len(raw) > 1_000_000:
        raise HTTPException(status_code=400, detail="body too large")
    try:
        body = json.loads(raw.decode() or "{}")
    except json.JSONDecodeError:
        body = {}
    if pool is None:
        logger.warning("ingress: database not configured, event not persisted")
        return Response(status_code=202)
    async with pool.acquire() as conn:
        await conn.execute(
            "INSERT INTO ingress_events (source, body) VALUES ($1, $2::jsonb)",
            "grafana",
            json.dumps(body),
        )
    return Response(status_code=202)
--- a/onguard24/integrations/init.py
+++ b/onguard24/integrations/init.py
@ -0,0 +1 @@
 """Внешние интеграции (Grafana, Vault, …)."""
--- a/onguard24/integrations/forgejo_api.py
+++ b/onguard24/integrations/forgejo_api.py
@ -0,0 +1,103 @@
 """Forgejo / Gitea HTTP API: Authorization: token <secret>."""
 import httpx
 def _auth(token: str) -> dict[str, str]:
    return {
        "Authorization": f"token {token}",
        "Accept": "application/json",
    }
 async def probe(base_url: str, token: str) -> dict:
    """
    Проверка токена. Сначала GET /api/v1/user (нужен scope read:user).
    При 403 из‑за scope — fallback: GET /api/v1/admin/config (часто доступен с write:admin).
    """
    if not base_url.strip() or not token.strip():
        return {"status": "error", "detail": "forgejo url or token empty"}
    base = base_url.rstrip("/")
    h = _auth(token)
    try:
        async with httpx.AsyncClient(timeout=15.0, verify=True, follow_redirects=True) as client:
            ru = await client.get(f"{base}/api/v1/user", headers=h)
            if ru.status_code == 200:
                try:
                    u = ru.json()
                except Exception:
                    u = {}
                login = u.get("login")
                out: dict = {
                    "status": "ok",
                    "url": base,
                    "api": "authenticated",
                    "scope": "read:user",
                }
                if login:
                    out["login"] = login
                return out
            if ru.status_code == 403:
                for path, name in (
                    ("/api/v1/admin/config", "admin_config"),
                    ("/api/v1/notifications?limit=1", "notifications"),
                ):
                    rx = await client.get(f"{base}{path}", headers=h)
                    if rx.status_code == 200:
                        return {
                            "status": "ok",
                            "url": base,
                            "api": "authenticated",
                            "scope_note": (
                                "в токене нет scope read:user — в Forgejo включи read:user у PAT "
                                "или создай новый токен с read:user, чтобы отображался login"
                            ),
                            "fallback": name,
                        }
            body = (ru.text or "")[:500]
            return {
                "status": "error",
                "url": base,
                "detail": f"http {ru.status_code}: {body}",
            }
    except Exception as e:
        return {"status": "error", "detail": str(e), "url": base_url.rstrip("/")}
 async def ping(base_url: str, token: str) -> tuple[bool, str | None]:
    """Обёртка для совместимости: True если status ok."""
    r = await probe(base_url, token)
    if r.get("status") == "ok":
        return True, None
    return False, r.get("detail", "unknown")
 async def get_user(base_url: str, token: str) -> tuple[dict | None, str | None]:
    base = base_url.rstrip("/")
    try:
        async with httpx.AsyncClient(timeout=15.0, verify=True, follow_redirects=True) as client:
            r = await client.get(f"{base}/api/v1/user", headers=_auth(token))
    except Exception as e:
        return None, str(e)
    if r.status_code != 200:
        return None, f"http {r.status_code}"
    try:
        return r.json(), None
    except Exception:
        return None, "invalid json"
 async def health_public(base_url: str) -> tuple[bool, str | None]:
    base = base_url.rstrip("/")
    try:
        async with httpx.AsyncClient(timeout=10.0, verify=True) as client:
            r = await client.get(f"{base}/api/v1/version")
    except Exception as e:
        return False, str(e)
    if r.status_code == 200:
        return True, None
    return False, f"http {r.status_code}"
--- a/onguard24/integrations/grafana_api.py
+++ b/onguard24/integrations/grafana_api.py
@ -0,0 +1,58 @@
 """HTTP API Grafana: service account token (Bearer), не пароль пользователя."""
 import httpx
 # Минимальный набор для проверки и будущих вызовов (алерты, папки и т.д.).
 async def ping(base_url: str, token: str) -> tuple[bool, str | None]:
    if not base_url.strip() or not token.strip():
        return False, "grafana url or token empty"
    base = base_url.rstrip("/")
    try:
        async with httpx.AsyncClient(timeout=15.0, verify=True, follow_redirects=True) as client:
            r = await client.get(
                f"{base}/api/org",
                headers={
                    "Authorization": f"Bearer {token}",
                    "Accept": "application/json",
                },
            )
    except Exception as e:
        return False, str(e)
    if r.status_code == 200:
        return True, None
    body = (r.text or "")[:300]
    return False, f"http {r.status_code}: {body}"
 async def get_signed_in_user(base_url: str, token: str) -> tuple[dict | None, str | None]:
    """GET /api/user — удобно убедиться, что токен от service account."""
    base = base_url.rstrip("/")
    try:
        async with httpx.AsyncClient(timeout=15.0, verify=True, follow_redirects=True) as client:
            r = await client.get(
                f"{base}/api/user",
                headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
            )
    except Exception as e:
        return None, str(e)
    if r.status_code != 200:
        return None, f"http {r.status_code}"
    try:
        return r.json(), None
    except Exception:
        return None, "invalid json"
 async def health_live(base_url: str) -> tuple[bool, str | None]:
    """GET /api/health — без авторизации, проверка что инстанс отвечает."""
    base = base_url.rstrip("/")
    try:
        async with httpx.AsyncClient(timeout=10.0, verify=True) as client:
            r = await client.get(f"{base}/api/health")
    except Exception as e:
        return False, str(e)
    if r.status_code == 200:
        return True, None
    return False, f"http {r.status_code}"
--- a/onguard24/main.py
+++ b/onguard24/main.py
@ -0,0 +1,108 @@
 import logging
 from contextlib import asynccontextmanager
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from starlette.responses import HTMLResponse, Response
 from onguard24.config import get_settings
 from onguard24.db import create_pool, migrate
 from onguard24.ingress import grafana as grafana_ingress
 from onguard24.modules import contacts, schedules, statusboard
 from onguard24.root_html import render_root_page
 from onguard24.status_snapshot import build as build_status
 from onguard24 import __version__ as app_version
 logging.basicConfig(level=logging.INFO)
 logging.getLogger("httpx").setLevel(logging.WARNING)
 log = logging.getLogger("onguard24")
 def parse_addr(http_addr: str) -> tuple[str, int]:
    s = http_addr.strip()
    if s.startswith(":"):
        return "0.0.0.0", int(s[1:])
    if ":" in s:
        h, p = s.rsplit(":", 1)
        return (h or "0.0.0.0"), int(p)
    return "0.0.0.0", int(s)
@asynccontextmanager
 async def lifespan(app: FastAPI):
    settings = get_settings()
    pool = await create_pool(settings)
    if pool:
        await migrate(pool)
    app.state.pool = pool
    app.state.settings = settings
    log.info("onGuard24 started, db=%s", "ok" if pool else "disabled")
    yield
    if pool:
        await pool.close()
        log.info("database pool closed")
 def create_app() -> FastAPI:
    app = FastAPI(title="onGuard24", version=app_version, lifespan=lifespan)
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["http://localhost:5173", "http://127.0.0.1:5173"],
        allow_credentials=True,
        allow_methods=["GET", "POST", "OPTIONS"],
        allow_headers=["*"],
    )
    @app.get("/")
    async def root(request: Request):
        if request.query_params.get("format") == "json":
            data = await build_status(request)
            data["links"] = {
                "docs": "/docs",
                "openapi": "/openapi.json",
                "health": "/health",
                "status_api": "/api/v1/status",
            }
            return data
        return HTMLResponse(await render_root_page(request))
    @app.get("/favicon.ico", include_in_schema=False)
    async def favicon():
        return Response(status_code=204)
    @app.get("/health")
    @app.get("/api/v1/health")
    async def health():
        return {"status": "ok", "service": "onGuard24"}
    @app.get("/api/v1/status")
    async def status(request: Request):
        return await build_status(request)
    app.include_router(grafana_ingress.router, prefix="/api/v1")
    app.include_router(schedules.router, prefix="/api/v1/modules/schedules")
    app.include_router(contacts.router, prefix="/api/v1/modules/contacts")
    app.include_router(statusboard.router, prefix="/api/v1/modules/statusboard")
    return app
 app = create_app()
 def run() -> None:
    import uvicorn
    settings = get_settings()
    host, port = parse_addr(settings.http_addr)
    lvl = settings.log_level.upper()
    uvicorn.run(
        "onguard24.main:app",
        host=host,
        port=port,
        log_level=lvl.lower() if lvl in {"DEBUG", "INFO", "WARNING", "ERROR"} else "info",
    )
 if __name__ == "__main__":
    run()
--- a/onguard24/modules/init.py
+++ b/onguard24/modules/init.py
@ -0,0 +1 @@
 """Подключаемые модули onGuard24."""
--- a/onguard24/modules/contacts.py
+++ b/onguard24/modules/contacts.py
@ -0,0 +1,12 @@
 from fastapi import APIRouter
 router = APIRouter(tags=["module-contacts"])
@router.get("/")
 async def contacts_root():
    return {
        "module": "contacts",
        "status": "stub",
        "note": "люди, группы, каналы доставки",
    }
--- a/onguard24/modules/schedules.py
+++ b/onguard24/modules/schedules.py
@ -0,0 +1,12 @@
 from fastapi import APIRouter
 router = APIRouter(tags=["module-schedules"])
@router.get("/")
 async def schedules_root():
    return {
        "module": "schedules",
        "status": "stub",
        "note": "календарь и смены — следующий этап",
    }
--- a/onguard24/modules/statusboard.py
+++ b/onguard24/modules/statusboard.py
@ -0,0 +1,13 @@
 from fastapi import APIRouter
 router = APIRouter(tags=["module-statusboard"])
@router.get("/")
 async def statusboard_root():
    return {
        "module": "statusboard",
        "status": "stub",
        "note": "светофор по сервисам — агрегация по алертам",
        "demo": [],
    }
--- a/onguard24/root_html.py
+++ b/onguard24/root_html.py
@ -0,0 +1,88 @@
 import html
 import json
 from onguard24.status_snapshot import build
 def _row(name: str, value: object) -> str:
    label = html.escape(name)
    if value == "disabled":
        badge = '<span class="badge muted">не настроено</span>'
        return f"<tr><th>{label}</th><td>{badge}</td></tr>"
    if isinstance(value, dict):
        st = value.get("status", "?")
        if st == "ok":
            badge = '<span class="badge ok">OK</span>'
        elif st == "reachable":
            badge = '<span class="badge warn">доступен</span>'
        elif st == "error":
            badge = '<span class="badge err">ошибка</span>'
        else:
            badge = f'<span class="badge muted">{html.escape(str(st))}</span>'
        extra = {k: v for k, v in value.items() if k != "status"}
        detail_html = ""
        if extra:
            detail_html = (
                f'<tr class="sub"><td colspan="2"><pre class="detail">'
                f"{html.escape(json.dumps(extra, ensure_ascii=False, indent=2))}"
                f"</pre></td></tr>"
            )
        return f"<tr><th>{label}</th><td>{badge}</td></tr>{detail_html}"
    badge = html.escape(str(value))
    return f"<tr><th>{label}</th><td>{badge}</td></tr>"
 async def render_root_page(request) -> str:
    data = await build(request)
    rows = ""
    for key in ("database", "vault", "grafana", "forgejo"):
        if key in data:
            rows += _row(key, data[key])
    payload = html.escape(json.dumps(data, ensure_ascii=False, indent=2))
    return f"""<!DOCTYPE html>
 <html lang="ru">
 <head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <title>onGuard24</title>
  <style>
    body {{ font-family: system-ui, sans-serif; margin: 2rem; background: #fafafa; color: #18181b; }}
    h1 {{ margin-top: 0; }}
    .badge {{ display: inline-block; padding: 0.15rem 0.5rem; border-radius: 6px; font-size: 0.85rem; font-weight: 600; }}
    .ok {{ background: #dcfce7; color: #166534; }}
    .warn {{ background: #fef9c3; color: #854d0e; }}
    .err {{ background: #fee2e2; color: #991b1b; }}
    .muted {{ background: #e4e4e7; color: #52525b; }}
    table {{ border-collapse: collapse; width: 100%; max-width: 56rem; background: #fff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px #0001; }}
    th {{ text-align: left; padding: 0.75rem 1rem; width: 10rem; vertical-align: top; border-bottom: 1px solid #e4e4e7; }}
    td {{ padding: 0.75rem 1rem; border-bottom: 1px solid #e4e4e7; }}
    tr.sub .detail {{ margin: 0; font-size: 0.8rem; max-height: 10rem; overflow: auto; }}
    .links a {{ margin-right: 1rem; }}
    .json {{ margin-top: 2rem; max-width: 56rem; }}
    .json pre {{ background: #18181b; color: #e4e4e7; padding: 1rem; border-radius: 8px; overflow: auto; font-size: 0.8rem; }}
  </style>
 </head>
 <body>
  <h1>onGuard24</h1>
  <p class="links">
    <a href="/docs">Swagger</a>
    <a href="/openapi.json">OpenAPI</a>
    <a href="/health">/health</a>
    <a href="/api/v1/status">JSON статус</a>
  </p>
  <h2>Проверки доступа</h2>
  <table>
    <tbody>
      {rows}
    </tbody>
  </table>
  <div class="json">
    <h3>Полный ответ <code>/api/v1/status</code></h3>
    <pre>{payload}</pre>
  </div>
 </body>
 </html>"""
--- a/onguard24/status_snapshot.py
+++ b/onguard24/status_snapshot.py
@ -0,0 +1,77 @@
 """Единая сборка ответа /api/v1/status (БД, Vault, Grafana, Forgejo)."""
 from fastapi import Request
 from onguard24.config import Settings
 from onguard24.integrations import forgejo_api, grafana_api
 from onguard24.vaultcheck import ping as vault_ping
 async def build(request: Request) -> dict:
    out: dict = {"service": "onGuard24"}
    pool = getattr(request.app.state, "pool", None)
    settings: Settings = request.app.state.settings
    if pool:
        try:
            async with pool.acquire() as conn:
                await conn.fetchval("SELECT 1")
            out["database"] = {"status": "ok"}
        except Exception as e:
            out["database"] = {"status": "error", "detail": str(e)}
    else:
        out["database"] = "disabled"
    if settings.vault_addr and settings.vault_token:
        ok, err = await vault_ping(settings.vault_addr, settings.vault_token)
        if ok:
            out["vault"] = {"status": "ok", "url": settings.vault_addr}
        else:
            out["vault"] = {"status": "error", "detail": err, "url": settings.vault_addr}
    else:
        out["vault"] = "disabled"
    gu = settings.grafana_url.strip()
    if not gu:
        out["grafana"] = "disabled"
    elif settings.grafana_service_account_token.strip():
        ok, err = await grafana_api.ping(gu, settings.grafana_service_account_token)
        if ok:
            user, _ = await grafana_api.get_signed_in_user(gu, settings.grafana_service_account_token)
            entry: dict = {"status": "ok", "url": gu, "api": "authenticated"}
            if user:
                login = user.get("login") or user.get("email")
                if login:
                    entry["service_account_login"] = login
            out["grafana"] = entry
        else:
            out["grafana"] = {"status": "error", "detail": err, "url": gu}
    else:
        live_ok, live_err = await grafana_api.health_live(gu)
        if live_ok:
            out["grafana"] = {
                "status": "reachable",
                "url": gu,
                "detail": "задай GRAFANA_SERVICE_ACCOUNT_TOKEN для вызовов API",
            }
        else:
            out["grafana"] = {"status": "error", "detail": live_err, "url": gu}
    fj = settings.forgejo_url.strip()
    if not fj:
        out["forgejo"] = "disabled"
    elif settings.forgejo_token.strip():
        entry_fj = await forgejo_api.probe(fj, settings.forgejo_token)
        out["forgejo"] = entry_fj
    else:
        pub_ok, pub_err = await forgejo_api.health_public(fj)
        if pub_ok:
            out["forgejo"] = {
                "status": "reachable",
                "url": fj,
                "detail": "задай FORGEJO_TOKEN (Personal Access Token в Forgejo)",
            }
        else:
            out["forgejo"] = {"status": "error", "detail": pub_err, "url": fj}
    return out
--- a/onguard24/vaultcheck.py
+++ b/onguard24/vaultcheck.py
@ -0,0 +1,18 @@
 import httpx
 async def ping(addr: str, token: str) -> tuple[bool, str | None]:
    if not addr or not token:
        return False, "vault addr or token empty"
    base = addr.rstrip("/")
    try:
        async with httpx.AsyncClient(timeout=5.0, verify=True) as client:
            r = await client.get(
                f"{base}/v1/sys/health",
                headers={"X-Vault-Token": token},
            )
    except Exception as e:
        return False, str(e)
    if r.status_code in (200, 429, 503, 501):
        return True, None
    return False, f"http {r.status_code}"
--- a/pyproject.toml
+++ b/pyproject.toml
@ -0,0 +1,28 @@
 [project]
 name = "onguard24"
 version = "1.0.0"
 description = "onGuard24 — модульный сервис (аналог IRM)"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.32.0",
    "pydantic-settings>=2.6.0",
    "python-dotenv>=1.0.1",
    "asyncpg>=0.30.0",
    "httpx>=0.28.0",
 ]
 [project.scripts]
 onguard = "onguard24.main:run"
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["onguard24"]
 [tool.ruff]
 line-length = 100
 target-version = "py311"
--- a/web/index.html
+++ b/web/index.html
@ -0,0 +1,12 @@
 <!DOCTYPE html>
 <html lang="ru">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>onGuard24</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
 </html>
--- a/web/package.json
+++ b/web/package.json
@ -0,0 +1,22 @@
 {
  "name": "onguard24-web",
  "private": true,
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/react": "^18.3.12",
    "@types/react-dom": "^18.3.1",
    "@vitejs/plugin-react": "^4.3.3",
    "typescript": "~5.6.2",
    "vite": "^5.4.10"
  }
 }
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@ -0,0 +1,32 @@
 import { useEffect, useState } from "react";
 type Status = Record<string, unknown>;
 export default function App() {
  const [status, setStatus] = useState<Status | null>(null);
  const [err, setErr] = useState<string | null>(null);
  useEffect(() => {
    fetch("/api/v1/status")
      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(String(r.status)))))
      .then(setStatus)
      .catch((e) => setErr(String(e)));
  }, []);
  return (
    <div style={{ fontFamily: "system-ui", padding: "2rem", maxWidth: 640 }}>
      <h1>onGuard24</h1>
      <p>Модульный монолит: API на FastAPI, модули — заглушки.</p>
      <h2>Статус</h2>
      {err && <p style={{ color: "crimson" }}>Ошибка: {err}</p>}
      {status && (
        <pre style={{ background: "#f4f4f5", padding: "1rem", borderRadius: 8 }}>
          {JSON.stringify(status, null, 2)}
        </pre>
      )}
      <p style={{ marginTop: "2rem", color: "#666" }}>
        Бэкенд: <code>uvicorn onguard24.main:app --port 8080</code>
      </p>
    </div>
  );
 }
--- a/web/src/index.css
+++ b/web/src/index.css
@ -0,0 +1,5 @@
 body {
  margin: 0;
  background: #fafafa;
  color: #18181b;
 }
--- a/web/src/main.tsx
+++ b/web/src/main.tsx
@ -0,0 +1,10 @@
 import React from "react";
 import ReactDOM from "react-dom/client";
 import App from "./App";
 import "./index.css";
 ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
 );
--- a/web/src/vite-env.d.ts
+++ b/web/src/vite-env.d.ts
@ -0,0 +1 @@
 /// <reference types="vite/client" />
--- a/web/tsconfig.json
+++ b/web/tsconfig.json
@ -0,0 +1,20 @@
 {
  "compilerOptions": {
    "target": "ES2022",
    "useDefineForClassFields": true,
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-js",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
 }
--- a/web/tsconfig.node.json
+++ b/web/tsconfig.node.json
@ -0,0 +1,10 @@
 {
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler"
  },
  "include": ["vite.config.ts"]
 }
--- a/web/vite.config.ts
+++ b/web/vite.config.ts
@ -0,0 +1,13 @@
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      "/api": { target: "http://127.0.0.1:8080", changeOrigin: true },
      "/health": { target: "http://127.0.0.1:8080", changeOrigin: true },
    },
  },
 });
		`@ -0,0 +1,3 @@`
							`"""onGuard24 — модульный монолит (ядро + модули)."""`

							`__version__ = "1.0.0"`
		`@ -0,0 +1 @@`
							`"""Входящие интеграции (Grafana и др.)."""`
		`@ -0,0 +1 @@`
							`"""Внешние интеграции (Grafana, Vault, …)."""`
		`@ -0,0 +1 @@`
							`"""Подключаемые модули onGuard24."""`