specs/openspec/changes/persist-tbank-data/specs/tbank-data-sync/spec.md

Purpose

Определяет постоянное хранение данных T-Bank, локальное чтение и синхронизацию по запросу с проверяемыми полнотой, свежестью и изоляцией подключения.

ADDED Requirements

Requirement: Все экраны читают сохранённые данные без ожидания T-Bank

Система SHALL постоянно сохранять уже загруженные счета, последний полный портфель, исполненные операции, данные инструментов, текущие котировки, дневные свечи и календари выплат. Доходы, личные позиции и прогнозные выплаты SHALL рассчитываться по сохранённым источникам. Все соответствующие экраны, включая режим «Все счета», поиск, сведения о компании и зависимости котировок, MUST читать доступные данные без ожидания ответа T-Bank. Перезапуск backend MUST NOT требовать повторной загрузки сохранённых полных интервалов.

Scenario: Брокер медленно отвечает при заполненном хранилище

• WHEN User открывает любой экран с сохранёнными данными текущего подключения, а T-Bank задерживает ответ
• THEN обычный серверный ответ содержит сохранённые данные и их состояние, не ожидая T-Bank, включая проверку доступных счетов

Scenario: Перезапуск сохраняет историю

• WHEN backend перезапущен и User запрашивает ранее полностью загруженный прошлый период
• THEN система возвращает его из постоянного хранилища без повторного получения операций или завершённых свечей этого периода

Scenario: Данные ещё не загружены

• WHEN User впервые запрашивает отсутствующие данные
• THEN ответ различает отсутствие загруженного результата и подтверждённый пустой результат, сообщает о запрошенной загрузке и не ожидает её завершения

Requirement: Обновление запускается только запросом с учётом свежести

Система MUST запускать синхронизацию только запросом экрана либо ручным обновлением. Обычный запрос SHALL планировать только отсутствующие зависимости, пропуски и данные с истекшим сроком свежести: портфель и текущие цены — 60 секунд; операции текущего месяца и доступные счета — 300 секунд; справочник инструментов, включая сведения о компании, и календари выплат — 24 часа; незавершённая дневная свеча — 60 секунд. Свежесть MUST отсчитываться от последнего успешного получения соответствующего источника, а не чтения ответа или расчёта производного представления. Полнота и свежесть MUST оставаться независимыми признаками. Периодические запуски MUST NOT выполняться. Для текущего изменяемого периода полнота SHALL относиться к состоянию на последний успешный asOf: рост to=now внутри TTL не является новым пропуском, требующим RPC. Настоящие пропуски до asOf и незавершённый хвост при переходе месяца MUST NOT маскироваться этим правилом.

Scenario: Данные ещё свежие

• WHEN экран повторно запрошен до истечения сроков всех его полных зависимостей
• THEN запрос не создаёт новых обращений к T-Bank

Scenario: Текущий период запрошен через секунду

• WHEN текущий месяц полностью загружен на asOf и повторный запрос через секунду имеет более поздний to=now
• THEN система возвращает сохранённый результат с исходным asOf без нового RPC до истечения пяти минут, не утверждая наблюдение новых операций после asOf

Scenario: Истекла только свежесть портфеля

• WHEN портфель получен 60 секунд назад, а полные счета и metadata ещё свежие
• THEN обычный запрос инициирует обновление портфеля и только иных необходимых устаревших зависимостей, сохраняя прежний ответ доступным

Scenario: Пользователь не обращается к системе

• WHEN запрошенная работа завершилась и сроки свежести истекают без новых запросов
• THEN никакая синхронизация не запускается, в том числе при запуске backend

Requirement: Ручное обновление ограничено текущим экраном

Действие «Обновить» SHALL обходить давность данных и запрашивать обновление экрана с его зависимостями: текущего счёта либо доступных счетов в режиме «Все счета», применённого периода и сравнений доходов, либо инструмента с показанными свечами, выплатами и личной историей. Сервер MUST определять разрешённые зависимости сам, сохраняя проверку входа и доступа. Обновление MUST NOT перечитывать всю накопленную историю других периодов и инструментов. Подтверждение приёма работы MUST NOT означать успешное обновление данных.

Scenario: Обновление старого месяца

• WHEN User нажимает «Обновить» на журнале за полностью загруженный прошлый месяц
• THEN перечитывается показанный период счёта и необходимые зависимости без принудительного перечитывания остальных полных месяцев

Scenario: Обновление доходов

• WHEN User обновляет аналитику за выбранный период
• THEN обновление охватывает выбранный и требуемые периоды сравнения, а результаты разных периодов не подменяют друг друга

