Files
alex d517820088
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
PLBA2-2. Архивация спек
2026-10-10 20:55:13 +03:00

6.0 KiB
Raw Permalink Blame History

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.
  2. Записываем шаг операции — адаптер сохраняет сообщение в trace_messages по OBS.BT-01.FR-02 и завершает с BUSINESS_TRACE_WRITTEN по OBS.BT-01.FR-03.
Альтернативы и ошибки
  • PostgreSQL недоступен или запись не выполнена — исходная ошибка передаётся приложению с BUSINESS_TRACE_WRITE_FAILED по OBS.BT-01.FR-03.
Результат

Бизнес-события сохранены отдельно от технических JSON-логов.

Коды завершения
Код Смысл Связанные FR
BUSINESS_TRACE_WRITTEN Контекст или сообщение сохранены OBS.BT-01.FR-03
BUSINESS_TRACE_WRITE_FAILED Запись в бизнес trace хранилище завершилась ошибкой OBS.BT-01.FR-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

Поле trace_id ссылается на trace_contexts.trace_id с каскадным удалением. Создаются индексы по trace_id, event_time и status. Таблица принадлежит приложению.

OBS.BT-01.FR-03: Результат записи

Приложение передаёт адаптеру пул PostgreSQL и имя своей схемы. Адаптер записывает контексты и сообщения по OBS.BT-01.FR-01 и OBS.BT-01.FR-02, добавляя application_id в attrs_json обоих типов записей. Приложение создаёт таблицы своей миграцией; PLBA2 не запускает миграции, не владеет данными, не публикует события в RabbitMQ и не реализует API истории.

Код Текст сообщения Дальнейшее поведение
BUSINESS_TRACE_WRITTEN Сообщение отсутствует Выполнение бизнес-сценария продолжается по решению приложения
BUSINESS_TRACE_WRITE_FAILED Сообщение отсутствует; исходная ошибка БД передаётся приложению PLBA2 не выполняет скрытый retry; приложение выбирает политику ошибки