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

Closed
opened 2026-10-17 21:50:30 +03:00 by codex-bot · 1 comment
Owner

Контекст

Change quiet-user-feedback реализован во frontend коммитом 5b30bb8 (2026-10-06) и его спецификации приняты в WealthLedger/specs#51. Нормативное поведение: тихое чтение клиента + видимое состояние источника — на экранах просмотра нет кнопок «Обновить»/«Повторить», индикаторов фонового чтения и технических предупреждений о собственном чтении, но время последнего успеха источника, устаревание, исход часовой попытки и неполнота показываются.

Документация описывает отменённое поведение. Проверено на origin/develop:

$ git show origin/develop:architecture/cross-cutting/ui-resilience.md | grep -niE 'ручн|предупрежд'
31:Ручное обновление сохраняет показанный результат и applied filters; кнопка
42:портфель с предупреждением. Он не превращается в глобальный fallback.

Файлы с описанием ручного обновления или обязательных предупреждений:

$ git grep -lniE 'ручн(ое|ого) обновлен|кнопк[аи] .?Обновить|предупрежден' origin/develop -- 'domains/**' 'architecture/**'
architecture/cross-cutting/ui-resilience.md
domains/income/overview.md
domains/instruments/stocks.md
domains/portfolio/how-to/investigate-discrepancy.md
domains/portfolio/overview.md

ADR о решении тоже отсутствует — последний релевантный adr/019-hourly-reads-and-online-instrument-reference.md, записи про тихое чтение нет:

$ git grep -lniE 'тих(ое|ого) чтени|quiet read|редкие уведомлен' origin/develop
(пусто)

Ожидаемое поведение

docs/ описывают фактическое AS-IS поведение: тихое чтение, ограниченное автоматическое восстановление, первичная недоступность вместо бесконечной загрузки, видимое состояние источника. Решение зафиксировано в ADR со связью с предыдущим решением о background sync.

Scope

