PLBA2-2. Архивация спек
This commit is contained in:
@@ -0,0 +1,90 @@
|
||||
# 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; приложение выбирает политику ошибки |
|
||||
Reference in New Issue
Block a user