Add VitePress technical specification draft

docs/.vitepress/config.ts

@@ -0,0 +1,44 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'Фрегат ЛК',
+  description: 'Техническое задание на разработку личного кабинета Фрегат',
+  lang: 'ru-RU',
+  cleanUrls: true,
+  themeConfig: {
+    nav: [
+      { text: 'ТЗ', link: '/tz/' },
+      { text: 'Этап 1', link: '/tz/stage-1/' },
+      { text: 'Текущее состояние', link: '/appendix/current-state' },
+    ],
+    sidebar: [
+      {
+        text: 'Техническое задание',
+        items: [
+          { text: 'Обзор', link: '/tz/' },
+          { text: 'Нормативная база', link: '/tz/normative-base' },
+          { text: 'Контур продукта', link: '/tz/product-scope' },
+          { text: 'Роли и доступ', link: '/tz/roles-access' },
+          { text: 'Функциональные требования', link: '/tz/functional-requirements' },
+          { text: 'Данные и интеграции', link: '/tz/data-integrations' },
+          { text: 'Этап 1 (UX/UI)', link: '/tz/stage-1/' },
+          { text: 'Приемка и артефакты', link: '/tz/acceptance' },
+        ],
+      },
+      {
+        text: 'Приложения',
+        items: [
+          { text: 'Текущее состояние продукта', link: '/appendix/current-state' },
+        ],
+      },
+    ],
+    outline: [2, 3],
+    search: {
+      provider: 'local',
+    },
+    footer: {
+      message: 'Черновик ТЗ для согласования с заказчиком',
+      copyright: 'Фрегат Групп / ИП Бакиев',
+    },
+  },
+});

docs/appendix/current-state.md

@@ -0,0 +1,51 @@
+# Приложение: текущее состояние продукта
+
+## Назначение приложения
+
+Этот раздел нужен, чтобы ТЗ не отрывалось от реальной реализации.
+
+Ниже перечислены основные разделы, уже присутствующие в кодовой базе `web-frontend`, которые можно использовать как фактическую основу для дальнейшей детализации ТЗ.
+
+## Клиентские разделы
+
+- главная страница
+- каталог товаров
+- карточка типа товара
+- корзина
+- список клиентских заказов
+- карточка клиентского заказа
+- профиль пользователя
+- адреса
+- уведомления
+- бонусная программа
+
+## Менеджерские разделы
+
+- список клиентов
+- карточка клиента
+- приглашение клиента
+- список заказов
+- карточка заказа
+- уведомления
+- настройки каталога
+- настройки сообщений
+- настройки синхронизации
+- бонусный блок
+
+## Что это означает для ТЗ
+
+ТЗ можно писать не с нуля, а на основании уже сложившейся структуры продукта.
+
+Это позволяет:
+
+- быстро привязать бизнес-требования к реальным экранам
+- не терять уже реализованные сущности
+- сократить расхождение между договорной документацией и кодом
+
+## Что еще нужно будет дозаполнить
+
+- окончательная экранная карта
+- перечень состояний каждого ключевого экрана
+- точные статусы заявок и заказов
+- детальное описание бонусного контура
+- детальная спецификация интеграции с 1С

docs/index.md

@@ -0,0 +1,34 @@
+---
+layout: home
+
+hero:
+  name: "Личный кабинет Фрегат"
+  text: "Подробное техническое задание"
+  tagline: "Черновой пакет документов по договору №28/04-26ПО от 28 апреля 2026 года"
+  actions:
+    - theme: brand
+      text: Открыть ТЗ
+      link: /tz/
+    - theme: alt
+      text: Этап 1
+      link: /tz/stage-1/
+
+features:
+  - title: По договору и спецификации
+    details: Структура документа собрана на основании договора, приложения со спецификацией и текущей реализации продукта.
+  - title: По ГОСТ-логике
+    details: Каркас построен по логике ГОСТ 19.201-78, но адаптирован под современный B2B веб-продукт.
+  - title: Из кода, а не из фантазий
+    details: В документ вынесены реальные роли, разделы, сценарии и сущности, которые уже заложены в продукте.
+---
+
+Этот пакет нужен как основа для согласования полного ТЗ и отдельного первого этапа. В текущей версии мы фиксируем:
+
+- рамки продукта
+- состав ролей и интерфейсов
+- сценарии клиента и менеджера
+- требования к данным и интеграциям
+- границы этапа 1 по UX/UI
+- состав итоговых артефактов и приемки
+
+Рекомендуемый следующий шаг: пройти разделы `/tz/` сверху вниз, внести уточнения по спорным бизнес-правилам и после этого выпускать согласованную редакцию.

