PLBA2-2. Архивация спек
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped

This commit is contained in:
2026-10-10 20:55:13 +03:00
parent 19fa591c31
commit d517820088
33 changed files with 1313 additions and 25 deletions
@@ -0,0 +1,86 @@
# Design
## Context
PLBA2 — библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. Изменение объединяет десять capabilities, перечисленных в [proposal.md](proposal.md), и использует PLBA v1 как ориентир для workers, health, workflow и business trace.
## Goals / Non-Goals
**Goals:**
- Запускать именованные workers независимо и управлять ими через lifecycle приложения.
- Предоставить единые contracts для lifecycle, health, workflow, HTTP API, application identity, двух слоёв конфигурации и business trace.
- Отделить business trace от технических логов.
- Позволить бизнес-коду читать настройки через `SettingsReader`, не завися от PostgreSQL-адаптера.
**Non-Goals:**
- Не создавать entrypoint, composition root, HTTP server, сервис конфигурации, хранилище/API бизнес-истории.
- Не предоставлять общую очередь рабочих заданий или RabbitMQ API для них; приложение самостоятельно читает и публикует такие сообщения.
- Не выполнять миграции приложения, не реализовывать бизнес-логику workflow и не доставлять технические логи в платформенные системы.
## Decisions
### Runtime и workers
- `runtime/worker` задаёт уникальное стабильное имя worker, его независимый lifecycle, расписание, остановку и health. Отдельных API для запуска или остановки worker нет.
- При старте приложения запускаются workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`. `disabled: true` исключает worker из запуска; изменение этого признака действует при следующем запуске приложения.
- Для включённого worker задаётся ровно одно положительное значение: `interval_seconds` или `pause_seconds`. Первый цикл начинается сразу, циклы одного worker не пересекаются. Интервал задаёт период между началами циклов; пауза задаётся после завершения цикла. Изменения расписания из активной конфигурации применяются при планировании следующего цикла.
- Graceful stop завершает текущий цикл и не запускает следующий. `force=true` прерывает активную обработку. Supervisor останавливает все запущенные workers и сообщает имена тех, кто ещё работает.
- Исключение цикла переводит автоматический health worker в `unhealthy`, но не завершает worker: runtime планирует следующий цикл. Превышение интервала даёт `degraded`; успешный следующий цикл восстанавливает автоматический статус `ok`. Итоговый статус — худший из автоматического и прикладного; прикладная health-логика не скрывает ошибку цикла.
### Lifecycle и health приложения
- `runtime/application-lifecycle` запускает все включённые workers; ошибка запуска переводит приложение в `failed`. При остановке lifecycle становится `stopped` после подтверждения остановки всех workers.
- Необязательный положительный `timeout_seconds` ограничивает ожидание ответа на stop-запрос. При истечении возвращается `stopping`, а остановка продолжается; без timeout ожидание не ограничено. Runtime не завершает OS process или HTTP host приложения.
- Health report включает `application_id`, lifecycle и состояния запущенных workers/contributors. Disabled workers не входят в набор ожидаемых компонентов. Статусы компонентов упорядочены `ok < degraded < unhealthy`; `unhealthy` некритичного компонента ограничивается до `degraded`. Отсутствующий некритичный worker даёт как минимум `degraded`, отсутствующий критичный — `unhealthy`. Lifecycle `new`/`failed` даёт `unhealthy`, `starting`/`stopping` — как минимум `degraded`, а `stopped` задаёт общий health `stopped`.
### Единый HTTP API
- `api/http/control-api` предоставляет общий route adapter, который приложение подключает к собственному HTTP host и listener. PLBA2 не запускает сервер и не открывает отдельный порт.
- Adapter предоставляет `GET /health`, `POST /runtime/start`, `POST /runtime/stop` и `GET /runtime/status`. Health делегируется aggregator, управление — lifecycle runtime; отдельные worker routes отсутствуют.
- `GET /health` возвращает health report без пересчёта в adapter. Start/status возвращают lifecycle status. Stop принимает `force` и необязательный положительный `timeout_seconds`; завершённая остановка возвращает HTTP 200 и `stopped`, продолжающаяся после timeout — HTTP 202 и `stopping`, некорректный запрос — HTTP 400.
### Workflow
- Приложение передаёт именованный `WorkflowDefinition` с начальным шагом и именованными узлами. Узел содержит `WorkflowStep` и карту переходов; шаг принимает `WorkflowContext` и возвращает `StepResult` с переходом, изменениями состояния и статусом.
- Engine применяет только объявленные переходы и не содержит бизнес-правил приложения. Переданный `WorkflowPersistence` сохраняет начало и итог запуска, начало и завершение каждого шага, snapshots контекста и ошибки.
- Исключение шага сохраняется и передаётся вызывающему коду; workflow прекращается без скрытого retry и без выполнения следующих шагов. Подключение к БД остаётся ответственностью приложения.
### Идентификатор приложения
- В корневом `config.yaml` приложение может задать необязательный строковый `application_id`. Непустое значение используется без изменений; иначе берётся `[project].name` из `pyproject.toml`, а при недоступности имени генерируется UUIDv4.
- Идентификатор разрешается до запуска зависимых компонентов, предоставляется runtime-контексту и не меняется в процессе. Сгенерированный UUIDv4 создаётся заново при следующем запуске, если имя проекта или значение в файле не заданы.
- Health report и технические логи используют этот ID; business trace adapter добавляет его в `attrs_json` контекста и каждого сообщения.
### Два слоя конфигурации
- `configuration/application-config-file` читает `config.yaml` из корня приложения по объявленной приложением типизированной модели. Общие поля PLBA2 — `application_id`, `workers.<worker_name>.disabled` (default `false`), `interval_seconds` и `pause_seconds`; остальные поля определяет приложение.
- YAML предназначен для редко меняемых технических параметров. Бизнес-параметры, feature toggles и технические значения, меняемые удалённо в runtime, хранятся в `settings`.
- Ошибка начальной загрузки файла блокирует запуск зависимых компонентов. При успешной проверке обновление атомарно заменяет активную конфигурацию без рестарта; уже полученные snapshots остаются неизменными. При ошибке перезагрузки остаётся последняя валидная конфигурация и приложению передаётся ошибка.
- `configuration/application-settings` задаёт таблицу `settings` в схеме приложения. В таблице хранятся `config_key`, `setting_key`, `setting_value`, `sort_order`, `is_enabled` и `description` вместе с идентификатором строки; уникальность `setting_key` не требуется. `is_enabled` включает строку в чтение, а значение feature toggle хранится в `setting_value`.
- Приложение создаёт таблицу `settings` и загружает начальные данные своей миграцией. PLBA2 миграции не запускает, строки не изменяет и YAML в БД не переносит.
- `SettingsReader` использует типизированные ключи и возвращает упорядоченные значения. PostgreSQL adapter читает через переданный приложением pool из его схемы, фильтрует по ключу, `config_key` и `is_enabled = TRUE`, сортирует по `sort_order`, затем `id`. Следующее чтение видит актуальные значения без рестарта.
### Business trace и технические логи
- Business trace adapter записывает контексты в `trace_contexts`, сообщения — в `trace_messages` схемы приложения. Публичный идентификатор называется `business_trace_id`, а в таблицах хранится как `trace_id`. В `attrs_json` обоих видов записей добавляется `application_id`.
- Приложение передаёт адаптеру PostgreSQL pool и имя схемы, а таблицы создаёт собственной миграцией. PLBA2 не владеет данными, не публикует business events в RabbitMQ и не предоставляет API бизнес-истории.
- Техническая запись — JSON-контракт с обязательными `timestamp`, `level`, `logger`, `message`, `application_id` и необязательными `attributes`, `business_trace_id`. Formatter использует stdlib `StreamHandler` для stdout; доставку и просмотр обеспечивает платформа.
## Risks / Trade-offs
- Если приложение не задаёт `application_id` и не имеет `[project].name`, UUIDv4 меняется между запусками; потребителям, которым нужен постоянный ID, следует задать его в `config.yaml`.
- Изменение `workers.<worker_name>.disabled` применяется только при следующем запуске приложения, тогда как валидные изменения расписания применяются при планировании следующего цикла.
- Приложению нужно владеть миграциями `settings`, `trace_contexts` и `trace_messages`, передавать PostgreSQL pool адаптерам и подключить HTTP routes к своему host.
## Migration Plan
1. Реализовать runtime, health, workflow, identity и контракты адаптеров согласно capabilities.
2. Добавить загрузку и перезагрузку `config.yaml`, PostgreSQL adapters для настроек и business trace, а также технический formatter для stdout.
3. Документировать для потребителей, что создание таблиц и начальных данных `settings`, `trace_contexts`, `trace_messages` выполняется миграциями приложения.
4. Подключить route adapter к host приложения и выпустить обновлённую версию библиотеки; миграции и изменение кода потребителей выполняются в самих приложениях.
## Open Questions
Нет. HTTP host и listener принадлежат приложению; PLBA2 предоставляет подключаемый route adapter.