fregat/web-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Replace textual specs with schematic diagrams

Browse Source
This commit is contained in:
Ruslan Bakiev
2026-05-01 12:11:04 +07:00
parent fccb3039bf
commit fc6117c8f5
14 changed files with 416 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/tz/database-model.md
View File

@@ -4,6 +4,8 @@
Основное хранилище данных программного продукта реализуется на `PostgreSQL`. Прикладной доступ к данным осуществляется через `Prisma ORM`.
![Схема модели данных](/diagrams/database-overview.svg)
Модель данных должна обеспечивать хранение:
- пользователей и ролей
@@ -135,23 +137,15 @@
## 7.7 Основные связи между сущностями
Укрупненная структура связей имеет следующий вид:
Укрупненная структура связей определяется следующими правилами:
```text
Company -> User -> Cart -> CartItem -> Product
-> Order -> OrderItem
-> CounterpartyProfile
-> DeliveryAddress
-> MessengerConnection
-> BonusTransaction
-> RewardWithdrawalRequest
Product -> ProductStock -> Warehouse
ProductType -> CatalogProductTypeSetting
User -> ReferralLink -> User
Order -> OrderStatusEvent
```
- `Company` объединяет пользователей одной клиентской организации
- `User` связан с `CounterpartyProfile`, `DeliveryAddress`, `MessengerConnection`, `Cart`, `Order`, `BonusTransaction` и `RewardWithdrawalRequest`
- `Cart` содержит набор `CartItem`, привязанных к конкретным `Product`
- `Order` содержит набор `OrderItem` и историю `OrderStatusEvent`
- `Product` связан с остатками `ProductStock`, распределенными по сущностям `Warehouse`
- настройки параметров по товарному направлению хранятся в `CatalogProductTypeSetting`
- реферальные связи реализуются через `ReferralLink`, связывающий одного пользователя с другим пользователем
## 7.8 Требования к хранению прикладных данных

124
docs/tz/stage-1/index.md
View File

