Update technical specification structure

docs/.vitepress/config.ts

@@ -13,8 +13,8 @@ export default defineConfig({
       {
         text: 'Техническое задание',
         items: [
-          { text: '1. Общие положения', link: '/' },
           { text: 'Единый документ ТЗ', link: '/' },
+          { text: 'Содержание разделов', link: '/tz/' },
         ],
       },
     ],

docs/index.md

@@ -2,6 +2,10 @@
 
 <!--@include: ./tz/project-overview.md-->
 
+<!--@include: ./tz/normative-base.md-->
+
+<!--@include: ./tz/product-scope.md-->
+
 <!--@include: ./tz/functional-requirements.md-->
 
 <!--@include: ./tz/roles-access.md-->
@@ -12,6 +16,14 @@
 
 <!--@include: ./tz/integrations.md-->
 
-<!--@include: ./tz/components-libraries.md-->
+<!--@include: ./tz/technical-architecture.md-->
 
-<!--@include: ./tz/infrastructure-operations.md-->
+<!--@include: ./tz/non-functional-requirements.md-->
+
+<!--@include: ./tz/documentation-requirements.md-->
+
+<!--@include: ./tz/economic-indicators.md-->
+
+<!--@include: ./tz/development-stages.md-->
+
+<!--@include: ./tz/acceptance.md-->

docs/tz/acceptance.md

@@ -1,6 +1,6 @@
-# 11. Порядок приемки и состав передаваемых материалов
+# 14. Порядок контроля, приемки и гарантийного сопровождения
 
-## 11.1 Общие положения приемки
+## 14.1 Общие положения приемки
 
 Приемка результата работ должна подтверждать соответствие программного продукта требованиям настоящего технического задания, условиям договора и согласованным требованиям заказчика.
 
@@ -14,9 +14,22 @@
 - сопровождение заказов
 - уведомления
 - бонусный и реферальный контур
-- интеграционный обмен в согласованном объеме
+- интеграционный обмен с 1С в согласованном объеме
+- пользовательская и эксплуатационная документация в согласованном объеме
 
-## 11.2 Критерии приемки
+## 14.2 Виды проверок
+
+Для контроля результата работ используются следующие виды проверок:
+
+- функциональная проверка основных пользовательских сценариев
+- проверка разграничения ролей и прав доступа
+- проверка корректности данных, статусов и истории изменений
+- проверка интерфейсов на desktop и mobile
+- проверка уведомлений по согласованным каналам
+- проверка интеграционного обмена с 1С
+- проверка запуска и работы сервисов в согласованном эксплуатационном контуре
+
+## 14.3 Критерии приемки
 
 Программный продукт считается соответствующим требованиям, если:
 
@@ -27,29 +40,25 @@
 - цена не отображается клиенту до публикации условий менеджером
 - менеджер имеет возможность обработать заявку и опубликовать условия
 - история изменений сохраняется и доступна в предусмотренных сценариях
+- сведения из 1С отображаются в согласованном объеме
+- текущая задолженность клиента и дата актуальности данных отображаются при наличии этих сведений из 1С
+- критичные дефекты, препятствующие выполнению основных сценариев, устранены до передачи результата
 
-## 11.3 Состав передаваемых материалов
+## 14.4 Передаваемые материалы
 
-В состав передаваемых заказчику материалов должны входить:
+В состав передаваемых заказчику материалов входят:
 
-- исходный код программного продукта
+- программный продукт, размещенный в согласованном эксплуатационном контуре
-- техническое задание в согласованной редакции
+- исходный код разработанных компонентов в репозитории проекта
-- сведения об используемых сторонних компонентах и их версиях
+- согласованная редакция настоящего технического задания
-- описание реализованных интеграций и используемых внешних интерфейсов
+- пользовательская документация в согласованном объеме
-- схемы взаимодействия модулей и движения данных
+- эксплуатационная документация в согласованном объеме
-- описание состава пользовательских ролей и прав доступа
+- интеграционная спецификация 1С, если точные форматы обмена фиксируются отдельно от настоящего технического задания
-- материалы, необходимые для сопровождения и эксплуатации продукта
+- перечень ключевых сторонних компонентов, сформированный на основании фактических файлов проекта
 
-## 11.4 Требования к документации
+Технические схемы, модель данных, роли, архитектура, стек, состав сервисов и требования к интеграциям являются частью настоящего технического задания и не дублируются в отдельных документах без отдельного согласования сторон.
 
-Передаваемая документация должна позволять:
+## 14.5 Порядок фиксации замечаний
-
-- идентифицировать состав реализованных функций
-- понять структуру данных и интеграций
-- сопровождать клиентский и менеджерский контуры
-- использовать систему в рамках согласованных ролей и сценариев
-
-## 11.5 Порядок фиксации замечаний
 
 Каждое замечание, выявленное при приемке, должно содержать:
 
@@ -59,3 +68,42 @@
 - фактический результат
 - уровень критичности
 - статус устранения
+
+Замечания, не препятствующие выполнению основных пользовательских и интеграционных сценариев, могут быть зафиксированы сторонами для последующего устранения в согласованном порядке.
+
+## 14.6 Гарантийный срок
+
+Гарантийный срок на разработанные модули, сервисы и дополнительный функционал составляет 6 месяцев с даты подписания акта приемки выполненных работ, если иной порядок не согласован сторонами.
+
+Гарантия распространяется на дефекты разработанного программного продукта, проявившиеся при штатной эксплуатации и относящиеся к функционалу, реализованному исполнителем.
+
+## 14.7 Порядок гарантийного обращения
+
+Гарантийное обращение должно быть передано исполнителю в письменной форме или иным согласованным сторонами способом.
+
+В обращении должны быть указаны:
+
+- описание дефекта
+- пользовательская роль или контур, в котором проявляется дефект
+- шаги воспроизведения
+- ожидаемый результат
+- фактический результат
+- дата и время обнаружения
+- дополнительные материалы, если они нужны для диагностики
+
+Исполнитель выполняет диагностику дефекта и, если дефект относится к гарантийной зоне ответственности, устраняет его без дополнительной оплаты.
+
+Срок устранения гарантийного дефекта составляет не более 3 дней с даты получения обращения либо иной срок, согласованный сторонами с учетом критичности и характера дефекта.
+
+## 14.8 Ограничения гарантийного сопровождения
+
+Гарантийное сопровождение не распространяется на случаи, когда некорректная работа вызвана:
+
+- самостоятельным изменением программного продукта заказчиком или третьими лицами без согласования с исполнителем
+- ошибками сервера, хостинга, инфраструктуры или базы данных, не связанными с разработанным функционалом
+- атакой, компрометацией доступа или нарушением требований информационной безопасности со стороны заказчика
+- некорректной работой стороннего программного обеспечения
+- недоступностью или некорректной работой внешних систем, включая 1С, Telegram, Max, почтовые сервисы и иные внешние API
+- изменением форматов или правил работы внешних систем без предварительного согласования и обновления интеграционной спецификации
+
+Если дефект связан с внешней системой или инфраструктурой, исполнитель фиксирует результат диагностики и передает заказчику сведения, достаточные для дальнейшего устранения причины на стороне соответствующей системы или поставщика.

docs/tz/components-libraries.md

@@ -1,125 +0,0 @@
-# 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 |

docs/tz/data-entities.md

@@ -1,6 +1,6 @@
-# 4. Требования к данным и сущностям
+# 6. Требования к данным и сущностям
 
-## 4.1 Общие требования к данным
+## 6.1 Общие требования к данным
 
 Основное хранилище данных программного продукта реализуется на `PostgreSQL`. Прикладной доступ к данным осуществляется через `Prisma ORM`.
 
@@ -18,7 +18,7 @@
 
 В прикладной реализации должны использоваться фактические сущности базы данных, определенные в `schema.prisma`. Наименование сущностей в документации и в базе данных должно сопоставляться однозначно.
 
-## 4.2 Справочник сущностей базы данных
+## 6.2 Справочник сущностей базы данных
 
 | Модель в базе данных | Русское наименование | Назначение |
 | --- | --- | --- |
@@ -42,7 +42,7 @@
 | `BonusTransaction` | Бонусная транзакция | Начисление или списание бонусов |
 | `RewardWithdrawalRequest` | Заявка на вывод бонусов | Заявка клиента на использование или вывод бонусов |
 
-## 4.3 Служебные перечисления и статусы
+## 6.3 Служебные перечисления и статусы
 
 В модели данных используются следующие перечисления:
 
@@ -53,9 +53,9 @@
 - `OrderStatus`: `NEW`, `MANAGER_PROCESSING`, `WAITING_DOUBLE_CONFIRM`, `CLIENT_REJECTED`, `MANAGER_REJECTED`, `MANAGER_BLOCKED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED`
 - `WithdrawalStatus`: `PENDING`, `APPROVED`, `REJECTED`
 
-## 4.4 Пользователи и компании
+## 6.4 Пользователи и компании
 
-### 4.4.1 Company
+### 6.4.1 Company
 
 Русское наименование: `Компания`
 
@@ -76,7 +76,7 @@
 
 - одна компания связана со многими пользователями
 
-### 4.4.2 User
+### 6.4.2 User
 
 Русское наименование: `Пользователь`
 
@@ -105,7 +105,7 @@
 - пользователь может выступать клиентом или менеджером в заказах
 - пользователь может иметь бонусные операции и заявки на вывод
 
-### 4.4.3 DeliveryAddress
+### 6.4.3 DeliveryAddress
 
 Русское наименование: `Адрес доставки`
 
@@ -125,7 +125,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.4.4 CounterpartyProfile
+### 6.4.4 CounterpartyProfile
 
 Русское наименование: `Профиль контрагента`
 
@@ -153,7 +153,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.4.5 RegistrationRequest
+### 6.4.5 RegistrationRequest
 
 Русское наименование: `Заявка на подключение`
 
@@ -175,7 +175,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.4.6 Invitation
+### 6.4.6 Invitation
 
 Русское наименование: `Приглашение`
 
@@ -195,7 +195,7 @@
 - `acceptedAt`
 - `createdAt`
 
-### 4.4.7 MessengerConnection
+### 6.4.7 MessengerConnection
 
 Русское наименование: `Подключение мессенджера`
 
@@ -216,9 +216,9 @@
 - `isActive`
 - `createdAt`
 
-## 4.5 Каталог и складской контур
+## 6.5 Каталог и складской контур
 
-### 4.5.1 Product
+### 6.5.1 Product
 
 Русское наименование: `Товар`
 
@@ -245,7 +245,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.5.2 CatalogProductTypeSetting
+### 6.5.2 CatalogProductTypeSetting
 
 Русское наименование: `Настройки типа товара`
 
@@ -274,7 +274,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.5.3 Warehouse
+### 6.5.3 Warehouse
 
 Русское наименование: `Склад`
 
@@ -290,7 +290,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.5.4 ProductStock
+### 6.5.4 ProductStock
 
 Русское наименование: `Складской остаток`
 
@@ -306,9 +306,9 @@
 - `availableQty`
 - `updatedAt`
 
-## 4.6 Корзина, заявки и заказы
+## 6.6 Корзина, заявки и заказы
 
-### 4.6.1 Cart
+### 6.6.1 Cart
 
 Русское наименование: `Корзина`
 
@@ -324,7 +324,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.6.2 CartItem
+### 6.6.2 CartItem
 
 Русское наименование: `Позиция корзины`
 
@@ -345,7 +345,7 @@
 - `createdAt`
 - `updatedAt`
 
-### 4.6.3 Order
+### 6.6.3 Order
 
 Русское наименование: `Заказ / заявка`
 
@@ -380,7 +380,7 @@
 - `kind = CALCULATION` означает сценарий расчета индивидуальной продукции
 - поле `calculationPayload` хранит параметры расчетной заявки
 
-### 4.6.4 OrderItem
+### 6.6.4 OrderItem
 
 Русское наименование: `Позиция заказа`
 
@@ -398,7 +398,7 @@
 - `unitPrice`
 - `createdAt`
 
-### 4.6.5 OrderStatusEvent
+### 6.6.5 OrderStatusEvent
 
 Русское наименование: `Событие статуса заказа`
 
@@ -415,9 +415,9 @@
 - `note`
 - `createdAt`
 
-## 4.7 Бонусный и реферальный контур
+## 6.7 Бонусный и реферальный контур
 
-### 4.7.1 ReferralLink
+### 6.7.1 ReferralLink
 
 Русское наименование: `Реферальная связь`
 
@@ -434,7 +434,7 @@
 - `bonusPercent`
 - `createdAt`
 
-### 4.7.2 BonusTransaction
+### 6.7.2 BonusTransaction
 
 Русское наименование: `Бонусная транзакция`
 
@@ -452,7 +452,7 @@
 - `referralLinkId`
 - `createdAt`
 
-### 4.7.3 RewardWithdrawalRequest
+### 6.7.3 RewardWithdrawalRequest
 
 Русское наименование: `Заявка на вывод бонусов`
 
@@ -471,7 +471,7 @@
 - `createdAt`
 - `updatedAt`
 
-## 4.8 Основные связи между сущностями
+## 6.8 Основные связи между сущностями
 
 Укрупненная структура связей определяется следующими правилами:
 
@@ -483,7 +483,7 @@
 - настройки параметров по товарному направлению хранятся в `CatalogProductTypeSetting`
 - реферальные связи реализуются через `ReferralLink`, связывающий одного пользователя с другим пользователем
 
-## 4.9 Структура хранения и модель базы данных
+## 6.9 Структура хранения и модель базы данных
 
 ![Укрупненная модель базы данных](/diagrams/database-model.svg)
 

docs/tz/data-integrations.md

@@ -1,175 +0,0 @@
-# 6. Требования к данным и интеграциям
-
-## 6.1 Основные сущности данных
-
-Система должна оперировать следующими основными сущностями:
-
-- пользователь
-- роль
-- контрагент
-- заявка на подключение
-- товар
-- складской остаток
-- корзина
-- заявка на заказ
-- заявка на расчет
-- заказ
-- событие изменения статуса
-- уведомление
-- бонусная связь
-- бонусная операция
-- заявка на использование либо вывод бонусов
-
-## 6.2 Обязательные данные по сущностям
-
-### 6.2.1 Пользователь
-
-Обязательные данные:
-
-- идентификатор
-- имя
-- адрес электронной почты
-- телефон
-- роль
-- статус учетной записи
-- связанный контрагент
-- подключенные каналы уведомлений
-
-### 6.2.2 Контрагент
-
-Обязательные данные:
-
-- идентификатор
-- наименование компании
-- ИНН
-- КПП
-- юридический адрес
-- контактные лица
-- закрепленный менеджер
-
-### 6.2.3 Товар
-
-Обязательные данные:
-
-- идентификатор
-- SKU
-- наименование
-- тип продукции
-- набор параметров
-- доступные варианты
-- остатки по складам
-- признаки доступности и кастомизации
-
-### 6.2.4 Заявка на заказ
-
-Обязательные данные:
-
-- идентификатор
-- инициатор
-- дата и время создания
-- состав позиций
-- параметры позиций
-- количество
-- комментарий клиента
-- статус
-- закрепленный менеджер
-- стоимость после обработки
-- условия поставки после обработки
-
-### 6.2.5 Заявка на расчет
-
-Обязательные данные:
-
-- идентификатор
-- инициатор
-- дата и время создания
-- параметры изделия
-- комментарий клиента
-- статус
-- закрепленный менеджер
-- стоимость после обработки
-- условия поставки после обработки
-
-### 6.2.6 Заказ
-
-Обязательные данные:
-
-- внутренний идентификатор
-- внешний идентификатор учетной системы
-- статус
-- даты изменения
-- состав заказа
-- стоимость
-- условия поставки
-- ссылка на исходную клиентскую заявку
-
-### 6.2.7 Бонусная операция
-
-Обязательные данные:
-
-- идентификатор операции
-- связанный клиент
-- тип операции
-- сумма или объем операции
-- основание операции
-- дата и время операции
-- текущий статус операции
-
-## 6.3 Требования к данным каталога
-
-Для каждой позиции и для каждого товарного направления система должна хранить и отображать:
-
-- тип продукции
-- доступные параметры выбора
-- стандартные значения параметров
-- описания параметров
-- признаки доступности индивидуальной длины, втулки с логотипом и нанесения надписи
-- доступные варианты товара
-- остатки по складам
-- сведения об актуальности данных
-
-## 6.4 Требования к интеграции с 1С
-
-Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога и заказов.
-
-Система должна обеспечивать получение из 1С следующих данных:
-
-- каталог товаров
-- характеристики товаров
-- складские остатки
-- сведения о заказах
-- статусы заказов
-- изменения состава, стоимости, доставки и иных существенных параметров заказа
-
-## 6.5 Требования к интеграционному обмену
-
-Интеграционный слой должен обеспечивать:
-
-- сопоставление внутренних идентификаторов и идентификаторов 1С
-- защиту от дублирования событий
-- регистрацию входящих и исходящих операций обмена
-- повторную обработку неуспешных сообщений
-- хранение истории обновлений по интеграционным операциям
-
-## 6.6 Требования к журналированию данных
-
-Для ключевых действий и изменений система должна сохранять:
-
-- тип объекта
-- идентификатор объекта
-- предыдущее состояние объекта
-- новое состояние объекта
-- дату и время изменения
-- пользователя либо источник, выполнивший изменение
-
-## 6.7 Требования к данным бонусного контура
-
-Для бонусной и реферальной программы система должна хранить:
-
-- текущий бонусный баланс клиента
-- историю начислений
-- историю списаний
-- историю использования бонусов
-- реферальные связи
-- заявки на использование либо вывод бонусов
-- статусы обработки таких заявок

docs/tz/database-model.md

@@ -1,167 +0,0 @@
-# 8. Структура данных и модель базы данных
-
-## 8.1 Общие положения
-
-Основное хранилище данных программного продукта реализуется на `PostgreSQL`. Прикладной доступ к данным осуществляется через `Prisma ORM`.
-
-![Укрупненная модель базы данных](/diagrams/database-model.svg)
-
-Модель данных должна обеспечивать хранение:
-
-- пользователей и ролей
-- компаний и профилей контрагентов
-- адресов доставки
-- каталога и складских остатков
-- корзины и ее позиций
-- заявок и заказов
-- событий изменения статусов
-- уведомлений и мессенджерных подключений
-- бонусных и реферальных сущностей
-
-## 8.2 Логические группы сущностей
-
-В модели базы данных выделяются следующие логические группы:
-
-- справочник пользователей и компаний
-- каталог и складской контур
-- заказный контур
-- контур уведомлений и мессенджеров
-- бонусный и реферальный контур
-- административные настройки каталога
-
-## 8.3 Справочник пользователей и компаний
-
-Базовые сущности группы:
-
-- `User`
-- `Company`
-- `CounterpartyProfile`
-- `DeliveryAddress`
-- `RegistrationRequest`
-- `Invitation`
-- `MessengerConnection`
-
-Назначение группы:
-
-- хранение учетных записей пользователей
-- хранение принадлежности пользователя к компании
-- хранение полного профиля контрагента
-- хранение адресов доставки
-- хранение заявок на подключение и приглашений
-- хранение подключений Telegram и MAX
-
-Связи группы:
-
-- одна компания может иметь нескольких пользователей
-- один пользователь может иметь один профиль контрагента
-- один пользователь может иметь несколько адресов доставки
-- один пользователь может иметь несколько подключенных мессенджеров
-
-## 8.4 Каталог и складской контур
-
-Базовые сущности группы:
-
-- `Product`
-- `Warehouse`
-- `ProductStock`
-- `CatalogProductTypeSetting`
-
-Назначение группы:
-
-- хранение товарных позиций и SKU
-- хранение параметров товара
-- хранение остатков по складам
-- хранение правил отображения и кастомизации по типам товара
-
-Основные поля сущности `Product`:
-
-- `sku`
-- `name`
-- `productType`
-- `widthMm`
-- `lengthM`
-- `thicknessMicron`
-- `sleeveBrand`
-- `quantityPerBox`
-- `tags`
-- `description`
-- `isCustomizable`
-- `isActive`
-
-Основные поля сущности `CatalogProductTypeSetting`:
-
-- признак показа транспортных и упаковочных параметров
-- разрешение на индивидуальную длину
-- минимальная, максимальная длина и шаг
-- разрешение на индивидуальную втулку
-- разрешение на индивидуальную надпись
-- списки стандартных значений ширины, длины, толщины, втулки, цвета и надписи
-
-## 8.5 Корзина и заказный контур
-
-Базовые сущности группы:
-
-- `Cart`
-- `CartItem`
-- `Order`
-- `OrderItem`
-- `OrderStatusEvent`
-
-Назначение группы:
-
-- хранение состава клиентской корзины
-- фиксация параметров выбранного товара
-- хранение заявки и заказа
-- хранение истории изменения статусов
-
-Ключевые особенности:
-
-- корзина привязана к конкретному пользователю
-- позиции корзины хранят снимок SKU, имени товара и параметров
-- заказ хранит состав позиций, статус, стоимость, условия поставки и историю изменений
-- события статуса обеспечивают аудит переходов между состояниями
-
-## 8.6 Бонусный и реферальный контур
-
-Базовые сущности группы:
-
-- `ReferralLink`
-- `BonusTransaction`
-- `RewardWithdrawalRequest`
-
-Назначение группы:
-
-- хранение реферальных связей между клиентами
-- хранение бонусных начислений и списаний
-- хранение заявок на использование либо вывод бонусов
-
-## 8.7 Основные связи между сущностями
-
-Укрупненная структура связей определяется следующими правилами:
-
-- `Company` объединяет пользователей одной клиентской организации
-- `User` связан с `CounterpartyProfile`, `DeliveryAddress`, `MessengerConnection`, `Cart`, `Order`, `BonusTransaction` и `RewardWithdrawalRequest`
-- `Cart` содержит набор `CartItem`, привязанных к конкретным `Product`
-- `Order` содержит набор `OrderItem` и историю `OrderStatusEvent`
-- `Product` связан с остатками `ProductStock`, распределенными по сущностям `Warehouse`
-- настройки параметров по товарному направлению хранятся в `CatalogProductTypeSetting`
-- реферальные связи реализуются через `ReferralLink`, связывающий одного пользователя с другим пользователем
-
-## 8.8 Требования к хранению прикладных данных
-
-Модель базы данных должна обеспечивать:
-
-- уникальность ключевых идентификаторов
-- хранение дат создания и изменения сущностей
-- хранение параметров товарных позиций в структурированном виде
-- хранение истории статусов и действий
-- хранение интеграционных идентификаторов для связи с внешними системами
-
-## 8.9 Требования к расширяемости модели
-
-Структура базы данных должна позволять:
-
-- добавлять новые типы продукции без изменения базовой логики ролей и заказов
-- расширять набор параметров каталога
-- развивать бонусный контур без нарушения заказного контура
-- расширять интеграции с 1С и иными внешними системами

docs/tz/development-stages.md

@@ -0,0 +1,99 @@
+# 13. Стадии и этапы разработки
+
+## 13.1 Общий порядок выполнения работ
+
+Работы выполняются поэтапно, чтобы согласовывать ключевые решения до перехода к следующей части реализации.
+
+Переход к следующему этапу выполняется после согласования сторонами результата предыдущего этапа либо после фиксации замечаний, не препятствующих продолжению работ.
+
+## 13.2 Этап 1. Разработка и согласование технического задания
+
+На этапе разрабатывается и согласуется настоящее техническое задание.
+
+Результат этапа:
+
+- согласованная редакция технического задания
+- зафиксированные границы продукта
+- зафиксированный состав пользовательских ролей
+- зафиксированные функциональные, интеграционные, технические и эксплуатационные требования
+
+Критерий завершения этапа: утверждение технического задания сторонами.
+
+## 13.3 Этап 2. UX/UI и согласование визуального подхода
+
+На этапе подготавливаются 2-3 сверстанные страницы личного кабинета с основными элементами интерфейса.
+
+В состав страниц для согласования могут входить:
+
+- страница входа или регистрации
+- каталог либо карточка товара
+- корзина либо карточка заявки
+- менеджерская карточка клиента или заказа
+
+Результат этапа:
+
+- согласованный визуальный подход
+- согласованные базовые интерфейсные элементы
+- подтверждение применимости выбранного подхода для клиентского и менеджерского контуров
+
+Критерий завершения этапа: согласование визуального подхода сторонами.
+
+## 13.4 Этап 3. Функциональная реализация без интеграции с 1С
+
+На этапе реализуются основные пользовательские и менеджерские сценарии без подключения обмена с 1С.
+
+В состав этапа входят:
+
+- регистрация и подключение клиентов
+- роли и разграничение доступа
+- каталог готовой продукции
+- корзина и заявки на заказ
+- заявки на расчет индивидуальной продукции
+- обработка заявок менеджером
+- статусы и история изменений
+- уведомления в согласованном объеме
+- бонусный и реферальный контур
+- административные настройки, необходимые для работы продукта
+
+Результат этапа:
+
+- работоспособный программный продукт с основным функционалом
+- возможность проверки клиентских, менеджерских и бонусных сценариев без обмена с 1С
+
+Критерий завершения этапа: готовность и приемка основного функционала без интеграции с 1С.
+
+## 13.5 Этап 4. Интеграция с 1С и отладка обмена
+
+На этапе выполняются подключение, настройка и отладка интеграции с 1С.
+
+В состав этапа входят:
+
+- согласование или уточнение интеграционной спецификации
+- настройка приема webhook-событий от 1С
+- настройка получения данных из 1С через согласованные методы
+- сопоставление внутренних идентификаторов и идентификаторов 1С
+- проверка получения каталога, остатков, заказов, статусов и задолженности
+- проверка обработки дублей и ошибок обмена
+- проверка отображения даты актуальности данных
+
+Результат этапа:
+
+- работоспособный интеграционный обмен с 1С в согласованном объеме
+- журналирование ключевых интеграционных событий
+- подтвержденная работоспособность сценариев, зависящих от данных 1С
+
+Критерий завершения этапа: подтвержденная сторонами работоспособность сценариев с 1С в согласованном объеме.
+
+## 13.6 Этап 5. Передача результата и приемка
+
+На этапе выполняются итоговая проверка, устранение критичных замечаний и передача результата работ.
+
+Результат этапа:
+
+- размещенный программный продукт в согласованном эксплуатационном контуре
+- согласованная редакция технического задания
+- пользовательская и эксплуатационная документация в согласованном объеме
+- перечень ключевых сторонних компонентов
+- акт приемки выполненных работ
+
+Критерий завершения этапа: подписание акта приемки либо наступление условий приемки, предусмотренных договором.

docs/tz/documentation-requirements.md

@@ -0,0 +1,89 @@
+# 11. Требования к программной документации
+
+## 11.1 Общий подход
+
+Настоящее техническое задание является основным техническим документом программного продукта.
+
+В составе настоящего технического задания фиксируются:
+
+- назначение и границы продукта
+- функциональные требования
+- роли пользователей и права доступа
+- требования к данным, сущностям и модели базы данных
+- требования к интерфейсам
+- требования к интеграциям
+- архитектура, стек, компоненты и эксплуатационный контур
+- нефункциональные требования
+- порядок контроля, приемки и гарантийного сопровождения
+
+Отдельные документы не должны дублировать техническое задание. Дополнительная документация должна описывать только то, что необходимо для использования, эксплуатации или интеграции программного продукта и не раскрыто в настоящем документе в достаточном объеме.
+
+## 11.2 Пользовательская документация
+
+Пользовательская документация должна быть подготовлена в объеме, достаточном для работы пользователей в предусмотренных ролях:
+
+- клиент
+- менеджер
+- суперменеджер
+
+Пользовательская документация должна описывать:
+
+- вход в личный кабинет и завершение регистрации
+- работу с профилем и каналами уведомлений
+- просмотр каталога готовой продукции
+- добавление товаров в корзину и отправку заявки
+- создание заявки на расчет индивидуальной продукции
+- просмотр заказов, статусов, условий и истории изменений
+- работу с бонусным кабинетом, бонусным балансом и заявками на вывод
+- действия менеджера по обработке клиентов, заявок, заказов и бонусных операций
+- действия суперменеджера в административных разделах, если они отличаются от действий менеджера
+
+Документация должна быть написана прикладным языком и ориентирована на выполнение пользовательских сценариев, а не на описание внутренней реализации.
+
+## 11.3 Эксплуатационная документация
+
+Эксплуатационная документация должна быть подготовлена в объеме, достаточном для сопровождения программного продукта после передачи результата работ.
+
+Эксплуатационная документация должна описывать:
+
+- состав сервисов и их назначение
+- порядок запуска и перезапуска сервисов через согласованный контур деплоя
+- используемые окружения и общие принципы конфигурации
+- порядок загрузки секретов из Vault
+- порядок просмотра логов и диагностики типовых сбоев
+- порядок проверки работоспособности клиентского, менеджерского и интеграционного контуров
+- порядок обновления приложения через Git и Dokploy
+- перечень технических контактов или зон ответственности, если они согласованы сторонами
+
+Эксплуатационная документация не должна содержать бизнес-секреты, токены, пароли и иные чувствительные значения. Для секретов указываются только имена переменных, назначение и источник получения.
+
+## 11.4 Интеграционная документация
+
+Для интеграции с 1С должна быть подготовлена интеграционная спецификация либо отдельный раздел настоящего технического задания, если к моменту согласования ТЗ формат обмена уже определен.
+
+Интеграционная документация должна описывать:
+
+- состав событий, передаваемых из 1С
+- состав методов получения данных из 1С
+- структуру payload для каждого события и метода
+- обязательные и необязательные поля
+- правила сопоставления идентификаторов
+- требования к авторизации, подписи или иному механизму защиты запросов
+- порядок обработки дублей
+- порядок фиксации ошибок и повторной обработки сообщений
+- критерии приемки интеграционного обмена
+
+Если точный формат обмена с 1С не определен на момент утверждения ТЗ, он фиксируется отдельной согласованной интеграционной спецификацией до начала завершающего этапа интеграции.
+
+## 11.5 Перечень сторонних компонентов
+
+Перечень сторонних компонентов формируется на основании фактических файлов проекта, включая `package.json`, lock-файлы, Dockerfile и конфигурационные файлы сервисов.
+
+Перечень должен содержать:
+
+- наименование компонента
+- версию или диапазон версий
+- назначение компонента в продукте
+- источник установки или репозиторий, если он отличается от стандартного пакетного менеджера
+
+Ключевые сторонние компоненты, используемые в текущей реализации, перечислены в разделе технической архитектуры настоящего технического задания.

docs/tz/economic-indicators.md

@@ -0,0 +1,25 @@
+# 12. Технико-экономические показатели
+
+## 12.1 Назначение показателей
+
+Технико-экономические показатели используются для фиксации ожидаемого прикладного эффекта от разработки программного продукта.
+
+Расчет финансовой эффективности, окупаемости или экономического эффекта в денежном выражении не входит в состав настоящего технического задания, если стороны не согласуют такой расчет отдельно.
+
+## 12.2 Ожидаемый прикладной эффект
+
+Разработка программного продукта должна обеспечить:
+
+- снижение объема ручной коммуникации при приеме и сопровождении заказов
+- единый интерфейс для клиента, менеджера и суперменеджера
+- ускорение обработки заявок за счет фиксации состава, параметров и статусов в системе
+- снижение риска потери информации по заказам, заявкам и бонусным операциям
+- повышение прозрачности статусов заказов и актуальности данных для клиента
+- централизованное хранение истории изменений
+- возможность дальнейшего развития клиентского, менеджерского, бонусного и интеграционного контуров
+
+## 12.3 Ограничения
+
+Программный продукт не заменяет учетную систему 1С и не является первичным источником бухгалтерских, складских или финансовых данных.
+
+Экономический эффект зависит от полноты внедрения продукта в рабочие процессы заказчика, качества данных 1С, доступности внешних каналов уведомлений и соблюдения эксплуатационных требований.

docs/tz/functional-requirements.md

@@ -1,6 +1,6 @@
-# 2. Функциональные требования
+# 4. Функциональные требования
 
-## 2.1 Требования к регистрации и подключению клиентов
+## 4.1 Требования к регистрации и подключению клиентов
 
 Система должна поддерживать два базовых сценария подключения клиента:
 
@@ -18,7 +18,7 @@
 7. После завершения регистрации клиент должен получить доступ к личному кабинету.
 8. Система должна поддерживать подключение доступных каналов уведомлений для клиентской учетной записи.
 
-## 2.2 Требования к каталогу готовой продукции
+## 4.2 Требования к каталогу готовой продукции
 
 Система должна предоставлять клиенту каталог готовой продукции без отображения цены до обработки менеджером.
 
@@ -33,7 +33,7 @@
 7. Система должна исключать отображение стоимости до момента публикации условий менеджером.
 8. Для параметров товара система должна отображать пояснения, помогающие клиенту понять назначение параметра и ограничения выбора.
 
-## 2.3 Требования к параметрам каталога и кастомизации
+## 4.3 Требования к параметрам каталога и кастомизации
 
 Система должна поддерживать настройку параметров по каждому товарному направлению.
 
@@ -47,7 +47,7 @@
 6. Наборы стандартных параметров должны редактироваться в административном контуре.
 7. Изменение набора стандартных параметров не должно приводить к потере уже сохраненных заказных данных.
 
-## 2.4 Требования к корзине и заявке на заказ
+## 4.4 Требования к корзине и заявке на заказ
 
 Система должна позволять клиенту собрать корзину и направить заявку на заказ.
 
@@ -61,7 +61,7 @@
 6. Для заявки должны сохраняться дата создания, инициатор и закрепленный менеджер.
 7. До обработки менеджером стоимость в заявке не должна отображаться клиенту.
 
-## 2.5 Требования к обработке заявки менеджером
+## 4.5 Требования к обработке заявки менеджером
 
 Менеджер должен иметь возможность обработать клиентскую заявку вручную.
 
@@ -77,7 +77,7 @@
 8. Менеджер должен иметь возможность перевести заявку в работу.
 9. Менеджер должен иметь возможность отменить заявку с фиксацией основания отмены.
 
-## 2.6 Требования к заявке на расчет индивидуальной продукции
+## 4.6 Требования к заявке на расчет индивидуальной продукции
 
 Система должна поддерживать отдельный сценарий расчета продукции с индивидуальными параметрами.
 
@@ -101,7 +101,7 @@
 - иные параметры в зависимости от вида продукции
 - текстовый комментарий клиента
 
-## 2.7 Требования к статусам заявок
+## 4.7 Требования к статусам заявок
 
 Система должна обеспечивать сквозное сопровождение заявок по статусам.
 
@@ -122,9 +122,9 @@
 - пользователя или источник, выполнивший изменение
 - комментарий, если он предусмотрен сценарием
 
-## 2.8 Требования к заказам и их сопровождению
+## 4.8 Требования к заказам и их сопровождению
 
-Система должна предоставлять клиенту и менеджеру доступ к списку заказов и карточке каждого заказа.
+Система должна предоставлять клиенту и менеджеру доступ к списку заказов, карточке каждого заказа и актуальным учетным сведениям, полученным из 1С.
 
 Функциональные требования:
 
@@ -134,8 +134,10 @@
 4. В карточке заказа должны отображаться состав, статус, стоимость, условия поставки и история изменений.
 5. В карточке заказа должна отображаться дата актуальности данных.
 6. При наличии обновлений из внешней системы сведения по заказу должны синхронизироваться и отображаться пользователю.
+7. Система должна отображать текущую задолженность клиента, если такие сведения получены из 1С.
+8. Для задолженности должна отображаться дата актуальности данных.
 
-## 2.9 Требования к уведомлениям
+## 4.9 Требования к уведомлениям
 
 Система должна поддерживать уведомления по нескольким каналам связи.
 
@@ -154,9 +156,9 @@
 - изменение бонусного баланса
 - обработка заявки на использование либо вывод бонусов
 
-## 2.10 Требования к бонусной и реферальной программе
+## 4.10 Требования к бонусной и реферальной программе
 
-Система должна включать бонусный контур как самостоятельную функциональную область.
+Система должна включать бонусный контур как самостоятельную функциональную область с отдельным пользовательским интерфейсом.
 
 Функциональные требования:
 
@@ -170,7 +172,7 @@
 8. Менеджер должен иметь возможность обрабатывать операции бонусного контура.
 9. Система должна уведомлять клиента об изменениях бонусного состояния.
 
-## 2.11 Требования к административным настройкам
+## 4.11 Требования к административным настройкам
 
 Система должна содержать административные разделы для управления следующими объектами:
 

docs/tz/index.md

@@ -4,17 +4,23 @@
 
 ## Содержание
 
+1. [Введение, основание, цель и состав проекта](/tz/project-overview)
 2. [Основания для разработки и нормативные материалы](/tz/normative-base)
 3. [Назначение и границы программного продукта](/tz/product-scope)
-4. [Роли пользователей и права доступа](/tz/roles-access)
+4. [Функциональные требования](/tz/functional-requirements)
-5. [Функциональные требования](/tz/functional-requirements)
+5. [Роли пользователей и права доступа](/tz/roles-access)
-6. [Требования к данным и интеграциям](/tz/data-integrations)
+6. [Требования к данным, сущностям и модели базы данных](/tz/data-entities)
-7. [Техническая архитектура, стек и состав компонентов](/tz/technical-architecture)
+7. [Требования к интерфейсу и прототипам](/tz/stage-1/)
-8. [Структура данных и модель базы данных](/tz/database-model)
+8. [Требования к интеграции с 1С и внешним интерфейсам](/tz/integrations)
-9. [Нефункциональные требования](/tz/non-functional-requirements)
+9. [Техническая архитектура, стек и эксплуатационный контур](/tz/technical-architecture)
-10. [Экранные формы и прототипы интерфейсов](/tz/stage-1/)
+10. [Нефункциональные требования](/tz/non-functional-requirements)
-11. [Порядок приемки и состав передаваемых материалов](/tz/acceptance)
+11. [Требования к программной документации](/tz/documentation-requirements)
+12. [Технико-экономические показатели](/tz/economic-indicators)
+13. [Стадии и этапы разработки](/tz/development-stages)
+14. [Порядок контроля, приемки и гарантийного сопровождения](/tz/acceptance)
 
 ## Назначение раздела
 
 Материалы раздела используются для согласования требований к программному продукту, его функциям, данным, интерфейсам, интеграциям и условиям приемки.
+
+Структура технического задания подготовлена с учетом ГОСТ 19.201-78 и адаптирована под разработку современного веб-программного продукта. Технические схемы, модель данных, архитектура, роли и интеграции являются частью настоящего технического задания и не требуют дублирования в отдельных документах, если иное не согласовано сторонами.

docs/tz/infrastructure-operations.md

@@ -1,79 +0,0 @@
-# 8. Требования к инфраструктуре и эксплуатации
-
-## 8.1 Инфраструктурная схема
-
-Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур.
-
-![Инфраструктура, деплой и эксплуатационный контур](/diagrams/infrastructure-topology.svg)
-
-## 8.2 Сервисы и окружение
-
-Сервисы проекта и способ их развёртывания:
-
-| Сервис | Путь в репозитории | Роль | Deploy mode | Сервер |
-| --- | --- | --- | --- | --- |
-| web-frontend | `web-frontend` | клиентский и менеджерский веб-интерфейс | `dokploy_webhook` | `main` |
-| apollo-backend | `apollo-backend` | GraphQL API и бизнес-логика | `dokploy_webhook` | `main` |
-| hatchet-worker | `hatchet-worker` | фоновый worker-контур | `dokploy_webhook` | `main` |
-| tg-bot | `tg-bot` | Telegram-контур | `dokploy_webhook` | `main` |
-| max-bot | `max-bot` | MAX-контур | `dokploy_webhook` | `main` |
-| bonus-bot | `bonus-bot` | бонусный сервис | `dokploy_webhook` | `main` |
-| vault | `vault` | сервис секретов | `dokploy_webhook` | `main` |
-
-## 8.3 Требования к деплою и запуску
-
-Для основных сервисов проекта используется режим `dokploy_webhook`.
-
-Цепочка развёртывания должна быть следующей:
-
-1. изменения фиксируются в Git-репозитории
-2. изменения публикуются в `main`
-3. Dokploy получает webhook-событие
-4. Dokploy выполняет сборку соответствующего сервиса
-5. сервис перезапускается с загрузкой секретов из Vault
-6. после старта выполняются bootstrap-действия, предусмотренные образом и entrypoint-командой
-
-Текущие особенности прикладных сервисов:
-
-- `web-frontend` стартует через загрузку Vault env и запуск `.output/server/index.mjs`
-- `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js`
-- bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js`
-
-## 8.4 Требования к секретам и конфигурации
-
-Сервисы программного продукта должны получать прикладные секреты из `Vault`.
-
-В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.
-
-Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`.
-
-Прикладные сервисы используют общий shell-bootstrap `load-vault-env.sh`, который:
-
-- ожидает доступность Vault по health endpoint
-- загружает shared secrets
-- загружает project secrets
-- экспортирует секреты в runtime environment процесса
-
-## 8.5 Требования к эксплуатации и надежности
-
-Система должна обеспечивать:
-
-- корректную работу в десктопных и мобильных браузерах
-- приемлемое время открытия основных экранов и выполнения действий
-- сохранность пользовательских данных
-- сохранность истории изменений по заявкам, заказам и бонусным операциям
-- фиксацию ошибок интеграционного обмена
-- журналирование значимых системных и пользовательских событий
-- возможность сопровождения и развития клиентского и менеджерского контуров
-
-## 8.6 Требования к передаче результата и эксплуатации
-
-По результатам выполнения работ заказчику должны быть переданы:
-
-- исходный код программного продукта
-- техническое задание в согласованной редакции
-- сведения об используемых компонентах и их версиях
-- описание реализованных интеграций и используемых внешних интерфейсов
-- схемы взаимодействия модулей и движения данных
-- описание пользовательских ролей и прав доступа
-- материалы, необходимые для сопровождения и эксплуатации продукта

docs/tz/integrations.md

@@ -1,21 +1,22 @@
-# 6. Требования к интеграциям
+# 8. Требования к интеграции с 1С и внешним интерфейсам
 
-## 6.1 Общие требования к интеграционному контуру
+## 8.1 Общие требования к интеграционному контуру
 
 Интеграционный слой должен обеспечивать обмен данными между личным кабинетом и внешними системами без потери целостности внутренних сущностей и статусов.
 
 Интеграционный контур должен обеспечивать:
 
 - получение данных из 1С
-- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов
+- прием событий от 1С
+- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов, если такой обмен согласован сторонами
 - сопоставление внутренних идентификаторов и идентификаторов внешних систем
 - регистрацию входящих и исходящих операций обмена
 - повторную обработку неуспешных сообщений
 - хранение истории обновлений по интеграционным операциям
 
-## 6.2 Интеграция с 1С
+## 8.2 Интеграция с 1С
 
-Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога и заказов.
+Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога, заказов, статусов, остатков и сведений о задолженности клиента.
 
 Система должна обеспечивать получение из 1С следующих данных:
 
@@ -25,8 +26,52 @@
 - сведения о заказах
 - статусы заказов
 - изменения состава, стоимости, доставки и иных существенных параметров заказа
+- текущая задолженность клиента
+- дата актуальности сведений, полученных из 1С
 
-## 6.3 Требования к структурам обмена
+1С рассматривается как первичный источник учетных данных по заказам, складам, статусам, стоимости, доставке и задолженности. Личный кабинет отображает эти сведения и фиксирует дату их актуальности.
+
+## 8.3 События от 1С
+
+Система должна поддерживать прием webhook-событий от 1С в согласованном формате.
+
+Минимальный состав событий:
+
+- создание нового заказа
+- изменение информации по заказу
+- изменение статуса заказа
+- изменение сроков, условий или параметров доставки
+- изменение состава заказа
+- изменение сведений о задолженности клиента, если такие данные передаются событийно
+
+Для каждого события должны фиксироваться:
+
+- тип события
+- внешний идентификатор объекта 1С
+- внутренний идентификатор объекта, если сопоставление выполнено
+- дата и время события
+- источник события
+- статус обработки
+- текст ошибки при неуспешной обработке
+
+Система должна защищаться от повторной обработки дублей webhook-событий.
+
+## 8.4 Методы получения данных из 1С
+
+Система должна поддерживать получение данных из 1С через согласованные методы.
+
+Минимальный состав методов:
+
+- получение заказов клиента
+- получение товарного каталога
+- получение характеристик товаров
+- получение доступных остатков по складам
+- получение статусов и изменений по заказам
+- получение текущей задолженности клиента и даты актуальности этих сведений
+
+Точный набор методов, параметры запросов, формат ответов и ограничения по частоте вызовов фиксируются в интеграционной спецификации.
+
+## 8.5 Требования к структурам обмена
 
 Входные и выходные данные интеграционного слоя должны описываться в структурированном виде и позволять однозначно восстанавливать:
 
@@ -39,7 +84,9 @@
 
 Для обмена должны использоваться структурированные payload-форматы, пригодные для сериализации в `JSON`.
 
-## 6.4 Интеграционные поля и служебные атрибуты
+Точная структура payload, схема подписи запросов и набор обязательных полей согласуются сторонами до начала этапа интеграции с 1С.
+
+## 8.6 Интеграционные поля и служебные атрибуты
 
 Для сущностей, участвующих в обмене, должны поддерживаться:
 
@@ -48,8 +95,9 @@
 - источник последнего обновления
 - признак успешной или неуспешной обработки
 - журнал интеграционных ошибок при наличии
+- технический идентификатор последнего обработанного события, если он передается 1С
 
-## 6.5 Журналирование интеграционных операций
+## 8.7 Журналирование интеграционных операций
 
 Для ключевых операций обмена система должна сохранять:
 
@@ -61,3 +109,29 @@
 - пользователя либо внешний источник, выполнивший изменение
 - статус обработки сообщения
 - текст ошибки при наличии
+
+## 8.8 Требования к защите интеграционного обмена
+
+Интеграционные запросы должны выполняться с использованием согласованного механизма авторизации или подписи.
+
+Система должна отклонять интеграционные запросы, если:
+
+- отсутствуют обязательные параметры авторизации
+- подпись или токен не прошли проверку
+- payload не соответствует согласованной структуре
+- невозможно определить тип события или объект обработки
+
+Секреты, используемые для интеграции с 1С, должны храниться только в Vault и передаваться сервисам через runtime-конфигурацию.
+
+## 8.9 Критерии приемки интеграции с 1С
+
+Интеграция с 1С считается готовой в согласованном объеме, если:
+
+- каталог и характеристики товаров получаются и отображаются в личном кабинете
+- остатки по складам отображаются в карточках товаров
+- заказы клиента получаются и отображаются с актуальными статусами
+- изменения заказа из 1С отображаются в карточке заказа
+- текущая задолженность клиента и дата актуальности данных отображаются в предусмотренных интерфейсах
+- webhook-события не обрабатываются повторно при дублях
+- ошибки интеграционного обмена фиксируются в журнале
+- неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке

docs/tz/non-functional-requirements.md

@@ -1,10 +1,10 @@
-# 9. Нефункциональные требования
+# 10. Нефункциональные требования
 
-## 9.1 Общие требования к архитектуре
+## 10.1 Общие требования к архитектуре
 
 Программный продукт должен быть реализован как веб-система с разделением клиентского и менеджерского контуров, серверной бизнес-логикой, постоянным хранением данных и возможностью интеграционного обмена с внешними системами.
 
-## 9.2 Требования к доступности интерфейсов
+## 10.2 Требования к доступности интерфейсов
 
 Система должна обеспечивать корректную работу:
 
@@ -14,7 +14,7 @@
 
 Интерфейсы должны сохранять работоспособность и читаемость при адаптивном отображении.
 
-## 9.3 Требования к производительности
+## 10.3 Требования к производительности
 
 При штатной эксплуатации система должна обеспечивать:
 
@@ -24,7 +24,7 @@
 
 Точные количественные показатели производительности подлежат фиксации в рабочей документации по инфраструктуре и тестированию.
 
-## 9.4 Требования к безопасности
+## 10.4 Требования к безопасности
 
 Система должна обеспечивать:
 
@@ -34,7 +34,7 @@
 - хранение и передачу чувствительных данных с использованием защищенных механизмов
 - исключение несанкционированного доступа к административным функциям
 
-## 9.5 Требования к надежности и журналированию
+## 10.5 Требования к надежности и журналированию
 
 Система должна обеспечивать:
 
@@ -43,7 +43,7 @@
 - фиксацию ошибок интеграционного обмена
 - фиксацию значимых системных и пользовательских событий
 
-## 9.6 Требования к сопровождаемости
+## 10.6 Требования к сопровождаемости
 
 Реализация должна обеспечивать возможность:
 
@@ -52,7 +52,7 @@
 - изменения параметров каталога и уведомлений без переработки базовой структуры системы
 - расширения интеграционного обмена с 1С и иными внешними системами
 
-## 9.7 Требования к данным и актуальности сведений
+## 10.7 Требования к данным и актуальности сведений
 
 Система должна обеспечивать:
 
@@ -60,7 +60,7 @@
 - отображение даты актуальности сведений, полученных из внешних систем, когда это применимо
 - защиту от потери данных при обновлении параметров каталога и заказных сущностей
 
-## 9.8 Требования к документации
+## 10.8 Требования к документации
 
 По результатам выполнения работ должна быть сформирована документация, достаточная для:
 

docs/tz/project-overview.md

@@ -1,4 +1,8 @@
-# 1. Основание, цель и состав проекта
+# 1. Введение, основание, цель и состав проекта
+
+Настоящее техническое задание описывает разработку программного продукта `Личный кабинет Фрегат` для поддержки клиентских, менеджерских, заказных, бонусных и интеграционных сценариев в едином веб-интерфейсе.
+
+Документ используется для согласования состава работ, функциональных и технических требований, этапов разработки, требований к программной документации, порядка приемки и гарантийного сопровождения.
 
 ## 1.1 Основание для разработки
 

docs/tz/roles-access.md

@@ -1,6 +1,6 @@
-# 3. Требования к ролям и правам доступа
+# 5. Требования к ролям и правам доступа
 
-## 3.1 Состав ролей
+## 5.1 Состав ролей
 
 В системе должны быть предусмотрены следующие роли пользователей:
 
@@ -8,7 +8,7 @@
 - менеджер
 - суперменеджер
 
-## 3.2 Роль клиента
+## 5.2 Роль клиента
 
 Пользователь с ролью `Клиент` представляет организацию-контрагента и работает только с данными своей компании.
 
@@ -29,7 +29,7 @@
 - просмотр бонусного баланса и истории бонусных операций
 - подача заявки на использование либо вывод бонусов при наличии соответствующих правил
 
-## 3.3 Роль менеджера
+## 5.3 Роль менеджера
 
 Пользователь с ролью `Менеджер` представляет сотрудника компании, закрепленного за клиентами.
 
@@ -47,7 +47,7 @@
 - просмотр карточек клиентов, заявок и заказов
 - выполнение операций в бонусном контуре в пределах полномочий
 
-## 3.4 Роль суперменеджера
+## 5.4 Роль суперменеджера
 
 Пользователь с ролью `Суперменеджер` обладает всеми правами менеджера и дополнительными административными полномочиями.
 
@@ -60,7 +60,7 @@
 - управление параметрами интеграции и синхронизации
 - расширенное управление бонусным и реферальным контуром
 
-## 3.5 Матрица доступа
+## 5.5 Матрица доступа
 
 | Действие | Клиент | Менеджер | Суперменеджер |
 | --- | --- | --- | --- |
@@ -79,7 +79,7 @@
 | Управление параметрами синхронизации | Нет | Нет | Да |
 | Управление бонусными правилами | Нет | Да | Да |
 
-## 3.6 Ограничения доступа и требования к безопасности
+## 5.6 Ограничения доступа и требования к безопасности
 
 Система должна обеспечивать:
 

docs/tz/stage-1/index.md

@@ -1,6 +1,6 @@
-# 5. Требования к интерфейсу и прототипам
+# 7. Требования к интерфейсу и прототипам
 
-## 5.1 Карта экранов
+## 7.1 Карта экранов
 
 Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта.
 
@@ -26,11 +26,11 @@
 | Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом |
 | Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы |
 
-## 5.2 Маршруты и экранные формы
+## 7.2 Маршруты и экранные формы
 
 Ниже приведен перечень экранных форм, предусмотренных в составе frontend-контура программного продукта.
 
-### 5.2.1 Публичные и клиентские страницы
+### 7.2.1 Публичные и клиентские страницы
 
 | Маршрут | Экран | Назначение |
 | --- | --- | --- |
@@ -44,7 +44,7 @@
 | `/notifications` | Уведомления | Список системных уведомлений |
 | `/bonus-program` | Бонусный кабинет | Бонусный баланс, подарочные карты и бонусные действия |
 
-### 5.2.2 Профиль клиента
+### 7.2.2 Профиль клиента
 
 | Маршрут | Экран | Назначение |
 | --- | --- | --- |
@@ -55,7 +55,7 @@
 | `/profile/notifications` | Настройки уведомлений | Подключение и настройка каналов уведомлений |
 | `/profile/notifications/success` | Успешное подключение уведомлений | Финальный экран сценария подключения канала |
 
-### 5.2.3 Менеджерские и административные страницы
+### 7.2.3 Менеджерские и административные страницы
 
 | Маршрут | Экран | Назначение |
 | --- | --- | --- |
@@ -68,7 +68,7 @@
 | `/settings-sync` | 1С / синхронизация | Управление и мониторинг синхронизации |
 | `/messages` | Сообщения | Шаблоны и тексты менеджерских сообщений |
 
-### 5.2.4 Бонусный менеджерский контур
+### 7.2.4 Бонусный менеджерский контур
 
 | Маршрут | Экран | Назначение |
 | --- | --- | --- |
@@ -78,7 +78,7 @@
 | `/bonus-system/transactions/new` | Добавить бонусную транзакцию | Ручное начисление или списание |
 | `/bonus-system/withdrawals/[id]` | Проверка заявки на вывод | Рассмотрение заявки клиента на вывод бонусов |
 
-## 5.3 Общие требования к экранным формам
+## 7.3 Общие требования к экранным формам
 
 Экранные формы должны обеспечивать:
 
@@ -96,9 +96,9 @@
 
 Ниже приведены низкодетализированные wireframe-прототипы. Они используются как визуальная фиксация состава страниц, ключевых блоков и пользовательских действий.
 
-## 5.4 Клиентские экранные формы
+## 7.4 Клиентские экранные формы
 
-### 5.4.1 Главная страница клиента
+### 7.4.1 Главная страница клиента
 
 Назначение страницы:
 
@@ -118,7 +118,7 @@ Wireframe-прототип:
 
 ![Прототип главной страницы клиента](/prototypes/dashboard.svg)
 
-### 5.4.2 Каталог продукции
+### 7.4.2 Каталог продукции
 
 Назначение страницы:
 
@@ -137,7 +137,7 @@ Wireframe-прототип:
 
 ![Прототип каталога продукции](/prototypes/catalog-grid.svg)
 
-### 5.4.3 Карточка товара
+### 7.4.3 Карточка товара
 
 Назначение страницы:
 
@@ -182,7 +182,7 @@ Wireframe-прототип:
 - правила по втулке с логотипом
 - правила по нанесению индивидуальной надписи
 
-### 5.4.4 Корзина
+### 7.4.4 Корзина
 
 Назначение страницы:
 
@@ -204,7 +204,7 @@ Wireframe-прототип:
 
 ![Прототип корзины](/prototypes/cart.svg)
 
-### 5.4.5 Карточка заявки или заказа
+### 7.4.5 Карточка заявки или заказа
 
 Назначение страницы:
 
@@ -227,7 +227,7 @@ Wireframe-прототип:
 - история статусов
 - системные комментарии
 
-### 5.4.6 Страница логина и регистрации
+### 7.4.6 Страница логина и регистрации
 
 Назначение страницы:
 
@@ -246,7 +246,7 @@ Wireframe-прототип:
 
 ![Прототип страницы логина и подключения](/prototypes/login.svg)
 
-### 5.4.7 Список заказов
+### 7.4.7 Список заказов
 
 Назначение страницы:
 
@@ -259,13 +259,13 @@ Wireframe-прототип:
 - таблица заказов
 - переход в карточку конкретного заказа
 
-### 5.4.8 Уведомления
+### 7.4.8 Уведомления
 
 Назначение страницы:
 
 - просмотр истории уведомлений по заказам, заявкам и бонусным операциям
 
-### 5.4.9 Бонусный кабинет
+### 7.4.9 Бонусный кабинет
 
 Назначение страницы:
 
@@ -285,9 +285,9 @@ Wireframe-прототип:
 
 ![Прототип бонусного кабинета](/prototypes/bonus-cabinet.svg)
 
-## 5.5 Менеджерские экранные формы
+## 7.5 Менеджерские экранные формы
 
-### 5.5.1 Список клиентов
+### 7.5.1 Список клиентов
 
 Назначение страницы:
 
@@ -305,7 +305,7 @@ Wireframe-прототип:
 
 ![Прототип списка клиентов](/prototypes/client-list.svg)
 
-### 5.5.2 Карточка клиента
+### 7.5.2 Карточка клиента
 
 Назначение страницы:
 
@@ -325,7 +325,7 @@ Wireframe-прототип:
 
 ![Прототип карточки клиента](/prototypes/client-card.svg)
 
-### 5.5.3 Карточка обработки заявки
+### 7.5.3 Карточка обработки заявки
 
 Назначение страницы:
 
@@ -348,7 +348,7 @@ Wireframe-прототип:
 - история изменений
 - блок действий со статусом
 
-### 5.5.4 Список заказов менеджера
+### 7.5.4 Список заказов менеджера
 
 Назначение страницы:
 
@@ -360,7 +360,7 @@ Wireframe-прототип:
 
 ![Прототип списка заказов менеджера](/prototypes/manager-orders.svg)
 
-### 5.5.5 Настройки каталога
+### 7.5.5 Настройки каталога
 
 Назначение страницы:
 
@@ -381,7 +381,7 @@ Wireframe-прототип:
 
 ![Прототип настроек каталога](/prototypes/catalog-settings.svg)
 
-### 5.5.6 Настройки синхронизации и уведомлений
+### 7.5.6 Настройки синхронизации и уведомлений
 
 Назначение страницы:
 
@@ -399,7 +399,7 @@ Wireframe-прототип:
 
 ![Прототип настроек синхронизации](/prototypes/sync-settings.svg)
 
-## 5.6 Дополнительные профильные и сервисные страницы
+## 7.6 Дополнительные профильные и сервисные страницы
 
 Помимо основных клиентских и менеджерских экранов, программный продукт включает дополнительные экранные формы:
 

docs/tz/technical-architecture.md

@@ -1,12 +1,12 @@
-# 7. Техническая архитектура, стек и состав компонентов
+# 9. Техническая архитектура, стек, компоненты и эксплуатационный контур
 
-## 7.1 Общая архитектурная схема
+## 9.1 Общая архитектурная схема
 
 Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений.
 
 ![Общая архитектурная схема](/diagrams/architecture-overview.svg)
 
-## 7.2 Состав прикладных сервисов
+## 9.2 Состав прикладных сервисов
 
 Согласно действующей карте деплоя в составе проекта используются следующие сервисы:
 
@@ -19,7 +19,7 @@
 
 Основные прикладные сервисы `web-frontend` и `apollo-backend` разворачиваются через `dokploy_webhook` на сервере `main`.
 
-## 7.3 Технологический стек фронтенда
+## 9.3 Технологический стек фронтенда
 
 Клиентская часть программного продукта реализуется на следующих технологиях:
 
@@ -31,7 +31,7 @@
 - `Storybook` — контур изоляционного просмотра компонентов
 - `VitePress` — подготовка проектной документации
 
-## 7.4 Технологический стек серверной части
+## 9.4 Технологический стек серверной части
 
 Серверная часть программного продукта реализуется на следующих технологиях:
 
@@ -43,7 +43,7 @@
 - `Zod` — валидация структур данных в прикладных сценариях
 - `Nodemailer` — отправка уведомлений по электронной почте
 
-## 7.5 Архитектура клиентской части
+## 9.5 Архитектура клиентской части
 
 Клиентская часть организована по следующим слоям:
 
@@ -64,11 +64,11 @@
 - `/catalog-settings` — административные настройки каталога
 - `/bonus-program`, `/bonus-system/*` — бонусный контур
 
-## 7.6 Карта слоев и компонентов
+## 9.6 Карта слоев и компонентов
 
 ![Карта слоев и компонентов](/diagrams/component-map.svg)
 
-## 7.7 Архитектура серверной части
+## 9.7 Архитектура серверной части
 
 Серверная часть организована по следующим основным модулям:
 
@@ -81,7 +81,7 @@
 - `src/prisma-client.js` — точка подключения Prisma
 - `src/messenger*.js`, `src/telegram*.js`, `src/max-mini-app.js` — мессенджерный контур и мини-приложения
 
-## 7.8 Взаимодействие фронтенда и backend
+## 9.8 Взаимодействие фронтенда и backend
 
 Взаимодействие клиентской и серверной части строится через GraphQL API.
 
@@ -98,7 +98,7 @@
 - централизованно передавать авторизационные данные
 - поддерживать единый клиентский GraphQL endpoint
 
-## 7.9 Интеграционные и вспомогательные HTTP-точки
+## 9.9 Интеграционные и вспомогательные HTTP-точки
 
 Помимо GraphQL API, во фронтенд-контуре реализованы вспомогательные серверные маршруты:
 
@@ -109,7 +109,7 @@
 - `/api/dadata/party` — подсказки контрагентов
 - `/api/messenger-avatar/[connectionId]` — выдача изображений, связанных с мессенджерными подключениями
 
-## 7.10 Компонентные требования к реализации
+## 9.10 Компонентные требования к реализации
 
 Архитектура программного продукта должна сохранять следующие правила:
 
@@ -120,13 +120,13 @@
 - серверная логика доступа к данным должна проходить через Prisma
 - бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом
 
-## 7.11 Требования к конфигурации и секретам
+## 9.11 Требования к конфигурации и секретам
 
 Сервисы программного продукта должны получать прикладные секреты из `Vault`.
 
 В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.
 
-## 7.12 Инфраструктура, деплой и эксплуатационный контур
+## 9.12 Инфраструктура, деплой и эксплуатационный контур
 
 Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур.
 
@@ -152,7 +152,7 @@
 
 Эксплуатационные операции доступа и диагностики выполняются через Tailscale SSH.
 
-## 7.13 Dokploy и цепочка развёртывания
+## 9.13 Dokploy и цепочка развёртывания
 
 Для основных сервисов проекта используется режим `dokploy_webhook`.
 
@@ -171,7 +171,7 @@
 - `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js`
 - bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js`
 
-## 7.14 Vault и хранение секретов
+## 9.14 Vault и хранение секретов
 
 Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`.
 
@@ -190,7 +190,7 @@
 - загружает project secrets
 - экспортирует секреты в runtime environment процесса
 
-## 7.15 Структура сервисных каталогов
+## 9.15 Структура сервисных каталогов
 
 Текущая сервисная структура репозитория:
 
@@ -203,7 +203,7 @@
 - `vault` — Dockerfile, конфигурация и entrypoint Vault
 - `hatchet` — docker-compose инфраструктурного контура Hatchet
 
-## 7.16 Контур фоновых процессов
+## 9.16 Контур фоновых процессов
 
 В проекте присутствует отдельный контур фонового исполнения задач:
 
@@ -214,7 +214,7 @@
 
 Конфигурация этого контура находится в `hatchet/docker-compose.yml`.
 
-## 7.17 Зафиксированные runtime-версии и технологические зависимости
+## 9.17 Зафиксированные runtime-версии и технологические зависимости
 
 ### Базовые runtime и контейнерные образы
 
@@ -237,12 +237,17 @@
 | `@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 |
+| `@fullcalendar/core` | `6.1.20` | calendar runtime |
+| `@fullcalendar/daygrid` | `6.1.20` | calendar day grid |
+| `@fullcalendar/vue3` | `6.1.20` | Vue integration for calendar |
 | `@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 |
+| `mermaid` | `11.14.0` | diagrams in documentation |
 | `@sentry/vue` | `10.46.0` | error tracking |
 | `storybook` | `8.6.14` | UI component review |
+| `vue-router` | `5.0.4` | Vue routing runtime |
 
 ### Основные зависимости backend
 
@@ -259,7 +264,14 @@
 | `nodemailer` | `8.0.4` | email notifications |
 | `dotenv` | `17.3.1` | env bootstrap in local/runtime layers |
 
-## 7.18 Технические конфигурационные файлы
+### Основные зависимости worker-контура
+
+| Библиотека | Версия | Назначение |
+| --- | --- | --- |
+| `@hatchet-dev/typescript-sdk` | `1.19.0` | worker runtime |
+| `dotenv` | `17.3.1` | env bootstrap in local/runtime layers |
+
+## 9.18 Технические конфигурационные файлы
 
 Ключевые технические файлы текущей реализации: