# 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  
(структурированный доступ к данным и подготовка к работе с ордерами)