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,40 @@
+# Documentation Impact
+
+## Summary
+
+Durable docs update нужен ограниченно: наблюдаемая семантика итога часовой
+попытки уже описана в AS-IS, но правила вывода итога, ограниченного ожидания и
+восстановления после сбоя сохранения/перезапуска в docs отсутствуют. Переносится
+только это знание; migration history остаётся в archived change.
+
+## Documentation Changes
+
+| Action | Target | Category | Resulting AS-IS | Source | Verification |
+|---|---|---|---|---|---|
+| update | `docs/architecture/cross-cutting/data-freshness.md` | cross-cutting | Рядом со словарём `lastAttempt` (`none`, `running`, `succeeded`, `partial`, `failed`): итог попытки выводится из фактических результатов её шагов; попытка, не завершившая обязательный шаг, не обозначается полным успехом; ожидание шага ограничено, зависший шаг учитывается как проблемный; попытка, потерявшая выполнение (сбой сохранения, остановка процесса), закрывается частичным успехом либо неуспехом и не блокирует следующий обход дольше обычного срока | System Analysis — Data and State Semantics, Error and Recovery Semantics; Design 1–5 | Страница не противоречит canonical spec `hourly-investment-sync` и фактическому поведению `meta` |
+| update | `docs/integrations/tbank.md` | integration | В разделе «Состояние и ошибки»: диагностические причины жизненного цикла попытки (`INTERRUPTED` — прервана до нормального завершения, `DEADLINE` — истечение ожидания шага) — внутренняя диагностика, не ошибки T-Bank; в hourly-read наружу не попадают, начатые обращения к T-Bank не отменяются | System Analysis — Observability Semantics; Design 3, 6 | Раздел различает ошибки подключения/external-коды и внутренние причины жизненного цикла |
+
+## Diagram Promotion
+
+Не переносить. Sequence-диаграммы (`hourly-attempt-terminal-barrier.mmd`,
+`hourly-bounded-wait.mmd`, `hourly-recovery.mmd`) — planning evidence этого
+change; AS-IS достаточно текстового описания семантики в `data-freshness.md`.
+
+## ADR Decision
+
+`N/A` — архитектурно значимого решения с новыми alternatives/consequences нет:
+чинятся существующие владельцы строк в прежней одно-процессной топологии,
+без новых компонентов и контрактов (Solution Assessment остаётся в archived
+change).
+
+## Glossary / Navigation Impact
+
+Нет: новые термины (`terminal barrier`, преемник попытки) — внутренние;
+публичный словарь состояний не расширяется, navigation не меняется.
+
+## No-Change Rationale
+
+`docs/architecture/containers.md` не меняется: раздел «Сохранение и
+восстановление данных» описывает backup/restore уровня базы, а не восстановление
+попытки приложением. Остальные AS-IS страницы не затрагиваются: HTTP contract
+и словарь состояний не изменились.