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

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

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

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

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

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

В прикладной реализации должны использоваться фактические сущности базы данных, определенные в schema.prisma. Наименование сущностей в документации и в базе данных должно сопоставляться однозначно.

4.2 Справочник сущностей базы данных

Модель в базе данных	Русское наименование	Назначение
Company	Компания	Клиентская организация
User	Пользователь	Учетная запись клиента, менеджера или суперменеджера
DeliveryAddress	Адрес доставки	Справочник адресов доставки клиента
CounterpartyProfile	Профиль контрагента	Юридические и банковские реквизиты клиента
RegistrationRequest	Заявка на подключение	Самостоятельная заявка клиента на подключение
Invitation	Приглашение	Менеджерское приглашение на регистрацию
MessengerConnection	Подключение мессенджера	Связка пользователя с Telegram или MAX
Product	Товар	Карточка товарной позиции каталога
CatalogProductTypeSetting	Настройки типа товара	Правила параметров и кастомизации по товарному направлению
Cart	Корзина	Корзина клиента
CartItem	Позиция корзины	Конкретный выбранный товар в корзине
Warehouse	Склад	Справочник складов
ProductStock	Складской остаток	Остаток товара на складе
Order	Заказ / заявка	Единая заказная сущность для готовой продукции и расчета
OrderItem	Позиция заказа	Состав заказа
OrderStatusEvent	Событие статуса заказа	История изменения статусов
ReferralLink	Реферальная связь	Связь между рекомендателем и приглашенным клиентом
BonusTransaction	Бонусная транзакция	Начисление или списание бонусов
RewardWithdrawalRequest	Заявка на вывод бонусов	Заявка клиента на использование или вывод бонусов

4.3 Служебные перечисления и статусы

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

• UserRole: CLIENT, MANAGER, SUPER_MANAGER
• RegistrationStatus: PENDING, APPROVED, REJECTED
• MessengerType: TELEGRAM, MAX
• OrderKind: READY, CALCULATION
• OrderStatus: NEW, MANAGER_PROCESSING, WAITING_DOUBLE_CONFIRM, CLIENT_REJECTED, MANAGER_REJECTED, MANAGER_BLOCKED, CONFIRMED, IN_PROGRESS, COMPLETED
• WithdrawalStatus: PENDING, APPROVED, REJECTED

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

4.4.1 Company

Русское наименование: Компания

Назначение:

• хранение клиентской организации
• объединение пользователей одной компании

Основные поля:

• id
• name
• inn
• createdAt
• updatedAt

Связи:

• одна компания связана со многими пользователями

4.4.2 User

Русское наименование: Пользователь

Назначение:

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

Основные поля:

• id
• email
• fullName
• role
• companyId
• defaultDeliveryAddressId
• createdAt
• updatedAt

Связи:

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

4.4.3 DeliveryAddress

Русское наименование: Адрес доставки

Назначение:

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

Основные поля:

• id
• userId
• label
• address
• unrestrictedValue
• fiasId
• createdAt
• updatedAt

4.4.4 CounterpartyProfile

Русское наименование: Профиль контрагента

Назначение:

• хранение полных реквизитов клиента для договоров, счетов и поставки

Основные поля:

• id
• userId
• companyName
• companyFullName
• inn
• kpp
• ogrn
• legalAddress
• bankName
• bik
• correspondentAccount
• checkingAccount
• signerFullName
• signerPosition
• signerBasis
• createdAt
• updatedAt

4.4.5 RegistrationRequest

Русское наименование: Заявка на подключение

Назначение:

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

Основные поля:

• id
• companyName
• inn
• contactName
• email
• status
• rejectionReason
• requesterId
• reviewedById
• createdAt
• updatedAt

4.4.6 Invitation

Русское наименование: Приглашение

Назначение:

• хранение менеджерского приглашения клиента на регистрацию

Основные поля:

• id
• token
• email
• companyName
• managerId
• acceptedById
• expiresAt
• acceptedAt
• createdAt

4.4.7 MessengerConnection

Русское наименование: Подключение мессенджера

Назначение:

• хранение подключенного Telegram или MAX-канала пользователя

Основные поля:

• id
• userId
• type
• channelId
• displayName
• username
• avatarFileId
• avatarFileUniqueId
• isActive
• createdAt

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

4.5.1 Product

Русское наименование: Товар

Назначение:

• хранение карточки товарной позиции каталога
• хранение параметров товара и признаков кастомизации

Основные поля:

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

4.5.2 CatalogProductTypeSetting

Русское наименование: Настройки типа товара

Назначение:

• хранение правил параметров по товарному направлению
• хранение разрешений на кастомизацию

Основные поля:

• id
• productType
• showQuantityPerBox
• allowCustomLength
• customLengthMinM
• customLengthMaxM
• customLengthStepM
• allowCustomSleeveBrand
• allowCustomLabel
• widthOptionsMm
• lengthOptionsM
• thicknessOptionsMicron
• sleeveOptions
• colorOptions
• labelOptions
• createdAt
• updatedAt

4.5.3 Warehouse

Русское наименование: Склад

Назначение:

• хранение справочника складов

Основные поля:

• id
• code
• name
• createdAt
• updatedAt

4.5.4 ProductStock

Русское наименование: Складской остаток

Назначение:

• хранение остатка товара на конкретном складе

Основные поля:

• id
• productId
• warehouseId
• availableQty
• updatedAt

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

4.6.1 Cart

Русское наименование: Корзина

Назначение:

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

Основные поля:

• id
• userId
• deliveryAddressId
• createdAt
• updatedAt

4.6.2 CartItem

Русское наименование: Позиция корзины

Назначение:

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

Основные поля:

• id
• cartId
• productId
• productName
• sku
• isCustomizable
• quantity
• parameters
• createdAt
• updatedAt

4.6.3 Order

Русское наименование: Заказ / заявка

Назначение:

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

Основные поля:

• id
• code
• kind
• customerId
• deliveryAddressId
• deliveryAddress
• managerId
• status
• clientApproved
• managerApproved
• blockReason
• deliveryTerms
• deliveryFee
• totalPrice
• calculationPayload
• createdAt
• updatedAt

Комментарий к модели:

• kind = READY означает сценарий заказа готовой продукции
• kind = CALCULATION означает сценарий расчета индивидуальной продукции
• поле calculationPayload хранит параметры расчетной заявки

4.6.4 OrderItem

Русское наименование: Позиция заказа

Назначение:

• хранение состава заказа

Основные поля:

• id
• orderId
• productId
• productName
• quantity
• unitPrice
• createdAt

4.6.5 OrderStatusEvent

Русское наименование: Событие статуса заказа

Назначение:

• хранение истории изменения статусов заказа или заявки

Основные поля:

• id
• orderId
• status
• actorUserId
• note
• createdAt

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

4.7.1 ReferralLink

Русское наименование: Реферальная связь

Назначение:

• фиксация связи между рекомендателем и приглашенным клиентом

Основные поля:

• id
• referrerId
• refereeId
• createdById
• bonusPercent
• createdAt

4.7.2 BonusTransaction

Русское наименование: Бонусная транзакция

Назначение:

• хранение начисления или списания бонусов

Основные поля:

• id
• userId
• amount
• reason
• orderId
• referralLinkId
• createdAt

4.7.3 RewardWithdrawalRequest

Русское наименование: Заявка на вывод бонусов

Назначение:

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

Основные поля:

• id
• requesterId
• amount
• status
• reviewedById
• reviewComment
• createdAt
• updatedAt

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

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

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

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

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

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