Restructure technical specification sections

This commit is contained in:
Ruslan Bakiev
2026-05-01 15:39:23 +07:00
parent 542ad1b648
commit 58e9d6806d
9 changed files with 576 additions and 119 deletions

View File

@@ -1,91 +1,19 @@
# Техническое задание на разработку программного продукта # Техническое задание на разработку программного продукта
## 1. Общие положения <!--@include: ./tz/project-overview.md-->
Наименование программного продукта: `Личный кабинет Фрегат`.
Заказчик: ООО `Фрегат Групп`.
Основанием для разработки являются:
- договор на разработку программного продукта №28/04-26ПО от 28 апреля 2026 года
- приложение №1 к договору: спецификация основных требований к программному обеспечению `Личный кабинет Фрегат`
- согласованный состав действующей клиентской и серверной реализации
Настоящее техническое задание устанавливает требования к составу, функциям, данным, интеграциям, интерфейсным формам, условиям приемки и составу материалов, подлежащих передаче заказчику по результатам выполнения работ.
## 1.1 Назначение программного продукта
Программный продукт предназначен для автоматизации взаимодействия между ООО `Фрегат Групп` и B2B-клиентами компании в части:
- подключения и регистрации клиентов
- выбора готовой продукции из каталога
- подачи заявок на заказ готовой продукции
- подачи заявок на расчет индивидуальной продукции
- согласования стоимости и условий поставки
- сопровождения заказов по статусам
- направления клиентских уведомлений
- ведения бонусной и реферальной программы
## 1.2 Объект автоматизации
Объектом автоматизации являются процессы клиентского обслуживания и внутренней обработки заявок, выполняемые менеджерами ООО `Фрегат Групп` при работе с готовой и индивидуальной продукцией.
## 1.3 Состав системы
В состав программного продукта входят:
- клиентский веб-интерфейс
- менеджерский веб-интерфейс
- серверная бизнес-логика
- база данных
- модуль синхронизации с внешними системами
- модуль уведомлений
- модуль бонусной программы
- модуль административных настроек
## 1.4 Общие принципы работы системы
Система должна обеспечивать следующие базовые принципы:
- доступ к функциям и данным определяется ролью пользователя
- клиент работает только в пределах собственных данных и данных своего контрагента
- стоимость товара и условия поставки публикуются только после обработки менеджером
- история изменений по заявкам, заказам и бонусным операциям фиксируется в системе
- сведения о товарах, остатках, заказах и статусах могут обновляться из внешней учетной системы
## 1.5 Содержание технического задания
2. Основания для разработки и нормативные материалы
3. Назначение и границы программного продукта
4. Роли пользователей и права доступа
5. Функциональные требования
6. Требования к данным и интеграциям
7. Техническая архитектура, стек и состав компонентов
8. Структура данных и модель базы данных
9. Нефункциональные требования
10. Экранные формы и прототипы интерфейсов
11. Порядок приемки и состав передаваемых материалов
12. Приложение. Текущее состояние программного продукта
<!--@include: ./tz/normative-base.md-->
<!--@include: ./tz/product-scope.md-->
<!--@include: ./tz/roles-access.md-->
<!--@include: ./tz/functional-requirements.md--> <!--@include: ./tz/functional-requirements.md-->
<!--@include: ./tz/data-integrations.md--> <!--@include: ./tz/roles-access.md-->
<!--@include: ./tz/technical-architecture.md--> <!--@include: ./tz/data-entities.md-->
<!--@include: ./tz/database-model.md-->
<!--@include: ./tz/non-functional-requirements.md-->
<!--@include: ./tz/stage-1/index.md--> <!--@include: ./tz/stage-1/index.md-->
<!--@include: ./tz/acceptance.md--> <!--@include: ./tz/integrations.md-->
<!--@include: ./tz/components-libraries.md-->
<!--@include: ./tz/infrastructure-operations.md-->
<!--@include: ./appendix/current-state.md--> <!--@include: ./appendix/current-state.md-->

View File

@@ -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 |

186
docs/tz/data-entities.md Normal file
View File

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

View File

