Files
plba_v2/openspec/specs/observability/business-tracing/spec.md
T
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

91 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 и схему приложения.
##### Основной поток
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; приложение выбирает политику ошибки |