From fc6117c8f5d1c5b5d5d2d017139cd3e53f6d6bf4 Mon Sep 17 00:00:00 2001 From: Ruslan Bakiev <572431+veikab@users.noreply.github.com> Date: Fri, 1 May 2026 12:11:04 +0700 Subject: [PATCH] Replace textual specs with schematic diagrams --- docs/public/diagrams/component-map.svg | 75 +++++++++++ docs/public/diagrams/database-overview.svg | 85 +++++++++++++ docs/public/diagrams/system-architecture.svg | 85 +++++++++++++ docs/public/prototypes/bonus-cabinet.svg | 8 ++ docs/public/prototypes/cart.svg | 12 ++ docs/public/prototypes/catalog-grid.svg | 37 ++++++ docs/public/prototypes/client-order.svg | 9 ++ docs/public/prototypes/dashboard.svg | 10 ++ docs/public/prototypes/manager-order.svg | 11 ++ docs/public/prototypes/manager-orders.svg | 9 ++ docs/public/prototypes/product-card.svg | 39 ++++++ docs/tz/database-model.md | 26 ++-- docs/tz/stage-1/index.md | 124 +++---------------- docs/tz/technical-architecture.md | 40 ++---- 14 files changed, 416 insertions(+), 154 deletions(-) create mode 100644 docs/public/diagrams/component-map.svg create mode 100644 docs/public/diagrams/database-overview.svg create mode 100644 docs/public/diagrams/system-architecture.svg create mode 100644 docs/public/prototypes/bonus-cabinet.svg create mode 100644 docs/public/prototypes/cart.svg create mode 100644 docs/public/prototypes/catalog-grid.svg create mode 100644 docs/public/prototypes/client-order.svg create mode 100644 docs/public/prototypes/dashboard.svg create mode 100644 docs/public/prototypes/manager-order.svg create mode 100644 docs/public/prototypes/manager-orders.svg create mode 100644 docs/public/prototypes/product-card.svg diff --git a/docs/public/diagrams/component-map.svg b/docs/public/diagrams/component-map.svg new file mode 100644 index 0000000..6bd4c90 --- /dev/null +++ b/docs/public/diagrams/component-map.svg @@ -0,0 +1,75 @@ + + + + Карта компонентов и слоев приложения + + + UI и маршруты + + app/pages + маршруты клиентского и менеджерского контура + + app/components + catalog / orders / ui / bonus + + app/composables + presentation + client-side state + + middleware / plugins + auth, mini-app, sentry + + + Контракт и transport + + graphql/operations + отдельный файл на документ + + generated.ts + typed documents + types + + Apollo client + typed query / mutation execution + + server/api/graphql + SSR-safe proxy to backend + + + Backend logic + + schema.graphql + контракт API + + resolvers.js + основные сценарии + + auth / access + токены, роли, guard logic + + messenger layer + Telegram / MAX / mail + + + Data + + Prisma + ORM + + schema.prisma + модель БД + + PostgreSQL + persistent data + + + + + + + + + + + + + + diff --git a/docs/public/diagrams/database-overview.svg b/docs/public/diagrams/database-overview.svg new file mode 100644 index 0000000..ba6f823 --- /dev/null +++ b/docs/public/diagrams/database-overview.svg @@ -0,0 +1,85 @@ + + + + Схема логической модели данных + + + Пользователи и компании + + User + + Company + + Counterparty + + DeliveryAddress + + + Каталог и остатки + + Product + + Warehouse + + ProductStock + + CatalogProduct + TypeSetting + + + Заказный контур + + Cart + + Order + + CartItem + + OrderItem + & StatusEvent + + + Регистрация и доступ + + Registration + + Invitation + + + Уведомления и мессенджеры + + Messenger + + Notification + + + Бонусный контур + + ReferralLink + + BonusTransaction + + RewardWithdrawal + + + + + + + + + + + + + + + + + + + + Ключевые связи + User связан с Company, CounterpartyProfile, DeliveryAddress, Cart, Order, MessengerConnection и бонусными сущностями. + Product связан с ProductStock и используется в CartItem / OrderItem. Настройки параметров хранятся отдельно по типу товара. + diff --git a/docs/public/diagrams/system-architecture.svg b/docs/public/diagrams/system-architecture.svg new file mode 100644 index 0000000..397de25 --- /dev/null +++ b/docs/public/diagrams/system-architecture.svg @@ -0,0 +1,85 @@ + + + + Схема архитектуры программного продукта + + + Браузер клиента + desktop / mobile + + + web-frontend + Nuxt 4 + Vue 3 + страницы, компоненты, composables + + + /api/graphql + server proxy + + + apollo-backend + Apollo Server + Express + GraphQL, auth, business logic + + + Prisma + ORM + + + PostgreSQL + основная БД + + + GraphQL документы + graphql/operations + typed generated documents + + + UI-компоненты + catalog, orders, profile + daisyUI / Tailwind + + + Telegram / MAX + каналы уведомлений + + + Vault + секреты и bootstrap env + + + 1С + заказы, статусы, остатки + + + Dokploy + deploy + rollout + + + + + + + + + + + + + + + + + + + + + + + + + + + + Сплошные линии — основной runtime-контур. Пунктир — внешние и инфраструктурные зависимости. + diff --git a/docs/public/prototypes/bonus-cabinet.svg b/docs/public/prototypes/bonus-cabinet.svg new file mode 100644 index 0000000..45976ed --- /dev/null +++ b/docs/public/prototypes/bonus-cabinet.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/docs/public/prototypes/cart.svg b/docs/public/prototypes/cart.svg new file mode 100644 index 0000000..896aa19 --- /dev/null +++ b/docs/public/prototypes/cart.svg @@ -0,0 +1,12 @@ + + + + Корзина + + + + + + + Отправить заявку + diff --git a/docs/public/prototypes/catalog-grid.svg b/docs/public/prototypes/catalog-grid.svg new file mode 100644 index 0000000..bd9f440 --- /dev/null +++ b/docs/public/prototypes/catalog-grid.svg @@ -0,0 +1,37 @@ + + + + + Каталог + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Схема: на странице отображается только сетка карточек товарных направлений. + diff --git a/docs/public/prototypes/client-order.svg b/docs/public/prototypes/client-order.svg new file mode 100644 index 0000000..89dd77e --- /dev/null +++ b/docs/public/prototypes/client-order.svg @@ -0,0 +1,9 @@ + + + + Карточка заявки / заказа + + + + + diff --git a/docs/public/prototypes/dashboard.svg b/docs/public/prototypes/dashboard.svg new file mode 100644 index 0000000..b4d4a9b --- /dev/null +++ b/docs/public/prototypes/dashboard.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/docs/public/prototypes/manager-order.svg b/docs/public/prototypes/manager-order.svg new file mode 100644 index 0000000..4c4c00e --- /dev/null +++ b/docs/public/prototypes/manager-order.svg @@ -0,0 +1,11 @@ + + + + Карточка обработки заявки менеджером + + + + + + Опубликовать условия / перевести в работу + diff --git a/docs/public/prototypes/manager-orders.svg b/docs/public/prototypes/manager-orders.svg new file mode 100644 index 0000000..5e19796 --- /dev/null +++ b/docs/public/prototypes/manager-orders.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/docs/public/prototypes/product-card.svg b/docs/public/prototypes/product-card.svg new file mode 100644 index 0000000..fb1ef24 --- /dev/null +++ b/docs/public/prototypes/product-card.svg @@ -0,0 +1,39 @@ + + + + + Карточка товара + + + + + + Параметры выбора + + + + + + + + + + + + Действие + + + + В корзину + + + Пояснение по параметрам + + + + + Таблица доступных вариантов + + + + diff --git a/docs/tz/database-model.md b/docs/tz/database-model.md index adfee2e..998cad1 100644 --- a/docs/tz/database-model.md +++ b/docs/tz/database-model.md @@ -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 Требования к хранению прикладных данных diff --git a/docs/tz/stage-1/index.md b/docs/tz/stage-1/index.md index cb9a565..ff0496f 100644 --- a/docs/tz/stage-1/index.md +++ b/docs/tz/stage-1/index.md @@ -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 Настройки каталога diff --git a/docs/tz/technical-architecture.md b/docs/tz/technical-architecture.md index 2b69e23..c9b695b 100644 --- a/docs/tz/technical-architecture.md +++ b/docs/tz/technical-architecture.md @@ -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`.