# 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.