# 7. Требования к компонентам и библиотекам

## 7.1 Общая компонентная схема

Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений.

![Общая архитектурная схема](/diagrams/architecture-overview.svg)

## 7.2 Компоненты клиентской части

Клиентская часть должна быть организована по следующим слоям:

- страницы `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/*`

## 7.3 Компоненты серверной части

Серверная часть должна быть организована по следующим основным модулям:

- `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` — мессенджерный контур и мини-приложения

## 7.4 Карта слоев и компонентов

![Карта слоев и компонентов](/diagrams/component-map.svg)

## 7.5 Требования к компонентной реализации

Архитектура программного продукта должна сохранять следующие правила:

- экранная логика должна находиться на уровне страниц и composables
- переиспользуемые элементы интерфейса должны быть вынесены в отдельные компоненты
- каждый GraphQL-документ должен храниться в отдельном `.graphql` файле
- клиентский код должен использовать сгенерированные типизированные документы
- серверная логика доступа к данным должна проходить через Prisma
- бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом

## 7.6 Требования к библиотекам и стеку

Клиентская часть реализуется на следующих библиотеках и платформах:

- `Nuxt 4`
- `Vue 3`
- `@nuxtjs/apollo`
- `@vue/apollo-composable`
- `GraphQL Code Generator`
- `Tailwind CSS`
- `daisyUI`
- `Storybook`
- `VitePress`

Серверная часть реализуется на следующих библиотеках и платформах:

- `Node.js`
- `Express 5`
- `Apollo Server 5`
- `Prisma 7`
- `PostgreSQL`
- `Zod`
- `Nodemailer`

## 7.7 Зафиксированные версии ключевых зависимостей

### Базовые runtime и контейнерные образы

| Компонент | Текущая версия |
| --- | --- |
| Node base image для web/backend/bots | `node:22-bookworm-slim` |
| Vault image | `hashicorp/vault:1.21.3` |
| Hatchet Postgres | `postgres:15.6` |
| Nuxt | `4.4.2` |
| Vue | `3.5.30` |
| Apollo Server | `5.5.0` |
| Prisma / Prisma Client | `7.6.0` |
| Mermaid | `11.14.0` |
| VitePress | `1.6.4` |

### Основные зависимости фронтенда

| Библиотека | Версия | Назначение |
| --- | --- | --- |
| `@nuxtjs/apollo` | `5.0.0-alpha.16` | GraphQL-клиентский слой |
| `@vue/apollo-composable` | `4.2.2` | composable API для GraphQL |
| `@apollo/client` | `3.14.1` | Apollo client runtime |
| `@nuxt/eslint` | `1.15.2` | linting Nuxt-проекта |
| `@nuxtjs/tailwindcss` | `6.14.0` | Tailwind integration |
| `daisyui` | `5.5.19` | UI primitives |
| `graphql` | `16.13.2` | GraphQL runtime |
| `@sentry/vue` | `10.46.0` | error tracking |
| `storybook` | `8.6.14` | UI component review |

### Основные зависимости backend

| Библиотека | Версия | Назначение |
| --- | --- | --- |
| `@apollo/server` | `5.5.0` | GraphQL server |
| `@as-integrations/express5` | `1.1.2` | Apollo + Express integration |
| `express` | `5.2.1` | HTTP server |
| `@prisma/client` | `7.6.0` | data access |
| `@prisma/adapter-pg` | `7.6.0` | Prisma adapter |
| `pg` | `8.20.0` | PostgreSQL driver |
| `graphql` | `16.13.2` | GraphQL runtime |
| `zod` | `4.3.6` | validation |
| `nodemailer` | `8.0.4` | email notifications |
| `dotenv` | `17.3.1` | env bootstrap in local/runtime layers |