Stage 03.5 - private account balance and portfolio UI

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