docs: describe quiet reading and visible source state (#51) #52

2026-10-17T22:10:24+03:00

codex-bot commented

2026-10-17 22:10:24 +03:00

Summary

Приводит документацию к фактическому поведению: автоматическое чтение клиента не сообщает о себе, а состояние источника из meta остаётся видимым. Решение реализовано во frontend коммитами 5b30bb8 и 3c226f8, спецификации приняты в WealthLedger/specs#51.

Linked Issue

#51

Changes

Новый adr/021-quiet-reading-and-rare-confirmations.md — Accepted, заменяет manual-refresh часть ADR 019 на стороне интерфейса и уточняет клиентскую часть ADR 007. Context, Decision (6 пунктов), Consequences. Внесён в adr/README.md.

Приведены к AS-IS:

Файл	Что исправлено
`architecture/cross-cutting/ui-resilience.md`	фоновое чтение без индикации и предупреждения; нет ручного обновления и повтора; видимое состояние источника; ограниченное первичное ожидание; navigation actions сохранены
`domains/accounts/overview.md`	`503` и неизвестная ошибка — спокойное состояние без действия повтора
`domains/income/overview.md`	ошибка даёт локальную недоступность без повтора; фоновое обновление без индикатора и предупреждения
`domains/instruments/bonds.md`	разделы показывают спокойное состояние без повторной попытки
`domains/instruments/stocks.md`	нет действия «Обновить»; ошибка поиска сообщается, повтор — обычным «Найти»; неполнота вместо предупреждения
`domains/portfolio/overview.md`	клиентская ошибка о себе не сообщает; видимо состояние источника
`domains/portfolio/how-to/investigate-discrepancy.md`	расхождение проверяется по состоянию источника, а не по результату ручного обновления

adr/017-local-tbank-reads-and-background-sync.md не правился: он помечен историческим и заменён ADR 019/021, его описание кнопки «Обновить» корректно для своего периода.

architecture/cross-cutting/data-freshness.md не правился: он описывает семантику meta и серверную сторону, устаревших утверждений о клиентском UI не содержит.

Основание

Проверено по frontend/origin/develop, а не по текстам:

$ git grep -nE 'investment\.refresh|events\.retry|accounts\.retry' -- 'src/pages/**' | wc -l
0
$ grep -cE 'Button|onClick' src/shared/ui/SourceSyncStatus/SourceSyncStatus.tsx
0
$ grep -cE 'sourceTime|attempt\.' src/shared/ui/SourceSyncStatus/SourceSyncStatus.tsx
3
$ grep -nE 'GET_DEADLINE_MS|RETRY_DELAYS_MS' src/shared/api/client.ts
15:const GET_DEADLINE_MS = 15_000;
18:const RETRY_DELAYS_MS = [FIRST_RETRY_DELAY_MS, SECOND_RETRY_DELAY_MS] as const;
$ grep -n 'INITIAL_WAIT_BUDGET_MS' src/shared/lib/initial-availability.ts
3:const INITIAL_WAIT_BUDGET_MS = 10_000;

AccountsPageError.view.tsx для 503 и неизвестной ошибки отдаёт StateView без action; AccountIncomePageError.view.tsx — без кнопок; на страницах stock и bond кнопок нет вовсе. Сохранившиеся Alert относятся к неполноте данных и устареванию позиции, а не к процессу чтения.

Verification

Команда	Результат
`npm run verify`	exit 0 — markdownlint с relative-links и якорями, затем `git diff --check`; новый файл охвачен
`npx commitlint --from HEAD~1 --to HEAD`	exit 0
Ручная проверка ссылок ADR 021	4/4 существуют; обратная ссылка из `ui-resilience.md` существует
Маршрут «разработчик → вопрос → объяснение → требование»	ADR 021 → `ui-resilience.md` → спецификации

Ограничения: Mermaid-рендер в gate не входит, диаграммы этим PR не добавлялись. Внешние URL правилом не проверяются. Gates соседних репозиториев не запускались — изменение только в docs.

Breaking Changes

Нет. Поведение приложения не меняется, документация приводится к уже реализованному.

## Summary Приводит документацию к фактическому поведению: автоматическое чтение клиента не сообщает о себе, а состояние источника из `meta` остаётся видимым. Решение реализовано во `frontend` коммитами `5b30bb8` и `3c226f8`, спецификации приняты в `WealthLedger/specs#51`. ## Linked Issue #51 ## Changes **Новый `adr/021-quiet-reading-and-rare-confirmations.md`** — Accepted, заменяет manual-refresh часть ADR 019 на стороне интерфейса и уточняет клиентскую часть ADR 007. Context, Decision (6 пунктов), Consequences. Внесён в `adr/README.md`. Приведены к AS-IS: | Файл | Что исправлено | | --- | --- | | `architecture/cross-cutting/ui-resilience.md` | фоновое чтение без индикации и предупреждения; нет ручного обновления и повтора; видимое состояние источника; ограниченное первичное ожидание; navigation actions сохранены | | `domains/accounts/overview.md` | `503` и неизвестная ошибка — спокойное состояние без действия повтора | | `domains/income/overview.md` | ошибка даёт локальную недоступность без повтора; фоновое обновление без индикатора и предупреждения | | `domains/instruments/bonds.md` | разделы показывают спокойное состояние без повторной попытки | | `domains/instruments/stocks.md` | нет действия «Обновить»; ошибка поиска сообщается, повтор — обычным «Найти»; неполнота вместо предупреждения | | `domains/portfolio/overview.md` | клиентская ошибка о себе не сообщает; видимо состояние источника | | `domains/portfolio/how-to/investigate-discrepancy.md` | расхождение проверяется по состоянию источника, а не по результату ручного обновления | `adr/017-local-tbank-reads-and-background-sync.md` **не правился**: он помечен историческим и заменён ADR 019/021, его описание кнопки «Обновить» корректно для своего периода. `architecture/cross-cutting/data-freshness.md` не правился: он описывает семантику `meta` и серверную сторону, устаревших утверждений о клиентском UI не содержит. ## Основание Проверено по `frontend/origin/develop`, а не по текстам: ``` $ git grep -nE 'investment\.refresh|events\.retry|accounts\.retry' -- 'src/pages/**' | wc -l 0 $ grep -cE 'Button|onClick' src/shared/ui/SourceSyncStatus/SourceSyncStatus.tsx 0 $ grep -cE 'sourceTime|attempt\.' src/shared/ui/SourceSyncStatus/SourceSyncStatus.tsx 3 $ grep -nE 'GET_DEADLINE_MS|RETRY_DELAYS_MS' src/shared/api/client.ts 15:const GET_DEADLINE_MS = 15_000; 18:const RETRY_DELAYS_MS = [FIRST_RETRY_DELAY_MS, SECOND_RETRY_DELAY_MS] as const; $ grep -n 'INITIAL_WAIT_BUDGET_MS' src/shared/lib/initial-availability.ts 3:const INITIAL_WAIT_BUDGET_MS = 10_000; ``` `AccountsPageError.view.tsx` для `503` и неизвестной ошибки отдаёт `StateView` без `action`; `AccountIncomePageError.view.tsx` — без кнопок; на страницах stock и bond кнопок нет вовсе. Сохранившиеся `Alert` относятся к неполноте данных и устареванию позиции, а не к процессу чтения. ## Verification | Команда | Результат | | --- | --- | | `npm run verify` | exit 0 — markdownlint с relative-links и якорями, затем `git diff --check`; новый файл охвачен | | `npx commitlint --from HEAD~1 --to HEAD` | exit 0 | | Ручная проверка ссылок ADR 021 | 4/4 существуют; обратная ссылка из `ui-resilience.md` существует | | Маршрут «разработчик → вопрос → объяснение → требование» | ADR 021 → `ui-resilience.md` → спецификации | Ограничения: Mermaid-рендер в gate не входит, диаграммы этим PR не добавлялись. Внешние URL правилом не проверяются. Gates соседних репозиториев не запускались — изменение только в `docs`. ## Breaking Changes Нет. Поведение приложения не меняется, документация приводится к уже реализованному.

codex-bot added 1 commit 2026-10-17 22:10:24 +03:00

docs: describe quiet reading and visible source state (#51 )

Conventional commits / commits (pull_request) Successful in 12s

Details

Docs security / security (pull_request) Successful in 7s

Details

Docs verify / verify (pull_request) Successful in 13s

Details

174fbf01c3

ADR 021 фиксирует решение: автоматическое чтение клиента не сообщает
о себе, состояние источника из meta остаётся видимым, ошибки явных
действий пользователя сохраняются.

Приведены к AS-IS: ui-resilience, accounts, income, bonds, stocks,
portfolio overview и how-to. ADR 017 не правился — он помечен
историческим и заменён ADR 019/021.

codex-bot added the Kind/Documentation

Priority

Medium

3

labels 2026-10-17 22:10:44 +03:00

hermes-agent was assigned by codex-bot

2026-10-17 22:10:45 +03:00

codex-bot merged commit e8e3ef6285 into develop

2026-10-17 22:11:50 +03:00

codex-bot referenced this pull request

2026-10-17 22:12:33 +03:00

docs: align UI resilience and freshness docs with quiet reading #51