Scenario: Обновление инструмента

• WHEN User обновляет инструмент с выбранным диапазоном графика и показанной личной историей
• THEN обновляются зависимости этого инструмента, диапазон свечей и показанный период личной истории разрешённых счетов без обновления всего каталога

Requirement: Первая загрузка приоритизирует экран и продолжает историю

Система SHALL сначала загружать данные нужного экрану периода, включая периоды сравнения доходов, затем всю доступную историю запрошенного счёта. Для режима «Все счета» это применяется к каждому доступному счёту. В рамках уже запрошенной работы SHALL заранее загружаться доступная рыночная история бумаг текущего портфеля; для остальных инструментов — при первом открытии. Новый запрос нужного экрану пропуска MUST получать приоритет перед ещё не начатой догрузкой старой истории. Начатая работа MAY завершиться после ухода со страницы. Недоказанная нижняя граница доступной истории MUST NOT выдаваться за подтверждение её полной загрузки.

Scenario: Сначала сравнения доходов

• WHEN история счёта отсутствует и User открывает доходы за месяц
• THEN выбранный месяц и доступные обязательные периоды сравнения загружаются перед остальной историей; состояние старой истории не задерживает уже полный результат экрана

Scenario: Уход со страницы

• WHEN User уходит после начала догрузки истории
• THEN запрошенная работа может закончиться и сохранить результат, но не создаёт расписание последующих обновлений

Scenario: Инструмент отсутствует в портфеле

• WHEN User впервые открывает такой инструмент
• THEN система запрашивает и сохраняет его историю, не предзагружая весь каталог

Requirement: Полнота подтверждается успешным покрытием интервалов

Система MUST считать историю счёта полной за период только после успешного получения всех доступных исполненных операций всего этого интервала на момент сверки. Полный период MAY быть пустым. Фильтр категорий, инструмента, размер страницы, отсутствие записей, максимальная дата операции и наличие курсора MUST NOT служить доказательством полноты. Производное представление «Все счета» MUST учитывать покрытие каждого входящего счёта. Полные прошлые месяцы SHALL сохраняться без автоматической повторной сверки; пропуски SHALL догружаться при запросе. Смена месяца MUST NOT автоматически закрывать незагруженный хвост прошлого месяца. Существующая семантика входных дат журнала и доходов MUST сохраняться без пропусков и двойного учёта на границах.

Scenario: Пустой полный интервал

• WHEN все страницы интервала успешно получены и операций нет
• THEN период обозначается полным и пустым; последующее обычное чтение прошлого месяца не обращается к брокеру за этим интервалом

Scenario: Сбой промежуточной страницы

• WHEN одна из нескольких страниц интервала недоступна
• THEN интервал остаётся неполным, сохранённый результат не удаляется, частичные записи не выдаются за полный период

Scenario: Граница месяца

• WHEN последний успешный запрос прошлого месяца закончился до его конца
• THEN первый подходящий запрос нового месяца догружает недостающий хвост; смена даты сама не подтверждает полноту прошлого месяца

Scenario: Неполон один из счетов

• WHEN все счета, кроме одного, полностью покрывают период общего дохода
• THEN общий период не считается полным, а отсутствующий вклад счёта не заменяется нулём

Requirement: Сверка операций сохраняет идентичность и прежний результат

Система SHALL использовать стабильный ID брокерской операции в границах пользователя, подключения и счёта как принятое допущение проекта, а не гарантию API. Повторное получение ID MUST обновлять поля той же операции без дубля и двойного финансового учёта. Ручная сверка MUST согласовывать состав и поля исполненных операций показанного интервала: отсутствующие в полном новом ответе записи могут быть удалены только вместе с успешным завершением всех страниц этого интервала. Частичный либо ошибочный новый ответ MUST NOT изменять ранее опубликованный полный финансовый результат и время его успешной сверки. Автоматическое обнаружение изменений полной старой истории и смены ID не требуется.

Scenario: Поля операции исправлены

• WHEN успешная повторная сверка получает прежний ID с другой суммой или статусом, меняющим вхождение в исполненную историю
• THEN итоговый набор отражает новый полный ответ без дублирования ID, а доходы пересчитываются из согласованного набора

Scenario: Операция исчезла при ручной сверке

• WHEN все страницы перечитанного интервала успешно завершились и прежняя операция отсутствует
• THEN операция исключается из опубликованного набора этого интервала и производных финансовых результатов

Scenario: Перезагрузка полного периода оборвалась

• WHEN после нескольких страниц ручной сверки возникает ошибка
• THEN прежний полный набор, его суммы, полнота и время успешной сверки остаются доступными вместе с ошибкой обновления

