docs: archive T-Bank connection change

openspec/specs/tbank-connection/spec.md

@@ -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