# Математические модели и спецификация API Firewire Analytics

Этот документ содержит детальное описание расчетных моделей, формул доходности, а также спецификацию ключевых REST API эндпоинтов приложения Firewire Analytics.

---

## 1. Математические модели и расчет доходностей

### 1.1 XIRR (Internal Rate of Return для нерегулярных денежных потоков)
Денежно-взвешенная доходность рассчитывается как внутренняя норма доходности для нерегулярных транзакций (пополнения, выводы, выплаты).

Формула нахождения годовой ставки $r$:
$$ \sum_{i=1}^{N} \frac{CF_i}{(1 + r)^{\frac{d_i - d_1}{365}}} = 0 $$

Где:
- $CF_i$ — величина $i$-го денежного потока (пополнения положительны, выводы и текущая стоимость портфеля на дату расчета отрицательны).
- $d_i$ — дата $i$-й транзакции.
- $d_1$ — дата первой транзакции (начало отсчета).
- $r$ — искомая доходность XIRR (доля в годовом исчислении).

Поиск корня $r$ осуществляется методом Ньютона-Рафсона с левой границей $-0.999$ для стабильной сходимости.

### 1.2 TWR (Time-Weighted Return, временно-взвешенная доходность)
Используется для исключения влияния объемов и дат ввода/вывода средств, оценивая только качество управления портфелем.

Портфель разбивается на субпериоды между внешними денежными потоками.
Доходность субпериода $t$:
$$ R_t = \frac{V_t - (V_{t-1} + CF_t)}{V_{t-1} + CF_t} $$

Где:
- $V_t$ — стоимость портфеля на конец субпериода $t$ (прямо перед следующим денежным потоком).
- $V_{t-1}$ — стоимость портфеля на конец предыдущего субпериода.
- $CF_t$ — величина внешнего денежного потока в начале периода $t$.

Итоговая доходность TWR за весь период рассчитывается как геометрическая сумма доходностей субпериодов:
$$ TWR = \left( \prod_{t=1}^{M} (1 + R_t) \right) - 1 $$

### 1.3 YTM (Yield to Maturity, доходность к погашению облигаций)
Доходность к погашению рассчитывается для долговых инструментов с учетом текущей грязной цены (чистая цена + НКД), будущих купонов и амортизационных выплат.

Формула YTM ($y$):
$$ P_{dirty} = \sum_{j=1}^{K} \frac{C_j}{(1 + y)^{\frac{t_j - t_0}{365}}} + \frac{N}{(1 + y)^{\frac{t_M - t_0}{365}}} $$

Где:
- $P_{dirty}$ — грязная цена облигации на дату расчета (рыночная цена + накопленный купонный доход).
- $C_j$ — размер $j$-го купона.
- $N$ — номинал к погашению (с учетом будущих амортизаций).
- $t_j$ — дата выплаты $j$-го купона.
- $t_0$ — дата расчета.
- $y$ — искомая доходность к погашению YTM.

### 1.4 Реальная доходность (Формула Фишера)
Реальная доходность учитывает инфляционное обесценение капитала.

Формула Фишера:
$$ 1 + r_{real} = \frac{1 + r_{nom}}{1 + i} \implies r_{real} = \frac{r_{nom} - i}{1 + i} $$

Где:
- $r_{nom}$ — номинальная годовая доходность (например, номинальная YTM или XIRR).
- $i$ — годовой уровень инфляции (индекс потребительских цен ИПЦ Росстата за последние 12 месяцев).

### 1.5 Дюрация Маколея ($D$) и Модифицированная дюрация ($MD$)
Определяет средневзвешенный срок до возврата инвестиций в облигацию и чувствительность её цены к изменению процентных ставок.

Дюрация Маколея:
$$ D = \frac{1}{P_{dirty}} \sum_{j=1}^{K} \frac{t_j - t_0}{365} \cdot \frac{C_j}{(1 + y)^{\frac{t_j - t_0}{365}}} $$

Модифицированная дюрация:
$$ MD = \frac{D}{1 + \frac{y}{m}} $$

Где $m$ — периодичность купонных выплат в год.

---

## 2. Спецификация ключевых API-эндпоинтов

### 2.1 Авторизация и профиль
- **POST `/api/v1/auth/register-code`**: Запрос кода верификации на email.
- **POST `/api/v1/auth/register`**: Регистрация нового пользователя по email и коду.
- **POST `/api/v1/auth/login`**: Вход в систему, выдача access-токена (JWT) и установка refresh-токена в httpOnly-cookie.
- **GET `/api/v1/users/me`**: Получение профиля текущего пользователя и его Bento-настроек.

### 2.2 Синхронизация и брокерские сессии
- **POST `/api/v1/broker/session`**: Запуск брокерской сессии (сохранение refresh-токена БКС).
- **POST `/api/v1/sync/run`**: Запуск фонового процесса импорта счетов и позиций из брокера.
- **GET `/api/v1/sync/status`**: Получение текущего статуса импорта (idle, running, ok, error).

### 2.3 Портфель и аналитика
- **GET `/api/v1/portfolio/summary`**: Получение сводных данных (стоимость, PnL, распределение активов по классам).
- **GET `/api/v1/portfolio/positions`**: Получение списка открытых позиций с финансовыми показателями.
- **GET `/api/v1/portfolio/valuations`**: Временной ряд стоимости портфеля для графиков динамики.
- **GET `/api/v1/yields`**: Получение отчета о доходностях (XIRR, TWR, YTM, реальная доходность) по портфелю и позициям.
- **GET `/api/v1/coupons`**: Календарь предстоящих купонных и дивидендных выплат.
- **GET `/api/v1/trades`**: Список совершенных сделок.