Expand technical specification architecture and prototypes

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 при старте приложения.