# Spec Delta ## Purpose Сохранять ход бизнес-операций в trace_contexts и trace_messages схемы приложения. ## ADDED Requirements ### Requirement: Персистентная бизнес-история **ID:** `OBS.BT-01` PLBA2 SHALL предоставлять приложению контракт и PostgreSQL-адаптер для записи бизнес-контекстов и сообщений в БД приложения. #### Scenario: Запись сообщения бизнес-операции ##### Участники - Прикладной workflow, business trace adapter и схема БД приложения. ##### Предусловия - Приложение установило business trace context и передало адаптеру пул PostgreSQL и схему приложения. ##### Основной поток 1. Создаём контекст — адаптер сохраняет его в `trace_contexts` по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts). 2. Записываем шаг операции — адаптер сохраняет сообщение в `trace_messages` по [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages) и завершает с `BUSINESS_TRACE_WRITTEN` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи). ##### Альтернативы и ошибки - PostgreSQL недоступен или запись не выполнена — исходная ошибка передаётся приложению с `BUSINESS_TRACE_WRITE_FAILED` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи). ##### Результат Бизнес-события сохранены отдельно от технических JSON-логов. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `BUSINESS_TRACE_WRITTEN` | Контекст или сообщение сохранены | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) | | `BUSINESS_TRACE_WRITE_FAILED` | Запись в бизнес trace хранилище завершилась ошибкой | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) | #### Функциональные требования ##### OBS.BT-01.FR-01 [DB]: Таблица хранения trace_contexts Таблица `trace_contexts` создаётся в схеме приложения и содержит: | Поле | Тип | Ограничения и значение по умолчанию | Назначение | | --- | --- | --- | --- | | `trace_id` | `UUID` | NOT NULL, primary key | Публичный `business_trace_id` контекста | | `parent_id` | `UUID` | NULL | `trace_id` родительского контекста | | `alias` | `TEXT` | NOT NULL | Короткое имя контекста | | `trace_type` | `TEXT` | NOT NULL | Тип бизнес-операции | | `event_time` | `TIMESTAMPTZ` | NOT NULL | Время создания контекста | | `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты контекста, включая `application_id` по RT.AI-01.FR-01 | Создаются индексы по `parent_id` и `event_time`. Таблица принадлежит приложению. ##### OBS.BT-01.FR-02 [DB]: Таблица хранения trace_messages Таблица `trace_messages` создаётся в схеме приложения и содержит: | Поле | Тип | Ограничения и значение по умолчанию | Назначение | | --- | --- | --- | --- | | `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор сообщения | | `trace_id` | `UUID` | NOT NULL | `trace_id` контекста | | `event_time` | `TIMESTAMPTZ` | NOT NULL | Время сообщения | | `step` | `TEXT` | NOT NULL | Имя шага бизнес-операции | | `status` | `TEXT` | NOT NULL | Результат шага | | `level` | `TEXT` | NOT NULL | Уровень бизнес-сообщения | | `message` | `TEXT` | NOT NULL | Текст бизнес-сообщения | | `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты сообщения, включая `application_id` по [RT.AI-01.FR-01](../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) | Поле `trace_id` ссылается на `trace_contexts.trace_id` с каскадным удалением. Создаются индексы по `trace_id`, `event_time` и `status`. Таблица принадлежит приложению. ##### OBS.BT-01.FR-03: Результат записи Приложение передаёт адаптеру пул PostgreSQL и имя своей схемы. Адаптер записывает контексты и сообщения по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts) и [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages), добавляя `application_id` в `attrs_json` обоих типов записей. Приложение создаёт таблицы своей миграцией; PLBA2 не запускает миграции, не владеет данными, не публикует события в RabbitMQ и не реализует API истории. | Код | Текст сообщения | Дальнейшее поведение | | --- | --- | --- | | `BUSINESS_TRACE_WRITTEN` | Сообщение отсутствует | Выполнение бизнес-сценария продолжается по решению приложения | | `BUSINESS_TRACE_WRITE_FAILED` | Сообщение отсутствует; исходная ошибка БД передаётся приложению | PLBA2 не выполняет скрытый retry; приложение выбирает политику ошибки |