docs/tz/acceptance.md

@@ -0,0 +1,62 @@
+# Приемка и передаваемые артефакты
+
+## Этапность приемки
+
+Разработка и приемка продукта выполняются последовательно.
+
+### Этап 1
+
+Критерий завершения:
+
+- заказчик согласовал 2-3 сверстанные страницы
+- подтвержден визуальный подход
+- подтверждена логика ключевых сценариев
+
+### Этап 2
+
+Критерий завершения:
+
+- реализован весь функционал, описанный в ТЗ, без интеграции с 1С
+- стороны подтвердили работоспособность сценариев внутри системы
+
+### Этап 3
+
+Критерий завершения:
+
+- настроен обмен с 1С
+- подтверждена работоспособность интеграционных сценариев
+- устранены блокирующие дефекты по интеграции
+
+## Итоговые артефакты, которые должны быть переданы
+
+По договору и спецификации в финальном комплекте должны быть:
+
+- исходный код всех разработанных компонентов
+- перечень сторонних модулей и версий
+- дистрибутивные комплекты и зависимости
+- схема взаимодействия модулей
+- схема движения данных
+- схемы баз данных и связей
+- описание используемых сторонних API
+- распределение ролей пользователей
+- сетевые требования, порты и протоколы
+- обучающие материалы
+- исходные графические материалы
+- схема графического интерфейса
+
+## Что нужно зафиксировать в актах приемки по этапам
+
+В акте или приложении к акту по каждому этапу желательно отдельно перечислять:
+
+- что именно показывалось заказчику
+- какие сценарии проверялись
+- какие замечания были сняты
+- какие вопросы перенесены на следующий этап
+
+## Открытые вопросы перед выпуском финальной редакции ТЗ
+
+- окончательный перечень страниц первого этапа
+- полный состав статусов заявок и заказов
+- формат и объем бонусного контура на первом релизе
+- обязательные поля клиента и контрагента
+- формат данных и событий для интеграции с 1С

docs/tz/data-integrations.md

@@ -0,0 +1,105 @@
+# Данные и интеграции
+
+## Основные сущности
+
+В текущем ТЗ должны быть формально закреплены следующие сущности:
+
+- пользователь
+- роль
+- контрагент
+- клиентская заявка на подключение
+- товар
+- остаток по складу
+- корзина
+- заявка на заказ
+- заявка на расчет
+- заказ
+- событие статуса заказа
+- уведомление
+- бонусная связь
+- бонусная транзакция
+- заявка на вывод
+
+## Минимальный состав данных по ключевым сущностям
+
+### Пользователь
+
+- идентификатор
+- имя
+- email
+- телефон
+- роль
+- статус доступа
+- связанные мессенджеры
+- привязанный контрагент
+
+### Товар
+
+- SKU
+- наименование
+- тип товара
+- параметры товара
+- флаги кастомизации
+- остатки по складам
+
+### Заявка на заказ / расчет
+
+- идентификатор
+- тип заявки
+- инициатор
+- состав позиций или параметры изделия
+- статус
+- история изменений
+- стоимость после обработки
+- параметры доставки
+- закрепленный менеджер
+
+### Заказ
+
+- идентификатор во внутренней системе
+- внешний идентификатор 1С
+- статус
+- даты статусов
+- состав
+- стоимость
+- доставка
+- связанная заявка
+
+## Интеграции
+
+### Интеграция с 1С
+
+На уровне ТЗ фиксируем две группы обменов.
+
+#### Входящие события
+
+- создание нового заказа
+- изменение заказа
+- обновление статуса
+- обновление параметров доставки
+- обновление состава и других полей заказа
+
+#### Методы получения данных
+
+- получение заказов клиента
+- получение каталога
+- получение характеристик товаров
+- получение остатков по складам
+
+## Что нужно зафиксировать отдельно до финальной версии
+
+- контракт webhook-событий
+- идентификаторы и правила синхронизации сущностей
+- правила дедупликации заказов
+- политика ретраев и повторной обработки
+- требования к логированию ошибок интеграции
+
+## Требования к журналированию
+
+Для спорных операций система должна хранить:
+
+- кто инициировал действие
+- когда оно произошло
+- какой объект был изменен
+- какое было предыдущее значение статуса
+- какое стало новое значение статуса

