docs: explain server-side portfolio metadata recovery

domains/instruments/stocks.md

@@ -22,6 +22,12 @@
 его, иначе сохраняют UID. Одинаковые UID в разных счетах используют один запрос и общий
 кэш страницы акции. До загрузки и при ошибке остаётся рабочая ссылка по UID;
 загрузка адресов не блокирует портфель.
+
+Названия, тикеры, ISIN и логотипы карточек портфеля приходят в его серверном
+ответе. Запрос страницы акции уточняет только ссылку и не подменяет эти поля
+на frontend. Общее для акций и облигаций восстановление справочных данных
+принадлежит [загрузке портфеля на backend](../portfolio/flows/portfolio-loading.md).
+
 Раздел «Акции» в боковой и мобильной навигации ведёт на `/stocks`: поиск
 по названию или тикеру через каталог Т-Банка, начиная с двух символов.
 Результаты разных выпусков, включая обыкновенные и привилегированные акции,

domains/portfolio/flows/portfolio-loading.md

@@ -56,8 +56,16 @@ sequenceDiagram
 
 Для нового снимка требуются оба финансовых ответа. Backend не выдаёт
 позиции без денег или деньги без позиций как полный портфель.
-Метаданные дополняют имя и идентификаторы, но их ошибка не срывает
+Метаданные дополняют имя и идентификаторы, но их временная недоступность
-финансовый результат. Общий серверный клиент обеспечивает TLS, очередь,
+не срывает финансовый результат. Поиск выполняется партиями по пять позиций,
+чтобы крупный портфель не переполнял очередь одновременными запросами.
+Порядок позиций сохраняется. Backend ищет сведения по UID, затем по FIGI,
+если UID не дал пригодного названия или тикера.
+Ожидание метаданных ограничено 30 секундами на снимок счёта. После этого
+используется доступный кэш либо идентификатор, новые поиски для снимка
+не запускаются. Уже начатые запросы могут закончиться позже и обновить общий
+справочный кэш, но не меняют выданный финансовый снимок.
+Общий серверный клиент обеспечивает TLS, очередь,
 ограничение частоты, deadline RPC и разрешённые повторные попытки —
 [граница интеграции](../../../integrations/tbank.md).
 
@@ -68,7 +76,7 @@ sequenceDiagram
 | Frontend | Последний успешный HTTP-ответ для выбранного счёта и сессии | Свежим считается 30 секунд; при обычном обновлении уже показанный ответ остаётся видимым |
 | Backend | Полный снимок пары пользователь–счёт в памяти процесса | До 30 секунд, только в том же поколении текущего подключения |
 | Backend при временной ошибке | Тот же полный снимок | Не старше пяти минут с момента успешного сохранения, только в том же поколении |
-| Метаданные инструмента | Успешный поиск или подтверждённое отсутствие | До 24 часов; общий ограниченный кэш на 500 ключей UID/FIGI, ошибки не сохраняются |
+| Метаданные инструмента | Успешный поиск или подтверждённое отсутствие | Свежими считаются 24 часа; общий кэш на 500 ключей UID/FIGI, ошибки не сохраняются |
 
 Это параметры текущей реализации, а не самостоятельная политика этого
 документа: [снимки](../../../../backend/src/tbank/portfolio.service.ts),
@@ -79,6 +87,23 @@ sequenceDiagram
 пять минут после окончания свежих 30 секунд. Запасной ответ сохраняет
 исходное `lastSuccessfulAt` и получает `isStale: true`.
 
+После истечения 24 часов backend обновляет справочные данные. Если обновление
+временно недоступно, ранее успешные сведения остаются запасным вариантом,
+пока запись есть в ограниченном кэше процесса. Ошибка не продлевает срок
+свежести: следующий поиск снова пытается обновить запись. Это относится только
+к названию, тикеру, ISIN и логотипу, а не к ценам или денежным значениям.
+Перезапуск backend и вытеснение записи из кэша удаляют этот запасной вариант.
+Неполный ответ без названия и тикера также не затирает известные сведения
+и не обновляет срок их свежести. Подтверждённое отсутствие инструмента
+заменяет прежнюю запись отрицательным результатом поиска.
+
+Время снимка фиксируется при получении финансовых ответов, до ожидания
+названий. Сроки серверного кэша отсчитываются от этого времени, поэтому
+долгая загрузка справочных данных не делает старые суммы новыми.
+Успешные справочные данные общие для всех пользователей; выполняющиеся
+запросы объединяются только внутри одного брокерского токена, чтобы ошибка
+его авторизации не передавалась другому подключению.
+
 Успешное создание, замена или удаление подключения меняет границу
 повторного использования финансовых данных. Старое или поздно завершившееся
 получение снимка не делает его доступным новым запросам другого поколения.
