Tracium

время чтения ~4 мин.

Схемы PostgreSQL

NOTE

Статус: Target schemas. Описание целевых схем данных. Миграции и реальные таблицы в backend/migrations/ могут отставать от документа. Правила маркировки — в 50-processes/documentation-standard.md.

Все DDL и миграции для PostgreSQL. Источник истины по структуре primary store, event store, outbox и справочников.

Структура

postgres/
├── README.md               # ← этот файл
├── ERD.mermaid             # Entity Relationship Diagram (TBD)
├── migrations/             # версионированные миграции
│   ├── 001_core.sql        # core: characteristic, unit, manufacturer, ...
│   ├── 002_catalog.sql     # canonical_product + characteristics storage
│   ├── 003_offers.sql      # supplier_offer, supplier_offer_observation, stock, raw payload metadata
│   ├── 004_pricing.sql     # price_rule, customer_pricing_group, customer, contract
│   ├── 005_identity.sql    # identity_profile
│   ├── 006_event_store.sql # event_store, snapshot_store, outbox, event_store_archive
│   ├── 007_estimates.sql   # estimate, estimate_line, estimate_version
│   ├── 008_credentials.sql # supplier_credential, supplier_credential_group, credential_dek, credential_decrypt_audit
│   ├── 009_supplier_graph.sql # supplier_role, supplier_relationship, supply_chain_trace
│   ├── 010_visibility.sql  # data_visibility_policy, policy_evaluation_audit
│   └── 011_jobs.sql        # enrichment_job, async_supplier_job, supplier_session
└── descriptions/           # пояснения к таблицам
    ├── event_store.md
    ├── canonical_product.md
    ├── supplier_offer.md
    └── ...

Инструмент миграций

Рекомендация: golang-migrate или Atlas. Миграции — forward-only с дисциплиной (down-миграции не используем в продакшене). Проверка в CI: применение всех миграций на чистую БД + pg_dump --schema-only с diff с проверочным снепшотом.

Базовые таблицы (стартовый набор)

Ниже — перечень стартовых таблиц с краткими комментариями. Полные DDL — в migrations/.

Справочники

  • manufacturer — производители.
  • manufacturer_alias — альтернативные написания, привязки к manufacturer.
  • characteristic — определения атрибутов.
  • characteristic_value — enum-значения характеристик.
  • unit — единицы измерения.
  • unit_alias — алиасы.
  • supplier — поставщики (ETM, …).
  • supplier_warehouse — склады поставщика.

Идентичность

  • identity_profile — профили идентичности.
  • identity_profile_matcher — JSONB-предикат.
  • identity_profile_critical_attrs — список characteristic.key.

Каталог

  • canonical_product — канонические товары.
  • canonical_characteristic — характеристики (JSONB или normalized).
  • canonical_classification_tag — теги классификации (опциональные).
  • canonical_content — контент (описание, media refs).
  • equivalence_class — классы эквивалентности.
  • equivalence_member — члены класса.

Предложения

  • supplier_offer — предложения поставщиков (товарная канва, без цен/остатков).
  • supplier_offer_characteristic — характеристики offer’а до матчинга.
  • supplier_offer_observation — append-only наблюдения (цены/остатки/условия) per (SupplierOffer, SupplierCredential). Источник для offer.observation.v1 Kafka topic.
  • supplier_offer_stock — текущие остатки по складам (read-model, проекция из observations).
  • raw_payload_ref — ссылки на S3-объекты raw payloads.

Ценообразование

  • price_rule — правила ценообразования.
  • customer_pricing_group — группы клиентов, объединённые общим набором Price Rules (b2c_retail, b2b_standard, …).
  • customer — клиенты.
  • contract — договоры B2B.

Учётные данные и шифрование (см. ADR-0009, ADR-0010, ADR-0018)

  • supplier_credential — учётные записи доступа к API поставщиков.
  • supplier_credential_group — группа дедуплицированных credentials с одинаковым fingerprint.
  • credential_dek — per-customer Data Encryption Keys (зашифрованы master key через MasterKeyProvider).
  • credential_decrypt_audit — лог расшифровок credentials (включая break-glass).

Граф поставщиков (см. ADR-0013, ADR-0017)

  • supplier — узлы графа поставщиков.
  • supplier_role — multi-role записи (api_provider, warehouse_operator, …).
  • supplier_relationship — направленные рёбра (aggregates / resells / is_agent_of / …).
  • supply_chain_trace — вычисленные snapshots цепочек supply chain per offer.
  • supplier_role_kind, supplier_relationship_kind — расширяемые kind dictionaries (см. ADR-0016).

Видимость (см. ADR-0012)

  • data_visibility_policy — правила видимости данных.
  • policy_evaluation_audit — sampled audit evaluation’ов (для отладки и compliance).

Хранение через события (см. ADR-0003, ADR-0020)

  • event_store — все события event-sourced агрегатов.
  • event_store_archive — архив событий агрегатов в терминальном состоянии или ≥ 365 дней без активности.
  • snapshot_store — snapshots для быстрого восстановления.
  • outbox — outbox для Kafka publishing (читается outbox-relay).

Сметы

  • estimate — сметы.
  • estimate_line — строки.
  • estimate_version — версии сметы.

Модерация

  • moderation_queue — задачи на модерацию.
  • supplier_attribute_alias — pending алиасы характеристик от поставщиков (на модерации).
  • manufacturer_alias — известные написания производителей.

Операционные таблицы

  • supplier_session — сессии / токены поставщиков (per credential).
  • async_supplier_job — long-running jobs у поставщиков (отчёты, выгрузки прайса).
  • enrichment_job — async обогащение (discovery, refresh, и т.д.) — см. 30-services/enrichment/.
  • connector_config_override — runtime override’ы конфигов коннекторов (для hot reload, см. 40-operations/rate-limits.md).

Конвенции именования

  • Таблицы — snake_case, единственное число.
  • Первичный ключ — id uuid для бизнес-сущностей, bigserial для служебных (event_store, outbox).
  • Foreign keys — <referenced_table>_id.
  • Timestamps — timestamptz, с именем created_at, updated_at, occurred_at.
  • Индексы — <table>_<columns>_idx.
  • Unique constraints — <table>_<columns>_uq.

Что в этом репо НЕ должно быть

  • Прямых UPDATE/INSERT из кода минуя соответствующие модули ядра.
  • “Manual migrations” в проде. Всё через инструмент.
  • Расходящегося с кодом состояния — проверяется CI.

Что ещё предстоит оформить

  • ERD.mermaid — сгенерируем после стабилизации начальных миграций.
  • Индексная стратегия для JSONB характеристик — отдельный документ.
  • Partitioning стратегия для event_store / outbox при росте.

Вид графа

Обратные ссылки