spec: finalize wealth-ledger SDD migration

2026-10-09 20:41:46 +03:00
parent b24a686188
commit 13e3e53d06
97 changed files with 3444 additions and 244 deletions
@@ -0,0 +1,94 @@
+# Proposal
+
+## Why
+
+Два завершённых legacy changes описывают несовместимые модели инвестиционной
+синхронизации. `persist-tbank-data` закрепляет запуск обновления запросом и
+ручное обновление, а `hourly-portfolio-sync-history` и фактическая система
+используют часовой обход и локальные read-only GET. Пока canonical specs и
+AS-IS документация содержат обе трактовки, ни один legacy change нельзя
+безопасно синхронизировать или архивировать.
+
+## What Changes
+
+- Зафиксировать единственную observable model: часовой обход обновляет личные
+  инвестиционные данные, а обычные GET читают сохранённый результат и не
+  запускают личную синхронизацию.
+- Сохранить узкие исключения первой загрузки отсутствующего исторического
+  интервала операций и впервые открытого диапазона свечей.
+- Уточнить видимые состояния свежести, полноты, последней попытки обхода и
+  доступности личных данных после смены подключения.
+- Согласовать canonical behavior specs и durable AS-IS documentation с этой
+  моделью, не создавая ещё один current OpenAPI source of truth.
+
+## Scope
+
+### In Scope
+
+- Investment accounts, Portfolio, операции изменяемого периода, forecasts/events,
+  personal connection boundary и связанные frontend recovery states.
+- Capabilities `brokerage-accounts`, `portfolio-view`,
+  `brokerage-account-ledger`, `brokerage-account-upcoming-events`,
+  `frontend-data-resilience`, `tbank-connection` и `tbank-data-sync`.
+- Описание и compatibility guidance для `{ data, meta }` resource responses и
+  backend-generated OpenAPI как executable HTTP contract.
+- Обновление durable documentation и ADR supersession, когда это необходимо.
+
+### Out of Scope / Non-Goals
+
+- Новый способ запуска синхронизации, публичное чтение истории стоимости,
+  валютная конвертация и многопроцессный scheduler.
+- Переписывание historical legacy changes или автоматическое объявление их
+  approval/Validation успешными.
+- Новая product feature, не требуемая для согласования уже поставленного
+  поведения.
+
+## Capabilities
+
+### New Capabilities
+
+- `hourly-investment-sync`: нормативно зафиксировать текущий наблюдаемый
+  часовой обход и его статус, если capability ещё отсутствует в canonical specs.
+- `portfolio-value-history`: зафиксировать существующую историю оценок и
+  границу её видимости, если capability ещё отсутствует в canonical specs.
+- `online-instrument-information`: зафиксировать online-only справочные
+  сведения, если capability ещё отсутствует в canonical specs.
+
+### Modified Capabilities
+
+- `brokerage-accounts`: локальное чтение и результат последнего обхода.
+- `portfolio-view`: read-only GET, часовая свежесть и отсутствие ручной
+  личной синхронизации.
+- `brokerage-account-ledger`: первая загрузка отсутствующего интервала и
+  локальное чтение полного прошлого периода.
+- `brokerage-account-upcoming-events`: последний complete forecast и
+  независимое состояние ошибки обновления.
+- `frontend-data-resilience`: distinction between retrying an HTTP read and
+  starting source work.
+- `tbank-connection`: границы текущих данных и скрытая история оценок после
+  смены либо удаления подключения.
+
+## Impact
+
+Пользователь получает предсказуемое обновление инвестиций без скрытого запуска
+брокерских запросов при чтении экранов. Backend и frontend уже содержат большую
+часть целевого поведения; change формализует его, устраняет расхождения
+requirements/docs и создаёт основу для корректного завершения legacy history.
+
+## Success Criteria
+
+- Canonical specs дают один непротиворечивый ответ о владельце обновления,
+  исключениях первой загрузки и read-only GET.
+- Backend-generated OpenAPI/runtime interface семантически соответствует
+  approved target contract при затронутых HTTP resource responses.
+- AS-IS docs и ADR guidance не обещают request-driven/manual sync там, где
+  фактическая система использует hourly model.
+- Legacy `persist-tbank-data` и `hourly-portfolio-sync-history` получают
+  безопасный дальнейший путь к archival finalization без конкурирующей sync.
+
+## Assumptions / Dependencies
+
+- Часовой scheduler, local resource reads и frontend 30-minute rereads остаются
+  целевой моделью, подтверждённой Change Owner.
+- System Analysis определит точные contracts, semantics forecasts/events и
+  допустимые first-load exceptions до implementation tasks.