diff --git a/docs/tz/data-entities.md b/docs/tz/data-entities.md index da7b504..49d0914 100644 --- a/docs/tz/data-entities.md +++ b/docs/tz/data-entities.md @@ -11,82 +11,225 @@ - адресов доставки - каталога и складских остатков - корзины и ее позиций -- заявок и заказов +- заказов и расчетных заявок - событий изменения статусов -- уведомлений и мессенджерных подключений +- подключений мессенджеров - бонусных и реферальных сущностей -## 4.2 Логические группы сущностей +В прикладной реализации должны использоваться фактические сущности базы данных, определенные в `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 Пользователи и компании +## 4.3 Служебные перечисления и статусы -Базовые сущности группы: +В модели данных используются следующие перечисления: -- `User` -- `Company` -- `CounterpartyProfile` -- `DeliveryAddress` -- `RegistrationRequest` -- `Invitation` -- `MessengerConnection` +- `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 Пользователи и компании -- хранение учетных записей пользователей -- хранение принадлежности пользователя к компании -- хранение полного профиля контрагента -- хранение адресов доставки -- хранение заявок на подключение и приглашений -- хранение подключений Telegram и MAX +### 4.4.1 Company -Обязательные данные: +Русское наименование: `Компания` -- пользователь: идентификатор, имя, email, телефон, роль, статус, связанная компания -- компания: идентификатор, наименование, ИНН, КПП, юридический адрес, закрепленный менеджер -- профиль контрагента: реквизиты, контактные лица, служебные признаки синхронизации -- адрес доставки: идентификатор, владелец, адрес, комментарий, признак основного адреса -- заявка на подключение: инициирующая компания или контакт, статус, дата создания, комментарий менеджера -- приглашение: получатель, токен или ссылка, срок действия, статус использования -- подключение мессенджера: тип канала, внешний идентификатор, статус подключения +Назначение: -## 4.4 Каталог и складской контур +- хранение клиентской организации +- объединение пользователей одной компании -Базовые сущности группы: +Основные поля: -- `Product` -- `Warehouse` -- `ProductStock` -- `CatalogProductTypeSetting` +- `id` +- `name` +- `inn` +- `createdAt` +- `updatedAt` -Назначение группы: +Связи: -- хранение товарных позиций и SKU -- хранение параметров товара -- хранение остатков по складам -- хранение правил отображения и кастомизации по типам товара +- одна компания связана со многими пользователями -Обязательные данные по товару: +### 4.4.2 User -- внутренний идентификатор -- SKU -- наименование -- тип продукции -- доступные параметры выбора -- доступные варианты товара -- складские остатки -- признаки доступности и кастомизации +Русское наименование: `Пользователь` -Основные поля сущности `Product`: +Назначение: +- хранение клиентской, менеджерской или административной учетной записи +- связывание пользователя с заказами, корзиной, бонусами и адресами + +Основные поля: + +- `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` @@ -99,68 +242,236 @@ - `description` - `isCustomizable` - `isActive` +- `createdAt` +- `updatedAt` -Основные поля сущности `CatalogProductTypeSetting`: +### 4.5.2 CatalogProductTypeSetting -- разрешение на индивидуальную длину -- минимальная, максимальная длина и шаг -- разрешение на втулку с логотипом -- разрешение на индивидуальную надпись -- списки стандартных значений ширины, длины, толщины, втулки, цвета и надписи -- пользовательские описания параметров +Русское наименование: `Настройки типа товара` -## 4.5 Корзина, заявки и заказы +Назначение: -Базовые сущности группы: +- хранение правил параметров по товарному направлению +- хранение разрешений на кастомизацию -- `Cart` -- `CartItem` -- `Order` -- `OrderItem` -- `OrderStatusEvent` +Основные поля: -Дополнительно в прикладной модели должны существовать сущности сценариев: +- `id` +- `productType` +- `showQuantityPerBox` +- `allowCustomLength` +- `customLengthMinM` +- `customLengthMaxM` +- `customLengthStepM` +- `allowCustomSleeveBrand` +- `allowCustomLabel` +- `widthOptionsMm` +- `lengthOptionsM` +- `thicknessOptionsMicron` +- `sleeveOptions` +- `colorOptions` +- `labelOptions` +- `createdAt` +- `updatedAt` -- заявка на заказ -- заявка на расчет индивидуальной продукции +### 4.5.3 Warehouse -Назначение группы: +Русское наименование: `Склад` -- хранение состава клиентской корзины -- фиксация параметров выбранного товара -- хранение заказной заявки и расчетной заявки -- хранение заказа и истории изменения статусов +Назначение: -Обязательные данные: +- хранение справочника складов -- корзина: идентификатор, владелец, состав позиций, даты создания и изменения -- позиция корзины: товар, снимок параметров, количество, комментарий -- заявка на заказ: идентификатор, пользователь-клиент, дата создания, состав позиций, комментарий, статус, закрепленный менеджер, стоимость после обработки, условия поставки -- заявка на расчет: идентификатор, пользователь-клиент, дата создания, тип продукции, параметры изделия, комментарий, статус, закрепленный менеджер, стоимость после обработки, условия поставки -- заказ: внутренний идентификатор, внешний идентификатор учетной системы, статус, состав заказа, стоимость, условия поставки, ссылка на исходную заявку -- событие статуса: объект, предыдущее состояние, новое состояние, дата и время, источник изменения, комментарий +Основные поля: -## 4.6 Бонусный и реферальный контур +- `id` +- `code` +- `name` +- `createdAt` +- `updatedAt` -Базовые сущности группы: +### 4.5.4 ProductStock -- `ReferralLink` -- `BonusTransaction` -- `RewardWithdrawalRequest` +Русское наименование: `Складской остаток` -Назначение группы: +Назначение: -- хранение реферальных связей между клиентами -- хранение бонусных начислений и списаний -- хранение заявок на использование либо вывод бонусов +- хранение остатка товара на конкретном складе -Обязательные данные: +Основные поля: -- реферальная связь: участники связи, дата создания, статус -- бонусная операция: идентификатор операции, клиент, тип операции, сумма или объем операции, основание операции, дата и время, текущий статус -- заявка на использование или вывод: клиент, тип действия, сумма, статус, комментарии менеджера +- `id` +- `productId` +- `warehouseId` +- `availableQty` +- `updatedAt` -## 4.7 Основные связи между сущностями +## 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 Основные связи между сущностями Укрупненная структура связей определяется следующими правилами: @@ -172,7 +483,7 @@ - настройки параметров по товарному направлению хранятся в `CatalogProductTypeSetting` - реферальные связи реализуются через `ReferralLink`, связывающий одного пользователя с другим пользователем -## 4.8 Структура хранения и модель базы данных +## 4.9 Структура хранения и модель базы данных ![Укрупненная модель базы данных](/diagrams/database-model.svg) diff --git a/docs/tz/stage-1/index.md b/docs/tz/stage-1/index.md index b0abee7..9ab213e 100644 --- a/docs/tz/stage-1/index.md +++ b/docs/tz/stage-1/index.md @@ -26,7 +26,59 @@ | Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом | | Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы | -## 5.2 Общие требования к экранным формам +## 5.2 Текущие маршруты и экранные формы по реализации + +Ниже приведен перечень фактически существующих страниц текущего frontend-контура. + +### 5.2.1 Публичные и клиентские страницы + +| Маршрут | Экран | Назначение | +| --- | --- | --- | +| `/` | Главная страница | Стартовая страница личного кабинета | +| `/login` | Вход | Вход и первичный сценарий доступа | +| `/products` | Каталог продукции | Список товарных направлений | +| `/products/[slug]` | Карточка товара | Выбор параметров, просмотр вариантов, добавление в корзину | +| `/cart` | Корзина | Состав выбранных позиций и отправка заявки | +| `/client-orders` | Список заказов клиента | История заявок и заказов клиента | +| `/client-orders/[id]` | Карточка заказа клиента | Детали конкретного заказа клиента | +| `/notifications` | Уведомления | Список системных уведомлений | +| `/bonus-program` | Бонусный кабинет | Бонусный баланс, подарочные карты и бонусные действия | + +### 5.2.2 Профиль клиента + +| Маршрут | Экран | Назначение | +| --- | --- | --- | +| `/profile` | Профиль | Основные данные пользователя | +| `/profile/counterparty` | Реквизиты контрагента | Юридические и банковские данные | +| `/profile/addresses` | Адреса доставки | Список адресов доставки | +| `/profile/addresses/new` | Новый адрес доставки | Создание адреса доставки | +| `/profile/notifications` | Настройки уведомлений | Подключение и настройка каналов уведомлений | +| `/profile/notifications/success` | Успешное подключение уведомлений | Финальный экран сценария подключения канала | + +### 5.2.3 Менеджерские и административные страницы + +| Маршрут | Экран | Назначение | +| --- | --- | --- | +| `/clients` | Клиенты | Список клиентских компаний и пользователей | +| `/clients/[id]` | Карточка клиента | Детали клиента, его заказы и бонусные данные | +| `/clients/invite` | Пригласить клиента | Создание приглашения на регистрацию | +| `/orders` | Список заказов | Очередь заказов и заявок для менеджера | +| `/orders/[id]` | Карточка заказа | Обработка стоимости, условий поставки и статуса | +| `/catalog-settings` | Настройки каталога | Параметры товарных направлений и кастомизации | +| `/settings-sync` | 1С / синхронизация | Управление и мониторинг синхронизации | +| `/messages` | Сообщения | Шаблоны и тексты менеджерских сообщений | + +### 5.2.4 Бонусный менеджерский контур + +| Маршрут | Экран | Назначение | +| --- | --- | --- | +| `/bonus-system` | Бонусная система | Список клиентов и бонусных сущностей | +| `/bonus-system/[userId]` | Карточка бонусного счета клиента | История и состояние бонусного счета | +| `/bonus-system/referrals/new` | Создать бонусный счет | Создание реферальной связи | +| `/bonus-system/transactions/new` | Добавить бонусную транзакцию | Ручное начисление или списание | +| `/bonus-system/withdrawals/[id]` | Проверка заявки на вывод | Рассмотрение заявки клиента на вывод бонусов | + +## 5.3 Общие требования к экранным формам Экранные формы должны обеспечивать: @@ -42,9 +94,9 @@ - остатки и доступные варианты отображаются в наглядном виде - пользователь понимает ограничения выбора и возможность кастомизации -## 5.3 Клиентские экранные формы +## 5.4 Клиентские экранные формы -### 5.3.1 Главная страница клиента +### 5.4.1 Главная страница клиента Назначение страницы: @@ -64,7 +116,7 @@ ![Прототип главной страницы клиента](/prototypes/dashboard.svg) -### 5.3.2 Каталог продукции +### 5.4.2 Каталог продукции Назначение страницы: @@ -83,7 +135,7 @@ ![Прототип каталога продукции](/prototypes/catalog-grid.svg) -### 5.3.3 Карточка товара +### 5.4.3 Карточка товара Назначение страницы: @@ -103,6 +155,10 @@ - таблица доступных вариантов - блок навигации к соседним товарным направлениям +Текущий маршрут реализации: + +- `/products/[slug]` + Схематичный прототип: ![Прототип карточки товара](/prototypes/product-card.svg) @@ -124,7 +180,7 @@ - правила по втулке с логотипом - правила по нанесению индивидуальной надписи -### 5.3.4 Корзина +### 5.4.4 Корзина Назначение страницы: @@ -146,7 +202,7 @@ ![Прототип корзины](/prototypes/cart.svg) -### 5.3.5 Карточка заявки или заказа +### 5.4.5 Карточка заявки или заказа Назначение страницы: @@ -169,7 +225,7 @@ - история статусов - системные комментарии -### 5.3.6 Страница логина и регистрации +### 5.4.6 Страница логина и регистрации Назначение страницы: @@ -184,7 +240,7 @@ - ссылка на самостоятельную заявку на подключение - блок пояснения по дальнейшему сценарию доступа -### 5.3.7 Список заказов +### 5.4.7 Список заказов Назначение страницы: @@ -197,13 +253,13 @@ - таблица заказов - переход в карточку конкретного заказа -### 5.3.8 Уведомления +### 5.4.8 Уведомления Назначение страницы: - просмотр истории уведомлений по заказам, заявкам и бонусным операциям -### 5.3.9 Бонусный кабинет +### 5.4.9 Бонусный кабинет Назначение страницы: @@ -223,9 +279,9 @@ ![Прототип бонусного кабинета](/prototypes/bonus-cabinet.svg) -## 5.4 Менеджерские экранные формы +## 5.5 Менеджерские экранные формы -### 5.4.1 Список клиентов +### 5.5.1 Список клиентов Назначение страницы: @@ -239,7 +295,7 @@ - индикаторы активности и количества заказов - действие приглашения нового клиента -### 5.4.2 Карточка клиента +### 5.5.2 Карточка клиента Назначение страницы: @@ -255,7 +311,7 @@ - список бонусных операций - связанные рефералы -### 5.4.3 Карточка обработки заявки +### 5.5.3 Карточка обработки заявки Назначение страницы: @@ -278,7 +334,7 @@ - история изменений - блок действий со статусом -### 5.4.4 Список заказов менеджера +### 5.5.4 Список заказов менеджера Назначение страницы: @@ -290,7 +346,7 @@ ![Прототип списка заказов менеджера](/prototypes/manager-orders.svg) -### 5.4.5 Настройки каталога +### 5.5.5 Настройки каталога Назначение страницы: @@ -307,7 +363,7 @@ - списки стандартных параметров - единое действие сохранения настроек -### 5.4.6 Настройки синхронизации и уведомлений +### 5.5.6 Настройки синхронизации и уведомлений Назначение страницы: @@ -320,3 +376,20 @@ - каналы отправки - статусы последних синхронизаций - диагностическая информация по обмену + +## 5.6 Дополнительные профильные и сервисные страницы + +Помимо основных клиентских и менеджерских экранов, текущая реализация содержит дополнительные экранные формы: + +- профиль пользователя +- реквизиты контрагента +- список адресов доставки +- создание нового адреса доставки +- настройки уведомлений пользователя +- экран успешного подключения канала уведомлений +- менеджерский экран сообщений +- бонусная система для менеджера +- карточка бонусного счета клиента +- создание реферальной связи +- создание бонусной транзакции +- проверка заявки на вывод бонусов