docs: archive T-Bank connection change
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# tbank-connection Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Позволяет авторизованному пользователю безопасно подключить T-Bank Invest для будущего получения только собственных инвестиционных данных через backend.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Статус подключения T-Bank
|
||||
Система SHALL предоставлять авторизованному User `GET /api/v1/tbank-connection`, возвращающий состояние его единственного подключения в форме `{ connected, connectedAt }`. При отсутствии подключения ответ MUST быть `{ connected: false, connectedAt: null }`; при наличии подключения `connectedAt` MUST быть timestamp в RFC 3339 UTC. Получение статуса MUST NOT обращаться к T-Bank.
|
||||
|
||||
#### Scenario: Подключение отсутствует
|
||||
- **WHEN** авторизованный User запрашивает статус без сохранённого подключения
|
||||
- **THEN** система отвечает `200` с `{ connected: false, connectedAt: null }`
|
||||
|
||||
#### Scenario: Подключение существует
|
||||
- **WHEN** авторизованный User запрашивает статус после успешного подключения
|
||||
- **THEN** система отвечает `200` с `{ connected: true, connectedAt: <RFC 3339 UTC timestamp> }` без token
|
||||
|
||||
### Requirement: Создание и замена подключения T-Bank
|
||||
Система SHALL позволять авторизованному User создать или заменить единственное подключение через `PUT /api/v1/tbank-connection` с token. Система MUST удалить внешние пробелы token, отклонить пустое значение как ошибку валидации и проверить token запросом T-Bank открытых счетов до сохранения. Пустой список счетов MUST считаться успешной проверкой. Успех MUST вернуть `200` с текущим статусом подключения; успешная замена MUST установить новый `connectedAt`.
|
||||
|
||||
#### Scenario: Успешное создание подключения без счетов
|
||||
- **WHEN** User отправляет непустой token и T-Bank успешно возвращает пустой список открытых счетов
|
||||
- **THEN** система сохраняет подключение и отвечает `200` с `{ connected: true, connectedAt: <RFC 3339 UTC timestamp> }`
|
||||
|
||||
#### Scenario: Успешная замена подключения
|
||||
- **WHEN** User с подключением отправляет другой token и T-Bank успешно его проверяет
|
||||
- **THEN** система заменяет token подключения, обновляет `connectedAt` и отвечает текущим статусом без token
|
||||
|
||||
#### Scenario: Невалидный token не заменяет существующее подключение
|
||||
- **WHEN** T-Bank отклоняет token как неаутентифицированный или не имеющий прав
|
||||
- **THEN** система отвечает `400` Problem Details с code `INVALID_TBANK_TOKEN` и сохраняет прежнее подключение без изменений
|
||||
|
||||
#### Scenario: T-Bank временно недоступен при проверке token
|
||||
- **WHEN** проверка token не завершается из-за временной или иной upstream-ошибки
|
||||
- **THEN** система отвечает `503` Problem Details с code `TBANK_UNAVAILABLE` и не создаёт либо не изменяет подключение
|
||||
|
||||
### Requirement: Удаление подключения T-Bank
|
||||
Система SHALL позволять авторизованному User удалить своё подключение через `DELETE /api/v1/tbank-connection`. Удаление MUST быть идемпотентным и отвечать `204`; после успешного удаления backend MUST прекратить использовать удалённый token и удалить относящиеся к User кэшированные данные T-Bank.
|
||||
|
||||
#### Scenario: Удаление существующего подключения
|
||||
- **WHEN** User удаляет существующее подключение
|
||||
- **THEN** система удаляет token и связанные кэшированные данные User, затем отвечает `204`
|
||||
|
||||
#### Scenario: Повторное удаление подключения
|
||||
- **WHEN** User удаляет уже отсутствующее подключение
|
||||
- **THEN** система отвечает `204`
|
||||
|
||||
### Requirement: Конфиденциальность token T-Bank
|
||||
Система MUST хранить не более одного token T-Bank для каждого User только в зашифрованном виде. Token MUST расшифровываться только для серверного вызова T-Bank и MUST NOT передаваться в frontend, HTTP-ответах, OpenAPI examples, сообщениях ошибок или application logs.
|
||||
|
||||
#### Scenario: API не раскрывает token
|
||||
- **WHEN** User создаёт, заменяет, удаляет или получает статус подключения
|
||||
- **THEN** ни один HTTP-ответ не содержит token или его фрагмент
|
||||
|
||||
### Requirement: Устойчивость проверки T-Bank
|
||||
Система SHALL выполнять проверку token только через защищённое TLS-подключение к T-Bank. Все вызовы T-Bank MUST проходить через общий для экземпляра backend лимит, задаваемый конфигурацией и равный 5 запросам в секунду по умолчанию, с FIFO-очередью не более 50 ожидающих вызовов. Для временных ошибок система MUST выполнить не более одного повторного вызова; если проверка не завершается успешно, token MUST NOT сохраняться.
|
||||
|
||||
#### Scenario: Лимит ожидания upstream-вызовов исчерпан
|
||||
- **WHEN** 50 вызовов T-Bank уже ожидают общий лимитер
|
||||
- **THEN** следующий запрос не обращается к T-Bank и получает `503` Problem Details с code `TBANK_UNAVAILABLE`
|
||||
|
||||
#### Scenario: Временная ошибка успешно повторяется
|
||||
- **WHEN** первая проверка token завершается временной ошибкой, а единственный повтор завершается успешно
|
||||
- **THEN** система сохраняет подключение и отвечает текущим статусом
|
||||
|
||||
### Requirement: Управление подключением в настройках
|
||||
Клиент SHALL показывать в настройках статус T-Bank connection, текст о необходимости read-only T-Bank Invest token, поле token и действие подключения либо замены. Для существующего подключения клиент MUST показывать действие удаления с modal-подтверждением. Во время создания, замены или удаления все действия секции подключения и действия modal MUST быть отключены. После успешного создания или замены клиент MUST очистить поле token и обновить статус; при ошибке token MUST остаться в поле.
|
||||
|
||||
#### Scenario: Пользователь подтверждает удаление
|
||||
- **WHEN** User подтверждает удаление в modal
|
||||
- **THEN** клиент блокирует действия секции до результата и после успешного ответа показывает состояние без подключения
|
||||
|
||||
#### Scenario: Ошибка загрузки статуса
|
||||
- **WHEN** клиент не может получить статус подключения
|
||||
- **THEN** клиент показывает отдельное error-состояние с возможностью повторить запрос и не показывает форму подключения
|
||||
|
||||
#### Scenario: Ошибка проверки token в клиенте
|
||||
- **WHEN** создание или замена получает `INVALID_TBANK_TOKEN` либо `TBANK_UNAVAILABLE`
|
||||
- **THEN** клиент показывает соответственно локализованное сообщение о token и правах либо о временной недоступности T-Bank, возвращает интерактивность и сохраняет введённый token
|
||||
Reference in New Issue
Block a user