dzentra_bot/docs/migrations/instrument_reference_data_migration.md

Dzentra --- Instrument Reference Data Migration Plan

Статус: Утверждённый базовый план миграции

Общая стратегия

Миграция выполняется постепенно без нарушения работы существующего бота.

Основные принципы:

• не переписывать подсистему целиком;
• не удалять legacy-код до полного перевода потребителей;
• сохранять публичные интерфейсы ExchangeService;
• не создавать параллельную бизнес-логику без плана удаления;
• разделять Acquisition, Validation, Storage и Processing;
• выполнять миграцию небольшими проверяемыми Build.

---

План Build

Build Цель                                                 Совместимость

---

  001 Внутренняя модель Instrument Reference Data          Без изменения runtime
  002 Raw-модели ответа Dzengi                             Полная
  003 Структурная валидация exchangeInfo                   Полная
  004 Parser exchangeInfo                                  Полная
  005 Value validation                                     Полная
  006 Mapper Dzengi → Instrument                           Полная
  007 Protocol и Exceptions                                Полная
  008 Dzengi REST Adapter                                  Полная
  009 Instrument Handler                                   Полная
  010 Instrument Feed                                      Полная
  011 Registry                                             Полная
  012 Acquisition Service                                  Полная
  013 Проверка эквивалентности старой и новой реализации   Полная
  014 Compatibility mapper Instrument → ExchangeSymbol     Полная
  015 Переключение get_exchange_symbols()                  Полная
  016 Перевод normalize_symbol()/symbol_candidates()       Полная
  017 Переключение validate_symbol()                       Полная
  018 Переключение get_symbol_runtime_status()             Полная
  019 Подготовка переноса кэша в Storage                   Полная
  020 Перенос кэша                                         Полная
  021 Перевод первой группы потребителей                   Полная
  022 Перевод валидации и runtime-статусов на канонический Instrumen
  023 Перевод рыночных runtime-потребителей на канонический Instrument
  024 Удаление неиспользуемого legacy Market Handler
  025 Удаление ExchangeSymbol compatibility layer и завершение миграции

---

Зависимости

001
 ↓
002
 ↓
003
 ↓
004
 ↓
005
 ↓
006
 ↓
007
 ↓
008
 ↓
009
 ↓
010
 ↓
011
 ↓
012
 ↓
013
 ↓
014
 ↓
015
 ├──→016→017
 └──→018
        ↓
019→020
        ↓
021→022+
        ↓
023
 ↓
024
 ↓
025

---

Точки обратной совместимости

До завершения миграции должны сохраняться:

• ExchangeService.get_exchange_symbols()
• ExchangeService.validate_symbol()
• ExchangeService.get_symbol_runtime_status()

Также сохраняются:

• сигнатуры методов;
• старые импорты;
• формат ошибок;
• Telegram UI;
• автоторговля;
• существующее поведение runtime;
• совместимость ExchangeSymbol через временный compatibility mapper.

---

Классификация изменений

Тип Значение

---

Исправление ошибки Исправляет неверную работу Обязательное архитектурное изменение Необходимо для новой архитектуры Улучшение надёжности Не меняет наблюдаемое поведение Изменение поведения Требует отдельного согласования

---

Улучшения допускаются

Допускается:

• усиление типизации;
• безопасная обработка неполных данных;
• исправление ошибок parser;
• корректная обработка filters;
• улучшение надёжности REST;
• отделение транспортной логики от предметной;
• тестируемые контракты.

Недопустимо без согласования:

• изменение поведения;
• изменение TTL кэша;
• изменение правил валидации;
• изменение логики UI.

---

Build 001

Цель

Создать независимую внутреннюю модель Instrument Reference Data.

На этом этапе:

• не переносится parser;
• не создаётся REST adapter;
• не меняется ExchangeService;
• не меняется runtime;
• не переносится кэш.

Для начала Build 001 необходимо получить

Обязательно:

1. модель ExchangeSymbol;
2. SymbolValidationResult;
3. normalize_symbol();
4. symbol_candidates();
5. validate_symbol();
6. integrations/exchange/service.py;
7. текущий parser exchangeInfo;
8. текущий mapper (если существует);
9. модели ответа exchangeInfo;
10. REST-клиент exchangeInfo;
11. обработку filters/status/marketModes.

Также нужны результаты grep по использованию этих сущностей и, если существуют, соответствующие тесты.

---

Обязательные правила

После каждого Build:

1. анализ;
2. внесение изменений только текущего этапа;
3. обновление тестов;
4. проверка импортов;
5. проверка синтаксиса;
6. запуск тестов;
7. запуск приложения;
8. проверка обратной совместимости.

Только после успешного завершения Build допускается переход к следующему этапу.