docs/tz/functional-requirements.md

@@ -0,0 +1,140 @@
+# Функциональные требования
+
+## 1. Авторизация и подключение
+
+Система должна поддерживать два способа входа клиента в продукт:
+
+- регистрация по персональному приглашению
+- самостоятельная регистрация с последующим согласованием менеджером
+
+### Обязательные сценарии
+
+- создание приглашения менеджером
+- отправка приглашения по email
+- самостоятельная подача заявки на подключение
+- approve/reject заявки менеджером
+- завершение регистрации и установка учетных данных
+- привязка пользователя к контрагенту
+- подключение Telegram и Max как каналов уведомлений
+
+## 2. Каталог готовой продукции
+
+Система должна предоставлять клиенту витрину готовой продукции.
+
+### Обязательные сценарии
+
+- просмотр списка типов товаров
+- переход в карточку конкретного типа товара
+- выбор параметров продукции
+- просмотр доступных вариантов
+- сравнение остатков по складам
+- добавление позиции в корзину без отображения цены
+
+### Обязательные особенности
+
+- по каждой позиции должны отображаться характеристики товара
+- по каждой позиции должны отображаться остатки по складам
+- клиент не должен видеть цену на этапе выбора
+- каталог должен поддерживать как стандартные параметры, так и информационные описания по применению
+
+## 3. Корзина и заявка на заказ
+
+Система должна позволять клиенту собрать корзину и отправить заявку менеджеру.
+
+### Обязательные сценарии
+
+- просмотр корзины
+- изменение количества позиций
+- удаление позиции
+- отправка заявки на заказ
+- фиксация состава заявки без цены
+- передача заявки закрепленному менеджеру
+
+## 4. Обработка заявки менеджером
+
+Менеджер должен иметь возможность вручную обработать заявку.
+
+### Обязательные сценарии
+
+- открытие заявки менеджером
+- заполнение стоимости по позициям или по заявке
+- указание параметров доставки
+- публикация обновленных условий клиенту
+- повторная корректировка до перевода в работу
+- перевод заявки в работу
+- отмена заявки
+
+Система должна фиксировать:
+
+- инициатора изменения
+- дату и время действия
+- историю изменения статусов
+
+## 5. Заявка на расчет
+
+Если готовая продукция не подходит, система должна переводить клиента в сценарий расчета.
+
+### Обязательные сценарии
+
+- переход из каталога в заказ с расчетом
+- заполнение параметров изделия
+- отправка заявки на расчет
+- ручная обработка стоимости менеджером
+- публикация расчета клиенту
+- перевод расчета в работу или отмену
+
+### Базовые параметры расчета
+
+Минимально в ТЗ должны быть закреплены:
+
+- тип продукции
+- ширина
+- длина
+- толщина
+- цвет
+- дополнительные параметры по конкретному типу товара
+- комментарий клиента
+
+## 6. Заказы и сопровождение
+
+Система должна отображать клиенту список заказов и карточку каждого заказа.
+
+### Обязательные сценарии
+
+- просмотр списка заказов
+- фильтрация по периоду
+- просмотр карточки заказа
+- отображение статуса из 1С
+- отображение изменений по заказу
+- отправка трекинг-уведомлений
+
+## 7. Уведомления
+
+Система должна поддерживать многоканальные уведомления.
+
+### Каналы
+
+- email
+- Telegram
+- Max
+
+### События
+
+- приглашение к регистрации
+- approve/reject подключения
+- публикация условий по заявке
+- изменение статуса заказа
+- изменения по бонусному балансу
+
+## 8. Бонусная программа
+
+Бонусный контур должен быть описан в ТЗ как отдельная функциональная область.
+
+Минимально должны быть зафиксированы:
+
+- реферальная привязка клиентов
+- начисления и списания
+- журнал бонусных операций
+- магазин вознаграждений
+- заявка на вывод
+- менеджерская обработка заявок на вывод

