specs/openspec/changes/archive/2026-10-09-reconcile-hourly-investment-sync/tasks.md

Tasks

1. Backend runtime and published contract

• 1.1 [backend] Привести durable hourly walk, connection-revision fence и локальные resource readers к утверждённой модели: только hourly owner для обычного обновления, узкие first-load исключения, сохранение complete fallback и изолированное наблюдение resource/connection attempt.

  • Covers: tbank-data-sync — Часовой обход владеет обновлением личных данных T-Bank; hourly-investment-sync — Часовой обход личных инвестиционных данных; hourly-investment-sync — Последний результат обхода доступен только для наблюдения; brokerage-account-ledger — Отсутствующий исторический интервал загружается только впервые; portfolio-view — Свежесть и fallback полного Portfolio Snapshot; portfolio-value-history — Полные оценки Portfolio сохраняются как история; portfolio-value-history — История оценки скрыта вне подтверждённого доступа; online-instrument-information — Справочные сведения и поиск инструментов получают онлайн; tbank-connection — Создание и замена подключения T-Bank; tbank-connection — Удаление подключения T-Bank
  • Source: System Analysis §§ Interaction Flows, Data and State Semantics, Error and Recovery Semantics, Observability Semantics, Security and NFR at System Boundaries; Design §§ Backend: retain storage owners and publication fences, Data / Storage Changes, Developer Verification Strategy; QA Analysis §§ Coverage Matrix, Cross-system Verification.
  • Verification: Run the backend's relevant runtime, SQLite/migration, controller, and E2E tests proving local ordinary GET/retry has no personal upstream call; hourly cadence and dropped overlaps; narrow first-load acquisition; persisted fallback/partial results; connection replacement/deletion fences; events windows; and no token or internal details in observable status.
  • Depends on: none

• 1.2 [backend] Replace the shared investment resource DTO/mapper and endpoint responses with the target { data, meta } projection, Accounts-only connection sync, then regenerate the backend OpenAPI from Swagger annotations.

  • Covers: tbank-data-sync — Результат личного обновления остаётся наблюдаемым; brokerage-accounts — Список активных брокерских счетов; brokerage-accounts — Состояния недоступности списка счетов; portfolio-view — Получение Portfolio выбранного Brokerage Account; portfolio-view — Свежесть и fallback полного Portfolio Snapshot; brokerage-account-upcoming-events — User can retrieve upcoming events for an account; brokerage-account-upcoming-events — Forecasts preserve event meaning and uncertainty; brokerage-account-upcoming-events — Upcoming events use complete source results
  • Source: System Analysis §§ Contracts, Compatibility / Migration; Design §§ Backend: one resource-meta projection and one connection-walk projection, Contract: Swagger is produced at the DTO boundary, Contract Implementation; QA Analysis §§ Cross-system Verification, Regression Impact.
  • Verification: Regenerate backend openapi.json and run the backend's OpenAPI contract/type/lint tests plus runtime response tests. Confirm semantic compatibility with system-analysis/contracts/investment-resource-envelope.schema.json: nullable data; all five required meta meanings; none|running|succeeded|partial|failed; nullable attempt fields; Accounts-only nullable top-level sync; established routes and Problem Details; and sync=observe never starting source work.
  • Depends on: 1.1

2. Frontend generated consumer and states

• 2.1 [frontend] Receive the published backend OpenAPI snapshot and regenerate the local transport types; project its target resource envelope directly through the existing resource-query seam without handwritten parallel types or compatibility normalization.

  • Covers: tbank-data-sync — Результат личного обновления остаётся наблюдаемым; brokerage-accounts — Список активных брокерских счетов; portfolio-view — Получение Portfolio выбранного Brokerage Account; brokerage-account-upcoming-events — User can retrieve upcoming events for an account
  • Source: System Analysis § Compatibility / Migration; Design §§ Contract: Swagger is produced at the DTO boundary, Frontend: one query cache and metadata-aware screen state; QA Analysis §§ Cross-system Verification, Regression Impact.
  • Verification: Run openapi:check and the frontend typecheck; verify the committed generated snapshot is the backend-published artifact and generated types expose nullable data, required target metadata, and Accounts-only sync.
  • Depends on: 1.2