Scenario: Сбой во втором месяце перечитываемого квартала

• WHEN ручная сверка полного квартала получила первый месяц, но оборвалась на странице второго
• THEN весь прежний результат показанного квартала, включая режим «Все счета», остаётся опубликованным; успешный новый первый месяц не смешивается с прежними остальными месяцами

Requirement: Прогресс переживает перезапуск и одновременные запросы

Система MUST сохранять завершённые интервалы, незавершённую работу и её прогресс. После перезапуска следующий подходящий запрос экрана или ручное обновление SHALL возобновлять запрошенную работу, повторяя незавершённый интервал безопасно и без повторной загрузки полных старых интервалов. Одновременные запросы одной границы данных SHALL объединять одинаковую работу, а пересекающиеся интервалы SHALL использовать общую загрузку пересечения. Ошибка MUST оставлять возможность следующего явного запроса, не создавая бесконечный цикл повторов. Поздняя публикация устаревшей попытки MUST NOT перезаписывать результат новой попытки.

Scenario: Двадцать одновременных запросов

• WHEN двадцать запросов требуют один отсутствующий интервал одного счёта
• THEN выполняется один проход страниц этого интервала с разрешёнными транспортными повторами, а все запросы видят общее состояние работы

Scenario: Перезапуск между страницами

• WHEN процесс остановлен после сохранения прогресса, но до полного завершения интервала
• THEN до следующего запроса работа не возобновляется; после запроса интервал перечитывается без дублей и без ложного признака полноты

Scenario: Ошибка завершила попытку

• WHEN запрошенная синхронизация исчерпала допустимые транспортные повторы
• THEN она показывает безопасную ошибку и прекращает попытки до следующего запроса; наблюдение её состояния не запускает её заново

Requirement: Общие данные инструментов отделены от личных

Система SHALL совместно использовать неперсональные metadata, котировки, свечи и календари одного инструмента между пользователями. Общие записи MUST NOT содержать аккаунты, личные позиции, остатки, операции, оценки выплат пользователя, token либо персональные ошибки. Личные данные и вычисления MUST оставаться ограничены пользователем, доступным счётом и текущим подключением. Успешный общий результат MAY переиспользоваться между счетами без повторного получения того же источника.

Scenario: Два пользователя открывают инструмент

• WHEN оба имеют право пользоваться интеграцией и общие данные инструмента уже загружены
• THEN они используют одни общие данные, но видят только собственные позиции, операции и оценки выплат

Scenario: Ошибка token одного пользователя

• WHEN источник отклоняет token одного пользователя при загрузке общего инструмента
• THEN личная ошибка не становится состоянием инструмента для другого пользователя и не удаляет ранее сохранённые общие данные

Requirement: Локальная проверка доступа сохраняет границу подключения

Каждое чтение и действие синхронизации MUST проверять сессию, текущее подключение и локально подтверждённую принадлежность счёта этому подключению. Отсутствие ранее подтверждённого списка SHALL означать загрузку доступа, а не доступ к произвольному accountId или доказанный пустой список. Устаревший подтверждённый список MAY использоваться до фоновой сверки; успешная сверка MUST отзывать доступ к исчезнувшим, закрытым или неподдержанным счетам. Известный отказ token MUST сохранять существующую ошибку INVALID_TBANK_TOKEN, отсутствие подключения — TBANK_NOT_CONNECTED, недоступный счёт — 404. Хранение не вводит архив без подключения. Успешная замена или удаление подключения MUST блокировать выдачу прежних личных данных и публикацию любых поздних результатов прежней работы. Неуспешная замена MUST сохранять действующую границу.

Scenario: Подтверждённый счёт проверяется локально

• WHEN User читает заполненные данные доступного счёта текущего подключения
• THEN проверка принадлежности не обращается синхронно к T-Bank и не использует список другого пользователя или подключения

Scenario: Прямой переход до загрузки счетов

• WHEN список текущего подключения ещё неизвестен и User запрашивает конкретный accountId
• THEN система сообщает о загрузке проверки доступа, не выдаёт личных данных этого ID и загружает доступные счета

Scenario: Доступ к счёту отозван

• WHEN успешная фоновая сверка больше не подтверждает доступ к ранее видимому счёту
• THEN последующие запросы этого счёта возвращают 404, а клиент прекращает показывать его как доступный

Scenario: Поздний результат прежнего подключения

• WHEN старый запрос заканчивается после успешной замены или удаления подключения
• THEN его данные, прогресс, ошибки и признаки свежести не публикуются и не становятся результатом нового подключения

Requirement: Завершённость свечей подтверждается источником

