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

Made-with: Cursor

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`, …

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 с ограничением).

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