diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 9a6f55e..61ceb80 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -19,9 +19,11 @@ export default defineConfig({ { text: '3. Роли пользователей и права доступа', link: '/tz/roles-access' }, { text: '4. Функциональные требования', link: '/tz/functional-requirements' }, { text: '5. Требования к данным и интеграциям', link: '/tz/data-integrations' }, - { text: '6. Нефункциональные требования', link: '/tz/non-functional-requirements' }, - { text: '7. Экранные формы и прототипы интерфейсов', link: '/tz/stage-1/' }, - { text: '8. Порядок приемки и состав передаваемых материалов', link: '/tz/acceptance' }, + { text: '6. Техническая архитектура, стек и состав компонентов', link: '/tz/technical-architecture' }, + { text: '7. Структура данных и модель базы данных', link: '/tz/database-model' }, + { text: '8. Нефункциональные требования', link: '/tz/non-functional-requirements' }, + { text: '9. Экранные формы и прототипы интерфейсов', link: '/tz/stage-1/' }, + { text: '10. Порядок приемки и состав передаваемых материалов', link: '/tz/acceptance' }, ], }, { diff --git a/docs/index.md b/docs/index.md index f4e801d..67b9a7e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -61,7 +61,9 @@ 3. [Роли пользователей и права доступа](/tz/roles-access) 4. [Функциональные требования](/tz/functional-requirements) 5. [Требования к данным и интеграциям](/tz/data-integrations) -6. [Нефункциональные требования](/tz/non-functional-requirements) -7. [Экранные формы и прототипы интерфейсов](/tz/stage-1/) -8. [Порядок приемки и состав передаваемых материалов](/tz/acceptance) -9. [Приложение. Текущее состояние программного продукта](/appendix/current-state) +6. [Техническая архитектура, стек и состав компонентов](/tz/technical-architecture) +7. [Структура данных и модель базы данных](/tz/database-model) +8. [Нефункциональные требования](/tz/non-functional-requirements) +9. [Экранные формы и прототипы интерфейсов](/tz/stage-1/) +10. [Порядок приемки и состав передаваемых материалов](/tz/acceptance) +11. [Приложение. Текущее состояние программного продукта](/appendix/current-state) diff --git a/docs/tz/acceptance.md b/docs/tz/acceptance.md index 70c0a07..3d5a5a0 100644 --- a/docs/tz/acceptance.md +++ b/docs/tz/acceptance.md @@ -1,6 +1,6 @@ -# 8. Порядок приемки и состав передаваемых материалов +# 10. Порядок приемки и состав передаваемых материалов -## 8.1 Общие положения приемки +## 10.1 Общие положения приемки Приемка результата работ должна подтверждать соответствие программного продукта требованиям настоящего технического задания, условиям договора и согласованным требованиям заказчика. @@ -16,7 +16,7 @@ - бонусный и реферальный контур - интеграционный обмен в согласованном объеме -## 8.2 Критерии приемки +## 10.2 Критерии приемки Программный продукт считается соответствующим требованиям, если: @@ -28,7 +28,7 @@ - менеджер имеет возможность обработать заявку и опубликовать условия - история изменений сохраняется и доступна в предусмотренных сценариях -## 8.3 Состав передаваемых материалов +## 10.3 Состав передаваемых материалов В состав передаваемых заказчику материалов должны входить: @@ -40,7 +40,7 @@ - описание состава пользовательских ролей и прав доступа - материалы, необходимые для сопровождения и эксплуатации продукта -## 8.4 Требования к документации +## 10.4 Требования к документации Передаваемая документация должна позволять: @@ -49,7 +49,7 @@ - сопровождать клиентский и менеджерский контуры - использовать систему в рамках согласованных ролей и сценариев -## 8.5 Порядок фиксации замечаний +## 10.5 Порядок фиксации замечаний Каждое замечание, выявленное при приемке, должно содержать: diff --git a/docs/tz/database-model.md b/docs/tz/database-model.md new file mode 100644 index 0000000..adfee2e --- /dev/null +++ b/docs/tz/database-model.md @@ -0,0 +1,173 @@ +# 7. Структура данных и модель базы данных + +## 7.1 Общие положения + +Основное хранилище данных программного продукта реализуется на `PostgreSQL`. Прикладной доступ к данным осуществляется через `Prisma ORM`. + +Модель данных должна обеспечивать хранение: + +- пользователей и ролей +- компаний и профилей контрагентов +- адресов доставки +- каталога и складских остатков +- корзины и ее позиций +- заявок и заказов +- событий изменения статусов +- уведомлений и мессенджерных подключений +- бонусных и реферальных сущностей + +## 7.2 Логические группы сущностей + +В модели базы данных выделяются следующие логические группы: + +- справочник пользователей и компаний +- каталог и складской контур +- заказный контур +- контур уведомлений и мессенджеров +- бонусный и реферальный контур +- административные настройки каталога + +## 7.3 Справочник пользователей и компаний + +Базовые сущности группы: + +- `User` +- `Company` +- `CounterpartyProfile` +- `DeliveryAddress` +- `RegistrationRequest` +- `Invitation` +- `MessengerConnection` + +Назначение группы: + +- хранение учетных записей пользователей +- хранение принадлежности пользователя к компании +- хранение полного профиля контрагента +- хранение адресов доставки +- хранение заявок на подключение и приглашений +- хранение подключений Telegram и MAX + +Связи группы: + +- одна компания может иметь нескольких пользователей +- один пользователь может иметь один профиль контрагента +- один пользователь может иметь несколько адресов доставки +- один пользователь может иметь несколько подключенных мессенджеров + +## 7.4 Каталог и складской контур + +Базовые сущности группы: + +- `Product` +- `Warehouse` +- `ProductStock` +- `CatalogProductTypeSetting` + +Назначение группы: + +- хранение товарных позиций и SKU +- хранение параметров товара +- хранение остатков по складам +- хранение правил отображения и кастомизации по типам товара + +Основные поля сущности `Product`: + +- `sku` +- `name` +- `productType` +- `widthMm` +- `lengthM` +- `thicknessMicron` +- `sleeveBrand` +- `quantityPerBox` +- `tags` +- `description` +- `isCustomizable` +- `isActive` + +Основные поля сущности `CatalogProductTypeSetting`: + +- признак показа транспортных и упаковочных параметров +- разрешение на индивидуальную длину +- минимальная, максимальная длина и шаг +- разрешение на индивидуальную втулку +- разрешение на индивидуальную надпись +- списки стандартных значений ширины, длины, толщины, втулки, цвета и надписи + +## 7.5 Корзина и заказный контур + +Базовые сущности группы: + +- `Cart` +- `CartItem` +- `Order` +- `OrderItem` +- `OrderStatusEvent` + +Назначение группы: + +- хранение состава клиентской корзины +- фиксация параметров выбранного товара +- хранение заявки и заказа +- хранение истории изменения статусов + +Ключевые особенности: + +- корзина привязана к конкретному пользователю +- позиции корзины хранят снимок SKU, имени товара и параметров +- заказ хранит состав позиций, статус, стоимость, условия поставки и историю изменений +- события статуса обеспечивают аудит переходов между состояниями + +## 7.6 Бонусный и реферальный контур + +Базовые сущности группы: + +- `ReferralLink` +- `BonusTransaction` +- `RewardWithdrawalRequest` + +Назначение группы: + +- хранение реферальных связей между клиентами +- хранение бонусных начислений и списаний +- хранение заявок на использование либо вывод бонусов + +## 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 +``` + +## 7.8 Требования к хранению прикладных данных + +Модель базы данных должна обеспечивать: + +- уникальность ключевых идентификаторов +- хранение дат создания и изменения сущностей +- хранение параметров товарных позиций в структурированном виде +- хранение истории статусов и действий +- хранение интеграционных идентификаторов для связи с внешними системами + +## 7.9 Требования к расширяемости модели + +Структура базы данных должна позволять: + +- добавлять новые типы продукции без изменения базовой логики ролей и заказов +- расширять набор параметров каталога +- развивать бонусный контур без нарушения заказного контура +- расширять интеграции с 1С и иными внешними системами diff --git a/docs/tz/index.md b/docs/tz/index.md index 24dc131..63e5c4f 100644 --- a/docs/tz/index.md +++ b/docs/tz/index.md @@ -9,9 +9,11 @@ 3. [Роли пользователей и права доступа](/tz/roles-access) 4. [Функциональные требования](/tz/functional-requirements) 5. [Требования к данным и интеграциям](/tz/data-integrations) -6. [Нефункциональные требования](/tz/non-functional-requirements) -7. [Экранные формы и прототипы интерфейсов](/tz/stage-1/) -8. [Порядок приемки и состав передаваемых материалов](/tz/acceptance) +6. [Техническая архитектура, стек и состав компонентов](/tz/technical-architecture) +7. [Структура данных и модель базы данных](/tz/database-model) +8. [Нефункциональные требования](/tz/non-functional-requirements) +9. [Экранные формы и прототипы интерфейсов](/tz/stage-1/) +10. [Порядок приемки и состав передаваемых материалов](/tz/acceptance) ## Назначение раздела diff --git a/docs/tz/non-functional-requirements.md b/docs/tz/non-functional-requirements.md index ef27dea..25adb17 100644 --- a/docs/tz/non-functional-requirements.md +++ b/docs/tz/non-functional-requirements.md @@ -1,10 +1,10 @@ -# 6. Нефункциональные требования +# 8. Нефункциональные требования -## 6.1 Общие требования к архитектуре +## 8.1 Общие требования к архитектуре Программный продукт должен быть реализован как веб-система с разделением клиентского и менеджерского контуров, серверной бизнес-логикой, постоянным хранением данных и возможностью интеграционного обмена с внешними системами. -## 6.2 Требования к доступности интерфейсов +## 8.2 Требования к доступности интерфейсов Система должна обеспечивать корректную работу: @@ -14,7 +14,7 @@ Интерфейсы должны сохранять работоспособность и читаемость при адаптивном отображении. -## 6.3 Требования к производительности +## 8.3 Требования к производительности При штатной эксплуатации система должна обеспечивать: @@ -24,7 +24,7 @@ Точные количественные показатели производительности подлежат фиксации в рабочей документации по инфраструктуре и тестированию. -## 6.4 Требования к безопасности +## 8.4 Требования к безопасности Система должна обеспечивать: @@ -34,7 +34,7 @@ - хранение и передачу чувствительных данных с использованием защищенных механизмов - исключение несанкционированного доступа к административным функциям -## 6.5 Требования к надежности и журналированию +## 8.5 Требования к надежности и журналированию Система должна обеспечивать: @@ -43,7 +43,7 @@ - фиксацию ошибок интеграционного обмена - фиксацию значимых системных и пользовательских событий -## 6.6 Требования к сопровождаемости +## 8.6 Требования к сопровождаемости Реализация должна обеспечивать возможность: @@ -52,7 +52,7 @@ - изменения параметров каталога и уведомлений без переработки базовой структуры системы - расширения интеграционного обмена с 1С и иными внешними системами -## 6.7 Требования к данным и актуальности сведений +## 8.7 Требования к данным и актуальности сведений Система должна обеспечивать: @@ -60,7 +60,7 @@ - отображение даты актуальности сведений, полученных из внешних систем, когда это применимо - защиту от потери данных при обновлении параметров каталога и заказных сущностей -## 6.8 Требования к документации +## 8.8 Требования к документации По результатам выполнения работ должна быть сформирована документация, достаточная для: diff --git a/docs/tz/stage-1/index.md b/docs/tz/stage-1/index.md index 646ae8e..cb9a565 100644 --- a/docs/tz/stage-1/index.md +++ b/docs/tz/stage-1/index.md @@ -1,6 +1,32 @@ -# 7. Экранные формы и прототипы интерфейсов +# 9. Экранные формы и прототипы интерфейсов -## 7.1 Общие требования к экранным формам +## 9.1 Карта экранов + +Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта. + +| Раздел | Маршрут | Роль | Назначение | +| --- | --- | --- | --- | +| Главная страница | `/` | клиент | стартовая точка, быстрые действия, актуальные события | +| Каталог | `/products` | клиент | выбор товарного направления | +| Карточка товара | `/products/[slug]` | клиент | выбор параметров, просмотр вариантов, добавление в корзину | +| Корзина | `/cart` | клиент | формирование и отправка заявки | +| Список заказов клиента | `/client-orders` | клиент | просмотр истории заявок и заказов | +| Карточка заказа клиента | `/client-orders/[id]` | клиент | просмотр статуса, состава, условий и истории | +| Профиль | `/profile` | клиент | базовые данные учетной записи | +| Контрагент | `/profile/counterparty` | клиент | реквизиты и юридические данные | +| Адреса доставки | `/profile/addresses` | клиент | адресный справочник | +| Уведомления | `/notifications` | клиент | история уведомлений | +| Бонусный кабинет | `/bonus-program` | клиент | баланс, история и бонусные действия | +| Список клиентов | `/clients` | менеджер | клиентская база | +| Карточка клиента | `/clients/[id]` | менеджер | данные компании, заказы, бонусы | +| Приглашение клиента | `/clients/invite` | менеджер | выдача приглашения на регистрацию | +| Список заказов | `/orders` | менеджер | обработка заказного контура | +| Карточка заказа | `/orders/[id]` | менеджер | обработка условий, статуса и доставки | +| Настройки каталога | `/catalog-settings` | суперменеджер | параметры товарных направлений | +| Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом | +| Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы | + +## 9.2 Общие требования к экранным формам Экранные формы должны обеспечивать: @@ -16,9 +42,9 @@ - остатки и доступные варианты отображаются в наглядном виде - пользователь понимает ограничения выбора и возможность кастомизации -## 7.2 Клиентские экранные формы +## 9.3 Клиентские экранные формы -### 7.2.1 Главная страница клиента +### 9.3.1 Главная страница клиента Назначение страницы: @@ -32,6 +58,7 @@ - блок актуальных заказов и заявок - блок последних уведомлений - блок бонусной информации при наличии подключенного бонусного контура +- индикатор статуса заполненности профиля клиента Прототип: @@ -49,7 +76,7 @@ +------------------------------------------------------------------+ ``` -### 7.2.2 Каталог продукции +### 9.3.2 Каталог продукции Назначение страницы: @@ -61,8 +88,22 @@ - заголовок раздела - поиск при необходимости - сетка карточек товарных направлений +- карточка каждого товарного направления с изображением и наименованием +- переход в карточку выбранного товарного направления -### 7.2.3 Карточка товара +Прототип: + +```text ++------------------------------------------------------------------+ +| Каталог | ++------------------------------------------------------------------+ +| [Карточка: Упаковочный скотч] [Карточка: Алюминиевый скотч] | +| [Карточка: Крепп] [Карточка: Вспененный скотч] | +| [Карточка: Двусторонний ПП] [Карточка: Двусторонний PVC] | ++------------------------------------------------------------------+ +``` + +### 9.3.3 Карточка товара Назначение страницы: @@ -80,6 +121,7 @@ - блок индивидуальных возможностей, если они разрешены - блок добавления в корзину - таблица доступных вариантов +- блок навигации к соседним товарным направлениям Прототип: @@ -89,9 +131,11 @@ | Алюминиевый скотч | +------------------------------------------------------------------+ | Изображение товара | Выбор параметров | -| | ширина / длина / толщина | -| | цвет / надпись / доп. условия | -| | [В корзину] | +| | [48 мм] [75 мм] | +| | [10 м] [25 м] [50 м] | +| | [50 мкм] | +| | [Цвет] [Надпись] | +| | [В корзину] | +------------------------------------------------------------------+ | Пояснения по параметрам | | Длина указывается в метрах. При наличии разрешения допускается | @@ -102,7 +146,24 @@ +------------------------------------------------------------------+ ``` -### 7.2.4 Корзина +Состав блока выбора параметров: + +- ширина +- длина +- толщина +- тип втулки +- цвет +- надпись +- индивидуальные опции при наличии разрешения + +Состав блока пояснений: + +- описание каждого параметра простым деловым языком +- ограничения по индивидуальной длине +- правила по втулке с логотипом +- правила по нанесению индивидуальной надписи + +### 9.3.4 Корзина Назначение страницы: @@ -117,8 +178,24 @@ - параметры и количество - комментарий клиента - действие отправки заявки +- выбранный адрес доставки +- итоговая сводка по количеству позиций -### 7.2.5 Карточка заявки или заказа +Прототип: + +```text ++------------------------------------------------------------------+ +| Корзина | ++------------------------------------------------------------------+ +| SKU | Товар | Параметры | Количество | Удалить | ++------------------------------------------------------------------+ +| Адрес доставки: [выбранный адрес] | +| Комментарий клиента: [........................................] | +| [Отправить заявку] | ++------------------------------------------------------------------+ +``` + +### 9.3.5 Карточка заявки или заказа Назначение страницы: @@ -141,20 +218,51 @@ +------------------------------------------------------------------+ ``` -### 7.2.6 Список заказов +Состав страницы: + +- номер документа +- статус +- состав позиций +- стоимость после публикации менеджером +- условия поставки и доставки +- история статусов +- системные комментарии + +### 9.3.6 Страница логина и регистрации + +Назначение страницы: + +- запуск входа в систему +- запуск самостоятельной заявки на подключение +- запуск сценариев входа через мессенджеры + +Состав страницы: + +- форма запроса кода входа +- выбор канала входа +- ссылка на самостоятельную заявку на подключение +- блок пояснения по дальнейшему сценарию доступа + +### 9.3.7 Список заказов Назначение страницы: - просмотр текущих и архивных заказов - фильтрация по периоду и статусу -### 7.2.7 Уведомления +Состав страницы: + +- фильтры +- таблица заказов +- переход в карточку конкретного заказа + +### 9.3.8 Уведомления Назначение страницы: - просмотр истории уведомлений по заказам, заявкам и бонусным операциям -### 7.2.8 Бонусный кабинет +### 9.3.9 Бонусный кабинет Назначение страницы: @@ -168,17 +276,42 @@ - история начислений и списаний - связанные реферальные сведения - форма подачи заявки на использование либо вывод бонусов +- правила бонусной программы -## 7.3 Менеджерские экранные формы +Прототип: -### 7.3.1 Список клиентов +```text ++------------------------------------------------------------------+ +| Бонусный кабинет | ++------------------------------------------------------------------+ +| Текущий баланс | ++------------------------------------------------------------------+ +| История операций | +| Дата | Тип | Основание | Сумма | Статус | ++------------------------------------------------------------------+ +| Реферальные связи | ++------------------------------------------------------------------+ +| [Подать заявку на использование / вывод] | ++------------------------------------------------------------------+ +``` + +## 9.4 Менеджерские экранные формы + +### 9.4.1 Список клиентов Назначение страницы: - просмотр клиентской базы - переход в карточку конкретного клиента -### 7.3.2 Карточка клиента +Состав страницы: + +- поиск и фильтры +- таблица клиентов +- индикаторы активности и количества заказов +- действие приглашения нового клиента + +### 9.4.2 Карточка клиента Назначение страницы: @@ -186,7 +319,15 @@ - просмотр истории заявок и заказов - просмотр бонусных и реферальных данных -### 7.3.3 Карточка обработки заявки +Состав страницы: + +- карточка компании и контактных данных +- реквизиты контрагента +- список заказов клиента +- список бонусных операций +- связанные рефералы + +### 9.4.3 Карточка обработки заявки Назначение страницы: @@ -211,15 +352,37 @@ +------------------------------------------------------------------+ ``` -### 7.3.4 Список заказов менеджера +Состав страницы: + +- клиент и контрагент +- состав позиции или расчетный payload +- стоимость +- доставка +- комментарий менеджера +- история изменений +- блок действий со статусом + +### 9.4.4 Список заказов менеджера Назначение страницы: - просмотр заказов по клиентам -- контроль статусов -- переход в карточку заказа +- фильтрация по статусам +- переход к обработке конкретного заказа -### 7.3.5 Настройки каталога +Прототип: + +```text ++------------------------------------------------------------------+ +| Заказы | ++------------------------------------------------------------------+ +| Фильтры: [Статус] [Клиент] [Период] | ++------------------------------------------------------------------+ +| Код | Клиент | Статус | Сумма | Менеджер | Дата | ++------------------------------------------------------------------+ +``` + +### 9.4.5 Настройки каталога Назначение страницы: @@ -228,9 +391,24 @@ - управление возможностями кастомизации - управление описаниями параметров -### 7.3.6 Настройки уведомлений и синхронизации +Состав страницы: + +- список товарных направлений +- карточка настроек конкретного направления +- чекбоксы разрешений кастомизации +- списки стандартных параметров +- единое действие сохранения настроек + +### 9.4.6 Настройки синхронизации и уведомлений Назначение страницы: - управление шаблонами уведомлений - управление параметрами интеграционного обмена + +Состав страницы: + +- список шаблонов уведомлений +- каналы отправки +- статусы последних синхронизаций +- диагностическая информация по обмену diff --git a/docs/tz/technical-architecture.md b/docs/tz/technical-architecture.md new file mode 100644 index 0000000..2b69e23 --- /dev/null +++ b/docs/tz/technical-architecture.md @@ -0,0 +1,147 @@ +# 6. Техническая архитектура, стек и состав компонентов + +## 6.1 Общая архитектурная схема + +Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений. + +Схема взаимодействия основных компонентов: + +```text +Пользовательский браузер + | + v +Nuxt web-frontend + | + v +/api/graphql proxy + | + v +Apollo GraphQL backend + | + v +Prisma ORM + | + v +PostgreSQL + +Дополнительно: +- Vault используется как источник секретов +- Telegram / Max используются как внешние каналы уведомлений +- 1С используется как внешняя учетная система +``` + +## 6.2 Состав прикладных сервисов + +Согласно действующей карте деплоя в составе проекта используются следующие сервисы: + +- `web-frontend` — клиентский и менеджерский веб-интерфейс +- `apollo-backend` — сервер GraphQL и бизнес-логика +- `vault` — централизованное хранилище секретов +- `tg-bot` — Telegram-контур +- `max-bot` — MAX-контур +- `bonus-bot` — бонусный мессенджерный контур + +Основные прикладные сервисы `web-frontend` и `apollo-backend` разворачиваются через `dokploy_webhook` на сервере `main`. + +## 6.3 Технологический стек фронтенда + +Клиентская часть программного продукта реализуется на следующих технологиях: + +- `Nuxt 4` — прикладной веб-фреймворк +- `Vue 3` — библиотека пользовательского интерфейса +- `@nuxtjs/apollo` и `@vue/apollo-composable` — работа с GraphQL +- `GraphQL Code Generator` — генерация типизированных GraphQL-документов +- `Tailwind CSS` и `daisyUI` — базовая стилизация интерфейсов +- `Storybook` — контур изоляционного просмотра компонентов +- `VitePress` — подготовка проектной документации + +## 6.4 Технологический стек серверной части + +Серверная часть программного продукта реализуется на следующих технологиях: + +- `Node.js` — среда выполнения +- `Express 5` — HTTP-сервер +- `Apollo Server 5` — GraphQL-сервер +- `Prisma 7` — доступ к данным и ORM-слой +- `PostgreSQL` — основное хранилище данных +- `Zod` — валидация структур данных в прикладных сценариях +- `Nodemailer` — отправка уведомлений по электронной почте + +## 6.5 Архитектура клиентской части + +Клиентская часть организована по следующим слоям: + +- страницы `app/pages` — входные экранные формы +- компоненты `app/components` — переиспользуемые элементы интерфейса +- composables `app/composables` — клиентская логика и представление данных +- GraphQL-документы `graphql/operations` — отдельные запросы и мутации +- сгенерированная типизированная схема `app/composables/graphql/generated.ts` +- серверные proxy и интеграционные обработчики `server/api` + +Ключевые экранные маршруты текущей реализации: + +- `/products` и `/products/[slug]` — каталог и карточка товара +- `/cart` — корзина +- `/client-orders` и `/client-orders/[id]` — клиентские заявки и заказы +- `/clients` и `/clients/[id]` — менеджерский контур клиентов +- `/orders` и `/orders/[id]` — менеджерский контур заказов +- `/catalog-settings` — административные настройки каталога +- `/bonus-program`, `/bonus-system/*` — бонусный контур + +## 6.6 Архитектура серверной части + +Серверная часть организована по следующим основным модулям: + +- `src/server.js` — инициализация HTTP-сервера и GraphQL-сервера +- `src/schema.graphql` — контракт GraphQL API +- `src/resolvers.js` — реализация GraphQL-операций +- `src/context.js` — построение контекста запроса +- `src/auth.js` — аутентификация и токены доступа +- `src/access.js` — правила авторизации и проверки ролей +- `src/prisma-client.js` — точка подключения Prisma +- `src/messenger*.js`, `src/telegram*.js`, `src/max-mini-app.js` — мессенджерный контур и мини-приложения + +## 6.7 Взаимодействие фронтенда и backend + +Взаимодействие клиентской и серверной части строится через GraphQL API. + +На стороне Nuxt используется серверный proxy-маршрут `/api/graphql`, который: + +- принимает запросы браузера +- прокидывает cookie и авторизационные заголовки +- перенаправляет запрос в `apollo-backend` +- возвращает результат в клиентское приложение + +Такой подход позволяет: + +- изолировать прямой backend endpoint от браузерного клиента +- централизованно передавать авторизационные данные +- поддерживать единый клиентский GraphQL endpoint + +## 6.8 Интеграционные и вспомогательные HTTP-точки + +Помимо GraphQL API, во фронтенд-контуре реализованы вспомогательные серверные маршруты: + +- `/api/graphql` — proxy в backend GraphQL API +- `/api/auth/messenger-start` — запуск сценариев messenger login / connect +- `/api/dadata/address` — подсказки адресов +- `/api/dadata/bank` — подсказки банковских реквизитов +- `/api/dadata/party` — подсказки контрагентов +- `/api/messenger-avatar/[connectionId]` — выдача изображений, связанных с мессенджерными подключениями + +## 6.9 Компонентные требования к реализации + +Архитектура программного продукта должна сохранять следующие правила: + +- экранная логика должна находиться на уровне страниц и composables +- переиспользуемые элементы интерфейса должны быть вынесены в компоненты +- каждый GraphQL-документ должен храниться в отдельном `.graphql` файле +- клиентский код должен использовать сгенерированные типизированные документы +- серверная логика доступа к данным должна проходить через Prisma +- бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом + +## 6.10 Требования к конфигурации и секретам + +Сервисы программного продукта должны получать прикладные секреты из `Vault`. + +В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.