Stage 05.2 - interactive draft builder

docs/stages/stage-05-2-interactive-draft-builder.md

@@ -0,0 +1,179 @@
+# Stage 05.2 — Interactive Draft Builder
+
+## Цель
+Сделать первый пошаговый конструктор черновика ордера внутри Telegram и перевести order entry из простой команды в управляемый пользовательский сценарий.
+
+---
+
+## Что реализовано
+
+### Пошаговый мастер (FSM)
+
+Пользователь проходит сценарий:
+
+1. выбор стороны:
+   - BUY
+   - SELL
+
+2. выбор типа ордера:
+   - MARKET
+   - LIMIT
+
+3. ввод количества
+
+4. для LIMIT — ввод цены
+
+---
+
+### UX улучшения
+
+#### Кнопки выбора стороны
+- 🟢 BUY  
+- 🔴 SELL  
+- ✖️ Отмена  
+
+---
+
+#### Кнопки выбора типа ордера
+- ⚡ MARKET  
+- 🎯 LIMIT  
+- ✖️ Отмена  
+
+---
+
+#### Отмена сценария
+Поддерживается:
+- команда `/cancel_order`
+- кнопка `✖️ Отмена`
+
+FSM очищается и сценарий корректно завершается.
+
+---
+
+### Ввод параметров
+
+- количество — вручную
+- цена — вручную (для LIMIT)
+
+Базовая валидация:
+- число
+- > 0
+
+---
+
+### Service слой
+
+`OrderDraftsService`:
+
+- build_draft
+- save_draft
+- list_recent_drafts
+- normalize_* методы
+
+---
+
+### Model слой
+
+`OrderDraft`:
+
+- symbol
+- side
+- order_type
+- quantity
+- price
+- status
+
+---
+
+### FSM состояния
+
+- waiting_side
+- waiting_type
+- waiting_quantity
+- waiting_price
+
+---
+
+### Storage
+
+Используется таблица:
+
+- `order_drafts`
+
+Payload:
+- source
+- mode
+- price
+
+---
+
+### Journal
+
+Логируется событие:
+
+- `order_draft_saved`
+
+---
+
+## Что это даёт
+
+Система получила:
+
+- управляемый order entry flow
+- безопасный draft (без отправки ордера)
+- основу для дальнейшей логики торговли
+
+---
+
+## Архитектура
+
+Telegram → FSM → OrderDraftsService → Repository → PostgreSQL
+
+---
+
+## Принципы
+
+### Draft first
+Сначала создаётся черновик, без отправки в биржу.
+
+---
+
+### Safety first
+Пошаговый ввод вместо одной команды.
+
+---
+
+### UX before validation
+Сначала UX, потом строгая валидация.
+
+---
+
+## Ограничения
+
+- один инструмент (DEFAULT_SYMBOL)
+- ручной ввод quantity и price
+- нет проверки:
+  - tickSize
+  - minQty
+  - minNotional
+- нет confirmation screen
+- нет live execution
+
+---
+
+## Что дальше
+
+### Stage 05.3 — Order Validation
+
+Будет добавлено:
+- проверки биржи (filters)
+- minQty / tickSize / notional
+- подготовка к confirm screen
+
+---
+
+## Итог
+
+Stage 05.2 завершает переход:
+
+простая команда → интерактивный order builder