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,99 @@
+# Портфель
+
+Портфель показывает, какими активами и доступными деньгами располагает
+брокерский счёт по последнему успешному наблюдению T-Bank. Это снимок состава
+и его текущей оценки, а не локальная история владения или расчёт полной
+инвестиционной доходности. Пользователь открывает его на
+`/accounts/:accountId`; [режим «Все счета»](all-accounts.md) объединяет
+доступные счета текущего подключения.
+
+## Снимок и связанные области
+
+Снимок состоит из позиций по инструментам, доступных денежных остатков,
+валютных итогов и структуры активов. Позиция означает ненулевое количество
+обычного инструмента в брокерском портфеле. Торгуемая валютная позиция
+`CURRENCY` и свободные деньги имеют разный смысл и передаются раздельно.
+Точный смысл сумм и неизвестных значений раскрыт в
+[справочнике данных](data-reference.md).
+
+Доступность счёта определяется [текущим подключением и списком счетов](../accounts/overview.md).
+SQLite не хранит сам портфель: backend получает данные через серверную
+[интеграцию T-Bank](../../integrations/tbank.md) и временно сохраняет успешный
+снимок в памяти. Frontend получает нормализованный результат через HTTP API.
+[Поток загрузки](flows/portfolio-loading.md) объясняет границы доступа,
+свежий кэш и восстановление после временной ошибки.
+
+Обзор счёта также показывает пять последних [операций](../operations/overview.md),
+[полученный доход](../income/overview.md) текущего месяца и до пяти
+[будущих событий](../income/upcoming-events.md). Каждый блок загружается
+самостоятельно: его ошибка или отсутствие данных не скрывает основной
+портфель. Полученные выплаты и прогноз не добавляются к текущей стоимости
+повторно и не превращают результат открытой позиции в полную доходность.
+
+## Как читать экран
+
+Валютная сводка показывает отдельную карточку для каждого полученного итога.
+Деньги уже включены в итог своей валюты. RUB, USD и EUR обозначены ₽, $ и €;
+другие валюты сохраняют ISO-код. Вспомогательным технологиям доступны полное
+значение и название валюты. Суммы сохраняют все исходные цифры, знак и
+дробные позиции, включая `-0,5`; длинные значения переносятся без обрезания.
+Карточки не интерактивны и занимают одну колонку на узком экране,
+две или три на широком. Отсутствующая валюта не получает искусственную
+нулевую карточку. Пустые итоги не скрывают доступный состав портфеля.
+
+Структура после сводки распределяет известную стоимость по акциям,
+облигациям, другим активам и свободным деньгам. При нескольких валютах
+пользователь выбирает одну; при одной отдельного переключателя нет.
+Кольцевая диаграмма дополнена текстовым списком сумм и долей и подсказкой;
+на узком экране список расположен под ней. Неизвестная оценка, отрицательные
+составляющие или нулевой итог ограничивают возможность показать доли —
+[почему кольцо бывает недоступно](data-reference.md#структура-и-доли).
+
+Акции и облигации показаны отдельными секциями, по одной карточке в ряду
+при любой ширине. Внутри сохраняется порядок источника. Слева находятся
+название, логотип, количество и идентификатор, справа — стоимость и результат.
+Средняя цена и доля размещены ниже. Логотип размером 40 px при недоступности
+изображения заменяется первой буквой имени. Акция показывает тикер, а при его
+отсутствии ISIN; облигация — ISIN. Название и логотип ведут на страницы
+[акции](../instruments/stocks.md) или [облигации](../instruments/bonds.md),
+когда доступен точный UID инструмента.
+
+Результат открытой позиции имеет явный знак: плюс при положительном,
+минус при отрицательном, без знака при нуле. Цвет дополняет знак.
+Иные отображаемые активы используют компактные плитки в адаптивной сетке
+без логотипа и с подписью результата. Отсутствующие показатели скрываются,
+а не подменяются нулём или заглушкой.
+
+Существует расхождение: [согласованная спецификация представления позиций](../../../specs/openspec/specs/portfolio-view/spec.md#requirement-представление-карточек-позиций-на-клиенте)
+требует доступности всех иных типов в отдельной секции, а текущие frontend
+и его проверка исключают `CURRENCY` только из списка карточек. Такие позиции
+остаются в ответе, валютных итогах, структуре и знаменателе долей остальных
+позиций. Это описание фактического ограничения; выбор между изменением
+интерфейса и согласованием требований остаётся отдельной задачей.
+
+## Свежесть и границы
+
+При первом запросе экран показывает каркас заголовка, сводки и разделов.
+Три формы валютных карточек в каркасе не обещают наличие трёх валют.
+Загрузка обозначена для вспомогательных технологий; декоративные элементы
+не содержат данных и не получают фокус. При обычном фоновом обновлении
+сохраняются предыдущие суммы и время успешного получения в UTC.
+
+Серверный `isStale` обозначает разрешённый запасной снимок backend.
+Клиентское предупреждение означает неудачную попытку обновить уже показанный
+ответ. Эти состояния независимы и могут появиться одновременно.
+Успешный повторный запрос обновляет суммы и время, снимает клиентскую ошибку;
+серверное предупреждение определяется новым `isStale`.
+Правила времени и ошибок приведены в [потоке загрузки](flows/portfolio-loading.md).
+
+В текущем решении нет долговременной истории снимков, графиков стоимости
+портфеля, валютной конвертации, учёта виртуальных позиций или заблокированных
+средств. Кэш теряется при перезапуске и рассчитан на локальную работу одного
+экземпляра backend. Отдельной команды принудительного обновления на экране
+нет; повторная попытка доступна после ошибки.
+
+Для проверки конкретной суммы используйте
+[руководство по расхождениям](how-to/investigate-discrepancy.md).
+Проверяемое поведение отдельного счёта описано в
+[спецификации портфеля](../../../specs/openspec/specs/portfolio-view/spec.md);
+точную форму HTTP-ответа задаёт [OpenAPI backend](../../architecture/http-api.md).