docs/tz/index.md

@@ -0,0 +1,62 @@
+# Техническое задание
+
+## Статус документа
+
+Документ является рабочим черновиком ТЗ на программный продукт `Личный кабинет Фрегат` по договору на разработку программного продукта №28/04-26ПО от 28 апреля 2026 года.
+
+Текущая редакция предназначена для:
+
+- фиксации объема продукта
+- декомпозиции работ по этапам
+- согласования первого этапа UX/UI
+- подготовки формального комплекта материалов для заказчика
+
+## Основания для разработки
+
+Разработка ведется на основании следующих документов:
+
+- договор на разработку программного продукта №28/04-26ПО от 28 апреля 2026 года
+- приложение №1 к договору: спецификация `Основные требования к программному обеспечению "Личный кабинет Фрегат"`
+- текущая кодовая база `apollo-backend` и `web-frontend`
+
+## Цель продукта
+
+Создать единый B2B личный кабинет для клиентов и сотрудников ООО `Фрегат Групп`, который обеспечивает:
+
+- регистрацию и подключение клиентов
+- выбор готовой продукции
+- оформление заявок на заказ и на расчет
+- обработку заявок менеджером
+- сопровождение заказа по статусам
+- уведомления по email и в мессенджеры
+- отображение истории заказов, задолженности и бонусной информации
+
+## Границы текущего ТЗ
+
+В рамках этого документа описываются:
+
+- клиентский веб-интерфейс
+- менеджерский веб-интерфейс
+- основные сущности и данные
+- обмен данными с 1С
+- приемка по этапам
+- состав документации, подлежащей передаче заказчику
+
+Не входят в предмет этой редакции:
+
+- точные payload-схемы webhooks от 1С
+- детальная сетевая схема production-контура
+- финансовая модель бонусной программы в части бухгалтерских расчетов
+
+## Структура этапов
+
+- Этап 1: согласование UX/UI на ограниченном наборе ключевых страниц
+- Этап 2: реализация полного функционала без интеграции с 1С
+- Этап 3: подключение, настройка и отладка интеграции с 1С
+
+## Что должно получиться после согласования этой версии
+
+- утвержденный каркас полного ТЗ
+- подтвержденный состав экранов и сценариев
+- согласованный объем первого этапа
+- перечень открытых вопросов, которые нужно добрать до финальной редакции

docs/tz/normative-base.md

@@ -0,0 +1,58 @@
+# Нормативная база и формат ТЗ
+
+## Базовый стандарт
+
+Структура настоящего ТЗ ориентирована на `ГОСТ 19.201-78` как на базовый стандарт для технического задания на программный продукт.
+
+В практической части документ адаптирован под современную веб-разработку, потому что продукт:
+
+- является B2B веб-системой
+- включает несколько ролей и интерфейсов
+- зависит от внешних интеграций
+- разрабатывается поэтапно
+
+## Принцип адаптации ГОСТ
+
+Мы не копируем ГОСТ механически, а используем его как каркас. Поэтому в ТЗ оставляем обязательную инженерную логику:
+
+- основания для разработки
+- назначение продукта
+- требования к продукту
+- требования к данным и документации
+- этапы разработки
+- порядок приемки
+
+И дополняем это современными разделами:
+
+- user flow
+- экранная карта
+- роли и права
+- интеграции и события
+- статусы бизнес-процессов
+- UX/UI-этап как отдельный приемочный блок
+
+## Разделы, которые должны быть в финальном ТЗ
+
+Финальная редакция ТЗ должна включать:
+
+1. Основания для разработки
+2. Назначение и цели продукта
+3. Объект автоматизации и границы системы
+4. Состав ролей и прав доступа
+5. Функциональные требования
+6. Нефункциональные требования
+7. Требования к данным и интеграциям
+8. Требования к документации и передаваемым материалам
+9. Этапы выполнения работ
+10. Критерии приемки
+11. Приложения
+
+## Что еще нужно будет приложить к финальной версии
+
+- карта экранов
+- перечень статусов и переходов
+- перечень сущностей и их полей
+- описание уведомлений
+- список интеграционных точек с 1С
+- перечень страниц Этапа 1
+- список артефактов, передаваемых заказчику по результату