In scope

  • ADR о тихом чтении и редких уведомлениях: причины, альтернативы, последствия, связь с adr/017-local-tbank-reads-and-background-sync.md и adr/019.
  • architecture/cross-cutting/ui-resilience.md и data-freshness.md — убрать обязательные предупреждения и ручное обновление, объяснить автоматическое восстановление и первичную недоступность.
  • Предметные описания в domains/**, затронутые изменёнными состояниями: income, instruments, portfolio.

Out of scope

  • Поведение приложения: оно уже реализовано и этой Issue не меняется.
  • Ошибки явных действий пользователя: они сохраняются и остаются видимыми, их описание не трогаем.
  • Состояние источника из meta — остаётся документированным как есть.

Acceptance Criteria

  • ADR о тихом чтении существует, пронумерован по порядку и связан с предыдущими решениями о background sync.
  • ui-resilience.md и data-freshness.md не описывают ручное обновление и обязательные предупреждения о собственном чтении как текущее поведение.
  • Затронутые domains/** согласованы с тихим UI; правятся только фрагменты об изменённых состояниях и recovery.
  • Описание состояния источника сохранено и не противоречит frontend-data-resilience.
  • npm run verify и git diff --check проходят; относительные ссылки целы.

Dependencies

Блокирует archive change quiet-user-feedback — WealthLedger/specs#50. По lifecycle spec archive отклоняется, пока affected delivery area не реализована, а docs входит в его tasks 8.1–8.4.

Verification

npm run verify
git grep -lniE 'ручн(ое|ого) обновлен|кнопк[аи] .?Обновить' -- 'domains/**' 'architecture/**'

Ограничение: tasks 8.1–8.4 в quiet-user-feedback/tasks.md отмечены выполненными, но фактически в docs не выполнены. Это расхождение отметки и факта; статус tasks исправляется вместе с этой работой.

## Контекст Change `quiet-user-feedback` реализован во `frontend` коммитом `5b30bb8` (2026-10-06) и его спецификации приняты в `WealthLedger/specs#51`. Нормативное поведение: **тихое чтение клиента + видимое состояние источника** — на экранах просмотра нет кнопок «Обновить»/«Повторить», индикаторов фонового чтения и технических предупреждений о собственном чтении, но время последнего успеха источника, устаревание, исход часовой попытки и неполнота показываются. Документация описывает отменённое поведение. Проверено на `origin/develop`: ``` $ git show origin/develop:architecture/cross-cutting/ui-resilience.md | grep -niE 'ручн|предупрежд' 31:Ручное обновление сохраняет показанный результат и applied filters; кнопка 42:портфель с предупреждением. Он не превращается в глобальный fallback. ``` Файлы с описанием ручного обновления или обязательных предупреждений: ``` $ git grep -lniE 'ручн(ое|ого) обновлен|кнопк[аи] .?Обновить|предупрежден' origin/develop -- 'domains/**' 'architecture/**' architecture/cross-cutting/ui-resilience.md domains/income/overview.md domains/instruments/stocks.md domains/portfolio/how-to/investigate-discrepancy.md domains/portfolio/overview.md ``` ADR о решении тоже отсутствует — последний релевантный `adr/019-hourly-reads-and-online-instrument-reference.md`, записи про тихое чтение нет: ``` $ git grep -lniE 'тих(ое|ого) чтени|quiet read|редкие уведомлен' origin/develop (пусто) ``` ## Ожидаемое поведение `docs/` описывают фактическое AS-IS поведение: тихое чтение, ограниченное автоматическое восстановление, первичная недоступность вместо бесконечной загрузки, видимое состояние источника. Решение зафиксировано в ADR со связью с предыдущим решением о background sync. ## Scope ### In scope - ADR о тихом чтении и редких уведомлениях: причины, альтернативы, последствия, связь с `adr/017-local-tbank-reads-and-background-sync.md` и `adr/019`. - `architecture/cross-cutting/ui-resilience.md` и `data-freshness.md` — убрать обязательные предупреждения и ручное обновление, объяснить автоматическое восстановление и первичную недоступность. - Предметные описания в `domains/**`, затронутые изменёнными состояниями: income, instruments, portfolio. ### Out of scope - Поведение приложения: оно уже реализовано и этой Issue не меняется. - Ошибки явных действий пользователя: они сохраняются и остаются видимыми, их описание не трогаем. - Состояние источника из `meta` — остаётся документированным как есть. ## Acceptance Criteria - [ ] ADR о тихом чтении существует, пронумерован по порядку и связан с предыдущими решениями о background sync. - [ ] `ui-resilience.md` и `data-freshness.md` не описывают ручное обновление и обязательные предупреждения о собственном чтении как текущее поведение. - [ ] Затронутые `domains/**` согласованы с тихим UI; правятся только фрагменты об изменённых состояниях и recovery. - [ ] Описание состояния источника сохранено и не противоречит `frontend-data-resilience`. - [ ] `npm run verify` и `git diff --check` проходят; относительные ссылки целы. ## Dependencies Блокирует archive change `quiet-user-feedback` — `WealthLedger/specs#50`. По lifecycle spec archive отклоняется, пока affected delivery area не реализована, а `docs` входит в его tasks 8.1–8.4. ## Verification ```bash npm run verify git grep -lniE 'ручн(ое|ого) обновлен|кнопк[аи] .?Обновить' -- 'domains/**' 'architecture/**' ``` Ограничение: tasks 8.1–8.4 в `quiet-user-feedback/tasks.md` отмечены выполненными, но фактически в `docs` не выполнены. Это расхождение отметки и факта; статус tasks исправляется вместе с этой работой.
codex-bot added the Kind/Documentation
Priority
Medium
3
labels 2026-10-17 21:50:30 +03:00
codex-bot self-assigned this 2026-10-17 21:55:46 +03:00
Author
Owner

Выполнено. PR #52 слит squash, develop = e8e3ef6.

Проверка Acceptance Criteria

$ git ls-tree origin/develop --name-only -- adr/021-quiet-reading-and-rare-confirmations.md
adr/021-quiet-reading-and-rare-confirmations.md

$ git grep -niE 'кнопк[аи] .?Обновить|действие .?Повторить|предлагает повторить|локальную повторную попытку' origin/develop -- '*.md' | grep -v 'adr/017'
adr/021-...md:12:кнопки «Обновить» и «Повторить», индикатор фонового обновления и сообщение

$ npm run verify
exit 0
  • ADR о тихом чтении существует — adr/021-quiet-reading-and-rare-confirmations.md, номер по порядку после 020, внесён в adr/README.md. Статус Accepted со ссылкой на замещаемую часть ADR 019 и уточняемую часть ADR 007.
  • ui-resilience.md не описывает ручное обновление и обязательные предупреждения как текущее поведение. Единственное оставшееся вхождение этих слов — в разделе Context нового ADR, где они описывают прежнее состояние, что корректно.
  • Затронутые domains/** согласованы: accounts, income, bonds, stocks, portfolio/overview, portfolio/how-to/investigate-discrepancy. Правились только фрагменты об изменённых состояниях и recovery.
  • Описание состояния источника сохранено и усилено: время последнего успеха, устаревание, исход часовой попытки и неполнота показываются текстом либо доступно именованным элементом.
  • npm run verify — exit 0 (markdownlint с relative-links и якорями, затем git diff --check), новый файл охвачен. Ссылки ADR 021 проверены вручную: 4/4 существуют, обратная ссылка из ui-resilience.md существует.

Два уточнения по scope

adr/017-local-tbank-reads-and-background-sync.md не правился. Он помечен «историческое архитектурное направление», его решения о ручном обновлении уже заменены ADR 019. Описание кнопки «Обновить» там корректно для своего периода; переписывание исторического ADR противоречило бы правилу docs о сохранении истории в Git.

architecture/cross-cutting/data-freshness.md не правился. Проверка показала, что он описывает семантику meta и серверную сторону — устаревших утверждений о клиентском UI не содержит. Исходный scope Issue предполагал правку, но факт её не потребовал.

Основание — код, а не тексты

Каждое утверждение сверено с frontend/origin/develop:

retry actions в src/pages/**                        → 0
Button/onClick в SourceSyncStatus.tsx               → 0
sourceTime + attempt renders                        → 3
GET_DEADLINE_MS                                     → 15_000
RETRY_DELAYS_MS                                     → [1000, 2000]
INITIAL_WAIT_BUDGET_MS                              → 10_000

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

Разблокирует archive change quiet-user-feedback — WealthLedger/specs#50.

Выполнено. PR #52 слит squash, `develop` = `e8e3ef6`. ## Проверка Acceptance Criteria ``` $ git ls-tree origin/develop --name-only -- adr/021-quiet-reading-and-rare-confirmations.md adr/021-quiet-reading-and-rare-confirmations.md $ git grep -niE 'кнопк[аи] .?Обновить|действие .?Повторить|предлагает повторить|локальную повторную попытку' origin/develop -- '*.md' | grep -v 'adr/017' adr/021-...md:12:кнопки «Обновить» и «Повторить», индикатор фонового обновления и сообщение $ npm run verify exit 0 ``` - [x] ADR о тихом чтении существует — `adr/021-quiet-reading-and-rare-confirmations.md`, номер по порядку после `020`, внесён в `adr/README.md`. Статус Accepted со ссылкой на замещаемую часть ADR 019 и уточняемую часть ADR 007. - [x] `ui-resilience.md` не описывает ручное обновление и обязательные предупреждения как текущее поведение. Единственное оставшееся вхождение этих слов — в разделе Context нового ADR, где они описывают прежнее состояние, что корректно. - [x] Затронутые `domains/**` согласованы: `accounts`, `income`, `bonds`, `stocks`, `portfolio/overview`, `portfolio/how-to/investigate-discrepancy`. Правились только фрагменты об изменённых состояниях и recovery. - [x] Описание состояния источника сохранено и усилено: время последнего успеха, устаревание, исход часовой попытки и неполнота показываются текстом либо доступно именованным элементом. - [x] `npm run verify` — exit 0 (markdownlint с relative-links и якорями, затем `git diff --check`), новый файл охвачен. Ссылки ADR 021 проверены вручную: 4/4 существуют, обратная ссылка из `ui-resilience.md` существует. ## Два уточнения по scope **`adr/017-local-tbank-reads-and-background-sync.md` не правился.** Он помечен «историческое архитектурное направление», его решения о ручном обновлении уже заменены ADR 019. Описание кнопки «Обновить» там корректно для своего периода; переписывание исторического ADR противоречило бы правилу docs о сохранении истории в Git. **`architecture/cross-cutting/data-freshness.md` не правился.** Проверка показала, что он описывает семантику `meta` и серверную сторону — устаревших утверждений о клиентском UI не содержит. Исходный scope Issue предполагал правку, но факт её не потребовал. ## Основание — код, а не тексты Каждое утверждение сверено с `frontend/origin/develop`: ``` retry actions в src/pages/** → 0 Button/onClick в SourceSyncStatus.tsx → 0 sourceTime + attempt renders → 3 GET_DEADLINE_MS → 15_000 RETRY_DELAYS_MS → [1000, 2000] INITIAL_WAIT_BUDGET_MS → 10_000 ``` `AccountsPageError.view.tsx` для `503` и неизвестной ошибки отдаёт `StateView` без `action`; `AccountIncomePageError.view.tsx` без кнопок; на страницах stock и bond кнопок нет. Сохранившиеся `Alert` относятся к неполноте данных и устареванию позиции, а не к процессу чтения. Разблокирует archive change `quiet-user-feedback` — `WealthLedger/specs#50`.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: WealthLedger/docs#51