Stage 04.2 - journal and event log

2026-04-16 13:13:03 +03:00
parent c35deeaefa
commit 2c49bb70c0
11 changed files with 780 additions and 28 deletions
--- a/docs/stages/stage-04-2-journal.md
+++ b/docs/stages/stage-04-2-journal.md
@@ -0,0 +1,205 @@
+# Stage 04.2 — Journal (Event Log)
+
+## Цель
+Добавить в систему слой журналирования (event log), который сохраняет события в PostgreSQL и отображает их пользователю через Telegram.
+
+---
+
+## Что реализовано
+
+### Journal (журнал событий)
+
+Добавлена таблица:
+
+- `journal_events`
+
+Структура:
+- `id`
+- `created_at`
+- `level` (INFO / WARNING / ERROR)
+- `event_type`
+- `message`
+- `payload_json`
+
+---
+
+### Repository слой
+
+Добавлен:
+
+- `JournalRepository`
+
+Функции:
+- запись события (`add_event`)
+- получение списка событий
+- получение количества событий
+- получение событий с offset (для пагинации)
+
+---
+
+### Service слой
+
+Добавлен:
+
+- `JournalService`
+
+Функции:
+- `log_info`
+- `log_warning`
+- `log_error`
+- `get_recent`
+- `get_page` (пагинация)
+- `get_total_count`
+- `get_journal_health`
+
+Особенность:
+- журнал не должен ломать приложение (все вызовы обёрнуты в try/except)
+
+---
+
+### Интеграция в систему
+
+#### При старте приложения
+Записывается событие:
+
+- `app_start`
+
+---
+
+#### ExchangeService
+
+Добавлено логирование:
+
+- `balance_summary_loaded`
+- `balance_summary_error`
+- `balance_summary_empty`
+- `market_price_error`
+
+---
+
+#### Portfolio handler (`💼 Портфель`)
+
+Добавлены события:
+
+- `user_open_portfolio`
+- `portfolio_open_success`
+- `portfolio_open_error`
+- `portfolio_empty`
+- `portfolio_zero_balances`
+
+---
+
+#### Market handler (`📈 Рынок`)
+
+Добавлены события:
+
+- `user_open_market`
+- `market_open_success`
+- `market_open_error`
+- `market_symbol_invalid`
+
+---
+
+### UI — экран `📒 Журнал`
+
+Функциональность:
+
+- вывод последних событий
+- форматирование:
+  - уровень
+  - время
+  - сообщение
+- отображение иконок:
+  - ℹ️ INFO
+  - 🟡 WARNING
+  - 🔴 ERROR
+
+---
+
+### Пагинация
+
+Реализована постраничная навигация:
+
+- размер страницы: 3 события
+- кнопки:
+  - ⏮️ — в начало
+  - ⬅️ — предыдущая страница
+  - ➡️ — следующая страница
+- отображение текущей страницы: `3/9`
+
+Особенности:
+- отсутствует дублирующий текст "Страница X из Y"
+- кнопка ⏮️ отображается только начиная со 2-й страницы
+
+---
+
+### Интеграция в `⚙️ Система`
+
+Добавлен компонент:
+
+- `🟢 Журнал`
+
+Проверка:
+- доступность БД
+- возможность чтения журнала
+
+---
+
+## Архитектурный результат
+
+После Stage 04.2 система получила:
+
+- persistent event log
+- трассировку пользовательских действий
+- диагностику ошибок через UI
+- основу для аналитики и трейдинга
+
+---
+
+## Важные принципы
+
+### 1. Journal = append-only
+События не удаляются и не изменяются.
+
+---
+
+### 2. Логируем только важное
+Не логируются:
+- каждый вызов system screen
+- внутренние технические операции
+
+Логируются:
+- действия пользователя
+- ошибки
+- ключевые результаты операций
+
+---
+
+### 3. Journal не влияет на стабильность
+Ошибки журнала не должны ломать приложение.
+
+---
+
+## Ограничения текущей реализации
+
+- журнал растёт без ограничения
+- нет фильтрации (по уровню / типу)
+- нет очистки или архивации
+
+---
+
+## Что дальше
+
+Возможные улучшения:
+
+- фильтр по уровню (ERROR / INFO)
+- локализация времени (timezone вместо UTC)
+- ограничение размера журнала
+- очистка старых событий
+
+---
+
+## Следующий этап
+
+- Stage 04.3 — Repositories  
+(структурированный доступ к данным и подготовка к работе с ордерами)