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,56 @@
+# Разобрать расхождение суммы портфеля
+
+Используйте этот порядок, когда итог, позиция или доля на экране отличаются
+от ожидаемого значения. Он помогает определить слой расхождения без изменения
+данных. Нужны адрес экрана и уже доступный ответ API либо синтетический пример
+из существующей проверки. Реальные токены, персональные выгрузки и содержимое
+базы для разбора не нужны; не переносите их в документацию или отчёт.
+
+1. **Определите предмет сравнения.** Запишите, открыт отдельный счёт или
+   «Все счета», какая валюта и какой показатель расходятся. Текущая стоимость,
+   свободные деньги, результат открытой позиции и полученный доход — разные
+   величины. Убедитесь, что сравниваемые значения относятся к одному составу
+   счетов и инструменту. Название или тикер сами по себе не доказывают
+   совпадение выпуска; используйте доступные UID, FIGI и ISIN.
+2. **Сопоставьте время.** Проверьте `lastSuccessfulAt`, `isStale` и наличие
+   предупреждения о клиентском обновлении. Серверный снимок не обещает время
+   каждой котировки, а общий портфель может соединять разные моменты.
+   Если запрос завершился ошибкой, доступное действие «Повторить» должно
+   обновить результат или оставить объяснимую ошибку. Перезагрузка backend
+   удаляет кэш и не восстанавливает историю стоимости.
+3. **Проверьте состав суммы.** Для одной валюты итог складывается из
+   вычислимых стоимостей позиций и доступных денег. Не добавляйте деньги
+   второй раз, не складывайте валюты и не включайте заблокированные средства.
+   Ненулевая позиция с `currentValue: null` делает оценку неполной, но не
+   даёт нулевой вклад в смысле полной стоимости. `CURRENCY` участвует
+   в суммах, хотя текущий интерфейс скрывает её карточку —
+   [известное расхождение со спецификацией](../overview.md#как-читать-экран).
+4. **Проверьте показатель по его определению.** Используйте
+   [справочник](../data-reference.md#состав-и-денежные-показатели).
+   Условный пример: 2 бумаги по 100 RUB и 50 RUB свободных денег дают
+   250 RUB стоимости. Доля позиции среди позиций равна 100%, а доля
+   соответствующей категории в структуре с деньгами — 80%.
+   Купоны и дивиденды не включаются в результат открытой позиции.
+   Для проверки десятичных сумм сохраняйте исходные строки;
+   арифметика с плавающей точкой может сама создать расхождение.
+5. **Найдите ответственную границу.** Если ответ API корректен, а экран
+   теряет цифры, валюту или показатель, исследуйте frontend.
+   Если исходные безопасные данные и нормализованный ответ расходятся,
+   исследуйте backend. Если не совпадают ожидаемое и описанное поведение,
+   сначала сопоставьте [спецификацию портфеля](../../../../specs/openspec/specs/portfolio-view/spec.md)
+   и ограничения [потока загрузки](../flows/portfolio-loading.md).
+   Исправление документации само по себе не разрешает конфликт требований
+   и реализации.
+
+Для адресной проверки исходников владельцами служат
+[сервис снимков](../../../../backend/src/tbank/portfolio.service.ts),
+[валютные итоги](../../../../backend/src/tbank/portfolio-totals.ts),
+[структура](../../../../backend/src/tbank/portfolio-structure.ts) и
+[подготовка экрана](../../../../frontend/src/pages/account/ui/AccountPage.vm.ts).
+Это точки продолжения расследования; смысл вычислений изложен выше.
+
+Разбор завершён, когда различие объяснено составом, временем или определением
+показателя либо получен воспроизводимый пример дефекта с ожидаемым и
+фактическим результатом. В последнем случае сохраните минимальный синтетический
+пример и адрес ответственного слоя. Ошибки источника и неизвестные значения
+не исправляются подстановкой нулей или обходом проверки доступа.