# 4. Требования к данным и сущностям

## 4.1 Общие требования к данным

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

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

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

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

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

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

## 4.3 Пользователи и компании

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

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

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

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

Обязательные данные:

- пользователь: идентификатор, имя, email, телефон, роль, статус, связанная компания
- компания: идентификатор, наименование, ИНН, КПП, юридический адрес, закрепленный менеджер
- профиль контрагента: реквизиты, контактные лица, служебные признаки синхронизации
- адрес доставки: идентификатор, владелец, адрес, комментарий, признак основного адреса
- заявка на подключение: инициирующая компания или контакт, статус, дата создания, комментарий менеджера
- приглашение: получатель, токен или ссылка, срок действия, статус использования
- подключение мессенджера: тип канала, внешний идентификатор, статус подключения

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

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

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

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

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

Обязательные данные по товару:

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

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

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

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

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

## 4.5 Корзина, заявки и заказы

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

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

Дополнительно в прикладной модели должны существовать сущности сценариев:

- заявка на заказ
- заявка на расчет индивидуальной продукции

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

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

Обязательные данные:

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

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

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

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

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

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

Обязательные данные:

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

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

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

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

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

![Укрупненная модель базы данных](/diagrams/database-model.svg)

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

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