specs/openspec/specs/brokerage-accounts/spec.md

brokerage-accounts Specification

Purpose

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

Requirements

Requirement: Список активных брокерских счетов

Система SHALL предоставлять авторизованному User GET /api/v1/brokerage-accounts, возвращающий массив его открытых поддерживаемых инвестиционных счетов T-Bank в порядке, полученном от T-Bank. Каждый элемент MUST содержать стабильный id, непустое name, нормализованный type (BROKERAGE, INDIVIDUAL_INVESTMENT, INVEST_BOX или MONEY_MARKET_FUND) и nullable openedOn в формате YYYY-MM-DD. Система MUST включать только счета T-Bank типов «брокерский счёт», «ИИС», «Инвесткопилка» и «фонд денежного рынка»; банковские и неизвестные типы MUST NOT возвращаться. Система MUST удалить внешние пробелы из имени и при пустом результате использовать непустое название соответствующего типа.

Scenario: Поддерживаемые счета возвращаются в upstream-порядке

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

Scenario: Пустой список поддерживаемых счетов

• WHEN User с действующим T-Bank connection не имеет открытых поддерживаемых инвестиционных счетов
• THEN система отвечает 200 пустым массивом

Scenario: Пустое название получает fallback

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

Scenario: Дата открытия отсутствует

• WHEN T-Bank не возвращает дату открытия поддерживаемого открытого счёта
• THEN система отвечает этим счётом с openedOn: null

Requirement: Состояния недоступности списка счетов

Система MUST NOT возвращать частичный или сохранённый ранее список счетов. При отсутствии T-Bank connection система MUST отвечать 409 Problem Details с code TBANK_NOT_CONNECTED. Если T-Bank отклоняет сохранённый token как неаутентифицированный или без прав, система MUST отвечать 400 Problem Details с code INVALID_TBANK_TOKEN и сохранять connection. При иной неуспешной попытке получить список из T-Bank система MUST отвечать 503 Problem Details с code TBANK_UNAVAILABLE.

Scenario: Подключение отсутствует

• WHEN User без сохранённого T-Bank connection запрашивает список
• THEN система не обращается к T-Bank и отвечает 409 Problem Details с code TBANK_NOT_CONNECTED

Scenario: Сохранённый token больше не действителен

• WHEN T-Bank отклоняет сохранённый token при запросе списка как неаутентифицированный или без прав
• THEN система отвечает 400 Problem Details с code INVALID_TBANK_TOKEN и не удаляет connection

Scenario: T-Bank временно недоступен

• WHEN запрос списка не завершается из-за временной либо иной upstream-ошибки
• THEN система отвечает 503 Problem Details с code TBANK_UNAVAILABLE без счетов

Requirement: Экран списка брокерских счетов

Клиент SHALL загружать список при открытии защищённого маршрута /accounts без ручного обновления и без автоматического refetch при возврате фокуса. Клиент MUST использовать успешный frontend-кэш списка в течение 60 секунд; после истечения этого срока при новом запросе клиент MUST скрывать ранее показанный список и показывать loading-состояние. При успешном непустом ответе клиент MUST отобразить светлые интерактивные карточки счетов с названием, локализованным типом и, если доступна, локализованной датой открытия без времени; карточки MUST вести на /accounts/:accountId. При успешном пустом ответе клиент MUST показать штатное состояние отсутствия инвестиционных счетов. После успешной замены или удаления T-Bank connection клиент MUST инвалидировать список счетов.

Scenario: Пользователь открывает счёт из списка

• WHEN клиент успешно загрузил непустой список и User выбирает карточку счёта
• THEN клиент переходит на /accounts/:accountId с id выбранного счёта

Scenario: Список пуст

• WHEN клиент получает успешный пустой массив
• THEN клиент показывает штатное сообщение об отсутствии инвестиционных счетов T-Bank

Scenario: Список берётся из свежего frontend-кэша

• WHEN User повторно открывает список в течение 60 секунд после успешной загрузки
• THEN клиент показывает сохранённые счета без нового API-запроса

Scenario: Устаревший список загружается повторно

• WHEN User открывает список после истечения 60 секунд frontend-кэша
• THEN клиент не показывает ранее загруженные счета до получения нового результата

Requirement: Клиентские состояния ошибки списка счетов

Клиент MUST NOT автоматически повторять неуспешный запрос списка. При TBANK_NOT_CONNECTED клиент SHALL показать объяснение отсутствия подключения и действие «Открыть настройки T-Bank». При INVALID_TBANK_TOKEN клиент SHALL показать объяснение недействительного token и то же действие. При TBANK_UNAVAILABLE клиент SHALL показать безопасное объяснение временной недоступности, действие повторной загрузки и действие открытия настроек T-Bank. При иной ошибке клиент MUST показать общий безопасный error-state только с действием повторной загрузки.

Scenario: Подключение требуется

• WHEN клиент получает TBANK_NOT_CONNECTED
• THEN клиент не показывает список и предлагает открыть настройки T-Bank

Scenario: Известная ошибка не повторяется автоматически

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

Scenario: Token требует внимания

• WHEN клиент получает INVALID_TBANK_TOKEN
• THEN клиент не показывает список и предлагает открыть настройки T-Bank

Scenario: Временная ошибка T-Bank

• WHEN клиент получает TBANK_UNAVAILABLE
• THEN клиент не показывает список и предлагает повторить загрузку либо открыть настройки T-Bank

Scenario: Неизвестная ошибка загрузки

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