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

## 7.1 Общие положения

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

![Схема модели данных](/diagrams/database-overview.svg)

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

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

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

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

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

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

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

- `User`
- `Company`
- `CounterpartyProfile`
- `DeliveryAddress`
- `RegistrationRequest`
- `Invitation`
- `MessengerConnection`

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

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

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

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

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

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

- `Product`
- `Warehouse`
- `ProductStock`
- `CatalogProductTypeSetting`

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

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

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

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

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

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

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

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

- `Cart`
- `CartItem`
- `Order`
- `OrderItem`
- `OrderStatusEvent`

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

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

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

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

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

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

- `ReferralLink`
- `BonusTransaction`
- `RewardWithdrawalRequest`

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

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

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

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

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

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

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

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

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

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

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