PLBA2-2. Реализация

This commit is contained in:
2026-10-10 19:36:32 +03:00
parent 473cde126f
commit 71998a6b13
120 changed files with 3675 additions and 21 deletions
+77
View File
@@ -0,0 +1,77 @@
# Database contracts
PLBA2 reads and writes application-owned tables through adapters. The application
owns the schema, migrations, initial values, and retention policy. PLBA2 does not
create tables or run migrations.
## `settings`
The application creates `settings` in its own schema and loads initial rows in
its migration. The table has this contract:
| Field | Type | Constraints | Purpose |
| --- | --- | --- | --- |
| `id` | `BIGINT` | Identity primary key, not null | Row identifier and final ordering key |
| `config_key` | `VARCHAR(128)` | Nullable | Application-defined scope or entity |
| `setting_key` | `VARCHAR(128)` | Not null | Stable setting name |
| `setting_value` | `TEXT` | Not null | Text value decoded by the application |
| `sort_order` | `INT` | Not null, default `0` | Order for repeated keys |
| `is_enabled` | `BOOLEAN` | Not null, default `TRUE` | Includes or excludes a row from reads |
| `description` | `TEXT` | Nullable | Human-readable explanation |
Indexes should support the adapter's filters and ordering, for example:
```sql
CREATE INDEX settings_key_enabled_order_idx
ON settings (setting_key, is_enabled, sort_order, id);
CREATE INDEX settings_scope_lookup_order_idx
ON settings (setting_key, config_key, is_enabled, sort_order, id);
```
There is no uniqueness constraint on `setting_key`; several enabled rows may
form an ordered list. Reads filter by `setting_key`, an optional `config_key`,
and `is_enabled = TRUE`, then order by `sort_order`, `id`. The value of a feature
toggle belongs in `setting_value`; `is_enabled` only controls whether the row is
read. `config_key` relationships are owned by the application.
`settings` stores business parameters, feature toggles, and technical values
that must change remotely while the process runs. Rarely changed technical
parameters remain in the root `config.yaml`; PLBA2 does not copy YAML into the
database.
## `trace_contexts` and `trace_messages`
The application creates both trace tables in its own schema through its own
migration. Public code calls the context identifier `business_trace_id`; both
tables store it as `trace_id`.
`trace_contexts` contains:
| Field | Type | Constraints | Purpose |
| --- | --- | --- | --- |
| `trace_id` | `UUID` | Primary key, not null | Public `business_trace_id` |
| `parent_id` | `UUID` | Nullable | Parent context identifier |
| `alias` | `TEXT` | Not null | Short context name |
| `trace_type` | `TEXT` | Not null | Business operation type |
| `event_time` | `TIMESTAMPTZ` | Not null | Context creation time |
| `attrs_json` | `JSONB` | Not null | Context attributes, including `application_id` |
Create indexes on `parent_id` and `event_time`.
`trace_messages` contains:
| Field | Type | Constraints | Purpose |
| --- | --- | --- | --- |
| `id` | `BIGINT` | Identity primary key, not null | Message identifier |
| `trace_id` | `UUID` | Not null, references `trace_contexts.trace_id` with `ON DELETE CASCADE` | Owning context |
| `event_time` | `TIMESTAMPTZ` | Not null | Message time |
| `step` | `TEXT` | Not null | Business step name |
| `status` | `TEXT` | Not null | Step result |
| `level` | `TEXT` | Not null | Business message level |
| `message` | `TEXT` | Not null | Human-readable business message |
| `attrs_json` | `JSONB` | Not null | Message attributes, including `application_id` |
Create indexes on `trace_id`, `event_time`, and `status`. The PostgreSQL
adapter only inserts rows, adds the runtime `application_id` to each
`attrs_json`, and passes database failures to the application. It does not
create tables, run migrations, publish RabbitMQ events, or expose a history API.