Stage 05.7 - trade draft UI restructuring and order context display

docs/stages/stage-03-3-exchange-info.txt

@@ -1 +0,0 @@
-docs_stage-03-3-exchange-info

docs/stages/stage_05-7-trade-draft-UI-restructuring.md

@@ -0,0 +1,241 @@
+# Stage 05.7 — trade draft UI restructuring and order context display
+
+## Что сделано
+
+На этом этапе был завершён крупный блок улучшений сценария создания черновика ордера в разделе **Торговля**.
+
+Основные изменения:
+
+- переработан UI сценария нового ордера
+- вынесены и унифицированы экранные рендеры
+- вынесены части логики в отдельные файлы
+- добавлено отображение контекста ордера на ключевых экранах
+- добавлены валюта котировки и базовый актив в отображение параметров ордера
+- улучшена работа экранов черновиков
+- введена общая UI-линия режима аккаунта
+- подготовлена база для дальнейшей декомпозиции trade-модуля
+
+---
+
+## Структурные изменения
+
+### Разделение сценария нового ордера
+
+Монолитный сценарий `new_order.py` был разложен на логические части:
+
+- `new_order_core.py` — общая точка ядра сценария
+- `new_order_flow.py` — основной FSM flow создания/редактирования черновика
+- `new_order_navigation.py` — навигационные переходы и back-логика
+- `new_order_ui.py` — клавиатуры, рендеры экранов, форматирование и список черновиков
+- `new_order.py` — точка сборки роутеров сценария
+
+Это позволило уменьшить связанность кода и подготовить модуль к дальнейшему безопасному рефакторингу.
+
+---
+
+## UI и UX улучшения
+
+### 1. Единый стиль экранов Trade
+
+Интерфейс экранов нового ордера приведён к единому стилю:
+
+- единый заголовок
+- единая строка режима аккаунта
+- единый формат шагов сценария
+- единый стиль ошибок и подтверждений
+
+### 2. Отображение контекста ордера
+
+На экранах сценария теперь показываются:
+
+- количество с базовым активом  
+  пример: `0.01 BTC`
+- цена с валютой котировки  
+  пример: `84500.00 USD`
+- сумма ордера с валютой котировки  
+  пример: `845.00 USD`
+
+### 3. Улучшение экранов ручного ввода
+
+Для ручного ввода количества и цены теперь отображаются:
+
+- шаг
+- минимальный допустимый ввод
+- оценочная сумма ордера
+- пример корректного значения
+- ориентир цены с валютой котировки
+
+### 4. Улучшение экрана подтверждения
+
+На шаге подтверждения черновика теперь выводятся:
+
+- инструмент
+- сторона
+- тип ордера
+- количество с активом
+- цена или ориентир цены
+- итоговая сумма ордера
+
+---
+
+## Логика ордера
+
+### Контекст входа в ордер
+
+Сервис формирования черновика теперь возвращает расширенный `OrderEntryContext`, в котором учитываются:
+
+- `balance_currency`
+- `quote_currency`
+- `base_currency`
+- `reference_price`
+- `available_balance`
+- `bid_price`
+- `ask_price`
+- `last_price`
+
+### Валюты и активы
+
+Добавлена корректная работа с:
+
+- `base_currency` — актив инструмента
+- `quote_currency` — валюта котировки
+
+Это позволило явно показывать пользователю, в каких единицах отображаются:
+
+- количество
+- цена
+- сумма
+
+### Защита от некорректного символа инструмента
+
+Если биржа не возвращает `base_asset` или `quote_asset`, сервис больше не продолжает работу молча, а:
+
+- логирует ошибку
+- поднимает исключение
+- предотвращает некорректный расчёт контекста ордера
+
+---
+
+## Черновики
+
+### Список черновиков
+
+Экран последних черновиков был обновлён и приведён к общему стилю.
+
+Поддерживается:
+
+- список последних записей
+- пагинация
+- открытие карточки черновика
+- переход в редактирование
+- возврат назад
+
+### Детальный экран черновика
+
+На экране конкретного черновика теперь корректно отображаются:
+
+- количество с активом
+- цена с валютой
+- статус
+- время создания
+
+---
+
+## Навигация и FSM
+
+### Улучшение сценарных переходов
+
+Были исправлены и стабилизированы переходы между шагами:
+
+- side → type
+- type → quantity
+- quantity → price
+- price → confirm
+- manual quantity back
+- manual price back
+- confirm back
+
+### Поддержка edit mode
+
+Сценарий редактирования черновика теперь использует тот же улучшенный UI и повторно использует общий flow.
+
+---
+
+## Общая UI инфраструктура
+
+### Единая mode line
+
+Строка режима аккаунта была унифицирована через общую функцию:
+
+- один источник правды
+- единое отображение на разных экранах
+- отсутствие дублирования в нескольких обработчиках
+
+---
+
+## Документация
+
+Добавлен файл:
+
+- `docs/terminology.md`
+
+Он фиксирует соответствие между:
+
+- терминологией биржи
+- терминологией UI бота
+- внутренними именами в коде
+
+Это нужно для снижения путаницы перед следующими этапами развития торгового модуля.
+
+---
+
+## Какие файлы были затронуты
+
+### Trade / order draft
+- `app/src/telegram/handlers/trade/new_order.py`
+- `app/src/telegram/handlers/trade/new_order_core.py`
+- `app/src/telegram/handlers/trade/new_order_flow.py`
+- `app/src/telegram/handlers/trade/new_order_navigation.py`
+- `app/src/telegram/handlers/trade/new_order_ui.py`
+- `app/src/telegram/handlers/trade/main.py`
+
+### Trading domain
+- `app/src/trading/orders/models.py`
+- `app/src/trading/orders/service.py`
+
+### Общий UI / menu / handlers
+- `app/src/telegram/ui/`
+- `app/src/telegram/keyboards/reply.py`
+- `app/src/telegram/handlers/start.py`
+- `app/src/telegram/handlers/home.py`
+- `app/src/telegram/handlers/system.py`
+- `app/src/telegram/handlers/market.py`
+- `app/src/telegram/handlers/portfolio.py`
+- `app/src/telegram/handlers/auto.py`
+- `app/src/telegram/handlers/journal.py`
+
+### Docs
+- `docs/terminology.md`
+
+---
+
+## Результат этапа
+
+После завершения Stage 05.7 модуль trade draft flow стал:
+
+- понятнее по структуре
+- стабильнее по FSM-переходам
+- чище по UI
+- информативнее для пользователя
+- готовым к следующему этапу декомпозиции и UX-улучшений
+
+---
+
+## Что подготовлено для следующего этапа
+
+Этот этап подготовил основу для:
+
+- отображения пути формируемого ордера на каждом шаге
+- дальнейшего дробления trade-модуля
+- выноса navigation/drafts/ui в ещё более чистую структуру
+- перехода к терминологии, ближе к терминологии биржи

