# 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 и завершение миграции

------------------------------------------------------------------------

## Зависимости

``` text
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 допускается переход к следующему
этапу.