# Design ## Context PLBA2 — Python-библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. PLBA2 предоставляет десять capabilities из [proposal.md](proposal.md). Реализации PLBA v1 служат ориентиром для worker, health, workflow и бизнес trace контрактов. ## Goals / Non-Goals **Goals:** - Запускать несколько независимо выполняемых workers с уникальными именами; управлять ими только через lifecycle всего приложения. - Дать приложению единые contracts для lifecycle, health, workflow, HTTP API, identity, двух слоёв конфигурации и business trace. - Разделить персистентную бизнес-историю и технический вывод в stdout. - Поддержать замену PostgreSQL settings adapter без изменения кода, использующего SettingsReader. **Non-Goals:** - Не создавать entrypoint, composition root, HTTP server, сервис настроек или API business history. - Не предоставлять общую очередь, RabbitMQ consumer/producer для рабочих заданий, outbox или retry framework. - Не управлять миграциями приложения, доставкой stdout логов или бизнес-правилами workflow. ## Decisions ### Runtime и workers - Capability `runtime/worker` отвечает за имена, независимый lifecycle, расписание, внутреннюю остановку и health отдельных workers. - Capability `runtime/application-lifecycle` управляет запуском и остановкой приложения; при запуске стартуют все workers без `disabled: true`. Отдельного API для запуска или остановки worker нет. Runtime не завершает принадлежащий приложению OS process или HTTP host. - При обычной остановке каждый worker завершает текущий цикл и не начинает следующий; `force=true` прерывает активную обработку. Приложение становится `stopped` после остановки всех workers. - `timeout_seconds` ограничивает только ожидание HTTP-вызова. При его истечении возвращается `stopping`, а остановка продолжается; отсутствие timeout означает неограниченное ожидание. - Worker читает признак запуска из `workers..disabled` и расписание из `workers..interval_seconds` или `pause_seconds` в `config.yaml`. Отсутствующий `disabled` эквивалентен `false`; изменение признака во время работы вступает в силу при следующем запуске приложения. - Интервал задаёт период между началами циклов, пауза — стабильное ожидание после каждого цикла; активные изменения расписания применяются при планировании следующего цикла. - Исключение цикла не завершает worker. Runtime выставляет автоматический health status; прикладная health-логика добавляет собственные условия, а `critical` ограничивает влияние worker по правилам health aggregation. ### Health - Сохраняется v1 модель worker health и агрегация `ok`, `degraded`, `unhealthy`. - Health report содержит application_id, runtime state и health-состояния запущенных workers; contributors вычисляют собственное состояние. Некритичный компонент может ухудшить aggregate до `degraded`, но не до `unhealthy` по HL.AG-01.FR-01. - Worker с `disabled: true` исключается из набора ожидаемых компонентов. - Если runtime lifecycle приложения `stopped`, aggregate health возвращает `stopped`. ### Единый HTTP API - PLBA2 предоставляет один router для health и lifecycle всего приложения; общий adapter описан в [API.HTTP.CA-01](specs/api/http/control-api/spec.md), отдельные endpoints — в своих Requirements. - Приложение подключает router к одному HTTP host и listener. Все routes используют один порт; capabilities не запускают собственные серверы. - HTTP слой делегирует расчёт health capability HL.AG-01 и управление приложением — RT.AL-01–RT.AL-02. Отдельных worker routes нет; состояния запущенных workers доступны в агрегированном health-отчёте. ### Workflow - Сохраняется object-based API PLBA v1: WorkflowDefinition, WorkflowNode, WorkflowStep, WorkflowContext и StepResult. - Engine применяет только объявленные переходы, сохраняет ход выполнения через WorkflowPersistence и передаёт исключения вызывающему приложению. - Рабочие сообщения, retries и предметные решения остаются у приложения. ### Идентификатор приложения - Необязательное `application_id` задаётся в корневом `config.yaml`. Если оно отсутствует или пустое, runtime берёт `[project].name` из `pyproject.toml`, а при недоступности метаданных генерирует UUIDv4. - Идентификатор разрешается до старта зависимых компонентов, предоставляется runtime-контексту и не меняется в течение процесса. Health и логирование используют его согласно требованиям своих capabilities. ### Настройки - CFG.AS-01 описывает таблицу `settings` для бизнес-параметров, feature toggles и технических значений, которые требуется менять удалённо в runtime. - По CFG.AS-02 приложение создаёт таблицу и загружает начальные значения собственными миграциями. Дальнейшие обновления строк выполняются владельцем приложения; PLBA2 не запускает миграции и не предоставляет сервис изменения конфигурации. - По CFG.AS-03 типизированный SettingsReader читает актуальные значения. Изменения в БД становятся доступны при следующем чтении без рестарта приложения; PostgreSQL adapter фильтрует строки и сортирует их по `sort_order`, `id`. ### Техническая конфигурация из файла - CFG.ACF-01 читает `config.yaml` из корня приложения. PLBA2 задаёт общее необязательное поле `application_id`, `workers..disabled` (по умолчанию `false`) и поля расписания `workers..interval_seconds` / `workers..pause_seconds`; остальные поля и типизированную модель файла определяет приложение. - Локальный file provider заменяет текущую модель удалённых configuration snapshots; отдельный configuration-service и сетевой client не входят в PLBA2. - Файл хранит редко меняемые технические параметры. Бизнес-параметры, feature toggles и технические значения для удалённых runtime-изменений находятся в таблице `settings`. - CFG.ACF-02 обнаруживает изменения файла и атомарно заменяет активную конфигурацию после проверки. Последующие чтения получают новый снимок; уже полученные снимки не мутируют. - Ошибка начальной загрузки блокирует запуск зависимых компонентов. При невалидном runtime-изменении сохраняется последний валидный снимок и приложению сообщается ошибка. - Реализация требует YAML parser; механизм обнаружения изменения файла остаётся деталью адаптера и не входит в публичный контракт. ### Business trace и технические логи - Business trace adapter пишет контексты и сообщения в `trace_contexts` и `trace_messages` схемы приложения; `application_id` входит в `attrs_json` контекста и каждого сообщения, без добавления колонок; migration приложения создаёт обе таблицы. - В публичном контракте используется `business_trace_id`, в совместимой схеме таблиц — поле `trace_id`. - Бизнес-события не публикуются через RabbitMQ. Чтение истории и API истории не входят в эту capability. - Technical logger формирует JSON с фиксированными полями и пишет в stdout; platform agent отвечает за доставку и просмотр. ## Risks / Trade-offs - Отсутствие индивидуального worker API упрощает управление приложением; уникальные имена нужны для конфигурации, регистрации и health. - Повторяющиеся setting keys требуют упорядоченного списка значений; adapter не сводит их к одной строке. - Приложению нужно подключить один route bundle и включить миграции до запуска адаптеров. - Изменение публичных контрактов текущего скелета требует отдельной версии PLBA2 и осознанной миграции потребителей. ## Migration Plan 1. Реализовать core contracts для application identity, worker runtime, health, workflow, двух слоёв конфигурации и business trace. 2. Добавить YAML loader dependency и PostgreSQL adapters; не добавлять RabbitMQ extra. 3. Включить создание `settings`, `trace_contexts` и `trace_messages` в первые миграции каждого приложения. 4. Перевести приложения на named workers, единый route bundle, SettingsReader, business trace adapter и JSON stdout formatter. 5. Выпустить новую major-версию; при откате вернуть предыдущую версию пакета, не удаляя данные приложений. ## Open Questions Нет. HTTP host и единственный listener остаются у приложения; PLBA2 отдаёт подключаемый router.