Система SHALL сохранять дневные свечи по инструменту и времени источника. Завершённые свечи MUST NOT перечитываться обычным запросом при полном покрытии диапазона. Незавершённая свеча SHALL обновляться при запросе после 60 секунд до явного подтверждения завершённости источником, даже если её календарный день прошёл. Успешное пустое окно MAY подтверждать отсутствие свечей только в завершённом диапазоне и MUST NOT создавать синтетические свечи. Открытое окно текущего дня, в том числе пока пустое, SHALL оставаться изменяемым с минутным сроком свежести. Ручное обновление SHALL перечитывать показанный диапазон, сохраняя прежние данные при ошибке.

Scenario: Наступил новый день

• WHEN сохранённая свеча предыдущего дня не подтверждена как завершённая источником
• THEN новый день не делает её окончательной, и подходящий запрос продолжает обновлять её с минутным сроком свежести

Scenario: Выходной без свечей

• WHEN источник успешно подтвердил пустое окно без торговых свечей
• THEN окно сохраняется как проверенное без выдуманных цен и повторной обычной загрузки завершённого диапазона

Scenario: До начала торгов свеча отсутствует

• WHEN запрос текущего дня вернул пустое окно, а после начала торгов User снова открывает график по истечении минуты
• THEN система запрашивает изменяемое окно и сохраняет появившуюся свечу; утренний ответ не закрепляет окончательное отсутствие свечи

Requirement: Интерфейс различает свежесть полноту и состояние работы

На всех экранах T-Bank клиент MUST показывать время последнего успешного получения, свежесть, загрузку и безопасную ошибку обновления применимых данных. Полнота MUST относиться к показанному периоду и его зависимостям; общий прогресс истории счёта MUST NOT подменять полноту экрана. Отсутствующие данные SHALL иметь состояние первичной загрузки; доступные данные SHALL оставаться видимыми во время обновления. Неполные totals/comparisons MUST NOT показываться как окончательные или как ноль; неполный пустой журнал MUST NOT сообщать, что операций нет. Наблюдение запрошенной работы MUST прекращаться после завершения либо ухода и MUST NOT запускать синхронизацию. Известные ошибки доступа MUST NOT маскироваться сохранённым результатом.

Scenario: Недавний период готов раньше всей истории

• WHEN показанный период и его зависимости полны, но старая история ещё загружается
• THEN пользователь видит готовый результат периода и отдельное состояние догрузки истории

Scenario: Полнота изменилась без новых записей

• WHEN источник подтвердил пустой период экрана, а остальная история ещё загружается
• THEN наблюдающий клиент получает изменение полноты и показывает подтверждённый пустой результат, не ожидая конца всей истории

Scenario: Ответы наблюдения завершились в обратном порядке

• WHEN поздний ответ чтения содержит прежние данные или доступ, а клиент уже принял более новое состояние этого ресурса либо отзыв доступа
• THEN прежний ответ не откатывает показанные данные и не восстанавливает недоступный личный результат

Scenario: Источник временно недоступен

• WHEN обновление сохранённого полного результата завершается временной ошибкой
• THEN прежние данные и время сохраняются, ошибка видима и доступно ручное повторное обновление; ошибка не обновляет время успешного получения и не считается успешной сверкой

Scenario: Неполное сравнение дохода

• WHEN выбранный период готов, а необходимый период сравнения ещё не загружен
• THEN сравнение обозначается как незавершённое без нулевой базы или окончательной разницы

Requirement: Быстродействие и сокращение запросов проверяются измерениями

Для обычных чтений заполненной БД система SHALL иметь целевой бюджет серверного ответа до 500 мс в зафиксированном профиле нагрузки. Выполнение цели MUST подтверждаться измерениями, а не предполагаться из наличия БД. Свежие полные зависимости MUST давать ноль новых RPC T-Bank; двадцать одновременных запросов одного устаревшего набора MUST создавать не более одной логической загрузки каждой зависимости. Полные старые операции и завершённые свечи MUST давать ноль повторных RPC для своих интервалов при обычном чтении, включая чтение после перезапуска.

Scenario: Измеряется заполненное хранилище

• WHEN проверяется согласованный набор обычных запросов при задержанном или недоступном T-Bank
• THEN фиксируются распределение серверных задержек, число RPC и параметры нагрузки; цель 500 мс не объявляется достигнутой без этих результатов

Scenario: Повторные открытия не перечитывают историю

• WHEN один и тот же полный прошлый период читается повторно без ручного обновления
• THEN сохранённые данные выдаются без RPC этого интервала, независимо от числа страниц клиентской выдачи