• 2.2 [frontend] Update Accounts, Portfolio, operations, and events query owners, page VMs, and views to render the five metadata meanings and separate server attempt, server stale, and client HTTP-read states; retain successful snapshots, keep retry/reread HTTP-only, and preserve access invalidation.

  • Covers: frontend-data-resilience — Client Cached Snapshot остаётся доступным при обновлении Accounts и Portfolio; brokerage-accounts — Экран списка брокерских счетов; brokerage-accounts — Клиентские состояния ошибки списка счетов; portfolio-view — Состояния и ошибки Portfolio на клиенте; brokerage-account-upcoming-events — Account page presents an upcoming events list; brokerage-account-upcoming-events — Account overview includes upcoming events
  • Source: System Analysis §§ Error and Recovery Semantics, Observability Semantics; Design §§ Frontend: one query cache and metadata-aware screen state, UI/UX Package, Developer Verification Strategy; QA Analysis §§ Coverage Matrix: Frontend recovery and accessibility, Manual / Exploratory Scope.
  • Verification: Run frontend unit/component tests and configured UI checks covering no automatic retry, retry as GET only, 30-minute reread, cache retention after background error, connection invalidation, no-data/empty/loaded states, distinct stale/attempt/transport warnings, keyboard-accessible status text, and narrow viewport wrapping.
  • Depends on: 2.1

3. Durable AS-IS documentation

• 3.1 [docs] Update architecture/cross-cutting/data-freshness.md with the approved hourly-owner, local-read, first-load-exception, and independent resource/attempt/client-state model.

  • Covers: N/A — approved documentation promotion; no additional product behavior.
  • Source: Docs Impact § Documentation Changes: architecture/cross-cutting/data-freshness.md.
  • Verification: Compare the page against delivered runtime responses and UI: ordinary GET/retry has no personal upstream call; target generated-contract meanings, stale fallback, no-result, client read failure, and hourly failure remain distinct.
  • Depends on: 1.2, 2.2

• 3.2 [docs] Update domains/portfolio/flows/portfolio-loading.md with read-only saved snapshot loading, 30-minute local rereads, fallback semantics, and connection/revision disclosure fences.

  • Covers: N/A — approved documentation promotion; no additional product behavior.
  • Source: Docs Impact § Documentation Changes: domains/portfolio/flows/portfolio-loading.md.
  • Verification: Compare the page with the delivered Portfolio route and screen: GET/retry does not call T-Bank or expose manual sync; no-data, empty, stale, failed hourly attempt, and failed HTTP reread remain distinct.
  • Depends on: 1.2, 2.2

• 3.3 [docs] Update domains/income/upcoming-events.md with saved forecast window intersection, calculatedAt, independent failed-update state, and empty/no-result semantics.

  • Covers: N/A — approved documentation promotion; no additional product behavior.
  • Source: Docs Impact § Documentation Changes: domains/income/upcoming-events.md.
  • Verification: Compare the page with delivered account and all events responses/screens: invalid periods return INVALID_EVENTS_PERIOD without source work, window intersection preserves forecast metadata, and empty intersection differs from failed-refresh fallback.
  • Depends on: 1.2, 2.2

• 3.4 [docs] Update the investment section of architecture/http-api.md to identify backend-generated OpenAPI as the executable { data, meta } contract and remove the request-started screen-sync model from AS-IS guidance.

  • Covers: N/A — approved documentation promotion; no additional product behavior.
  • Source: Docs Impact § Documentation Changes: architecture/http-api.md.
  • Verification: Compare prose and examples with the backend-generated OpenAPI and runtime responses: target nullability/enums and required metadata match, only Accounts has top-level sync, and ordinary reads cannot trigger personal work.
  • Depends on: 1.2

• 3.5 [docs] Update adr/017-local-tbank-reads-and-background-sync.md to preserve historical context while explicitly superseding its request-driven/manual-refresh decisions through ADR 019.

  • Covers: N/A — approved documentation promotion; no additional product behavior.
  • Source: Docs Impact § Documentation Changes: adr/017-local-tbank-reads-and-background-sync.md.
  • Verification: Confirm ADR 017 explicitly identifies superseded decisions, links to ADR 019 and current freshness documentation, and no longer presents manual/request-driven sync as current architecture.
  • Depends on: 3.1, 3.6

• 3.6 [docs] Update adr/019-hourly-reads-and-online-instrument-reference.md with the current-connection-scoped hourly result, ordinary read-only GET/retry boundary, two narrow acquisition exceptions, and observation-not-command rule.

  • Covers: N/A — approved documentation promotion; no additional product behavior.
  • Source: Docs Impact § Documentation Changes: adr/019-hourly-reads-and-online-instrument-reference.md.
  • Verification: Confirm ADR 019 describes only the delivered hourly model and bounded exceptions, agrees with the updated freshness page, and does not introduce another HTTP contract source.
  • Depends on: 1.2, 2.2