Expand entities and page prototypes in specification

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`
+- `UserRole`: `CLIENT`, `MANAGER`, `SUPER_MANAGER`
-- `Company`
+- `RegistrationStatus`: `PENDING`, `APPROVED`, `REJECTED`
-- `CounterpartyProfile`
+- `MessengerType`: `TELEGRAM`, `MAX`
-- `DeliveryAddress`
+- `OrderKind`: `READY`, `CALCULATION`
-- `RegistrationRequest`
+- `OrderStatus`: `NEW`, `MANAGER_PROCESSING`, `WAITING_DOUBLE_CONFIRM`, `CLIENT_REJECTED`, `MANAGER_REJECTED`, `MANAGER_BLOCKED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`
-- `Invitation`
+- `WithdrawalStatus`: `PENDING`, `APPROVED`, `REJECTED`
-- `MessengerConnection`
 
-Назначение группы:
+## 4.4 Пользователи и компании
 
-- хранение учетных записей пользователей
+### 4.4.1 Company
-- хранение принадлежности пользователя к компании
-- хранение полного профиля контрагента
-- хранение адресов доставки
-- хранение заявок на подключение и приглашений
-- хранение подключений Telegram и MAX
 
-Обязательные данные:
+Русское наименование: `Компания`
 
-- пользователь: идентификатор, имя, email, телефон, роль, статус, связанная компания
+Назначение:
-- компания: идентификатор, наименование, ИНН, КПП, юридический адрес, закрепленный менеджер
-- профиль контрагента: реквизиты, контактные лица, служебные признаки синхронизации
-- адрес доставки: идентификатор, владелец, адрес, комментарий, признак основного адреса
-- заявка на подключение: инициирующая компания или контакт, статус, дата создания, комментарий менеджера
-- приглашение: получатель, токен или ссылка, срок действия, статус использования
-- подключение мессенджера: тип канала, внешний идентификатор, статус подключения
 
-## 4.4 Каталог и складской контур
+- хранение клиентской организации
+- объединение пользователей одной компании
 
-Базовые сущности группы:
+Основные поля:
 
-- `Product`
+- `id`
-- `Warehouse`
+- `name`
-- `ProductStock`
+- `inn`
-- `CatalogProductTypeSetting`
+- `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)
 

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