docs: reorganize system knowledge by domain

2026-09-12 14:45:42 +03:00
parent 3a99af1a6e
commit f20c3f47bc
83 changed files with 2229 additions and 7335 deletions
@@ -0,0 +1,98 @@
+# Данные и показатели портфеля
+
+Этот справочник объясняет значения снимка одного счёта. Он нужен при чтении
+экрана, API-ответа или разборе расхождения сумм. Для
+[общего портфеля](all-accounts.md) действуют те же денежные правила,
+но данные счетов получаются не одновременно.
+
+## Точные значения и неизвестность
+
+Деньги представлены значением Money: ISO-код валюты и десятичная строка,
+например `{ "currency": "RUB", "value": "12500.5" }` — условный пример.
+Количества также передаются десятичными строками. Backend выполняет
+десятичную арифметику без промежуточного `Number`, нормализует отрицательные
+целую и дробную части и убирает незначащие конечные нули. Экспоненциальной
+записи нет. Frontend форматирует полученные строки в русской локали без
+сокращения, округления сумм и потери присланных дробных цифр.
+
+`null` означает, что показатель нельзя определить из доступных данных.
+Это не ноль. Известная нулевая цена отличается от отсутствующей;
+позиция с ненулевым количеством и неизвестной стоимостью остаётся в составе.
+Несколько валют никогда не складываются в одну общую стоимость.
+
+## Состав и денежные показатели
+
+| Понятие или показатель | Смысл и источник | Ограничение |
+| --- | --- | --- |
+| Позиция | Ненулевое количество обычного инструмента из `GetPortfolio.positions` | Виртуальные позиции не включаются; порядок источника сохраняется |
+| `quantity` | Количество из текущей позиции брокера | Допустимы дробные и отрицательные количества; это не число лотов |
+| `currentValue` | Количество × текущая цена из `GetPortfolio` | `null`, если цена или её валюта недоступны |
+| `averagePurchasePrice` | Средняя цена позиции, переданная брокером | Это цена единицы, а не сумма затрат или рассчитанная приложением история покупок |
+| `absoluteReturn` | Количество × (текущая цена − средняя цена) | Требует обеих цен в одной известной валюте; не включает продажи, купоны и дивиденды |
+| Cash Balance | Суммы из `GetPositions.money`, объединённые по валюте | Заблокированные деньги не прибавляются; торгуемый инструмент `CURRENCY` остаётся позицией |
+| `totalsByCurrency` | Стоимости позиций + доступные деньги той же валюты | Не включает невычислимую стоимость; не обещает полную оценку портфеля |
+| `lastSuccessfulAt` | Время формирования успешного снимка, UTC | Не является временем каждой котировки; запасной снимок сохраняет исходное время |
+| `isStale` | Backend вернул предыдущий полный снимок после временной ошибки | Не описывает состояние клиентского кэша или ошибку фонового запроса |
+
+Ненулевые денежные остатки одной валюты суммируются. Позиции одинаковых
+инструментов в ответе отдельного счёта не объединяются; визуальная группировка
+между счетами описана [отдельно](all-accounts.md#данные-и-вычисления).
+Сводка уже включает Cash Balance: прибавление денег к ней второй раз неверно.
+
+При отсутствии вычислимой стоимости у части позиций известный итог остаётся
+полезен, но представляет только оценённую часть. Известные нулевые итоги
+отдельного счёта не создают валютные карточки. Если `totalsByCurrency` пуст,
+но позиции или деньги присутствуют, это не пустой портфель.
+
+## Идентификация и оформление инструмента
+
+UID определяет конкретный инструмент брокера и используется для перехода
+на его страницу. FIGI, ISIN и тикер сохраняются как доступные идентификаторы;
+одно название или совпадение тикера не доказывает тождество инструментов.
+Для получения метаданных backend сначала использует UID, затем FIGI.
+Отображаемое имя выбирается в порядке: полное имя, тикер, FIGI.
+Если нет и FIGI, текущая реализация использует `Unknown instrument`.
+
+ISIN, тикер и `logoName` могут быть `null`. `logoName` — имя файла бренда,
+а не URL: frontend строит ссылку на публичный CDN. Ошибка изображения
+или метаданных не меняет количество, суммы и свежесть снимка и не скрывает
+финансовые данные. Имя ожидается перед завершением нового снимка;
+ошибка поиска оставляет доступный идентификатор.
+
+## Структура и доли
+
+`structure` распределяет стоимость по четырём категориям: акции (`STOCK`),
+облигации (`BOND`), прочие инструменты (`OTHER`) и деньги (`CASH`).
+Торгуемые валютные инструменты входят в `OTHER`; денежные остатки — в `CASH`.
+Сервер строит структуру из позиций и денег, без повторного добавления
+`totalsByCurrency`.
+
+Доля категории — её стоимость / известная стоимость позиций и денег
+в выбранной валюте × 100. Backend округляет процент до шести знаков;
+frontend показывает до сотых. Положительное значение меньше 0,01%
+отображается как «< 0,01 %», если серверное округление не превратило его в ноль.
+В геометрию диаграммы передаются только числовые проценты; суммы в списке
+и подсказке форматируются из исходных точных строк.
+
+Доля на карточке отдельной позиции использует другой знаменатель:
+сумму стоимостей всех позиций той же валюты **без денег**. Это приблизительный
+показатель для отображения, рассчитанный frontend. Он не изменяет Money.
+В режиме всех счетов знаменатель охватывает все показанные счета.
+
+| Состояние | Доступное представление |
+| --- | --- |
+| Все составляющие оценены, неотрицательны, итог положителен | Суммы, доли и кольцевая диаграмма выбранной валюты |
+| Есть позиция без оценки | `unvaluedCategories` содержит её категорию и количество; суммы известной части остаются, доли и кольцо недоступны для всех валют |
+| Есть отрицательная составляющая | Суммы со знаком остаются; доли и кольцо отключены для её валюты, даже если итог категории положителен |
+| Состав пуст или имеет нулевую стоимость | Текстовое состояние вместо кольца |
+
+Неоценённой позиции нельзя достоверно назначить валюту по её стоимости,
+поэтому ограничение долей действует на все валюты. В общем портфеле проверка
+отрицательных денег выполняется по остаткам счетов до взаимозачёта.
+
+Нормативные основы: [нормализованный состав](../../../specs/openspec/specs/portfolio-view/spec.md#requirement-нормализованный-состав-portfolio)
+и [точные значения и валютные агрегаты](../../../specs/openspec/specs/portfolio-view/spec.md#requirement-точные-значения-и-валютные-агрегаты).
+Структура и общий режим подтверждены реализацией и её проверками;
+отдельных требований к ним в основной спецификации портфеля пока нет.
+Поля транспорта следует сверять с [HTTP API](../../architecture/http-api.md),
+а свежесть — с [потоком загрузки](flows/portfolio-loading.md).