@@ -1,6 +1,6 @@
# 5. Функциональные требования # 2. Функциональные требования
## 5.1 Требования к регистрации и подключению клиентов ## 2.1 Требования к регистрации и подключению клиентов
Система должна поддерживать два базовых сценария подключения клиента: Система должна поддерживать два базовых сценария подключения клиента:
@@ -18,7 +18,7 @@
7. После завершения регистрации клиент должен получить доступ к личному кабинету. 7. После завершения регистрации клиент должен получить доступ к личному кабинету.
8. Система должна поддерживать подключение доступных каналов уведомлений для клиентской учетной записи. 8. Система должна поддерживать подключение доступных каналов уведомлений для клиентской учетной записи.
## 5.2 Требования к каталогу готовой продукции ## 2.2 Требования к каталогу готовой продукции
Система должна предоставлять клиенту каталог готовой продукции без отображения цены до обработки менеджером. Система должна предоставлять клиенту каталог готовой продукции без отображения цены до обработки менеджером.
@@ -33,7 +33,7 @@
7. Система должна исключать отображение стоимости до момента публикации условий менеджером. 7. Система должна исключать отображение стоимости до момента публикации условий менеджером.
8. Для параметров товара система должна отображать пояснения, помогающие клиенту понять назначение параметра и ограничения выбора. 8. Для параметров товара система должна отображать пояснения, помогающие клиенту понять назначение параметра и ограничения выбора.
## 5.3 Требования к параметрам каталога и кастомизации ## 2.3 Требования к параметрам каталога и кастомизации
Система должна поддерживать настройку параметров по каждому товарному направлению. Система должна поддерживать настройку параметров по каждому товарному направлению.
@@ -47,7 +47,7 @@
6. Наборы стандартных параметров должны редактироваться в административном контуре. 6. Наборы стандартных параметров должны редактироваться в административном контуре.
7. Изменение набора стандартных параметров не должно приводить к потере уже сохраненных заказных данных. 7. Изменение набора стандартных параметров не должно приводить к потере уже сохраненных заказных данных.
## 5.4 Требования к корзине и заявке на заказ ## 2.4 Требования к корзине и заявке на заказ
Система должна позволять клиенту собрать корзину и направить заявку на заказ. Система должна позволять клиенту собрать корзину и направить заявку на заказ.
@@ -61,7 +61,7 @@
6. Для заявки должны сохраняться дата создания, инициатор и закрепленный менеджер. 6. Для заявки должны сохраняться дата создания, инициатор и закрепленный менеджер.
7. До обработки менеджером стоимость в заявке не должна отображаться клиенту. 7. До обработки менеджером стоимость в заявке не должна отображаться клиенту.
## 5.5 Требования к обработке заявки менеджером ## 2.5 Требования к обработке заявки менеджером
Менеджер должен иметь возможность обработать клиентскую заявку вручную. Менеджер должен иметь возможность обработать клиентскую заявку вручную.
@@ -77,7 +77,7 @@
8. Менеджер должен иметь возможность перевести заявку в работу. 8. Менеджер должен иметь возможность перевести заявку в работу.
9. Менеджер должен иметь возможность отменить заявку с фиксацией основания отмены. 9. Менеджер должен иметь возможность отменить заявку с фиксацией основания отмены.
## 5.6 Требования к заявке на расчет индивидуальной продукции ## 2.6 Требования к заявке на расчет индивидуальной продукции
Система должна поддерживать отдельный сценарий расчета продукции с индивидуальными параметрами. Система должна поддерживать отдельный сценарий расчета продукции с индивидуальными параметрами.
@@ -101,7 +101,7 @@
- иные параметры в зависимости от вида продукции - иные параметры в зависимости от вида продукции
- текстовый комментарий клиента - текстовый комментарий клиента
## 5.7 Требования к статусам заявок ## 2.7 Требования к статусам заявок
Система должна обеспечивать сквозное сопровождение заявок по статусам. Система должна обеспечивать сквозное сопровождение заявок по статусам.
@@ -122,7 +122,7 @@
- пользователя или источник, выполнивший изменение - пользователя или источник, выполнивший изменение
- комментарий, если он предусмотрен сценарием - комментарий, если он предусмотрен сценарием
## 5.8 Требования к заказам и их сопровождению ## 2.8 Требования к заказам и их сопровождению
Система должна предоставлять клиенту и менеджеру доступ к списку заказов и карточке каждого заказа. Система должна предоставлять клиенту и менеджеру доступ к списку заказов и карточке каждого заказа.
@@ -135,7 +135,7 @@
5. В карточке заказа должна отображаться дата актуальности данных. 5. В карточке заказа должна отображаться дата актуальности данных.
6. При наличии обновлений из внешней системы сведения по заказу должны синхронизироваться и отображаться пользователю. 6. При наличии обновлений из внешней системы сведения по заказу должны синхронизироваться и отображаться пользователю.
## 5.9 Требования к уведомлениям ## 2.9 Требования к уведомлениям
Система должна поддерживать уведомления по нескольким каналам связи. Система должна поддерживать уведомления по нескольким каналам связи.
@@ -154,7 +154,7 @@
- изменение бонусного баланса - изменение бонусного баланса
- обработка заявки на использование либо вывод бонусов - обработка заявки на использование либо вывод бонусов
## 5.10 Требования к бонусной и реферальной программе ## 2.10 Требования к бонусной и реферальной программе
Система должна включать бонусный контур как самостоятельную функциональную область. Система должна включать бонусный контур как самостоятельную функциональную область.
@@ -170,7 +170,7 @@
8. Менеджер должен иметь возможность обрабатывать операции бонусного контура. 8. Менеджер должен иметь возможность обрабатывать операции бонусного контура.
9. Система должна уведомлять клиента об изменениях бонусного состояния. 9. Система должна уведомлять клиента об изменениях бонусного состояния.
## 5.11 Требования к административным настройкам ## 2.11 Требования к административным настройкам
Система должна содержать административные разделы для управления следующими объектами: Система должна содержать административные разделы для управления следующими объектами:

