6.4 KiB
Capability: Бизнес-история приложения
Purpose
Сохранять ход бизнес-операций в trace_contexts и trace_messages схемы приложения.
Границы
- В capability входят контракты trace_contexts и trace_messages и PostgreSQL adapter для записи в схему приложения. Таблицы и миграции принадлежат приложению; API просмотра истории не входит в capability.
Requirements
Requirement: Персистентная бизнес-история
ID: OBS.BT-01
PLBA2 SHALL предоставлять приложению контракт и PostgreSQL-адаптер для записи бизнес-контекстов и сообщений в БД приложения.
Scenario: Запись сообщения бизнес-операции
Участники
- Прикладной workflow, business trace adapter и схема БД приложения.
Предусловия
- Приложение установило business trace context и передало адаптеру пул PostgreSQL и схему приложения.
Основной поток
- Создаём контекст — адаптер сохраняет его в
trace_contextsпо OBS.BT-01.FR-01. - Записываем шаг операции — адаптер сохраняет сообщение в
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; приложение выбирает политику ошибки |