Архитектура модульной платформы

Слои

Слой	Путь	Роль
Ядро	app/Integrations/	Шина хуков, snapshot, outbound, REST, лицензии, Filament‑реестр
Пакеты	modules/Integrations/{Code}/	manifest, hooks.php, handlers, instance_form
Админка	Модули интеграций	Каталог, подключения, мониторинг
Очереди	Laravel Queue	integrations.*, при необходимости default

Operational

Модуль operational, если:

1. Есть в БД (Синхронизировать в каталоге);
2. Включён;
3. Лицензия valid (или license.required: false);
4. Legacy: дополнительно IntegrationModuleInterface::enabled().

php artisan integrations:package:inspect MyModule

Подключения и точки

Snapshot содержит pickup_point_id.

Инстанс	События
На конкретную точку	Только эта точка
Все точки (bulk)	Отдельный инстанс на каждую активную точку с теми же настройками
Нет подключений	Handler из hooks.php может работать без привязки; outbound — нет

Outbound привязан к активному инстансу.

Два канала исходящих событий

PlatformHookBus на каждый хук:

1. Jobs outbound для endpoint инстанса;
2. Jobs handler для пакетов из hooks.php.

Каналы независимы.

Snapshot

Массив JSON, не Eloquent. Для статусов: status_code, status_semantic, previous_*.

Идемпотентность

integration_hook_deliveries: (package, hook, idempotency_key). Повтор completed не вызывает handler.

Backpressure

Механизм	Env
max pending	INTEGRATION_HOOK_MAX_PENDING (500)
rate limit	INTEGRATION_HOOK_RATE_LIMIT (120/мин)
circuit breaker	INTEGRATION_CB_*

Legacy

МойСклад и др. без manifest — is_legacy, старый sync, форма Интеграции. Новые модули — manifest + Подключения.

Очереди

INTEGRATION_DEDICATED_QUEUES (config по умолчанию true):

Очередь	Содержимое
integrations.{Code}	Handlers платформы, inbound job
integrations.outbound	POST наружу

Jobs внутри модуля могут использовать свою логику очереди. То есть сам пакет при необходимости может отправлять тяжёлые внутренние задачи либо в default, либо в свою отдельную очередь.

Не смешивайте тяжёлый синк каталога с integrations без необходимости.

После commit

Статусы, оплаты — только DB::afterCommit.

Связанные разделы

• Подключения
• Очереди
• Хуки