View File

@@ -0,0 +1,79 @@
# 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 Требования к передаче результата и эксплуатации
По результатам выполнения работ заказчику должны быть переданы:
- исходный код программного продукта
- техническое задание в согласованной редакции
- сведения об используемых компонентах и их версиях
- описание реализованных интеграций и используемых внешних интерфейсов
- схемы взаимодействия модулей и движения данных
- описание пользовательских ролей и прав доступа
- материалы, необходимые для сопровождения и эксплуатации продукта

63
docs/tz/integrations.md Normal file
View File

@@ -0,0 +1,63 @@
# 6. Требования к интеграциям
## 6.1 Общие требования к интеграционному контуру
Интеграционный слой должен обеспечивать обмен данными между личным кабинетом и внешними системами без потери целостности внутренних сущностей и статусов.
Интеграционный контур должен обеспечивать:
- получение данных из 1С
- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов
- сопоставление внутренних идентификаторов и идентификаторов внешних систем
- регистрацию входящих и исходящих операций обмена
- повторную обработку неуспешных сообщений
- хранение истории обновлений по интеграционным операциям
## 6.2 Интеграция с 1С
Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога и заказов.
Система должна обеспечивать получение из 1С следующих данных:
- каталог товаров
- характеристики товаров
- складские остатки
- сведения о заказах
- статусы заказов
- изменения состава, стоимости, доставки и иных существенных параметров заказа
## 6.3 Требования к структурам обмена
Входные и выходные данные интеграционного слоя должны описываться в структурированном виде и позволять однозначно восстанавливать:
- тип объекта обмена
- идентификатор объекта
- дату и время события
- полезную нагрузку объекта
- статус обработки
- источник изменения
Для обмена должны использоваться структурированные payload-форматы, пригодные для сериализации в `JSON`.
## 6.4 Интеграционные поля и служебные атрибуты
Для сущностей, участвующих в обмене, должны поддерживаться:
- внешний идентификатор учетной системы
- дата последней синхронизации
- источник последнего обновления
- признак успешной или неуспешной обработки
- журнал интеграционных ошибок при наличии
## 6.5 Журналирование интеграционных операций
Для ключевых операций обмена система должна сохранять:
- тип объекта
- идентификатор объекта
- предыдущее состояние
- новое состояние
- дату и время изменения
- пользователя либо внешний источник, выполнивший изменение
- статус обработки сообщения
- текст ошибки при наличии

