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