196 lines
17 KiB
Markdown
196 lines
17 KiB
Markdown
## Context
|
||
|
||
`GET /api/v1/brokerage-accounts` уже разрешает текущее T-Bank connection и
|
||
поддерживаемые счета через `TbankAccessService`, сохраняя upstream-порядок и
|
||
существующее отображение публичных ошибок. Получение Portfolio использует ту
|
||
же границу доступа и рассчитывает точные итоги по каждой валюте из значений
|
||
позиций `GetPortfolio` и денежных остатков `GetPositions`. Текущая
|
||
нормализация также обогащает позиции для экрана деталей счёта, что не нужно
|
||
для сводки списка счетов.
|
||
|
||
Frontend уже потребляет сгенерированный OpenAPI-тип через один
|
||
аутентифицированный React Query hook с 60-секундной политикой актуальности. Его
|
||
page VM сохраняет успешный query snapshot во время фонового refetch и выбирает
|
||
известные error-состояния списка. Сейчас entity рендерит двухколоночную
|
||
коллекцию ссылок только с метаданными счета. Новый контракт должен сохранить
|
||
существующую семантику connection, query, навигации и клавиатуры, обогащая
|
||
каждый элемент без представления разных валют как единого значения.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- Расширить существующий контракт списка явной nullable-сводкой Portfolio для
|
||
каждого счёта, сохранив policy доступа к счетам и upstream-порядок.
|
||
- Переиспользовать точный сохраняющий валюты расчёт итогов Portfolio и для
|
||
snapshot деталей, и для сводок списка без работы с метаданными позиций.
|
||
- Локализовать временный upstream-сбой на сводке затронутого счёта, сохранив
|
||
установленную семантику ошибок connection и token на уровне списка.
|
||
- Сохранить существующий 60-секундный React Query-кэш и policy Client Cached
|
||
Snapshot, выражая состояния сводки через текущую границу page VM и
|
||
presentation.
|
||
- Обновить as-built документацию только после проверки поставленного поведения.
|
||
|
||
**Non-Goals:**
|
||
|
||
- FX-conversion, межвалютный или межсчётный агрегат, отдельное отображение Cash
|
||
Balance, сортировка/фильтрация/настройки списка или постоянное хранение
|
||
Portfolio.
|
||
- Переработка Portfolio на странице деталей счёта, управления T-Bank
|
||
connection, resilience policy T-Bank client или глобальной frontend fetch
|
||
policy.
|
||
|
||
## Decisions
|
||
|
||
### D1. Обогатить каждый нормализованный счёт nullable-сводкой на существующей границе списка
|
||
|
||
`TbankAccessService` продолжит владеть разрешением current connection, policy
|
||
поддерживаемых счетов, обработкой token и начальным вызовом `GetAccounts`.
|
||
Поток списка сделает разрешённый token и ID поддерживаемых upstream-счетов
|
||
доступными `BrokerageAccountsService`, который сохранит ответственность за
|
||
формирование ответа списка. Для каждого поддерживаемого счёта он параллельно
|
||
запросит два upstream-входа Portfolio и сохранит нормализованный счёт на его
|
||
исходной позиции.
|
||
|
||
Работа по каждому счёту будет собрана без изменения порядка счетов. Результат
|
||
`TBANK_UNAVAILABLE` любого из входов сводки создаёт `portfolioSummary: null`
|
||
только для этого счёта. Начальное разрешение connection, обнаружение счетов,
|
||
перевод invalid-token и непредвиденные ошибки сохраняют текущее поведение
|
||
Problem Details на уровне списка; они не превращаются молча в частичный успех.
|
||
|
||
*Альтернатива:* вызывать public Portfolio service страницы деталей для каждого
|
||
счёта. Отклонено, поскольку это свяжет список с cache snapshot деталей,
|
||
семантикой timestamp и stale-fallback и вызовет нерелевантное обогащение
|
||
метаданных Instrument.
|
||
|
||
*Альтернатива:* делать любую неуспешную сводку ошибкой списка. Отклонено,
|
||
поскольку это противоречит требуемому поведению частичной доступности и
|
||
скрывает в ином случае доступную навигацию к счёту.
|
||
|
||
### D2. Извлечь общий normalizer точных итогов, а не вторую модель Portfolio
|
||
|
||
Небольшой backend-owned normalizer примет upstream-значения позиций и денежные
|
||
остатки и вернёт итоги `Money[]`, сгруппированные по нормализованной исходной
|
||
валюте. Он сохранит существующую decimal-арифметику и правила включения:
|
||
нулевые значения или значения без валюты исключаются; валидные текущие
|
||
значения позиций и Cash Balance в одной валюте точно складываются;
|
||
FX-conversion не выполняется. Portfolio service деталей использует helper при
|
||
формировании существующего snapshot, а поток списка обернёт тот же результат
|
||
как `{ totalsByCurrency }`.
|
||
|
||
Это сохраняет денежный инвариант в одном месте и устраняет зависимость от
|
||
маппинга позиций Portfolio, запросов метаданных, timestamp или cache-поведения.
|
||
Пустой успешный upstream Portfolio становится пустым массивом итогов и,
|
||
следовательно, доступной non-null сводкой списка.
|
||
|
||
*Альтернатива:* дублировать текущий aggregation loop в service списка.
|
||
Отклонено, поскольку две реализации точных денежных расчётов могут разойтись
|
||
на edge cases денежных остатков или валют.
|
||
|
||
*Альтернатива:* возвращать в списке полный `PortfolioDto`. Отклонено, поскольку
|
||
контракт списка не требует ни позиций, ни метаданных snapshot/cache и раскроет
|
||
избыточно дорогой payload.
|
||
|
||
### D3. Сделать OpenAPI DTO и generated client единственным транспортным изменением
|
||
|
||
`BrokerageAccountDto` получает nullable `portfolioSummary`, единственное поле
|
||
которой — `totalsByCurrency: MoneyDto[]`. Swagger/OpenAPI описывает эту форму,
|
||
после чего frontend snapshot и generated types обновляются установленным
|
||
workflow runtime contract. Frontend-код продолжает выводить тип счёта из
|
||
сгенерированных `paths`, не создавая параллельный transport interface.
|
||
|
||
Это совместимое аддитивное изменение ответа, но оно остаётся изменением
|
||
публичного контракта и требует cross-repository gate runtime/OpenAPI.
|
||
|
||
### D4. Сохранить query-поведение списка; подготовить представление карточек в page VM
|
||
|
||
Существующие query key brokerage-account, 60-секундный `staleTime`, policy без
|
||
retry и invalidation после замены/удаления T-Bank connection не изменяются.
|
||
Accounts page VM сохранит текущее top-level выделение loading/error/empty/loaded
|
||
и поведение cached snapshot. Он подготовит ограниченную display model каждой
|
||
карточки из generated account: не более двух итогов исходных валют и явный
|
||
счётчик/индикатор остальных валют либо раздельные локальные состояния
|
||
недоступной и пустой сводки.
|
||
|
||
Presentation component списка счетов станет одноколоночной последовательностью
|
||
широких карточек-ссылок. Каждая ссылка сохраняет навигацию по всей карточке и
|
||
native keyboard focus и показывает локализованные тип, имя, сводку, вторичные
|
||
метаданные даты открытия и видимое действие открытия. Presentation-код
|
||
форматирует одно переданное значение Money существующим shared formatter; он
|
||
не агрегирует и не конвертирует значения.
|
||
|
||
*Альтернатива:* рассчитывать видимые два итога в entity view. Отклонено,
|
||
поскольку выбор и подсчёт значений из коллекции — derived presentation data,
|
||
принадлежащие page VM согласно frontend VM boundary.
|
||
|
||
*Альтернатива:* ввести новый client cache или независимо получать Portfolio
|
||
каждого счёта. Отклонено, поскольку обогащённый endpoint списка уже передаёт
|
||
нужное компактное наблюдение, а отдельные query добавят fan-out, loading states
|
||
и пути invalidation.
|
||
|
||
## Delivery Map
|
||
|
||
| Area | Status | Architectural outcome or N/A reason |
|
||
| --- | --- | --- |
|
||
| frontend | `affected` | Regenerated list response type, существующие query policy/invalidation, page VM card display models и доступные одноколоночные summary cards реализуют обогащённые состояния списка. |
|
||
| backend | `affected` | Существующая account access boundary поставляет поддерживаемые счета; общий normalizer точных итогов Portfolio и orchestration списка формируют сводки по каждому счёту с локальной обработкой upstream-недоступности и аддитивным DTO. |
|
||
| specs | `affected` | Этот change хранит утверждённые Proposal, Delta Specs, Design и последующие implementation Tasks в canonical store. |
|
||
| docs | `affected` | После поставки as-built Brokerage Accounts и релевантная system documentation описывают фактический обогащённый контракт списка, частичную доступность сводки и неизменную границу наблюдения current connection. |
|
||
|
||
### Contract Gate Decision
|
||
|
||
| Gate | Status | Reason |
|
||
| --- | --- | --- |
|
||
| runtime-openapi | `required` | Backend изменяет публичный ответ списка, а frontend потребляет его generated OpenAPI snapshot. |
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **Upstream fan-out растёт с количеством поддерживаемых счетов.** Список
|
||
выполняет два Portfolio RPC на счёт, но использует существующие client-wide
|
||
rate limiter, deadline и retry policy вместо создания другого механизма
|
||
concurrency. Временно недоступная отдельная сводка деградирует локально.
|
||
- **Расхождение агрегатов сводки и деталей.** Общая точная нормализация и
|
||
фокусированные money tests исключают разную обработку Cash Balance, нулевых
|
||
сумм и исходных валют.
|
||
- **Частичный ответ может скрыть невалидные учётные данные.** Локальным для
|
||
сводки является только известный результат недоступности; token и другие
|
||
сбои уровня списка проходят через существующий error translation.
|
||
- **Широкие карточки могут стать хуже для сканирования на малых экранах.**
|
||
Одноколоночный layout сохраняет компактные вторичные метаданные, ограничивает
|
||
отображаемые валюты двумя и явно обозначает пропущенные.
|
||
- **Кэшированные данные могут быть временно устаревшими.** Это сохраняет
|
||
установленный trade-off 60-секундного Client Cached Snapshot: фоновое
|
||
обновление и его предупреждение остаются видимыми, а известные данные не
|
||
очищаются.
|
||
|
||
## Migration Plan
|
||
|
||
1. Добавить компактный summary DTO и разделить точную нормализацию итогов
|
||
Portfolio между существующим потоком деталей и обогащённым потоком списка
|
||
счетов.
|
||
2. Расширить orchestration списка для получения сводок внутри существующей
|
||
T-Bank access и resilience boundary, сохранив порядок счетов и отображая в
|
||
`null` только недоступность отдельного счёта.
|
||
3. Перегенерировать frontend OpenAPI snapshot/types из работающего backend и
|
||
пройти runtime contract gate.
|
||
4. Адаптировать существующие consumer account query, page VM, карточки,
|
||
переводы и risk-based tests, сохранив loading, error, empty, cache и
|
||
invalidation behavior.
|
||
5. После проверки реализации обновить as-built feature/system documentation
|
||
до поставленных контракта и поведения.
|
||
|
||
### Rollback Contract
|
||
|
||
| Field | Decision |
|
||
| --- | --- |
|
||
| Status | `required` |
|
||
| Reason | Аддитивное поле ответа — публичный API contract, потребляемый frontend. |
|
||
| Trigger | Release-blocking defect в доступности списка счетов, точности денежной сводки или совместимости с generated client. |
|
||
| Actions | Одновременно откатить frontend consumption и backend additive summary/DTO; перед выпуском откатываемой пары перегенерировать и закоммитить соответствующий frontend OpenAPI snapshot. |
|
||
| Data safety | Schema, persisted Portfolio, Brokerage Account или данные владения не создаются и не мутируют; rollback лишь убирает из ответа текущее upstream-наблюдение. |
|
||
| Verification | Запустить canonical gates затронутых backend и frontend, а также runtime OpenAPI gate против откатанного контракта; проверить, что список сохраняет прежние метаданные, навигацию и error states. |
|
||
|
||
## Open Questions
|
||
|
||
<!-- none -->
|