View File

@@ -0,0 +1,76 @@
# 1. Основание, цель и состав проекта
## 1.1 Основание для разработки
Разработка программного продукта выполняется на основании следующих документов и материалов:
- договор на разработку программного продукта №28/04-26ПО от 28 апреля 2026 года
- приложение №1 к договору: спецификация основных требований к программному обеспечению `Личный кабинет Фрегат`
- согласованные требования заказчика к клиентскому, менеджерскому, бонусному и интеграционному контурам
- действующее состояние клиентской и серверной кодовой базы, используемое как основа для детализации требований
## 1.2 Цель разработки
Программный продукт `Личный кабинет Фрегат` предназначен для организации единого цифрового канала взаимодействия между ООО `Фрегат Групп` и B2B-клиентами компании.
Система должна обеспечивать:
- подключение и регистрацию клиентов
- выбор готовой продукции из каталога
- подачу заявок на заказ готовой продукции
- подачу заявок на расчет продукции с индивидуальными параметрами
- согласование стоимости и условий поставки
- сопровождение заказов по статусам
- отправку клиентских уведомлений
- ведение бонусной и реферальной программы
## 1.3 Объект автоматизации
Объектом автоматизации являются процессы клиентского обслуживания и внутренней обработки заявок, выполняемые менеджерами ООО `Фрегат Групп` при работе с готовой и индивидуальной продукцией.
## 1.4 Состав системы
В состав программного продукта входят:
- клиентский веб-интерфейс
- менеджерский веб-интерфейс
- серверная бизнес-логика
- база данных
- модуль синхронизации с внешними системами
- модуль уведомлений
- модуль бонусной программы
- модуль административных настроек
## 1.5 Границы реализации
В состав программного продукта входят следующие функциональные области:
- регистрация и подключение клиента
- профиль клиента и данные компании
- каталог готовой продукции
- карточка товара и выбор параметров
- корзина и заявка на заказ
- заявка на расчет индивидуальной продукции
- обработка заявок менеджером
- список заказов и карточка заказа
- уведомления
- бонусный кабинет
- административные настройки
Программный продукт не предназначен для выполнения следующих функций:
- самостоятельного ценообразования клиентом
- ведения бухгалтерского учета
- выполнения функций публичного B2C-магазина
- прямого редактирования клиентом внутренних бизнес-правил компании
- замены учетной системы 1С как первичного источника учетных данных
## 1.6 Основные принципы работы
Система должна обеспечивать следующие базовые принципы:
- доступ к функциям и данным определяется ролью пользователя
- клиент работает только в пределах собственных данных и данных своего контрагента
- стоимость товара и условия поставки публикуются только после обработки менеджером
- история изменений по заявкам, заказам и бонусным операциям фиксируется в системе
- сведения о товарах, остатках, заказах и статусах могут обновляться из внешней учетной системы

View File

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

View File