docs/tz/product-scope.md

@@ -0,0 +1,79 @@
+# Контур продукта
+
+## Назначение
+
+`Личный кабинет Фрегат` предназначен для того, чтобы клиент мог самостоятельно работать с заказами и взаимодействием с менеджером в единой системе без постоянной ручной переписки.
+
+## Основные пользовательские блоки
+
+### Для клиента
+
+- вход и завершение регистрации
+- профиль компании и контактов
+- каталог готовой продукции
+- карточка товара с параметрами и остатками
+- корзина
+- заявка на заказ
+- заявка на расчет кастомной продукции
+- список заказов
+- карточка заказа
+- уведомления
+- бонусная программа
+
+### Для менеджера
+
+- обработка заявок на подключение
+- обработка клиентских заказов и расчетов
+- ручное заполнение стоимости и условий доставки
+- публикация обновленных условий клиенту
+- просмотр клиентов и контрагентов
+- управление реферальными связями
+- обработка бонусных операций и заявок на вывод
+- настройка каталога, уведомлений и синхронизации
+
+## Ключевые бизнес-сценарии
+
+### Сценарий 1. Подключение клиента
+
+1. Клиент получает приглашение или самостоятельно подает заявку.
+2. Менеджер проверяет данные.
+3. При approve клиент завершает регистрацию.
+4. Клиент получает доступ в кабинет.
+
+### Сценарий 2. Заказ готовой продукции
+
+1. Клиент открывает каталог.
+2. Выбирает тип товара и параметры.
+3. Видит доступные остатки по складам.
+4. Добавляет позиции в корзину.
+5. Отправляет заявку без цены.
+6. Менеджер проставляет цену и условия доставки.
+7. Клиент получает обновленные условия.
+8. Одна из сторон переводит заявку в работу или отменяет ее.
+
+### Сценарий 3. Заявка на расчет
+
+1. Клиент понимает, что готовая продукция не подходит.
+2. Переходит в режим расчета.
+3. Заполняет параметры продукции.
+4. Отправляет заявку менеджеру.
+5. Менеджер указывает цену и условия доставки.
+6. Клиент получает расчет и принимает решение.
+
+### Сценарий 4. Сопровождение заказа
+
+1. После создания заказа статусы поступают из 1С.
+2. Клиент видит актуальный статус и изменения.
+3. Система отправляет уведомления по подключенным каналам.
+
+## Границы первой проектной фиксации
+
+Для первой полноценной редакции ТЗ мы фиксируем все разделы продукта, но детализируем в первую очередь:
+
+- авторизацию и подключение клиента
+- каталог и заказ готовой продукции
+- расчет кастомной продукции
+- менеджерскую обработку заявки
+- карточку заказа и список заказов
+
+Бонусная программа должна быть описана в ТЗ, но на раннем этапе может иметь меньшую глубину детализации интерфейсов, чем заказный контур.

docs/tz/roles-access.md

