Expand entities and page prototypes in specification

2026-05-01 15:51:51 +07:00
parent 58e9d6806d
commit e050fd55a5
2 changed files with 501 additions and 117 deletions
--- 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)

--- 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 Дополнительные профильные и сервисные страницы
+
+Помимо основных клиентских и менеджерских экранов, текущая реализация содержит дополнительные экранные формы:
+
+- профиль пользователя
+- реквизиты контрагента
+- список адресов доставки
+- создание нового адреса доставки
+- настройки уведомлений пользователя
+- экран успешного подключения канала уведомлений
+- менеджерский экран сообщений
+- бонусная система для менеджера
+- карточка бонусного счета клиента
+- создание реферальной связи
+- создание бонусной транзакции
+- проверка заявки на вывод бонусов