web-frontend/docs/tz/database-model.md

8. Структура данных и модель базы данных

8.1 Общие положения

Основное хранилище данных программного продукта реализуется на PostgreSQL. Прикладной доступ к данным осуществляется через Prisma ORM.

Модель данных должна обеспечивать хранение:

• пользователей и ролей
• компаний и профилей контрагентов
• адресов доставки
• каталога и складских остатков
• корзины и ее позиций
• заявок и заказов
• событий изменения статусов
• уведомлений и мессенджерных подключений
• бонусных и реферальных сущностей

8.2 Логические группы сущностей

В модели базы данных выделяются следующие логические группы:

• справочник пользователей и компаний
• каталог и складской контур
• заказный контур
• контур уведомлений и мессенджеров
• бонусный и реферальный контур
• административные настройки каталога

8.3 Справочник пользователей и компаний

Базовые сущности группы:

• User
• Company
• CounterpartyProfile
• DeliveryAddress
• RegistrationRequest
• Invitation
• MessengerConnection

Назначение группы:

• хранение учетных записей пользователей
• хранение принадлежности пользователя к компании
• хранение полного профиля контрагента
• хранение адресов доставки
• хранение заявок на подключение и приглашений
• хранение подключений Telegram и MAX

Связи группы:

• одна компания может иметь нескольких пользователей
• один пользователь может иметь один профиль контрагента
• один пользователь может иметь несколько адресов доставки
• один пользователь может иметь несколько подключенных мессенджеров

8.4 Каталог и складской контур

Базовые сущности группы:

• Product
• Warehouse
• ProductStock
• CatalogProductTypeSetting

Назначение группы:

• хранение товарных позиций и SKU
• хранение параметров товара
• хранение остатков по складам
• хранение правил отображения и кастомизации по типам товара

Основные поля сущности Product:

• sku
• name
• productType
• widthMm
• lengthM
• thicknessMicron
• sleeveBrand
• quantityPerBox
• tags
• description
• isCustomizable
• isActive

Основные поля сущности CatalogProductTypeSetting:

• признак показа транспортных и упаковочных параметров
• разрешение на индивидуальную длину
• минимальная, максимальная длина и шаг
• разрешение на индивидуальную втулку
• разрешение на индивидуальную надпись
• списки стандартных значений ширины, длины, толщины, втулки, цвета и надписи

8.5 Корзина и заказный контур

Базовые сущности группы:

• Cart
• CartItem
• Order
• OrderItem
• OrderStatusEvent

Назначение группы:

• хранение состава клиентской корзины
• фиксация параметров выбранного товара
• хранение заявки и заказа
• хранение истории изменения статусов

Ключевые особенности:

• корзина привязана к конкретному пользователю
• позиции корзины хранят снимок SKU, имени товара и параметров
• заказ хранит состав позиций, статус, стоимость, условия поставки и историю изменений
• события статуса обеспечивают аудит переходов между состояниями

8.6 Бонусный и реферальный контур

Базовые сущности группы:

• ReferralLink
• BonusTransaction
• RewardWithdrawalRequest

Назначение группы:

• хранение реферальных связей между клиентами
• хранение бонусных начислений и списаний
• хранение заявок на использование либо вывод бонусов

8.7 Основные связи между сущностями

Укрупненная структура связей определяется следующими правилами:

• Company объединяет пользователей одной клиентской организации
• User связан с CounterpartyProfile, DeliveryAddress, MessengerConnection, Cart, Order, BonusTransaction и RewardWithdrawalRequest
• Cart содержит набор CartItem, привязанных к конкретным Product
• Order содержит набор OrderItem и историю OrderStatusEvent
• Product связан с остатками ProductStock, распределенными по сущностям Warehouse
• настройки параметров по товарному направлению хранятся в CatalogProductTypeSetting
• реферальные связи реализуются через ReferralLink, связывающий одного пользователя с другим пользователем

8.8 Требования к хранению прикладных данных

Модель базы данных должна обеспечивать:

• уникальность ключевых идентификаторов
• хранение дат создания и изменения сущностей
• хранение параметров товарных позиций в структурированном виде
• хранение истории статусов и действий
• хранение интеграционных идентификаторов для связи с внешними системами

8.9 Требования к расширяемости модели

Структура базы данных должна позволять:

• добавлять новые типы продукции без изменения базовой логики ролей и заказов
• расширять набор параметров каталога
• развивать бонусный контур без нарушения заказного контура
• расширять интеграции с 1С и иными внешними системами