498 lines
15 KiB
Markdown
498 lines
15 KiB
Markdown
# 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 Структура хранения и модель базы данных
|
||
|
||
|
||
|
||
Модель базы данных должна обеспечивать:
|
||
|
||
- уникальность ключевых идентификаторов
|
||
- хранение дат создания и изменения сущностей
|
||
- хранение параметров товарных позиций в структурированном виде
|
||
- хранение истории статусов и действий
|
||
- хранение интеграционных идентификаторов для связи с внешними системами
|
||
- расширение состава параметров товаров без разрушения базовой структуры ролей и заказов
|