docs/terminology.md

@@ -0,0 +1,65 @@
+# 🧭 Терминология: биржа → UI бота → код
+
+| 🏦 Термин биржи                | 🤖 UI бота (как показываем)        | 🧠 В коде (модель)              | 💬 Комментарий |
+|------------------------------|------------------------------------|--------------------------------|---------------|
+| Купить                       | Купить (LONG)                      | `side = "BUY"`                 | Открытие long |
+| Продать                      | Продать (SHORT)                    | `side = "SELL"`                | Открытие short |
+| Режим левереджа              | 📈 Левередж                        | `trade_mode = "leverage"`      | Основной режим |
+| Режим торгов                 | 💱 Торги / Спот                    | `trade_mode = "spot"`          | Без плеча |
+| Купить сейчас                | ⚡ MARKET                          | `order_type = "MARKET"`        | Исполнение сразу |
+| Купить когда цена = X        | 🎯 LIMIT                           | `order_type = "LIMIT"`         | Отложенный ордер |
+| Цена                         | Цена                               | `price`                        | Только для LIMIT |
+| Количество / Размер          | Количество                         | `quantity`                     | Базовая величина |
+| % от баланса                 | 5% / 10% / ...                     | `quantity` (расчёт)            | UI-обёртка |
+| Левередж                     | Плечо                              | `leverage`                     | Пока нет в модели |
+| Доступно                     | Доступно                           | `available_balance`            | из context |
+| Ориентир цены (Last/Bid/Ask) | Ориентир цены                      | `reference_price`              | для UI |
+| Стоп-лосс                    | Стоп-лосс                          | `stop_loss`                    | будущий параметр |
+| Тейк-профит                  | Тейк-профит                        | `take_profit`                  | будущий параметр |
+| Сумма ордера                 | Сумма                              | `notional`                     | `price * quantity` |
+| Мин. сумма                   | Мин. сумма                         | `min_notional`                 | правило биржи |
+| Шаг количества               | Шаг                                | `step_size`                    | правило |
+| Мин. количество              | Минимум                            | `min_qty`                      | правило |
+| Черновик                     | Черновик                           | `draft`                        | статус |
+| Подтвердить                  | Подтвердить                        | —                              | UI-действие |
+
+---
+
+## 🔥 Основные принципы
+
+### 1. UI ≠ код
+- UI: язык биржи (понятный пользователю)
+- Код: строгая техническая модель
+
+---
+
+### 2. MARKET / LIMIT — это тип ордера
+- не путать с режимом торговли (левередж / спот)
+
+---
+
+### 3. LONG / SHORT
+- LONG = `BUY`
+- SHORT = `SELL`
+
+---
+
+### 4. Текущий статус модели
+
+✔ Уже есть:
+- `side`
+- `order_type`
+- `quantity`
+- `price`
+
+🔜 Нужно добавить:
+- `leverage`
+- `stop_loss`
+- `take_profit`
+
+---
+
+## 🧭 Итог
+
+Пользователь видит **терминологию биржи**,  
+система работает на **нормализованной модели**.