# Market Intelligence Research Methodology

## Контроль документа

| Свойство | Значение |
|----------|----------|
| Документ | Market Intelligence Research Methodology |
| Тип документа | Engineering Standard |
| Версия | 1.0 |
| Статус | Release |
| Проект | Dzentra |
| Подсистема | Market Intelligence |
| Язык | Русский |

---

# Назначение

Настоящий документ определяет единую методологию исследования источников рыночной информации.

Методология применяется при исследовании любых источников данных независимо от:

- биржи;
- транспортного протокола;
- версии API;
- способа получения данных.

Настоящий документ определяет общий порядок проведения исследований, но не содержит перечень конкретных проверок.

Конкретные проверки определяются специализированными документами Research Checklist.

---

# Фундаментальная модель исследования

Подсистема Market Intelligence строится на трех последовательно связанных уровнях.

```text
ФАКТЫ
    │
    ▼
ЗНАНИЯ
    │
    ▼
РЕШЕНИЯ
```

Каждый следующий уровень может строиться исключительно на основании предыдущего.

---

## Уровень 1. Факты

Факты представляют собой объективную информацию, получаемую непосредственно от биржи.

На данном уровне отсутствует какая-либо интерпретация данных.

Примеры фактов:

- bid;
- ask;
- volume;
- trade;
- candle;
- order book;
- funding rate;
- open interest;
- liquidation.

Результатом данного уровня являются подтвержденные информационные сущности (Information Facts).

---

## Уровень 2. Знания

Знания представляют собой интерпретацию подтвержденных фактов.

На данном уровне строится модель состояния рынка.

Примеры знаний:

- тренд;
- импульс;
- ликвидность;
- волатильность;
- дисбаланс стакана;
- направление движения;
- фаза рынка;
- вероятность продолжения движения;
- вероятность разворота.

Знания никогда не извлекаются непосредственно из API.

Они формируются исключительно на основании подтвержденных фактов.

---

## Уровень 3. Решения

Решения представляют собой результат работы торговой системы.

Примеры решений:

- открыть позицию;
- закрыть позицию;
- увеличить позицию;
- уменьшить позицию;
- изменить Stop Loss;
- изменить Take Profit;
- отказаться от входа в рынок.

Решения принимаются исключительно на основании знаний.

Факты не используются для принятия торговых решений напрямую.

---

# Основные архитектурные принципы

## Принцип последовательного построения знаний

Построение подсистемы Market Intelligence всегда выполняется в следующем порядке:

1. Исследование фактов.
2. Подтверждение фактов.
3. Построение модели знаний.
4. Принятие решений.

Нарушение данной последовательности считается архитектурной ошибкой.

---

## Принцип отсутствия предположений

Подсистема Market Intelligence не использует предположения в качестве знаний.

Любая информационная сущность должна иметь подтвержденный источник происхождения.

Любое знание должно иметь подтвержденную зависимость от фактов.

Любое решение должно иметь подтвержденную зависимость от знаний.

---

## Принцип полной трассируемости

Любое торговое решение должно быть полностью прослеживаемо до фактов, полученных непосредственно от биржи.

Для любого решения должна существовать непрерывная цепочка происхождения информации.

```text
Биржа
    │
    ▼
Факты
    │
    ▼
Знания
    │
    ▼
Решение
```

Каждый переход между уровнями должен быть объяснимым и проверяемым.

---

## Принцип воспроизводимости

Любой вывод, содержащийся в документации Market Intelligence, должен быть воспроизводим.

Повторное выполнение исследования должно приводить к тем же результатам при одинаковых исходных условиях.

---

# Цель исследования

Любое исследование должно ответить на главный вопрос.

> **Какие факты о состоянии рынка предоставляет исследуемый источник данных?**

Исследование не должно ограничиваться описанием структуры API.

Результатом исследования является выявление подтвержденных информационных сущностей, содержащихся в исследуемом источнике данных.

---

# Основные принципы исследования

## Исследуется источник информации

Объектом исследования является не программный интерфейс API, а информация, передаваемая данным источником.

---

## Исследуются фактические данные

Все выводы должны подтверждаться одновременно:

- официальной документацией;
- фактическими сообщениями биржи;
- экспериментальными исследованиями.

Если подтверждение отсутствует, вывод считается неподтвержденным.

---

## Исследуются информационные факты

Исследование должно отвечать не на вопрос

> Какие поля содержит JSON?

а на вопрос

> Какие факты о состоянии рынка передает данный источник?

---

