onGuard24/README.md

# onGuard24

**Версия: 1.6.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) | Краткий контекст для доработок |
| [docs/DOMAIN.md](docs/DOMAIN.md) | Сущности (инцидент, алерт, эскалация), шина событий |
| [docs/MODULES.md](docs/MODULES.md) | Как добавлять модули и подписки на события |
| [docs/IRM.md](docs/IRM.md) | Функционал IRM: что делаем, что в Grafana |
| [docs/CICD.md](docs/CICD.md) | Forgejo Actions: деплой на сервер, откат по тегу |

**Репозиторий:** [forgejo.pvenode.ru/admin/onGuard24](https://forgejo.pvenode.ru/admin/onGuard24)

---

## Что уже есть (функционал v1)

- Запуск HTTP API (`uvicorn`), конфиг из `.env`.
- **PostgreSQL:** пул asyncpg, таблица `ingress_events` для сырых тел webhook Grafana; схема через **Alembic** (отдельные ревизии в `alembic/versions/`).
- **POST `/api/v1/ingress/grafana`** — приём JSON алерта (опционально защита `X-OnGuard-Secret`).
- **GET `/`**, **GET `/api/v1/status`** — проверки: БД, Vault, Grafana (service account), Forgejo (PAT).
- **Модули (API + веб-UI):** IRM — **инциденты**, **задачи**, **эскалации**, дежурства, контакты, светофор; JSON под `/api/v1/modules/...`, UI под `/ui/modules/<slug>/` (см. [docs/MODULES.md](docs/MODULES.md), [docs/IRM.md](docs/IRM.md)).
- **Фронт (опционально):** `web/` — Vite + React, прокси на API.

Чего **ещё нет** (следующие версии): авторизация публичных API (кроме секрета webhook), полноценная бизнес-логика IRM в коде (эскалации, дежурства, светофор), фоновые задачи. Доменные сущности и задел под модули описаны в [docs/DOMAIN.md](docs/DOMAIN.md).

## Быстрый старт

```bash
cd onGuard24
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
```

Скопируй `.env.example` в `.env` и заполни секреты (см. ниже). Перед первым запуском с БД примените миграции (в т.ч. таблицы IRM: `incidents`, `tasks`, `escalation_policies`):

```bash
alembic upgrade head
```

```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`).

## Миграции БД (Alembic)

- URL БД: переменная **`DATABASE_URL`** (как у приложения; в `alembic/env.py` используется синхронный драйвер `postgresql+psycopg`). К URL автоматически добавляется **`client_encoding=utf8`**, чтобы миграции не падали с `TypeError: ... bytes-like object`, если на сервере PostgreSQL включён режим вроде `SQL_ASCII`.
- Применить схему: `alembic upgrade head`.
- Новая ревизия: `alembic revision -m "описание"` и правка файла в `alembic/versions/`.

Приложение **не** выполняет DDL при старте — только пул соединений.

## Тесты

```bash
pip install -e ".[dev]"
pytest
```

Покрытие: `/health`, `/api/v1/status`, webhook Grafana; внешние вызовы (Vault, Grafana, Forgejo) в тестах статуса подменяются моками.

## Docker и CI/CD

```bash
docker compose build && docker compose up -d
```

Деплой через **Forgejo Actions** (тег `v*`, SSH на сервер): см. [docs/CICD.md](docs/CICD.md). **Откат:** вручную запустить workflow **Deploy** с полем `ref` = нужный старый тег.