specs/openspec/changes/harden-hourly-sync-lifecycle/design.md

Engineering Design

Context and Constraints

• Один backend-процесс; durable fence — reservation попытки в SQLite; таймер процесса только предлагает работу (существующий инвариант, комментарии в tbank-hourly.scheduler.ts).
• Итог попытки пишется CAS-обновлением только из состояния running: устаревшая публикация после появления преемника уже отклоняется существующим fence (settleHourly where state: 'running'; read() при несовпадении progress.attempts помечает шаг cancelled).
• Сегодня итог вычисляется по in-memory списку ошибок walk (пуст при исключении — ложный succeeded), ошибка settleHourly подавляется .catch(() => undefined), settledWorks поллит без deadline, а id строк шагов не персистятся на hourly-попытке (progress: { sections: [] }).
• Финализаторы enrichment/operations могут очистить память без durable finish — шаг остаётся running.
• Топология не меняется: без lease и мультреплик; CAS-ограничения attempt/revision/source не ослабляются.

Technical Goals / Non-Goals

Goals

• Итог попытки выводится из durable-состояния шагов; ложный succeeded невозможен ни на одном error-пути.
• Каждая попытка достигает терминального итога в ограниченное время (ограничение ожидания на каждый шаг).
• Попытка с утраченным выполнением закрывается диагностируемо (INTERRUPTED) и не блокирует следующий обход дольше обычного часового срока.
• Поздняя публикация шага текущей попытки сохраняется до фиксации итога; после появления преемника отклоняется существующим fence.

Non-Goals

• Lease, очередь, вторая реплика, параллельный scheduler.
• Отмена уже начатых обращений к T-Bank.
• Новый публичный статус попытки и изменения HTTP contract.
• Graceful drain — только если тест контролируемой остановки докажет необходимость.

Implementation Impact Map

main

N/A — workspace/dev/release orchestration не меняется.

frontend

N/A — публичный словарь состояний и форма meta не меняются.

backend

affected — координатор tbank-hourly.scheduler.ts (walk/settle/ settledWorks/launch), tbank-sync.repository.ts (reserveHourly/ settleHourly), персист id шагов на попытке, durable finish в финализаторах catalog-enrichment.service.ts и brokerage-operations-sync.service.ts, изолированные SQLite-тесты reservation/coordinator.

qa

N/A — QA repository не существует; системная верификация остаётся ручной по QA Analysis.

Decisions

backend

1. Итог выводится из durable-состояния шагов (корневой фикс). settleHourly в одной транзакции читает строки шагов попытки и вычисляет итог: succeeded — только когда каждый обязательный шаг успешен и закрытие инициировано нормальным завершением walk; partial — успешны некоторые; failed — ни один. Вызывающие больше не передают результат и список ошибок; walk передаёт максимум cause: 'INTERRUPTED' (закрытие до нормального завершения), который капит итог до partial. Исключение — обязательные секции, чей dispatch не создал durable-строку шага: walk передаёт их как дополнительные problem-записи (наблюдаемый факт диспатча, не результат), иначе попытка могла бы получить ложный успех. Альтернатива «прокидывать настоящий failures-map в catch» отклонена: не закрывает lost-settle и краш-пути — каждый error-путь требовал бы своего guard. Отдельный janitor-сервис отклонён: issue требует чинить существующих владельцев, не вводить параллельный scheduler.

2. Id шагов персистятся на попытке в момент dispatch. progress hourly-попытки переиспользует существующую форму children: string[] + attempts: { [id]: attemptId } (паттерн ScreenProgress/progress()). Walk записывает id каждой строки шага сразу после dispatch, до ожидания — иначе recovery после краша не знает множество шагов попытки, а шаг, упавший в dispatch, исчезает из множества.

3. Ограниченное ожидание на каждый шаг. settledWorks получает per-id deadline: константа WORK_WAIT_BOUND_MS = 15 * 60 * 1000; истёкший id возвращается как проблемный шаг с причиной DEADLINE. Управляемые часы в тестах — jest fake timers, инъекция clock в production-код не вводится. RPC не отменяется; поздний результат шага сохраняется его собственной строкой — учтён ли он в итоге, решает fence и момент фиксации.

4. In-memory активные обходы + recovery на существующем tick. TbankHourlyScheduler держит active: Set<string> (attemptId): добавление в начале walk, удаление в finally. launch() перед reserveHourly вызывает recoverAbandoned(userId): если строка hourly running, processRunId свой и attemptId не в active — попытка потеряла settle и закрывается через settleHourly с cause: 'INTERRUPTED' (итог из детей, максимум partial). Это же закрывает застрявшие legacy-строки running. Новых таймеров и санитаров нет — восстановление едет на существующем минутном tick.

