84 lines
9.9 KiB
Markdown
84 lines
9.9 KiB
Markdown
# 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** клиент не показывает список и предлагает только повторить загрузку
|