web-frontend/docs/tz/data-entities.md

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 Структура хранения и модель базы данных

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

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