## Исследования являются воспроизводимыми

Каждый вывод должен подтверждаться экспериментом, который может быть повторен независимо от автора исследования.

---

## Принцип минимально необходимого исследования

Исследование должно проводиться в объеме, достаточном для подтверждения или опровержения информации, содержащейся в официальной документации.

Если официальная документация содержит однозначное описание исследуемого аспекта и фактическое поведение API соответствует этому описанию, дополнительные эксперименты не проводятся.

Экспериментальные исследования выполняются только в случаях, когда:

- документация отсутствует;
- документация неоднозначна;
- документация противоречит фактическому поведению API;
- требуется определить неописанное поведение системы.

---

# Общий процесс исследования

Любое исследование выполняется в строго определенной последовательности.

Каждый следующий этап может начинаться только после завершения предыдущего.

---

## Этап 1. Изучение официальной документации

Цель этапа — определить ожидаемое назначение исследуемого источника данных.

Результат этапа:

- понимание назначения endpoint;
- понимание способа взаимодействия;
- понимание ожидаемой структуры сообщений;
- определение перечня исследуемых сущностей.

На данном этапе не делаются выводы о фактическом поведении источника данных.

---

## Этап 2. Получение фактических данных

Цель этапа — получить реальные сообщения исследуемого источника.

Получение данных выполняется посредством специализированных Probe.

Результат этапа:

- реальные сообщения биржи;
- реальные ответы endpoint;
- реальные особенности поведения;
- материал для последующего анализа.

---

## Этап 3. Определение типов сообщений

Для исследуемого источника необходимо определить:

- все типы сообщений;
- назначение каждого типа сообщений;
- сообщения, содержащие рыночную информацию;
- служебные сообщения;
- сообщения управления;
- сообщения об ошибках.

Результатом этапа является классификация сообщений исследуемого источника.

---

## Этап 4. Исследование структуры сообщений

Для каждого типа сообщений необходимо определить:

- перечень полей;
- тип каждого поля;
- обязательность поля;
- допустимые значения;
- ограничения;
- взаимное расположение данных.

Результатом этапа является описание структуры каждого типа сообщений.

---

## Этап 5. Исследование семантики

Для каждого поля необходимо определить:

- фактическое назначение;
- происхождение информации;
- ограничения использования;
- степень достоверности;
- взаимосвязь с другими полями.

На данном этапе запрещается использовать предположения как подтвержденные знания.

---

## Этап 6. Выделение информационных фактов

На основании исследованных сообщений необходимо определить:

- какие информационные факты содержит источник;
- какие факты можно вычислить непосредственно из сообщения;
- какие факты отсутствуют.

Результатом этапа является перечень информационных фактов, предоставляемых исследуемым источником.

---

## Этап 7. Исследование поведения

Для исследуемого источника необходимо определить:

- особенности изменения данных;
- последовательность сообщений;
- взаимосвязь изменений;
- особенности временного поведения;
- ограничения источника;
- особенности протокола.

Результатом этапа является описание поведения исследуемого источника.

---

## Этап 8. Сравнение с другими источниками

Для каждого информационного факта необходимо определить:

- существует ли аналогичный источник;
- подтверждается ли эквивалентность;
- имеются ли различия;
- какой источник является приоритетным.

Эквивалентность считается подтвержденной только после экспериментальной проверки.

---

## Этап 9. Формирование экспериментальных выводов

После завершения исследования все выводы должны быть разделены на следующие категории:

- подтвержденные;
- предварительно подтвержденные;
- гипотезы;
- опровергнутые.

Только подтвержденные выводы могут использоваться при построении Information Mapping.

---

## Этап 10. Подготовка Endpoint Research

Результаты исследования оформляются отдельным документом Endpoint Research.

Документ должен содержать:

- описание источника;
- результаты исследований;
- подтвержденные информационные факты;
- особенности поведения;
- результаты сравнений;
- экспериментальные выводы.

Endpoint Research является основным документом, описывающим исследуемый источник данных.

---

## Этап 11. Обновление Information Mapping

После подтверждения информационных фактов обновляется документ:

> Dzengi Market Intelligence Information Mapping.

В Information Mapping включаются только подтвержденные информационные факты.

---

## Этап 12. Обновление Information Model

Если исследование выявило новые информационные факты или новые взаимосвязи между ними, обновляется документ:

> Dzentra Market Intelligence Information Model.

---

## Этап 13. Обновление Knowledge Catalogue

Если исследование позволило сформировать новые знания о рынке, обновляется документ:

