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,140 @@
+# System Analysis
+
+## Requirement Coverage
+
+| Requirement / Scenario | Flow | Contract / Semantics |
+| --- | --- | --- |
+| Последний результат обхода… — Сбой после частичного обновления | `hourly-attempt-terminal-barrier.mmd` | Outcome derivation, terminal barrier |
+| Последний результат обхода… — Сбой до первого обновления | `hourly-attempt-terminal-barrier.mmd` | Outcome derivation |
+| Последний результат обхода… — Частичный успех | `hourly-attempt-terminal-barrier.mmd` | Step results preserved |
+| Каждая попытка обхода достигает итога в ограниченное время — Шаг не завершается | `hourly-bounded-wait.mmd` | Bounded wait per required step |
+| Каждая попытка обхода достигает итога в ограниченное время — Наблюдение не ждёт без ограничения | `hourly-bounded-wait.mmd` | Bounded terminal outcome |
+| Восстановление после сбоя сохранения… — Потерянное закрытие попытки | `hourly-recovery.mmd` | Recovery of lost settle |
+| Восстановление после сбоя сохранения… — Перезапуск процесса | `hourly-recovery.mmd` | Recovery of abandoned attempt |
+| Устаревшая публикация… — Поздняя публикация после появления преемника | `hourly-recovery.mmd` | Successor fencing |
+| Устаревшая публикация… — Поздняя публикация до фиксации итога | `hourly-bounded-wait.mmd` | Late publication counts before outcome is recorded |
+
+## Systems and Responsibilities
+
+- **Hourly walk coordinator** (backend): резервирует попытку часового обхода для
+  текущего подключения, запускает обязательные шаги, ждёт их терминального
+  результата с ограничением, выводит итог попытки и закрывает её.
+- **Durable attempt status** (SQLite): единственная durable-запись попытки
+  (состояние, диагностическая причина, результаты шагов) и источник итога для
+  наблюдения и восстановления.
+- **Child step owners**: шаги membership, Portfolio, операций и будущих событий
+  публикуют свой полный результат в durable-хранилище и обозначают свой
+  терминальный результат; финализатор шага обязан фиксировать результат даже
+  при ошибке.
+- **T-Bank и публичные источники**: внешние данные; начатые обращения не
+  отменяются по внутреннему ограничению ожидания.
+- **Resource GET observer**: читает сохранённые данные и `meta` с состоянием
+  последней попытки; наблюдение не запускает обход.
+
+## Interaction Flows
+
+- `sequences/hourly-attempt-terminal-barrier.mmd` — попытка, шаги, terminal
+  barrier и вывод итога из фактических результатов шагов.
+- `sequences/hourly-bounded-wait.mmd` — ограничение ожидания шага, закрытие
+  попытки по его истечении и учёт позднего результата до появления преемника.
+- `sequences/hourly-recovery.mmd` — восстановление после сбоя сохранения и
+  после перезапуска процесса, отклонение устаревшей публикации.
+
+## Contracts
+
+- Новых и изменённых межсистемных HTTP/event contracts нет. Публичный словарь
+  состояний последней попытки (`выполнение`, `полный успех`, `частичный успех`,
+  `неуспех`) и форма `{ data, meta }` не меняются.
+- Машинно-читаемый target contract в `system-analysis/contracts/` не создаётся:
+  изменения ограничены уточнением значений внутри существующих полей.
+- Диагностическое поле причины остаётся открытым строковым полем; значения
+  причин прерывания (`INTERRUPTED` — ошибка, сбой сохранения, остановка
+  процесса; `DEADLINE` — истечение ограничения ожидания шага) дополняют
+  существующие коды ошибок шагов и не требуют изменения формы ответа.
+- Compatibility check до закрытия change: backend-generated OpenAPI остаётся
+  семантически совместимым с текущим контрактом (ожидаются только дополнительные
+  значения открытого строкового поля диагностики).
+
+## Data and State Semantics
+
+- **Попытка**: `running` → терминальный итог (`succeeded` | `partial` | `failed`).
+  Попытка, не завершившая обязательный шаг, не может получить `succeeded`.
+- **Terminal barrier**: итог попытки выводится только после того, как каждый
+  обязательный шаг достиг терминального результата либо учтён как истёкший по
+  ограничению ожидания. Итог не вычисляется по неполному списку шагов.
+- **Вывод итога**: `succeeded` — только когда все обязательные шаги успешны и
+  координатор сам зафиксировал закрытие попытки; `partial` — успешны некоторые
+  шаги; `failed` — не успешен ни один. Успешные результаты шагов сохраняются
+  независимо от итога.
+- **Причина прерывания**: попытка, закрытая до нормального завершения всех
+  шагов, сохраняет причину прерывания в диагностическом поле и не превышает
+  `partial`.
+- **Internal coordinator decisions** `first`, `not-due`, `running`, `restart`,
+  `partial`: внутренние метки решения о запуске и проверки итога после terminal
+  barrier; в HTTP contract не входят и публично не наблюдаемы.
+- **Шаги**: каждый шаг владеет своей durable-строкой результата; строка шага
+  устаревшей попытки помечается устаревшей относительно преемника.
+
+## Error and Recovery Semantics
+
+- **Сбой шага** (внешняя ошибка T-Bank): шаг фиксирует терминальный неуспех со
+  своим кодом ошибки; остальные шаги продолжаются; итог — `partial` или `failed`.
+- **Сбой сохранения** (завершение шага, публикация результата, закрытие
+  попытки): ошибка не подавляется молча в durable-состоянии; попытка, оставшаяся
+  `running`, закрывается восстановлением по фактическим результатам шагов.
+- **Остановка процесса**: начатая попытка остаётся `running` в SQLite;
+  следующий запуск процесса закрывает её как прерванную (`partial` или `failed`
+  с сохранёнными результатами шагов) и не создаёт перекрывающийся обход.
+- **Ограничение ожидания**: истечение ограничивает только ожидание шага; уже
+  начатое обращение к T-Bank не отменяется. Его поздний результат сохраняется и
+  учитывается при выводе итога своей попытки, если итог ещё не зафиксирован, и
+  отклоняется как устаревший после появления преемника.
+- **Повтор**: неуспешная попытка не повторяется ранее следующего часового срока,
+  отсчитанного от начала этой попытки; восстановление не сокращает и не
+  продлевает этот срок.
+- **Overlapping**: следующая попытка не резервируется, пока предыдущая не
+  терминальна; восстановление обязано сначала закрыть предыдущую.
+
+## Observability Semantics
+
+- Наблюдаемый итог попытки и безопасный перечень проблемных счетов/разделов —
+  существующее обязательство; значения итога не расширяются.
+- Семантические коды причин: `INTERRUPTED` — попытка прервана до нормального
+  завершения (ошибка, сбой сохранения, остановка процесса); `DEADLINE` — шаг не
+  завершился в ограничение ожидания. Коды сохраняются в диагностическом поле
+  попытки и/или шага и дополняют коды ошибок шагов без изменения формы `meta`.
+- SDK/exporter/logger — вне границ этого изменения; используется существующий
+  структурный лог backend.
+
+## Security and NFR at System Boundaries
+
+- Граница наблюдения попытки остаётся границей текущего подключения: результат
+  прежней границы не раскрывается (существующее обязательство).
+- Ограниченное время достижения итога попытки — наблюдаемое обязательство
+  надёжности: ожидание шага и ожидание наблюдателя ограничены.
+- Новых trust boundaries, authn/authz требований нет.
+
+## Compatibility / Migration
+
+- Схема данных и HTTP contract не меняются; миграция не требуется.
+- Уже застрявшие строки попыток в состоянии выполнения закрываются первым
+  проходом восстановления по правилам этого изменения: итог из фактических
+  результатов шагов, причина прерывания, без полного успеха. Это ожидаемое
+  разовое приведение legacy-состояния к диагностируемому виду.
+- Совместимость с одно-процессной топологией сохраняется; межпроцессный lease
+  не требуется.
+
+## Durable Documentation Candidates
+
+- `docs/integrations/tbank.md` (раздел «Состояние и ошибки»): итог часовой
+  попытки, причины прерывания и правило ограниченного ожидания как часть
+  наблюдаемого состояния интеграции.
+- `docs/architecture/containers.md` (раздел «Сохранение и восстановление
+  данных»): восстановление попытки после сбоя сохранения и после перезапуска
+  процесса как durable-свойство системы.
+- Итоговое решение о переносе принимает `docs-impact`.
+
+## Open Questions
+
+- Нет блокирующих вопросов. Частота проявления механизма в production остаётся
+  не установленной и не влияет на contract.
@@ -0,0 +1,23 @@
+sequenceDiagram
+  participant Coordinator
+  participant DB as Durable attempt status
+  participant Steps as Child step owners
+  participant TB as T-Bank and public sources
+  participant API as Resource GET
+
+  Coordinator->>DB: Reserve attempt for current connection
+  DB-->>Coordinator: Attempt with connection revision
+  Coordinator->>Steps: Run required steps (membership, portfolios, operations, events)
+  Steps->>TB: Fetch missing data
+  Steps->>DB: Publish complete successful step result
+  Steps->>DB: Record terminal step result (success or failure with code)
+  Coordinator->>DB: Read step results after terminal barrier
+  alt All required steps succeeded
+    Coordinator->>DB: Settle succeeded
+  else Some required steps succeeded
+    Coordinator->>DB: Settle partial with safe problem sections
+  else No required step succeeded
+    Coordinator->>DB: Settle failed with safe problem sections
+  end
+  API->>DB: Read last attempt result
+  DB-->>API: Time, outcome, safe problem list
@@ -0,0 +1,24 @@
+sequenceDiagram
+  participant Coordinator
+  participant DB as Durable attempt status
+  participant Steps as Child step owners
+  participant TB as T-Bank and public sources
+
+  Coordinator->>Steps: Run required steps
+  Steps->>TB: Start upstream call
+  Coordinator->>Coordinator: Wait for step result within bound
+  alt Step reaches terminal result in time
+    Steps->>DB: Publish complete result
+    Coordinator->>DB: Settle attempt after terminal barrier
+  else Wait bound expires
+    Note over Coordinator,TB: Upstream call is not cancelled
+    Coordinator->>DB: Record step problem cause DEADLINE
+    Coordinator->>DB: Settle partial or failed after terminal barrier
+    Steps->>TB: Upstream call completes later
+    Steps->>DB: Publish late result for the same attempt
+    alt Outcome not recorded yet and no successor
+      DB-->>Steps: Late result is preserved and counts at outcome derivation
+    else Successor attempt already started
+      DB-->>Steps: Publication rejected as stale
+    end
+  end
@@ -0,0 +1,23 @@
+sequenceDiagram
+  participant Coordinator
+  participant DB as Durable attempt status
+  participant Steps as Child step owners
+
+  Note over Coordinator,DB: Attempt is still running but its walk no longer executes
+  Coordinator->>DB: Detect running attempt without active walk
+  alt Process still alive after lost settle
+    Coordinator->>DB: Read actual step results
+    Coordinator->>DB: Close attempt as partial or failed with cause INTERRUPTED
+  else Process restarted after stop
+    Coordinator->>DB: Read actual step results
+    Coordinator->>DB: Close abandoned attempt as partial or failed with cause INTERRUPTED
+  end
+  DB-->>Coordinator: Attempt is terminal, no overlap possible
+  Coordinator->>DB: Reserve next attempt at next hourly term from attempt start
+  alt Next term reached
+    DB-->>Coordinator: Successor attempt starts
+    Steps->>DB: Late publication from previous attempt
+    DB-->>Steps: Publication rejected as stale relative to successor
+  else Next term not reached
+    DB-->>Coordinator: No work (not-due)
+  end