85eb61b576
- Миграции PostgreSQL через Alembic; DDL убран из lifespan приложения. - Тесты: health, status, ingress Grafana; моки Vault/Grafana/Forgejo. - Пакет onguard24/domain/ (сущности, шина событий), docs/DOMAIN.md. - Обновлены README, CHANGELOG, ARCHITECTURE. Made-with: Cursor
61 lines
4.2 KiB
Markdown
61 lines
4.2 KiB
Markdown
# Архитектура onGuard24 (для разработки и доработок)
|
||
|
||
Цель продукта: **модульный монолит** в духе IRM — ядро + подключаемые области (дежурства, контакты, «светофор» по сервисам). Текущая версия — **каркас v1.1**: HTTP, БД, ingress Grafana, проверки интеграций, Alembic, задел домена в `onguard24/domain/`.
|
||
|
||
## Дерево пакетов
|
||
|
||
```
|
||
onGuard24/
|
||
├── alembic/ # Ревизии миграций PostgreSQL (Alembic)
|
||
├── alembic.ini
|
||
├── onguard24/
|
||
│ ├── main.py # FastAPI app, lifespan, маршруты верхнего уровня
|
||
│ ├── config.py # Settings: .env из корня репозитория (не от cwd)
|
||
│ ├── db.py # asyncpg pool (без DDL)
|
||
│ ├── domain/ # Сущности и шина событий (задел под модули)
|
||
│ ├── 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
|
||
├── pytest.ini
|
||
├── tests/ # pytest: health, status, ingress
|
||
├── 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/domain/` + [DOMAIN.md](DOMAIN.md); позже сервисный слой и БД |
|
||
| Новая таблица БД | Alembic: `alembic revision`, правка `alembic/versions/`, `alembic upgrade head` |
|
||
| Новая внешняя интеграция | `onguard24/integrations/<name>.py`, вызов из `status_snapshot` при необходимости |
|
||
|
||
## Конфигурация
|
||
|
||
Все секреты только через **переменные окружения** / `.env` (файл **не в git**). Список ключей — `.env.example`.
|
||
|
||
## Зависимости между компонентами
|
||
|
||
- `status_snapshot.build(request)` читает `request.app.state.pool` и `request.app.state.settings` (устанавливаются в `lifespan`).
|
||
- Модули **не** зависят друг от друга; контракт заделан через **доменные события** (`domain/events.py`, `EventBus`) и описан в [DOMAIN.md](DOMAIN.md); проводка в HTTP пока не подключена.
|
||
|
||
## Известные ограничения
|
||
|
||
- Нет единой модели «инцидент» в БД — только сырой ingest в `ingress_events` (в коде есть Pydantic-модели в `domain/entities.py` как задел).
|
||
- Нет очереди/воркеров для эскалаций.
|
||
- Нет auth на GET `/api/v1/status` (только для внутренней сети / за reverse proxy с ограничением).
|