Restructure technical specification sections

2026-05-01 15:39:23 +07:00
parent 542ad1b648
commit 58e9d6806d
9 changed files with 576 additions and 119 deletions
--- a/docs/tz/components-libraries.md
+++ b/docs/tz/components-libraries.md
@@ -0,0 +1,125 @@
+# 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 |