8.5 KiB
8.5 KiB
Documentation Impact
Summary
Durable AS-IS documentation requires updates. The current pages still describe
request-driven freshness, screen-started work, and legacy sync metadata;
after delivery they must describe the hourly owner, local resource reads, and
the independent resource-result and hourly-attempt state.
Documentation Changes
| Action | Target | Category | Resulting AS-IS | Source | Verification |
|---|---|---|---|---|---|
| update | architecture/cross-cutting/data-freshness.md |
cross-cutting | Ordinary personal-resource GETs and HTTP retries read saved local results and never start personal T-Bank work. The hourly walk is the normal update owner; only an unconfirmed historical ledger interval and an unopened candle range may acquire their own missing result. Document the independent data freshness, completeness, lastSuccessfulAt, availability, and resource-relevant last hourly attempt; retained complete data remains available after a later failed or partial attempt, while no complete result is data: null. Keep Client Cached Snapshot, Portfolio.isStale, and failed browser rereads distinct from server result and hourly-attempt state. |
tbank-data-sync — Часовой обход владеет обновлением личных данных T-Bank; tbank-data-sync — Результат личного обновления остаётся наблюдаемым; System Analysis §§ Interaction Flows, Data and State Semantics, Error and Recovery Semantics, Observability Semantics; Design § Cross-cutting Implementation. |
Compare the page with delivered resource responses and UI: normal GET/retry has no upstream personal call; documented state meanings match generated OpenAPI/runtime responses; stale fallback, no-result state, client read failure, and hourly failure remain separately explained. |
| update | domains/portfolio/flows/portfolio-loading.md |
domain | Portfolio loading reads the saved current-connection snapshot through a read-only envelope. The hourly walk refreshes Portfolio independently of the screen; the open screen's 30-minute reread and retry are local HTTP reads only. The page explains data: null before a complete snapshot, preserved snapshot/time after a failed or partial walk, separate resource metadata and Portfolio.isStale, and current-connection/revision disclosure fences without a manual refresh or status-observer flow. |
portfolio-view — Получение Portfolio выбранного Brokerage Account; portfolio-view — Свежесть и fallback полного Portfolio Snapshot; frontend-data-resilience — Client Cached Snapshot остаётся доступным при обновлении Accounts и Portfolio; System Analysis §§ Contracts, Data and State Semantics, Error and Recovery Semantics; Design § Frontend: one query cache and metadata-aware screen state. |
Read the delivered Portfolio route and screen against the page: GET and retry do not call T-Bank or expose a manual sync action; snapshot fallback retains its original time; no-data, empty, stale, failed hourly attempt, and failed HTTP reread are not conflated. |
| update | domains/income/upcoming-events.md |
domain | Upcoming events reads the saved forecast for account or all scope without starting personal sync. It documents strict inclusive UTC request dates, defaults, filtering to the intersection with the forecast's original inclusive window, and retention of that forecast's calculatedAt and source window. A later failed hourly events update leaves the last complete forecast readable and reports its failure independently; absent complete forecast is data: null, while an empty intersection is a successful empty result. |
brokerage-account-upcoming-events — User can retrieve upcoming events for an account; brokerage-account-upcoming-events — Upcoming events use complete source results; System Analysis § Contracts; System Analysis §§ Data and State Semantics, Error and Recovery Semantics; QA Analysis § Coverage Matrix: Events query and saved forecast. |
Compare account and all responses/screens with the page: invalid range returns INVALID_EVENTS_PERIOD without source work; window intersection preserves original forecast metadata; empty intersection and failed-refresh fallback are correctly distinguished. |
| update | architecture/http-api.md |
architecture | The investment API section describes the generated backend OpenAPI as the executable contract for { data, meta } resource responses: nullable data; required independent resource-result meanings; resource-scoped hourly lastAttempt; and Accounts-only connection-wide sync. It states that legacy sync=observe may remain a read-observation compatibility parameter but cannot start source work, removes the request-started screen-sync command/status model as current AS-IS, and retains established route identities and Problem Details behavior. |
System Analysis §§ Contracts, Compatibility / Migration; tbank-data-sync — Результат личного обновления остаётся наблюдаемым; hourly-investment-sync — Последний результат обхода доступен только для наблюдения; Design § Contract: Swagger is produced at the DTO boundary; QA Analysis §§ Cross-system Verification, Regression Impact. |
Compare prose and examples with the backend-generated OpenAPI and runtime responses: affected envelopes expose target nullability/enums and required metadata, only Accounts has top-level sync, and ordinary reads cannot trigger personal work. |
| update | adr/017-local-tbank-reads-and-background-sync.md |
ADR | Preserve ADR 017's historical decision and rationale, but mark its request-driven, manual-refresh, and no-periodic-walk decisions superseded by ADR 019. Retain its still-valid local-storage, completeness, and access-boundary context, with a link to current freshness documentation. | System Analysis § Durable Documentation Candidates; Proposal § Why; Design § Risks / Trade-offs. | ADR 017 explicitly identifies superseded decisions and links to ADR 019; it no longer presents a manual/request-driven sync model as current architecture. |
| update | adr/019-hourly-reads-and-online-instrument-reference.md |
ADR | Clarify the accepted hourly architecture: the last walk is scoped to the current connection; ordinary GET/retry does not acquire personal data; only the first unconfirmed ledger interval and first unopened candle range are narrow acquisition exceptions. Clarify that resource-result state and hourly-attempt state remain independent and that observation is not a command. | System Analysis §§ Interaction Flows, Contracts, Observability Semantics; tbank-data-sync — Часовой обход владеет обновлением личных данных T-Bank; hourly-investment-sync — Последний результат обхода доступен только для наблюдения; Design § Cross-cutting Implementation. |
ADR 019 describes only the delivered hourly model and its bounded exceptions; it agrees with the updated freshness page and does not introduce a second HTTP contract source. |
Diagram Promotion
None. system-analysis/sequences/hourly-investment-walk.mmd and
system-analysis/sequences/read-only-resource-get.mmd are approval-time
interaction evidence. Their durable operational meaning is covered by the
updated freshness, portfolio-loading, events, and HTTP API pages; promoting
them would duplicate those explanations without adding a durable navigation or
architecture view.
ADR Decision
N/A. No new architectural decision is required: ADR 019 already accepts the durable hourly-read architecture and is clarified above. ADR 017 is an historical decision whose conflicting request-driven/manual-refresh portions must be explicitly superseded, not rewritten into a new decision.
Glossary / Navigation Impact
N/A. The change refines existing concepts (freshness, completeness, Client Cached Snapshot, Portfolio snapshot, and T-Bank connection) rather than adding a durable term needing a glossary definition or a new navigation entry.
No-Change Rationale
No new documentation page, diagram, or machine-readable HTTP artifact is promoted. Backend-generated OpenAPI remains the executable HTTP contract; the change-local schema and sequences remain archived planning evidence. No docs entry is planned for private retained portfolio-value history because this change does not introduce a public history read, and its access boundary is already covered by the connection/freshness documentation.