5. Restart-ветка reserveHourly закрывает попытку итогом. Существующая ветка «running + чужой processRunId» вместо голой записи state: 'cancelled' выполняет тот же derived settle с cause: 'INTERRUPTED' внутри транзакции reservation; далее прежний due-гейт: новый обход — не ранее следующего часового срока от начала попытки. cancelled для hourly-строк перестаёт писаться; существующие маппинги cancelled в hourly()/hourlyAttempt() остаются толерантным чтением и не удаляются.

6. Причина прерывания — в существующем поле errorCode. INTERRUPTED — уровень попытки (закрытие до нормального завершения); DEADLINE — уровень шага (истечение ожидания), попадает в errorCode попытки как первая ошибка секции по существующему precedence. Коды ошибок шагов остаются в progress.sections[].errorCode. Поле — открытое строковое: форма ответа и enum TbankErrorCode не расширяются (маркеры жизненного цикла — не ошибки T-Bank).

7. Durable finish в дочерних финализаторах. Внешний catch финализаторов (enrichment, operations drain/step) обязан перед возвратом или пробросом записать терминальный неуспешный результат своей строки шага существующим путём записи ошибки, а не только очистить память. Иначе шаг остаётся running, и попытка не проходит terminal barrier.

Cross-cutting Implementation

• Подавление ошибки settleHourly (.catch(() => undefined)) допустимо только как пара к решению 4: walk удаляет attemptId из active в finally, и следующий tick закрывает строку recovery. Ошибка фиксируется существующим структурным логом.
• Новых фоновых таймеров, очередей и таблиц нет; concurrency не меняется (один walk на подключение).

Data / Storage Changes

• Миграции нет: children/attempts живут в существующем JSON progress строки tbankSyncWork; поле errorCode уже в схеме (20260924170000_persist_tbank_data/migration.sql:177).
• Legacy-застрявшие running строки закрываются первым recovery-проходом (итог из детей + INTERRUPTED); чтение уже закрытых строк не меняется.

Contract Implementation

• HTTP contract не меняется: форма meta и словарь состояний (running/succeeded/partial/failed) прежние; cancelled остаётся в enum DTO как толерантное чтение.
• До закрытия change: backend-generated OpenAPI проверяется на семантическую совместимость с текущим контрактом — изменения формы не ожидаются; новые значения существуют только внутри открытого строкового поля диагностики и в hourly-read наружу не попадают.

Developer Verification Strategy

• Изолированные SQLite-тесты reservation/coordinator (не stub upcoming-events): ветки first, not-due, running, restart, partial; итог проверяется после terminal barrier.
• Инъекция ошибок отдельно в дочерние шаги и в родительский settle; восстановление после ошибки сохранения; защита от overlap и от поздней публикации; controlled stop/restart — нет бесконечного drain, после остановки новые reservations не создаются.
• Управляемые часы — jest fake timers.
• Сохранить существующие наборы auth/money/publication; полный backend verify на финальном diff.
• Graceful drain не добавляется, пока тест остановки не покажет необходимость.

UI/UX Package

N/A — UI не меняется; новый mockup не требуется.

Risks / Trade-offs

• Derivation зависит от полноты children: пропуск записи id при dispatch делает шаг невидимым для итога. Митигируется решением 2 (запись до await) и тестом инъекции ошибки в dispatch.
• Per-step deadline может закрыть попытку как partial при медленном, но живом шаге; поздний результат сохраняется строкой шага, данные не теряются.
• In-memory active не переживает рестарт — этот случай закрывает restart-ветка reservation (решение 5).
• Константа 15 минут без конфигурации: потолок опыта одного процесса (ponytail: вынести в конфиг, если медленные шаги станут регулярными).

Migration / Rollout / Rollback

• Rollout: один PR в backend; миграций и флагов нет; следующий tick после деплоя закрывает застрявшие строки.
• Rollback contract: N/A — нет миграции, security или public contract изменения; откат — revert кода, уже закрытые recovery строки остаются в корректном терминальном виде.

Solution Assessment

Обязателен (concurrency/recovery). Варианты:

• (a) Root-cause: settle выводит итог из durable-детей; recovery на существующем tick/reservation; один guard в общей точке.
• (b) Минимальный патч: настоящий failures-map в catch плюс guard в каждом вызывающем.
• (c) Отдельный janitor/очередь с lease.

Выбор — (a): закрывает все error-пути одной точкой (exception, lost settle, краш, deadline), переиспользует существующие fence и progress-паттерн, без новых компонентов. (b) оставляет открытыми lost-settle и краш — каждый новый error-путь снова требует своего guard, что и есть текущий баг. (c) отклонён: issue явно запрещает параллельный scheduler, lease не даёт выгоды в одно-процессной топологии, а стоимость нового компонента выше фикса.