@@ -0,0 +1,62 @@
+# Роли и доступ
+
+## Основные роли
+
+### Клиент
+
+Клиент работает в личном кабинете своей организации и имеет доступ только к данным, относящимся к его компании.
+
+Клиент может:
+
+- войти по приглашению или после approve заявки
+- редактировать профиль и контактные данные в разрешенных пределах
+- подключать каналы уведомлений
+- выбирать готовую продукцию
+- создавать заявки на заказ
+- создавать заявки на расчет
+- просматривать заказы, статусы, историю и уведомления
+- просматривать бонусную информацию и подавать заявки на вывод, если это предусмотрено правилами
+
+### Менеджер
+
+Менеджер работает с закрепленными клиентами, их заявками, заказами и бонусными операциями.
+
+Менеджер может:
+
+- рассматривать заявки на подключение
+- approve/reject регистрацию
+- привязывать клиента к контрагенту
+- принимать клиентские заявки на заказ и расчет
+- вручную указывать стоимость и параметры доставки
+- публиковать условия клиенту
+- переводить заявку в работу или отменять ее
+- просматривать связанные с клиентами данные
+- управлять реферальными связями и бонусными операциями
+
+### Суперменеджер
+
+Суперменеджер имеет все права менеджера плюс расширенные права на управление данными и настройками.
+
+Суперменеджер может:
+
+- работать со всеми клиентами, а не только со своими
+- управлять настройками каталога
+- управлять шаблонами уведомлений
+- управлять параметрами синхронизации
+- выполнять административные операции по бонусной системе
+
+## Ограничения доступа
+
+Система должна обеспечивать:
+
+- раздельные интерфейсы клиента и менеджера
+- изоляцию клиентских данных по контрагенту
+- контроль административных настроек только для расширенных ролей
+- журналирование ключевых действий по заявкам и заказам
+
+## Открытые вопросы для финальной фиксации
+
+- может ли один клиент иметь несколько пользователей внутри одной организации
+- как разделяются полномочия между менеджером и суперменеджером в части справочников
+- кто именно может изменять каталог, уведомления и бонусные настройки
+- требуется ли дополнительная роль наблюдателя или оператора

docs/tz/stage-1/index.md

@@ -0,0 +1,84 @@
+# Этап 1: UX/UI
+
+## Назначение этапа
+
+Первый этап нужен не для полной разработки продукта, а для согласования визуального подхода, экранной структуры и базовой логики пользовательских сценариев.
+
+Согласно приложению к договору, на этапе должны быть представлены `2-3 сверстанные страницы` с основными элементами интерфейса.
+
+## Рекомендуемый состав страниц этапа
+
+### Страница 1. Каталог / карточка товара
+
+Цель страницы:
+
+- показать, как клиент выбирает готовую продукцию
+- показать параметры, доступные варианты и остатки
+- показать переход к заказу и к расчету
+
+Что должно быть на странице:
+
+- список или карточка типа товара
+- иллюстрация товара
+- выбор параметров
+- описания параметров и сценариев применения
+- доступные варианты
+- индикация остатков по складам
+- действие `В корзину`
+- действие перехода в расчетный сценарий
+
+### Страница 2. Карточка заявки / заказа клиента
+
+Цель страницы:
+
+- показать, как клиент видит созданную заявку или заказ
+- показать статусы, историю изменений и опубликованные менеджером условия
+
+Что должно быть на странице:
+
+- номер заявки или заказа
+- текущий статус
+- состав заказа
+- стоимость после обработки менеджером
+- параметры доставки
+- история статусов
+- действия `Отправить в работу` / `Отменить`, если стадия это допускает
+
+### Страница 3. Менеджерская обработка заявки
+
+Цель страницы:
+
+- показать рабочее место менеджера
+- показать, как менеджер вносит стоимость и условия
+
+Что должно быть на странице:
+
+- данные клиента
+- состав заявки или параметры расчета
+- поле стоимости
+- блок доставки
+- комментарий менеджера
+- публикация условий клиенту
+- действия по статусу заявки
+
+## Что должно быть согласовано по результату этапа
+
+- визуальный стиль кабинета
+- логика компоновки клиентских и менеджерских экранов
+- базовый набор UI-паттернов
+- структура основных карточек и таблиц
+- подход к отображению статусов, уведомлений и складских остатков
+
+## Что не требуется завершать на этом этапе
+
+- полную реализацию бизнес-логики
+- реальные интеграции с 1С
+- все вспомогательные разделы
+- полную настройку бонусной программы
+
+## Связанные материалы, которые желательно приложить к этапу
+
+- экранная карта
+- список состояний каждой из 3 страниц
+- перечень компонентов интерфейса
+- список открытых вопросов, блокирующих следующий этап

package.json

@@ -10,7 +10,10 @@
     "postinstall": "nuxt prepare",
     "codegen": "graphql-codegen --config codegen.ts",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "dependencies": {
     "@apollo/client": "^3.14.1",
@@ -37,6 +40,7 @@
     "@storybook/addon-essentials": "8.6.14",
     "@storybook/vue3-vite": "^8.6.14",
     "storybook": "^8.6.14",
-    "typescript": "5.9.2"
+    "typescript": "5.9.2",
+    "vitepress": "1.6.4"
   }
 }