@@ -1,6 +1,6 @@
# 10. Экранные формы и прототипы интерфейсов # 5. Требования к интерфейсу и прототипам
## 10.1 Карта экранов ## 5.1 Карта экранов
Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта. Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта.
@@ -26,7 +26,7 @@
| Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом | | Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом |
| Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы | | Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы |
## 10.2 Общие требования к экранным формам ## 5.2 Общие требования к экранным формам
Экранные формы должны обеспечивать: Экранные формы должны обеспечивать:
@@ -42,9 +42,9 @@
- остатки и доступные варианты отображаются в наглядном виде - остатки и доступные варианты отображаются в наглядном виде
- пользователь понимает ограничения выбора и возможность кастомизации - пользователь понимает ограничения выбора и возможность кастомизации
## 10.3 Клиентские экранные формы ## 5.3 Клиентские экранные формы
### 10.3.1 Главная страница клиента ### 5.3.1 Главная страница клиента
Назначение страницы: Назначение страницы:
@@ -64,7 +64,7 @@
![Прототип главной страницы клиента](/prototypes/dashboard.svg) ![Прототип главной страницы клиента](/prototypes/dashboard.svg)
### 10.3.2 Каталог продукции ### 5.3.2 Каталог продукции
Назначение страницы: Назначение страницы:
@@ -83,7 +83,7 @@
![Прототип каталога продукции](/prototypes/catalog-grid.svg) ![Прототип каталога продукции](/prototypes/catalog-grid.svg)
### 10.3.3 Карточка товара ### 5.3.3 Карточка товара
Назначение страницы: Назначение страницы:
@@ -124,7 +124,7 @@
- правила по втулке с логотипом - правила по втулке с логотипом
- правила по нанесению индивидуальной надписи - правила по нанесению индивидуальной надписи
### 10.3.4 Корзина ### 5.3.4 Корзина
Назначение страницы: Назначение страницы:
@@ -146,7 +146,7 @@
![Прототип корзины](/prototypes/cart.svg) ![Прототип корзины](/prototypes/cart.svg)
### 10.3.5 Карточка заявки или заказа ### 5.3.5 Карточка заявки или заказа
Назначение страницы: Назначение страницы:
@@ -169,7 +169,7 @@
- история статусов - история статусов
- системные комментарии - системные комментарии
### 10.3.6 Страница логина и регистрации ### 5.3.6 Страница логина и регистрации
Назначение страницы: Назначение страницы:
@@ -184,7 +184,7 @@
- ссылка на самостоятельную заявку на подключение - ссылка на самостоятельную заявку на подключение
- блок пояснения по дальнейшему сценарию доступа - блок пояснения по дальнейшему сценарию доступа
### 10.3.7 Список заказов ### 5.3.7 Список заказов
Назначение страницы: Назначение страницы:
@@ -197,13 +197,13 @@
- таблица заказов - таблица заказов
- переход в карточку конкретного заказа - переход в карточку конкретного заказа
### 10.3.8 Уведомления ### 5.3.8 Уведомления
Назначение страницы: Назначение страницы:
- просмотр истории уведомлений по заказам, заявкам и бонусным операциям - просмотр истории уведомлений по заказам, заявкам и бонусным операциям
### 10.3.9 Бонусный кабинет ### 5.3.9 Бонусный кабинет
Назначение страницы: Назначение страницы:
@@ -223,9 +223,9 @@
![Прототип бонусного кабинета](/prototypes/bonus-cabinet.svg) ![Прототип бонусного кабинета](/prototypes/bonus-cabinet.svg)
## 10.4 Менеджерские экранные формы ## 5.4 Менеджерские экранные формы
### 10.4.1 Список клиентов ### 5.4.1 Список клиентов
Назначение страницы: Назначение страницы:
@@ -239,7 +239,7 @@
- индикаторы активности и количества заказов - индикаторы активности и количества заказов
- действие приглашения нового клиента - действие приглашения нового клиента
### 10.4.2 Карточка клиента ### 5.4.2 Карточка клиента
Назначение страницы: Назначение страницы:
@@ -255,7 +255,7 @@
- список бонусных операций - список бонусных операций
- связанные рефералы - связанные рефералы
### 10.4.3 Карточка обработки заявки ### 5.4.3 Карточка обработки заявки
Назначение страницы: Назначение страницы:
@@ -278,7 +278,7 @@
- история изменений - история изменений
- блок действий со статусом - блок действий со статусом
### 10.4.4 Список заказов менеджера ### 5.4.4 Список заказов менеджера
Назначение страницы: Назначение страницы:
@@ -290,7 +290,7 @@
![Прототип списка заказов менеджера](/prototypes/manager-orders.svg) ![Прототип списка заказов менеджера](/prototypes/manager-orders.svg)
### 10.4.5 Настройки каталога ### 5.4.5 Настройки каталога
Назначение страницы: Назначение страницы:
@@ -307,7 +307,7 @@
- списки стандартных параметров - списки стандартных параметров
- единое действие сохранения настроек - единое действие сохранения настроек
### 10.4.6 Настройки синхронизации и уведомлений ### 5.4.6 Настройки синхронизации и уведомлений
Назначение страницы: Назначение страницы: