854 lines
22 KiB
Markdown
854 lines
22 KiB
Markdown
# Build 040 — Восстановление принудительного REST refresh котировки на канонической модели Quote
|
||
|
||
**Статус:** Завершён
|
||
**Проект:** Dzentra
|
||
**Подсистема:** Market Data Acquisition / Exchange Integration / Market Data Runtime
|
||
**Тип изменения:** Восстановление runtime-контракта после миграции legacy price/snapshot API
|
||
**Язык документа:** Русский
|
||
|
||
---
|
||
|
||
## 1. Цель Build 040
|
||
|
||
Цель Build 040 — восстановить принудительный REST refresh текущей рыночной котировки для `MarketDataRunner` после завершения Build 039 и удаления legacy price/snapshot API.
|
||
|
||
В Build 039 были удалены legacy-сущности и методы:
|
||
|
||
```text
|
||
TickerPrice
|
||
MarketPriceSnapshot
|
||
get_price()
|
||
get_market_snapshot()
|
||
get_fresh_market_snapshot()
|
||
refresh_price_cache()
|
||
refresh_market_snapshot_cache()
|
||
_get_real_price()
|
||
```
|
||
|
||
После завершения миграции был обнаружен один оставшийся активный consumer удалённого метода:
|
||
|
||
```text
|
||
src/integrations/exchange/market_data_runner.py
|
||
```
|
||
|
||
который продолжал вызывать:
|
||
|
||
```python
|
||
ExchangeService().refresh_market_snapshot_cache
|
||
```
|
||
|
||
Таким образом, целью Build 040 являлось не изменение runtime-архитектуры и не новый рефакторинг, а минимальное восстановление разорванного контракта на основе канонической модели:
|
||
|
||
```text
|
||
src.market_data.acquisition.models.quote.Quote
|
||
```
|
||
|
||
При этом необходимо было сохранить существующую логику работы старого бота без изменений.
|
||
|
||
---
|
||
|
||
## 2. Исходное состояние
|
||
|
||
После Build 039 проект находился в следующем состоянии:
|
||
|
||
1. все основные consumers текущей рыночной цены были переведены на `Quote`;
|
||
|
||
2. legacy-модели:
|
||
|
||
```text
|
||
TickerPrice
|
||
MarketPriceSnapshot
|
||
```
|
||
|
||
были удалены;
|
||
|
||
3. legacy-методы получения и обновления price/snapshot были удалены;
|
||
|
||
4. полный regression suite успешно проходил:
|
||
|
||
```text
|
||
606 passed
|
||
```
|
||
|
||
5. контрольный grep по основным legacy-контрактам был пустым;
|
||
|
||
6. при дополнительном анализе runtime-компонентов был обнаружен оставшийся вызов:
|
||
|
||
```python
|
||
ExchangeService().refresh_market_snapshot_cache
|
||
```
|
||
|
||
в:
|
||
|
||
```text
|
||
app/src/integrations/exchange/market_data_runner.py
|
||
```
|
||
|
||
Метод уже отсутствовал в `ExchangeService`, поэтому существовал разорванный runtime-контракт, который не проявлялся в предыдущем полном наборе тестов.
|
||
|
||
---
|
||
|
||
## 3. Архитектурный принцип Build 040
|
||
|
||
Build 040 сохраняет утверждённый архитектурный поток:
|
||
|
||
```text
|
||
Exchange / Market Data Sources
|
||
↓
|
||
Market Data Acquisition
|
||
↓
|
||
Canonical Quote
|
||
↓
|
||
Quote Store / Market Price Cache
|
||
↓
|
||
ExchangeService
|
||
↓
|
||
MarketDataRunner / Trading Consumers
|
||
```
|
||
|
||
Канонической моделью текущей котировки остаётся:
|
||
|
||
```python
|
||
Quote
|
||
```
|
||
|
||
из:
|
||
|
||
```text
|
||
src.market_data.acquisition.models.quote
|
||
```
|
||
|
||
Build 040 не вводит новую параллельную price/snapshot-модель и не восстанавливает удалённые legacy-контракты.
|
||
|
||
Вместо этого добавляется минимальный публичный compatibility-метод:
|
||
|
||
```python
|
||
refresh_quote_cache()
|
||
```
|
||
|
||
который использует существующий канонический acquisition pipeline.
|
||
|
||
---
|
||
|
||
## 4. Главное требование сохранения поведения
|
||
|
||
Основным требованием Build 040 являлось:
|
||
|
||
> Не менять логику работы текущих файлов и существующего runtime.
|
||
|
||
Поэтому перед реализацией была восстановлена фактическая старая реализация удалённого метода:
|
||
|
||
```python
|
||
refresh_market_snapshot_cache()
|
||
```
|
||
|
||
из истории Git.
|
||
|
||
Это позволило определить реальный контракт старого метода без предположений.
|
||
|
||
Старая реализация выполняла:
|
||
|
||
```text
|
||
нормализация runtime_key
|
||
↓
|
||
принудительное получение свежего REST snapshot
|
||
↓
|
||
проверка ценовых полей
|
||
↓
|
||
запись результата в MarketPriceCache
|
||
↓
|
||
возврат свежего snapshot
|
||
```
|
||
|
||
Критически важно:
|
||
|
||
- cache перед REST-запросом не читался;
|
||
- всегда выполнялось принудительное получение свежих данных;
|
||
- результат сохранялся в cache соответствующего runtime;
|
||
- возвращался свежий результат;
|
||
- ошибки не подавлялись самим refresh-методом;
|
||
- mock-режим сохранялся.
|
||
|
||
---
|
||
|
||
## 5. Восстановление старого контракта через Git
|
||
|
||
Для определения фактического поведения удалённого метода была использована история Git.
|
||
|
||
Команда:
|
||
|
||
```bash
|
||
git log -S"def refresh_market_snapshot_cache" \
|
||
--oneline \
|
||
-- src/integrations/exchange/service.py
|
||
```
|
||
|
||
Результат:
|
||
|
||
```text
|
||
a996f2f feat: add market data architecture and complete migration through build 039
|
||
e97dcd3 07.4.3.16 — Production Execution Pricing Layer
|
||
```
|
||
|
||
Старая реализация была извлечена командой:
|
||
|
||
```bash
|
||
git show a996f2f^:app/src/integrations/exchange/service.py \
|
||
| grep -n -A45 -B10 "def refresh_market_snapshot_cache"
|
||
```
|
||
|
||
Восстановленный контракт подтвердил, что новый метод должен быть принудительным refresh-механизмом и не должен использовать обычную cache-first логику `get_quote()`.
|
||
|
||
---
|
||
|
||
## 6. Почему get_quote() не подходит для REST fallback
|
||
|
||
Существующий метод:
|
||
|
||
```python
|
||
ExchangeService.get_quote()
|
||
```
|
||
|
||
реализует cache-first поведение:
|
||
|
||
```text
|
||
валидация символа
|
||
↓
|
||
чтение MarketPriceCache
|
||
↓
|
||
если Quote свежий
|
||
↓
|
||
возврат cached Quote
|
||
↓
|
||
иначе REST acquisition
|
||
```
|
||
|
||
Такое поведение корректно для обычных consumers, но не подходит для:
|
||
|
||
```python
|
||
MarketDataRunner._rest_fallback_once()
|
||
```
|
||
|
||
После отказа WebSocket runner должен проверить именно доступность REST-механизма.
|
||
|
||
Если использовать `get_quote()`, возможна ситуация:
|
||
|
||
```text
|
||
WebSocket отключился
|
||
↓
|
||
в cache остаётся свежий WebSocket Quote
|
||
↓
|
||
get_quote() возвращает cached Quote
|
||
↓
|
||
REST-запрос фактически не выполняется
|
||
↓
|
||
runner ошибочно устанавливает REST state = AVAILABLE
|
||
```
|
||
|
||
Поэтому Build 040 вводит отдельный принудительный refresh-контракт.
|
||
|
||
---
|
||
|
||
## 7. Новый публичный контракт refresh_quote_cache()
|
||
|
||
В `ExchangeService` добавлен метод:
|
||
|
||
```python
|
||
def refresh_quote_cache(
|
||
self,
|
||
symbol: str | None = None,
|
||
*,
|
||
runtime_key: str | None = None,
|
||
) -> Quote:
|
||
```
|
||
|
||
Его ответственность:
|
||
|
||
```text
|
||
нормализовать runtime_key
|
||
↓
|
||
определить symbol
|
||
↓
|
||
если exchange disabled
|
||
получить mock Quote
|
||
иначе
|
||
валидировать symbol
|
||
↓
|
||
принудительно получить свежий Quote через REST acquisition
|
||
↓
|
||
сохранить тот же Quote в MarketPriceCache
|
||
↓
|
||
вернуть тот же Quote
|
||
```
|
||
|
||
Метод не читает cache перед получением свежей котировки.
|
||
|
||
---
|
||
|
||
## 8. Сохранение mock-поведения
|
||
|
||
Старый метод:
|
||
|
||
```python
|
||
refresh_market_snapshot_cache()
|
||
```
|
||
|
||
через:
|
||
|
||
```python
|
||
get_fresh_market_snapshot()
|
||
```
|
||
|
||
поддерживал режим:
|
||
|
||
```text
|
||
exchange_enabled = False
|
||
```
|
||
|
||
В этом режиме создавались mock-данные, которые затем сохранялись в cache.
|
||
|
||
Новый метод сохраняет эквивалентное поведение через:
|
||
|
||
```python
|
||
mock_quote(symbol_to_use)
|
||
```
|
||
|
||
При выключенной бирже:
|
||
|
||
- REST acquisition не выполняется;
|
||
- validation через exchange reference data не требуется;
|
||
- создаётся канонический `Quote`;
|
||
- тот же объект сохраняется в `MarketPriceCache`;
|
||
- тот же объект возвращается consumer.
|
||
|
||
---
|
||
|
||
## 9. Принудительное получение свежего Quote
|
||
|
||
В real-режиме новый метод использует:
|
||
|
||
```python
|
||
self._get_fresh_quote(
|
||
validation.normalized_symbol,
|
||
)
|
||
```
|
||
|
||
Этот метод вызывает существующий канонический pipeline:
|
||
|
||
```text
|
||
DzengiQuoteDocumentSource
|
||
↓
|
||
DzengiQuoteDocumentHandler
|
||
↓
|
||
QuotesFeed
|
||
↓
|
||
QuoteFeedRegistry
|
||
↓
|
||
QuoteAcquisitionService
|
||
↓
|
||
Quote
|
||
```
|
||
|
||
Таким образом, Build 040 не добавляет новый способ получения котировок и не дублирует Market Data Acquisition.
|
||
|
||
---
|
||
|
||
## 10. Почему QuoteAcquisitionService не изменялся
|
||
|
||
В ходе анализа было подтверждено, что:
|
||
|
||
```python
|
||
QuoteAcquisitionService
|
||
```
|
||
|
||
намеренно отвечает только за получение канонической модели через зарегистрированный feed.
|
||
|
||
Он не должен выполнять:
|
||
|
||
- runtime isolation;
|
||
- cache management;
|
||
- fallback orchestration;
|
||
- validation торгового runtime;
|
||
- выбор `runtime_key`;
|
||
- compatibility-поведение старого бота.
|
||
|
||
Поэтому Build 040 не изменяет:
|
||
|
||
```text
|
||
app/src/market_data/acquisition/service.py
|
||
app/src/market_data/acquisition/feeds/quotes_feed.py
|
||
```
|
||
|
||
Compatibility и runtime semantics остаются в:
|
||
|
||
```text
|
||
ExchangeService
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Изменение MarketDataRunner
|
||
|
||
В:
|
||
|
||
```text
|
||
app/src/integrations/exchange/market_data_runner.py
|
||
```
|
||
|
||
был изменён только один runtime-вызов.
|
||
|
||
До Build 040:
|
||
|
||
```python
|
||
ExchangeService().refresh_market_snapshot_cache
|
||
```
|
||
|
||
После Build 040:
|
||
|
||
```python
|
||
ExchangeService().refresh_quote_cache
|
||
```
|
||
|
||
При этом не изменялись:
|
||
|
||
- `asyncio.to_thread`;
|
||
- передаваемый symbol;
|
||
- `runtime_key`;
|
||
- `last_rest_state`;
|
||
- `last_rest_error_key`;
|
||
- WebSocket-first поведение;
|
||
- cooldown;
|
||
- retry-логика;
|
||
- journal events;
|
||
- event titles;
|
||
- lifecycle runner;
|
||
- exception handling.
|
||
|
||
---
|
||
|
||
## 12. Runtime isolation
|
||
|
||
Новый метод сохраняет существующее разделение runtime-контекстов через:
|
||
|
||
```python
|
||
runtime_key
|
||
```
|
||
|
||
Перед использованием ключ нормализуется существующим методом:
|
||
|
||
```python
|
||
self._runtime_key(runtime_key)
|
||
```
|
||
|
||
Котировка сохраняется через:
|
||
|
||
```python
|
||
MarketPriceCache.set_quote(
|
||
quote,
|
||
runtime_key=normalized_runtime_key,
|
||
)
|
||
```
|
||
|
||
Это сохраняет независимость runtime-контекстов, включая:
|
||
|
||
```text
|
||
auto
|
||
debug_auto
|
||
default
|
||
```
|
||
|
||
и другие существующие значения, если они используются текущим runtime.
|
||
|
||
---
|
||
|
||
## 13. Сохранение identity канонического Quote
|
||
|
||
Каноническая модель:
|
||
|
||
```python
|
||
Quote
|
||
```
|
||
|
||
является immutable-моделью:
|
||
|
||
```python
|
||
@dataclass(frozen=True, slots=True)
|
||
```
|
||
|
||
Build 040 не создаёт копию полученного объекта.
|
||
|
||
Последовательность:
|
||
|
||
```text
|
||
fresh Quote
|
||
↓
|
||
MarketPriceCache.set_quote(quote)
|
||
↓
|
||
return quote
|
||
```
|
||
|
||
В cache сохраняется тот же экземпляр, который возвращается из метода.
|
||
|
||
Это зафиксировано тестами.
|
||
|
||
---
|
||
|
||
## 14. Изменённые production-файлы
|
||
|
||
В рамках Build 040 изменены только два production-файла:
|
||
|
||
```text
|
||
app/src/integrations/exchange/service.py
|
||
app/src/integrations/exchange/market_data_runner.py
|
||
```
|
||
|
||
### 14.1. service.py
|
||
|
||
Добавлен новый публичный метод:
|
||
|
||
```python
|
||
refresh_quote_cache()
|
||
```
|
||
|
||
Существующие методы не подвергались сопутствующему рефакторингу.
|
||
|
||
В частности, не изменялись:
|
||
|
||
```text
|
||
get_quote()
|
||
get_execution_snapshot()
|
||
_get_fresh_quote()
|
||
_load_quote_via_acquisition()
|
||
```
|
||
|
||
### 14.2. market_data_runner.py
|
||
|
||
Изменена только ссылка на удалённый legacy refresh-метод.
|
||
|
||
Остальная логика runner сохранена.
|
||
|
||
---
|
||
|
||
## 15. Изменённые тестовые файлы
|
||
|
||
В рамках Build 040 изменены:
|
||
|
||
```text
|
||
app/tests/unit/integrations/exchange/test_service_quote.py
|
||
app/tests/unit/integrations/exchange/test_market_data_runner.py
|
||
```
|
||
|
||
Добавлены тесты нового refresh-контракта и REST fallback runner.
|
||
|
||
---
|
||
|
||
## 16. Тесты refresh_quote_cache()
|
||
|
||
Тестами зафиксировано следующее поведение:
|
||
|
||
- принудительное получение свежего `Quote`;
|
||
- отсутствие cache-first поведения;
|
||
- замена существующей cache-записи новым объектом;
|
||
- сохранение того же экземпляра `Quote`;
|
||
- использование правильного `runtime_key`;
|
||
- нормализация runtime key;
|
||
- использование default runtime key;
|
||
- сохранение `ExchangeError` для невалидного символа;
|
||
- отсутствие REST acquisition при невалидном символе;
|
||
- сохранение exception semantics acquisition pipeline;
|
||
- отсутствие обновления cache при ошибке;
|
||
- сохранение mock-поведения.
|
||
|
||
---
|
||
|
||
## 17. Тесты REST fallback MarketDataRunner
|
||
|
||
Тестами зафиксировано поведение:
|
||
|
||
```python
|
||
MarketDataRunner._rest_fallback_once()
|
||
```
|
||
|
||
При успешном refresh:
|
||
|
||
```text
|
||
refresh_quote_cache() вызывается
|
||
↓
|
||
передаётся текущий symbol
|
||
↓
|
||
передаётся context.runtime_key
|
||
↓
|
||
last_rest_state = AVAILABLE
|
||
↓
|
||
last_rest_error_key = None
|
||
```
|
||
|
||
При ошибке сохраняется существующее поведение runner:
|
||
|
||
```text
|
||
last_rest_state = UNAVAILABLE
|
||
```
|
||
|
||
и существующая обработка ошибки не изменяется.
|
||
|
||
---
|
||
|
||
## 18. Целевая проверка Build 040
|
||
|
||
Выполнена команда:
|
||
|
||
```bash
|
||
python -m pytest -q \
|
||
tests/unit/integrations/exchange/test_service_quote.py \
|
||
tests/unit/integrations/exchange/test_market_data_runner.py
|
||
```
|
||
|
||
Финальный результат:
|
||
|
||
```text
|
||
18 passed in 0.11s
|
||
```
|
||
|
||
Все целевые тесты Build 040 успешно пройдены.
|
||
|
||
---
|
||
|
||
## 19. Связанные регрессионные тесты
|
||
|
||
Выполнена команда:
|
||
|
||
```bash
|
||
python -m pytest -q \
|
||
tests/unit/integrations/exchange/test_service_execution_quote.py \
|
||
tests/unit/integrations/exchange/test_service_symbol_runtime_status.py \
|
||
tests/unit/integrations/exchange/test_market_cache.py \
|
||
tests/unit/integrations/exchange/test_market_stream.py \
|
||
tests/unit/storage/test_quote_store.py
|
||
```
|
||
|
||
Финальный результат:
|
||
|
||
```text
|
||
107 passed in 1.81s
|
||
```
|
||
|
||
Связанные компоненты работают без регрессий.
|
||
|
||
---
|
||
|
||
## 20. Полный regression suite
|
||
|
||
После завершения Build 040 выполнен полный набор тестов:
|
||
|
||
```bash
|
||
python -m pytest -q
|
||
```
|
||
|
||
Финальный результат:
|
||
|
||
```text
|
||
614 passed in 2.03s
|
||
```
|
||
|
||
Все тесты успешно пройдены.
|
||
|
||
По сравнению с Build 039 количество тестов увеличилось:
|
||
|
||
```text
|
||
606 → 614
|
||
```
|
||
|
||
Добавлено:
|
||
|
||
```text
|
||
8 тестов
|
||
```
|
||
|
||
---
|
||
|
||
## 21. Финальный архитектурный grep
|
||
|
||
Выполнена команда:
|
||
|
||
```bash
|
||
grep -RIn \
|
||
--exclude-dir="__pycache__" \
|
||
--exclude="*.pyc" \
|
||
-E "refresh_market_snapshot_cache|refresh_price_cache|MarketPriceSnapshot|TickerPrice" \
|
||
src tests
|
||
```
|
||
|
||
Финальный результат:
|
||
|
||
```text
|
||
<пусто>
|
||
```
|
||
|
||
Это подтверждает отсутствие следующих legacy-контрактов:
|
||
|
||
```text
|
||
refresh_market_snapshot_cache
|
||
refresh_price_cache
|
||
MarketPriceSnapshot
|
||
TickerPrice
|
||
```
|
||
|
||
в:
|
||
|
||
```text
|
||
src
|
||
tests
|
||
```
|
||
|
||
---
|
||
|
||
## 22. Что намеренно не изменялось
|
||
|
||
В Build 040 намеренно не изменялись:
|
||
|
||
```text
|
||
Market Data Acquisition architecture
|
||
Quote model
|
||
QuoteAcquisitionService
|
||
QuotesFeed
|
||
Quote Store
|
||
MarketPriceCache contract
|
||
get_quote()
|
||
get_execution_snapshot()
|
||
WebSocket adapter
|
||
market_stream.py
|
||
MarketDataRunner lifecycle
|
||
MarketDataRunner retry logic
|
||
runtime state transitions
|
||
journal events
|
||
event titles
|
||
Telegram UI
|
||
trading strategies
|
||
execution logic
|
||
diagnostics logic
|
||
```
|
||
|
||
Также не выполнялись:
|
||
|
||
- переносы файлов;
|
||
- переименования каталогов;
|
||
- изменение утверждённой структуры проекта;
|
||
- добавление новых abstraction layers;
|
||
- добавление override-параметров «на будущее»;
|
||
- удаление дополнительных legacy-компонентов вне границ Build 040.
|
||
|
||
---
|
||
|
||
## 23. Критерии завершения Build 040
|
||
|
||
Build 040 считается завершённым, поскольку выполнены все критерии:
|
||
|
||
- [x] найден оставшийся активный вызов удалённого `refresh_market_snapshot_cache`;
|
||
- [x] фактический старый контракт восстановлен из Git;
|
||
- [x] новый контракт реализован на канонической модели `Quote`;
|
||
- [x] добавлен `refresh_quote_cache()`;
|
||
- [x] новый метод не использует cache-first поведение;
|
||
- [x] fresh Quote принудительно получается через существующий acquisition pipeline;
|
||
- [x] runtime isolation сохранена;
|
||
- [x] mock-поведение сохранено;
|
||
- [x] exception semantics сохранена;
|
||
- [x] тот же экземпляр `Quote` сохраняется и возвращается;
|
||
- [x] `MarketDataRunner` переключён на новый метод;
|
||
- [x] WebSocket-first логика не изменена;
|
||
- [x] lifecycle runner не изменён;
|
||
- [x] целевые тесты проходят;
|
||
- [x] связанные регрессионные тесты проходят;
|
||
- [x] полный regression suite проходит;
|
||
- [x] финальный legacy grep пуст.
|
||
|
||
---
|
||
|
||
## 24. Итоговое состояние после Build 040
|
||
|
||
После завершения Build 040 runtime-поток получения котировки имеет следующий вид:
|
||
|
||
```text
|
||
WebSocket available
|
||
↓
|
||
DzengiWebSocketQuoteAdapter
|
||
↓
|
||
Quote
|
||
↓
|
||
MarketPriceCache
|
||
```
|
||
|
||
При отказе WebSocket:
|
||
|
||
```text
|
||
WebSocket unavailable
|
||
↓
|
||
MarketDataRunner._rest_fallback_once()
|
||
↓
|
||
ExchangeService.refresh_quote_cache()
|
||
↓
|
||
Quote Acquisition Pipeline
|
||
↓
|
||
Fresh REST Quote
|
||
↓
|
||
MarketPriceCache
|
||
↓
|
||
REST state = AVAILABLE
|
||
```
|
||
|
||
При ошибке REST refresh:
|
||
|
||
```text
|
||
REST acquisition error
|
||
↓
|
||
ExchangeError
|
||
↓
|
||
MarketDataRunner existing error handling
|
||
↓
|
||
REST state = UNAVAILABLE
|
||
```
|
||
|
||
Таким образом, Build 040 восстанавливает разорванный fallback-контракт, не изменяя существующую runtime-логику.
|
||
|
||
---
|
||
|
||
## 25. Зафиксированный принцип для следующих Builds
|
||
|
||
Build 040 подтверждает принцип, зафиксированный после Build 039:
|
||
|
||
> При миграции нельзя считать новую функцию эквивалентной старой только потому, что они решают похожую задачу.
|
||
|
||
Перед заменой legacy-компонента необходимо восстановить и сравнить фактическое поведение:
|
||
|
||
```text
|
||
порядок операций
|
||
чтение cache
|
||
запись cache
|
||
принудительность refresh
|
||
тип возвращаемого значения
|
||
identity результата
|
||
runtime isolation
|
||
mock-поведение
|
||
fallback-поведение
|
||
exception semantics
|
||
side effects
|
||
граничные условия
|
||
```
|
||
|
||
Если старый контракт доступен в истории Git, его необходимо использовать как источник фактического поведения вместо предположений.
|
||
|
||
---
|
||
|
||
## 26. Статус Build
|
||
|
||
```text
|
||
Build 040: COMPLETED
|
||
Target tests: 18 passed
|
||
Related regression tests: 107 passed
|
||
Full regression suite: 614 passed
|
||
Legacy grep: empty
|
||
Canonical quote model: Quote
|
||
REST fallback contract: refresh_quote_cache()
|
||
```
|
||
|
||
Build 040 полностью завершён.
|