@@ -104,18 +129,25 @@ Frontend сбрасывает всё поддерево финансовых з
 
 `INVALID_TBANK_TOKEN` и `404` не заменяются серверным запасным снимком.
 Временная ошибка определения доступных счетов также может использовать
-пригодный снимок того же поколения. Сбой метаданных использует идентификатор
+пригодный снимок того же поколения. При временном сбое метаданных сначала
-инструмента и не устанавливает `isStale`.
+используются ранее успешные сведения, а при их отсутствии — идентификатор
+инструмента; это не устанавливает `isStale`. Отказ авторизации при поиске
+метаданных не маскируется запасным названием.
 
-На клиенте нет polling, автоматического повтора неуспешного запроса или
+Для запроса самого портфеля на клиенте нет polling, автоматического повтора или
 обновления при возврате фокуса. При обновлении того же уже показанного
 результата клиент оставляет его на экране, добавляя индикатор загрузки
 или предупреждение с доступной с клавиатуры повторной попыткой.
 Это клиентский сохранённый ответ, независимо от серверного `isStale`.
 
+Frontend отображает название и остальные сведения из ответа портфеля.
+Повторные попытки поиска для акций, облигаций и других типов инструментов
+принадлежат [общему клиенту T-Bank на backend](../../../integrations/tbank.md#конфигурация-и-ограничения).
+
 Первое обращение к крупному портфелю может потребовать много метаданных.
-Переполнение общей очереди RPC означает временную недоступность конкретного
+Переполнение общей очереди RPC может произойти при конкурирующих запросах;
-поиска. После успешного поиска метаданные используются повторно до истечения
+поиск метаданных в этом случае повторяется с ограниченными паузами. После
+успешного поиска метаданные используются повторно до истечения
 кэша. Значение `TBANK_RATE_LIMIT_PER_SECOND` следует соотносить с квотой
 источника; его увеличение не является гарантированным исправлением
 ограничения самого T-Bank.

integrations/tbank.md

@@ -127,10 +127,17 @@ Backend хранит token в шифротексте AES-256-GCM с новым n
 
 Параметры окружения определяет backend
 [validateEnv](../../backend/src/config/env.validation.ts) (workspace-ссылка).
-Общий FIFO-лимитер ограничивает поток RPC и отклоняет новый вызов при 50
+Общий FIFO-лимитер ограничивает поток RPC и не допускает более 50
 ожидающих. Для `UNAVAILABLE`, `DEADLINE_EXCEEDED` и `RESOURCE_EXHAUSTED`
-предусмотрен один повтор через секунду. Deadline каждой попытки — 15 секунд,
+обычный RPC допускает один повтор через секунду. Deadline каждой попытки — 15 секунд,
 а ожидание места в лимитере не является временем этой сетевой попытки.
+Для поиска метаданных `GetInstrumentBy` разрешены две повторные попытки
+с паузами 2 и 4 секунды после неудачных попыток. Они применяются к тем же
+временным кодам и к переполнению локальной очереди; перед каждой попыткой
+проверяется её вместимость. Постоянные ошибки и отказ авторизации
+не повторяются. Подтверждённый `NOT_FOUND` при поиске метаданных означает
+отсутствие инструмента, а не временный сбой. Остальные RPC при полной
+очереди завершаются сразу.
 Параметры попыток принадлежат
 [T-Bank client](../../backend/src/tbank/tbank.client.ts) (workspace-ссылка);
 решение об ограниченных повторах — [ADR 005](../adr/005-tbank-upstream-resilience.md).