spec: add harden-hourly-sync-lifecycle change (WealthLedger/backend#56)

2026-10-12 20:28:58 +03:00
parent 78f01066d2
commit 14174a7bb3
11 changed files with 828 additions and 0 deletions
@@ -0,0 +1,90 @@
+# QA Analysis
+
+## Verification Scope
+
+### In Scope
+
+- Дельта `hourly-investment-sync`: «Последний результат обхода доступен только
+  для наблюдения» (MODIFIED) и ADDED «Каждая попытка обхода достигает итога в
+  ограниченное время», «Восстановление после сбоя сохранения не блокирует
+  последующие обходы», «Устаревшая публикация не влияет на актуальную попытку».
+- Системные проверки через resource GET `meta` и durable-состояние попытки
+  после контролируемых действий backend (инъекции сбоев, остановка/запуск
+  процесса).
+
+### Out of Scope
+
+- Внутренние unit/component тесты — developer-owned, определены Design.
+- Неизменяемые поведения `tbank-data-sync`/`tbank-connection` — только
+  regression.
+- Проверка часовой cadence (T03) и cleanup workflow — независимые задачи.
+
+## Coverage Matrix
+
+| Requirement / Scenario | Системная проверка |
+| --- | --- |
+| Последний результат… — Сбой после частичного обновления | Инъекция сбоя шага после успешного обновления Portfolio одного счёта: GET обозначает частичный успех с проблемным шагом, данные первого счёта остаются обновлёнными |
+| Последний результат… — Сбой до первого обновления | Инъекция сбоя до завершения любого шага: GET обозначает неуспех, не полный успех |
+| Последний результат… — Частичный успех / Наблюдение не запускает обход / Старая граница подключения | Regression существующего поведения `meta` |
+| Каждая попытка… — Шаг не завершается | Зависший шаг с управляемыми часами: попытка достигает терминального итога в ограниченное время, шаг учтён как проблемный |
+| Каждая попытка… — Наблюдение не ждёт без ограничения | Наблюдение результата получает итоговое состояние, а не бесконечное «выполняется» |
+| Восстановление… — Потерянное закрытие попытки | Ошибка закрытия при живом процессе: следующий проход закрывает попытку диагностируемо, следующая допустимая попытка стартует |
+| Восстановление… — Перезапуск процесса | Остановка процесса во время обхода и повторный запуск: брошенная попытка закрыта, новый обход не ранее следующего часового срока, перекрытия нет |
+| Устаревшая публикация… — После появления преемника | Позднее завершение шага старой попытки после запуска следующей: данные не изменились, итог актуальной попытки не изменился |
+| Устаревшая публикация… — До фиксации итога | Позднее завершение шага до фиксации итога попытки: результат сохранён и учтён в итоге |
+
+## Cross-system Verification
+
+- T-Bank upstream не отменяется при истечении ожидания; поздний ответ после
+  появления преемника не изменяет данные (проверяется на симулированном
+  upstream в контролируемой среде backend-тестов).
+- Внешние ошибки шагов отображаются только безопасным перечнем проблемных
+  счетов/разделов; причины `INTERRUPTED`/`DEADLINE` не раскрывают наружу
+  ничего сверх существующей формы `meta`.
+
+## Risk-based Priorities
+
+- **Critical**: ложный полный успех (целостность данных), бесконечное
+  «выполняется», перекрытие обходов, порча данных устаревшей публикацией.
+- **Compatibility**: публичный словарь состояний `meta` неизменен;
+  `cancelled` в enum остаётся толерантным значением.
+- **Money/data integrity**: успешные результаты шагов не теряются при сбоях
+  остальных.
+
+## Test Data and Environment Needs
+
+- Изолированный backend на SQLite с управляемыми часами и симулированным
+  upstream T-Bank (контролируемая тестовая среда; внутренние mocks — на
+  усмотрение разработчиков по Design).
+- Подключение с не менее чем двумя доступными счетами для сценариев частичного
+  успеха.
+
+## Manual / Exploratory Scope
+
+- Ручная проверка отображения результата последнего обхода на инвестиционных
+  экранах после симулированного сбоя сохранения.
+- Exploratory: повторные остановки процесса в разных фазах обхода; наблюдение
+  результата сразу после старта процесса.
+
+## Automation Candidates
+
+- Black-box API-кандидаты (GET `meta` после инъекций сбоев, контролируемая
+  остановка) — `deferred until QA repo exists`.
+
+## Observability Verification
+
+- Причины `INTERRUPTED`/`DEADLINE` наблюдаются в durable-диагностике попытки,
+  а не в публичном API; подавленная ошибка закрытия фиксируется структурным
+  логом backend.
+
+## Regression Impact
+
+- Существующие наборы auth/money/publication и полный `backend verify`.
+- Happy path часового обхода, первый обход после подключения, скрытие
+  результата прежней границы подключения.
+
+## Gaps / Blockers
+
+- Gaps нет. Graceful drain остаётся условным: добавляется только если
+  controlled-stop тест докажет необходимость (routing: пересмотр Design/QA
+  после теста).