> Dzentra Market Knowledge Catalogue.

Knowledge Catalogue никогда не строится непосредственно на данных API.

Он строится исключительно на основании подтвержденных информационных фактов и Information Model.

---

## Этап 14. Завершение исследования

Исследование считается завершенным только при выполнении всех следующих условий:

- подготовлен Endpoint Research;
- обновлен Information Mapping;
- при необходимости обновлена Information Model;
- при необходимости обновлен Knowledge Catalogue;
- все выводы имеют степень подтверждения.

После завершения исследования результаты могут использоваться другими подсистемами Dzentra.

---

# Степени подтверждения

Любой вывод, содержащийся в документации Market Intelligence, должен иметь явно указанную степень подтверждения.

Использование неподтвержденных выводов в качестве знаний запрещается.

| Статус | Описание |
|---------|----------|
| Не исследовано | Исследование соответствующего вопроса не проводилось. |
| Гипотеза | Имеется предположение, основанное на документации или наблюдениях, но отсутствует экспериментальное подтверждение. |
| Предварительно подтверждено | Подтверждено ограниченным количеством экспериментов. Требуется дополнительная проверка. |
| Подтверждено | Подтверждено официальной документацией и экспериментальными исследованиями либо многократно подтверждено экспериментально. |
| Опровергнуто | Экспериментально доказано отсутствие соответствия первоначальному предположению. |

---

# Критерии качества исследования

Исследование считается качественно выполненным, если выполняются все следующие условия.

## Полнота

Исследованы все типы сообщений исследуемого источника.

Исследованы все поля сообщений.

Исследованы все информационные факты.

---

## Подтверждаемость

Каждый вывод имеет экспериментальное подтверждение либо явно обозначен как гипотеза.

---

## Воспроизводимость

Любой эксперимент может быть повторен другим разработчиком и привести к тем же результатам.

---

## Трассируемость

Каждый информационный факт имеет подтвержденный источник происхождения.

Каждое знание имеет подтвержденную зависимость от информационных фактов.

Каждое торговое решение должно быть объяснимо через цепочку:

```text
Биржа
    │
    ▼
Информационные факты
    │
    ▼
Знания
    │
    ▼
Решение
```

---

## Документированность

Все результаты исследования отражены в соответствующих документах:

- Endpoint Research;
- Information Mapping;
- Information Model;
- Knowledge Catalogue.

---

# Жизненный цикл исследований

Исследование источников рыночной информации является непрерывным процессом.

Появление новых возможностей API, изменение поведения биржи или обнаружение новых фактов требует повторного проведения соответствующих исследований.

Исследование никогда не считается завершенным окончательно.

Каждый исследованный источник может быть повторно исследован при появлении новых обстоятельств.

---

## Основания для повторного исследования

Повторное исследование выполняется при возникновении одного или нескольких следующих событий:

- выпуск новой версии API;
- изменение структуры сообщений;
- появление новых полей;
- изменение семантики существующих полей;
- обнаружение противоречий между источниками;
- получение новых экспериментальных данных;
- обнаружение ошибок предыдущих исследований;
- изменение архитектурных требований Dzentra.

---

# Использование результатов исследований

Результаты исследований используются исключительно как источник подтвержденных информационных фактов.

Настоящий документ не определяет:

- архитектуру Engine;
- алгоритмы анализа рынка;
- методы прогнозирования;
- торговые стратегии;
- правила управления капиталом;
- правила открытия или закрытия позиций.

Указанные вопросы рассматриваются отдельными архитектурными документами Dzentra.

---

# Связанные документы

Настоящий документ используется совместно со следующими документами:

- Market Intelligence Stream Research Checklist;
- Market Intelligence REST Research Checklist;
- Market Intelligence WebSocket Request Research Checklist;
- Endpoint Research;
- Dzengi Market Intelligence Information Mapping;
- Dzentra Market Intelligence Information Model;
- Dzentra Market Knowledge Catalogue.

---

# Заключение

Настоящая методология определяет единый инженерный подход к исследованию источников рыночной информации.

Все знания, используемые подсистемой Market Intelligence, должны быть построены исключительно на основании подтвержденных информационных фактов.

Таким образом обеспечиваются:

- воспроизводимость исследований;
- объяснимость полученных знаний;
- трассируемость торговых решений;
- независимость знаний от конкретной реализации API;
- возможность повторного исследования при изменении источников данных.

Следование настоящей методологии является обязательным требованием при разработке и сопровождении подсистемы Market Intelligence проекта Dzentra.