@@ -60,21 +60,9 @@
- блок бонусной информации при наличии подключенного бонусного контура
- индикатор статуса заполненности профиля клиента
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Header: Каталог | Заказы | Уведомления | Бонусы | Профиль |
+------------------------------------------------------------------+
| Быстрые действия |
| [Каталог] [Мои заказы] [Заявка на расчет] [Бонусы] [Профиль] |
+------------------------------------------------------------------+
| Актуальные заказы и заявки |
| № | Тип | Статус | Дата | Действие |
+------------------------------------------------------------------+
| Последние уведомления |
+------------------------------------------------------------------+
```
![Прототип главной страницы клиента](/prototypes/dashboard.svg)
### 9.3.2 Каталог продукции
@@ -91,17 +79,9 @@
- карточка каждого товарного направления с изображением и наименованием
- переход в карточку выбранного товарного направления
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Каталог |
+------------------------------------------------------------------+
| [Карточка: Упаковочный скотч] [Карточка: Алюминиевый скотч] |
| [Карточка: Крепп] [Карточка: Вспененный скотч] |
| [Карточка: Двусторонний ПП] [Карточка: Двусторонний PVC] |
+------------------------------------------------------------------+
```
![Прототип каталога](/prototypes/catalog-grid.svg)
### 9.3.3 Карточка товара
@@ -123,28 +103,9 @@
- таблица доступных вариантов
- блок навигации к соседним товарным направлениям
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Назад |
| Алюминиевый скотч |
+------------------------------------------------------------------+
| Изображение товара | Выбор параметров |
| | [48 мм] [75 мм] |
| | [10 м] [25 м] [50 м] |
| | [50 мкм] |
| | [Цвет] [Надпись] |
| | [В корзину] |
+------------------------------------------------------------------+
| Пояснения по параметрам |
| Длина указывается в метрах. При наличии разрешения допускается |
| заказ индивидуального значения в согласованных пределах. |
+------------------------------------------------------------------+
| Доступные варианты |
| SKU | Параметры | Остаток | Доступность | Действие |
+------------------------------------------------------------------+
```
![Прототип карточки товара](/prototypes/product-card.svg)
Состав блока выбора параметров:
@@ -181,19 +142,9 @@
- выбранный адрес доставки
- итоговая сводка по количеству позиций
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Корзина |
+------------------------------------------------------------------+
| SKU | Товар | Параметры | Количество | Удалить |
+------------------------------------------------------------------+
| Адрес доставки: [выбранный адрес] |
| Комментарий клиента: [........................................] |
| [Отправить заявку] |
+------------------------------------------------------------------+
```
![Прототип корзины](/prototypes/cart.svg)
### 9.3.5 Карточка заявки или заказа
@@ -204,19 +155,9 @@
- просмотр стоимости и условий поставки после публикации
- просмотр истории изменений
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Номер заявки или заказа | Статус |
+------------------------------------------------------------------+
| Состав позиции |
+------------------------------------------------------------------+
| Стоимость и условия поставки |
+------------------------------------------------------------------+
| История изменений |
+------------------------------------------------------------------+
```
![Прототип бонусного кабинета](/prototypes/bonus-cabinet.svg)
Состав страницы:
@@ -278,22 +219,9 @@
- форма подачи заявки на использование либо вывод бонусов
- правила бонусной программы
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Бонусный кабинет |
+------------------------------------------------------------------+
| Текущий баланс |
+------------------------------------------------------------------+
| История операций |
| Дата | Тип | Основание | Сумма | Статус |
+------------------------------------------------------------------+
| Реферальные связи |
+------------------------------------------------------------------+
| [Подать заявку на использование / вывод] |
+------------------------------------------------------------------+
```
![Прототип карточки заказа](/prototypes/client-order.svg)
## 9.4 Менеджерские экранные формы
@@ -336,21 +264,9 @@
- публикация условий клиенту
- перевод заявки в работу либо отмена
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Клиент | Контрагент | Ответственный менеджер |
+------------------------------------------------------------------+
| Состав заявки или параметры индивидуального изделия |
+------------------------------------------------------------------+
| Стоимость |
| Условия поставки и доставки |
| Комментарий менеджера |
+------------------------------------------------------------------+
| [Опубликовать условия] [Перевести в работу] [Отменить] |
+------------------------------------------------------------------+
```
![Прототип списка заказов менеджера](/prototypes/manager-orders.svg)
Состав страницы:
@@ -370,17 +286,9 @@
- фильтрация по статусам
- переход к обработке конкретного заказа
Прототип:
Схематичный прототип:
```text
+------------------------------------------------------------------+
| Заказы |
+------------------------------------------------------------------+
| Фильтры: [Статус] [Клиент] [Период] |
+------------------------------------------------------------------+
| Код | Клиент | Статус | Сумма | Менеджер | Дата |
+------------------------------------------------------------------+
```
![Прототип менеджерской обработки заявки](/prototypes/manager-order.svg)
### 9.4.5 Настройки каталога

40
docs/tz/technical-architecture.md
View File

@@ -4,31 +4,7 @@
Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений.
Схема взаимодействия основных компонентов:
```text
Пользовательский браузер
|
v
Nuxt web-frontend
|
v
/api/graphql proxy
|
v
Apollo GraphQL backend
|
v
Prisma ORM
|
v
PostgreSQL
Дополнительно:
- Vault используется как источник секретов
- Telegram / Max используются как внешние каналы уведомлений
- 1С используется как внешняя учетная система
```
![Схема архитектуры](/diagrams/system-architecture.svg)
## 6.2 Состав прикладных сервисов
@@ -88,7 +64,11 @@ PostgreSQL
- `/catalog-settings` — административные настройки каталога
- `/bonus-program`, `/bonus-system/*` — бонусный контур
## 6.6 Архитектура серверной части
## 6.6 Карта слоев и компонентов
![Карта компонентов](/diagrams/component-map.svg)
## 6.7 Архитектура серверной части
Серверная часть организована по следующим основным модулям:
@@ -101,7 +81,7 @@ PostgreSQL
- `src/prisma-client.js` — точка подключения Prisma
- `src/messenger*.js`, `src/telegram*.js`, `src/max-mini-app.js` — мессенджерный контур и мини-приложения
## 6.7 Взаимодействие фронтенда и backend
## 6.8 Взаимодействие фронтенда и backend
Взаимодействие клиентской и серверной части строится через GraphQL API.
@@ -118,7 +98,7 @@ PostgreSQL
- централизованно передавать авторизационные данные
- поддерживать единый клиентский GraphQL endpoint
## 6.8 Интеграционные и вспомогательные HTTP-точки
## 6.9 Интеграционные и вспомогательные HTTP-точки
Помимо GraphQL API, во фронтенд-контуре реализованы вспомогательные серверные маршруты:
@@ -129,7 +109,7 @@ PostgreSQL
- `/api/dadata/party` — подсказки контрагентов
- `/api/messenger-avatar/[connectionId]` — выдача изображений, связанных с мессенджерными подключениями
## 6.9 Компонентные требования к реализации
## 6.10 Компонентные требования к реализации
Архитектура программного продукта должна сохранять следующие правила:
@@ -140,7 +120,7 @@ PostgreSQL
- серверная логика доступа к данным должна проходить через Prisma
- бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом
## 6.10 Требования к конфигурации и секретам
## 6.11 Требования к конфигурации и секретам
Сервисы программного продукта должны получать прикладные секреты из `Vault`.