Stage 03.5 - private account balance and portfolio UI

docs/decisions/0008-private-account-first.md

@@ -0,0 +1,86 @@
+# 0008 — Private API starts from Account Balance (Stable)
+
+## Решение
+Начать интеграцию private API с получения баланса аккаунта (`/api/v2/account`), а не с ордеров.
+
+---
+
+## Причины
+
+### 1. Безопасность
+- чтение баланса не изменяет состояние системы
+- отсутствует риск случайной торговли
+
+---
+
+### 2. Простота отладки
+Позволяет проверить:
+- API ключ
+- подпись (HMAC)
+- headers
+- timestamp
+
+---
+
+### 3. Быстрый UX результат
+Пользователь сразу видит:
+- баланс
+- активы
+
+---
+
+### 4. База для следующих этапов
+Баланс используется в:
+- расчёте риска
+- позициях
+- ордерах
+- журнале
+
+---
+
+## Реализация
+
+Добавлено:
+- ExchangePrivateClient
+- balance_parser
+- get_balance_summary()
+- get_private_auth_health()
+- экран 💼 Портфель
+- статус авторизации в ⚙️ Система
+
+---
+
+## Последствия
+
+### Положительные
+✔ быстрый результат  
+✔ безопасная интеграция  
+✔ понятный UI  
+✔ устойчивая архитектура  
+
+---
+
+### Отрицательные
+- не покрывает сразу торговый сценарий
+- требует следующего этапа (orders)
+
+---
+
+## Альтернативы
+
+### Начать с ордеров
+❌ отклонено:
+- риск
+- сложность
+- сложнее отлаживать
+
+---
+
+## Статус
+Stable
+
+---
+
+## Следующий шаг
+
+➡ Stage 03.6 — Orders skeleton

docs/stages/stage-03-5-account-balance.md

@@ -0,0 +1,151 @@
+# Stage 03.5 — Private Account + Portfolio UI (Stable)
+
+## Цель
+Реализовать первый реальный private API запрос и вывести баланс пользователя в Telegram.
+
+---
+
+## Что добавлено
+
+### 1. Private API endpoint
+Используется:
+- `GET /api/v2/account`
+
+Особенности:
+- требуется `timestamp`
+- требуется `signature`
+- требуется header `X-MBX-APIKEY`
+
+---
+
+### 2. Private client
+Добавлен:
+- `ExchangePrivateClient`
+
+Функции:
+- подпись запроса (HMAC SHA256)
+- формирование headers
+- отправка signed-запроса
+
+---
+
+### 3. Парсер баланса
+Добавлен:
+- `balance_parser.py`
+
+Особенности:
+- поддерживает разные форматы ответа API:
+  - `balances`
+  - `payload.balances`
+  - `payload`
+  - `assets`
+- безопасный парсинг чисел
+- защита от "грязных" данных API
+
+---
+
+### 4. ExchangeService
+
+Добавлено:
+
+- `get_balance_summary()`
+- `get_private_auth_health()`
+
+Функции:
+- получение баланса
+- проверка private API
+- централизованная обработка ошибок
+
+---
+
+### 5. Telegram — экран 💼 Портфель
+Добавлено:
+- отображение баланса пользователя
+
+---
+
+### 6. UX улучшения (Stage 03.5+)
+
+Экран портфеля теперь:
+
+- показывает значки валют (₿, 💵, Ξ и др.)
+- скрывает нулевые балансы
+- сортирует активы
+- выделяет основные активы:
+  - USD
+  - USDT
+  - BTC
+  - ETH
+- разбивает на блоки:
+  - основные активы
+  - прочие активы
+- показывает итоговое количество активов
+
+---
+
+### 7. Экран ⚙️ Система
+
+Добавлено:
+
+🟢 Авторизация  
+— Private API OK. Балансов получено: N  
+
+или  
+
+🔴 Авторизация  
+— ошибка подписи / ключа / доступа  
+
+---
+
+## Как работает
+
+### EXCHANGE_ENABLED=false
+- используется mock режим
+- баланс берётся из mock
+
+### EXCHANGE_ENABLED=true
+
+Flow:
+
+1. Проверка ключей  
+2. Формирование signed запроса  
+3. Запрос `/api/v2/account`  
+4. Парсинг ответа  
+5. Вывод в Telegram  
+
+---
+
+## Что теперь гарантируется
+
+✔ private API реально работает  
+✔ ошибки авторизации видны пользователю  
+✔ бот не падает при нестабильном API  
+✔ баланс отображается корректно  
+✔ UX пригоден для реального использования  
+
+---
+
+## Ограничения
+
+Пока НЕ реализовано:
+
+- ордера  
+- торговля  
+- PnL  
+- оценка портфеля в USD  
+- кэширование  
+- rate limit handling  
+
+---
+
+## Рекомендуемый commit
+
+Stage 03.5 - private account balance and portfolio UI
+
+---
+
+## Следующий этап
+
+➡ Stage 03.6 — Orders skeleton  
+или  
+➡ Stage 04 — Storage / Journal