Design background cleanup for stale pending application installations

[mesilov]

Summary

ApplicationInstallations now allows a valid pending state where Install without applicationToken leaves both Bitrix24Account and ApplicationInstallation in status new until OnAppInstall finishes the flow.

If Bitrix24 never delivers the finish-step, these installations can remain stuck in new indefinitely.

Goal

Design a background mechanism for detecting and handling stale pending installations.

Why this is needed

• synchronous install flow should stay SDK-compatible and not guess failure too early
• missing ONAPPINSTALL should not leave unbounded stale new entities forever
• operators need a deterministic recovery path for broken install attempts

Options to evaluate

1. TTL worker that marks stale new installations as failed/broken after a timeout
2. TTL worker with alert-only behavior and no state transition
3. Reconciliation job that re-checks portal/app state before deciding what to do
4. Manual operational flow with tooling/documented runbook

Design constraints

• preserve SDK contract compatibility
• do not introduce a second canonical finish-flow besides OnAppInstall
• keep auditability of why a pending installation was considered stale
• account for both master Bitrix24Account and ApplicationInstallation state transitions

Acceptance criteria

• proposed lifecycle for stale new installations is documented
• trigger conditions and TTL are defined
• target statuses/events are defined for both aggregates
• operational and observability requirements are captured
• chosen approach does not conflict with the current Install / OnAppInstall contract

[KarlsonComplete]

Изучил текущий install-флоу. Предлагаю два варианта механизма очистки зависших установок в new. Оба опираются на уже заложенные переходы и не ломают Install / OnAppInstall контракт.

Что считаем «зависшими»: ApplicationInstallation (и связанный мастер Bitrix24Account) в статусе new, созданные через Install без applicationToken, для которых OnAppInstall не пришёл в течение TTL.

Мастер-аккаунт: предлагаю чистить оба агрегата в одной транзакции (new → blocked → deleted). Переходы заложены в сущностях: markAsBlocked($comment) → applicationUninstalled(null) (null-токен разрешён). Мастер без завершённой установки бесполезен, оставлять его в new — та же проблема.

Поиск зависших: создаём Bitrix24AccountReadModelRepository (по аналогии с JournalItemRepositoryInterface в Journal BC) с методом поиска аккаунтов по статусу + старше даты. Сами установки получаем существующими методами findByBitrix24AccountMemberId / findByBitrix24AccountId. В домен изменений не вносим.

Инфраструктура: реализация в виде Symfony Console-команды + UseCase, запуск по cron.

Вариант 1 — TTL-воркер с очисткой состояния

Находит зависшие new старше TTL, переводит new → blocked → deleted для обоих агрегатов, с комментарием причины в markAsBlocked.

• Плюсы: простая детерминированная очистка, без сетевых вызовов.
• Минусы: TTL надо калибровать — может удалить валидную установку с задержкой OnAppInstall; не проверяет реальное состояние портала.

Вариант 3 — Reconciliation job (проверка портала)

TTL находит зависшие, но перед сменой статуса проверяет портал через SDK (app.info). Если приложение не установлено — каскадная очистка. Если статус неясен или портал недоступен — оставляет в new и алертит.

• Плюсы: не повреждает валидные «медленные» установки; покрывает «deterministic recovery path».
• Минусы: сетевые вызовы (таймауты, ретраи, rate-limit), сложнее в реализации и тестах.

Вопросы

1. Вариант 1 vs 3, или гибрид (1 как база + флаг --verify-portal из 3)?
2. TTL по умолчанию — предлагаю 1 час (защита от долгих ручных установок). Приемлемо?
3. Мастер-аккаунт — подтверждаете каскадное удаление вместе с установкой, или только блокировка?
4. Domain event — новое ApplicationInstallationMarkedStaleEvent, или достаточно ApplicationInstallationBlockedEvent с причиной в $comment?

[camaxtly]

Суть, если к нам не пришел токен (для осбытий), то ни одно событие мы не сможем обработать, так как не сможем подтвердить его цифроваую подпись. В нашем случае получается, что часть функционала не работает. Единственный вариант это исправить это "переустановить" приложение. Вот для этого возмжно нам понадобится отдельный статус установки и сценарий работы.

В этом случае надо "блокировать" работу приложения, и просить пользователя переустановить приложение.