Restructure technical specification sections
This commit is contained in:
Ruslan Bakiev
@@ -1,91 +1,19 @@
|
||||
# Техническое задание на разработку программного продукта
|
||||
|
||||
## 1. Общие положения
|
||||
|
||||
Наименование программного продукта: `Личный кабинет Фрегат`.
|
||||
|
||||
Заказчик: ООО `Фрегат Групп`.
|
||||
|
||||
Основанием для разработки являются:
|
||||
|
||||
- договор на разработку программного продукта №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/project-overview.md-->
|
||||
|
||||
<!--@include: ./tz/functional-requirements.md-->
|
||||
|
||||
<!--@include: ./tz/data-integrations.md-->
|
||||
<!--@include: ./tz/roles-access.md-->
|
||||
|
||||
<!--@include: ./tz/technical-architecture.md-->
|
||||
|
||||
<!--@include: ./tz/database-model.md-->
|
||||
|
||||
<!--@include: ./tz/non-functional-requirements.md-->
|
||||
<!--@include: ./tz/data-entities.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-->
|
||||
|
||||
125
docs/tz/components-libraries.md
Normal file
125
docs/tz/components-libraries.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# 7. Требования к компонентам и библиотекам
|
||||
|
||||
## 7.1 Общая компонентная схема
|
||||
|
||||
Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений.
|
||||
|
||||
|
||||
|
||||
## 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 Карта слоев и компонентов
|
||||
|
||||
|
||||
|
||||
## 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
186
docs/tz/data-entities.md
Normal 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 Структура хранения и модель базы данных
|
||||
|
||||
|
||||
|
||||
Модель базы данных должна обеспечивать:
|
||||
|
||||
- уникальность ключевых идентификаторов
|
||||
- хранение дат создания и изменения сущностей
|
||||
- хранение параметров товарных позиций в структурированном виде
|
||||
- хранение истории статусов и действий
|
||||
- хранение интеграционных идентификаторов для связи с внешними системами
|
||||
- расширение состава параметров товаров без разрушения базовой структуры ролей и заказов
|
||||
@@ -1,6 +1,6 @@
|
||||
# 5. Функциональные требования
|
||||
# 2. Функциональные требования
|
||||
|
||||
## 5.1 Требования к регистрации и подключению клиентов
|
||||
## 2.1 Требования к регистрации и подключению клиентов
|
||||
|
||||
Система должна поддерживать два базовых сценария подключения клиента:
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
7. После завершения регистрации клиент должен получить доступ к личному кабинету.
|
||||
8. Система должна поддерживать подключение доступных каналов уведомлений для клиентской учетной записи.
|
||||
|
||||
## 5.2 Требования к каталогу готовой продукции
|
||||
## 2.2 Требования к каталогу готовой продукции
|
||||
|
||||
Система должна предоставлять клиенту каталог готовой продукции без отображения цены до обработки менеджером.
|
||||
|
||||
@@ -33,7 +33,7 @@
|
||||
7. Система должна исключать отображение стоимости до момента публикации условий менеджером.
|
||||
8. Для параметров товара система должна отображать пояснения, помогающие клиенту понять назначение параметра и ограничения выбора.
|
||||
|
||||
## 5.3 Требования к параметрам каталога и кастомизации
|
||||
## 2.3 Требования к параметрам каталога и кастомизации
|
||||
|
||||
Система должна поддерживать настройку параметров по каждому товарному направлению.
|
||||
|
||||
@@ -47,7 +47,7 @@
|
||||
6. Наборы стандартных параметров должны редактироваться в административном контуре.
|
||||
7. Изменение набора стандартных параметров не должно приводить к потере уже сохраненных заказных данных.
|
||||
|
||||
## 5.4 Требования к корзине и заявке на заказ
|
||||
## 2.4 Требования к корзине и заявке на заказ
|
||||
|
||||
Система должна позволять клиенту собрать корзину и направить заявку на заказ.
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
6. Для заявки должны сохраняться дата создания, инициатор и закрепленный менеджер.
|
||||
7. До обработки менеджером стоимость в заявке не должна отображаться клиенту.
|
||||
|
||||
## 5.5 Требования к обработке заявки менеджером
|
||||
## 2.5 Требования к обработке заявки менеджером
|
||||
|
||||
Менеджер должен иметь возможность обработать клиентскую заявку вручную.
|
||||
|
||||
@@ -77,7 +77,7 @@
|
||||
8. Менеджер должен иметь возможность перевести заявку в работу.
|
||||
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. В карточке заказа должна отображаться дата актуальности данных.
|
||||
6. При наличии обновлений из внешней системы сведения по заказу должны синхронизироваться и отображаться пользователю.
|
||||
|
||||
## 5.9 Требования к уведомлениям
|
||||
## 2.9 Требования к уведомлениям
|
||||
|
||||
Система должна поддерживать уведомления по нескольким каналам связи.
|
||||
|
||||
@@ -154,7 +154,7 @@
|
||||
- изменение бонусного баланса
|
||||
- обработка заявки на использование либо вывод бонусов
|
||||
|
||||
## 5.10 Требования к бонусной и реферальной программе
|
||||
## 2.10 Требования к бонусной и реферальной программе
|
||||
|
||||
Система должна включать бонусный контур как самостоятельную функциональную область.
|
||||
|
||||
@@ -170,7 +170,7 @@
|
||||
8. Менеджер должен иметь возможность обрабатывать операции бонусного контура.
|
||||
9. Система должна уведомлять клиента об изменениях бонусного состояния.
|
||||
|
||||
## 5.11 Требования к административным настройкам
|
||||
## 2.11 Требования к административным настройкам
|
||||
|
||||
Система должна содержать административные разделы для управления следующими объектами:
|
||||
|
||||
|
||||
79
docs/tz/infrastructure-operations.md
Normal file
79
docs/tz/infrastructure-operations.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# 8. Требования к инфраструктуре и эксплуатации
|
||||
|
||||
## 8.1 Инфраструктурная схема
|
||||
|
||||
Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур.
|
||||
|
||||
|
||||
|
||||
## 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
63
docs/tz/integrations.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# 6. Требования к интеграциям
|
||||
|
||||
## 6.1 Общие требования к интеграционному контуру
|
||||
|
||||
Интеграционный слой должен обеспечивать обмен данными между личным кабинетом и внешними системами без потери целостности внутренних сущностей и статусов.
|
||||
|
||||
Интеграционный контур должен обеспечивать:
|
||||
|
||||
- получение данных из 1С
|
||||
- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов
|
||||
- сопоставление внутренних идентификаторов и идентификаторов внешних систем
|
||||
- регистрацию входящих и исходящих операций обмена
|
||||
- повторную обработку неуспешных сообщений
|
||||
- хранение истории обновлений по интеграционным операциям
|
||||
|
||||
## 6.2 Интеграция с 1С
|
||||
|
||||
Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога и заказов.
|
||||
|
||||
Система должна обеспечивать получение из 1С следующих данных:
|
||||
|
||||
- каталог товаров
|
||||
- характеристики товаров
|
||||
- складские остатки
|
||||
- сведения о заказах
|
||||
- статусы заказов
|
||||
- изменения состава, стоимости, доставки и иных существенных параметров заказа
|
||||
|
||||
## 6.3 Требования к структурам обмена
|
||||
|
||||
Входные и выходные данные интеграционного слоя должны описываться в структурированном виде и позволять однозначно восстанавливать:
|
||||
|
||||
- тип объекта обмена
|
||||
- идентификатор объекта
|
||||
- дату и время события
|
||||
- полезную нагрузку объекта
|
||||
- статус обработки
|
||||
- источник изменения
|
||||
|
||||
Для обмена должны использоваться структурированные payload-форматы, пригодные для сериализации в `JSON`.
|
||||
|
||||
## 6.4 Интеграционные поля и служебные атрибуты
|
||||
|
||||
Для сущностей, участвующих в обмене, должны поддерживаться:
|
||||
|
||||
- внешний идентификатор учетной системы
|
||||
- дата последней синхронизации
|
||||
- источник последнего обновления
|
||||
- признак успешной или неуспешной обработки
|
||||
- журнал интеграционных ошибок при наличии
|
||||
|
||||
## 6.5 Журналирование интеграционных операций
|
||||
|
||||
Для ключевых операций обмена система должна сохранять:
|
||||
|
||||
- тип объекта
|
||||
- идентификатор объекта
|
||||
- предыдущее состояние
|
||||
- новое состояние
|
||||
- дату и время изменения
|
||||
- пользователя либо внешний источник, выполнивший изменение
|
||||
- статус обработки сообщения
|
||||
- текст ошибки при наличии
|
||||
76
docs/tz/project-overview.md
Normal file
76
docs/tz/project-overview.md
Normal 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 Основные принципы работы
|
||||
|
||||
Система должна обеспечивать следующие базовые принципы:
|
||||
|
||||
- доступ к функциям и данным определяется ролью пользователя
|
||||
- клиент работает только в пределах собственных данных и данных своего контрагента
|
||||
- стоимость товара и условия поставки публикуются только после обработки менеджером
|
||||
- история изменений по заявкам, заказам и бонусным операциям фиксируется в системе
|
||||
- сведения о товарах, остатках, заказах и статусах могут обновляться из внешней учетной системы
|
||||
@@ -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 Ограничения доступа и требования к безопасности
|
||||
|
||||
Система должна обеспечивать:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 10. Экранные формы и прототипы интерфейсов
|
||||
# 5. Требования к интерфейсу и прототипам
|
||||
|
||||
## 10.1 Карта экранов
|
||||
## 5.1 Карта экранов
|
||||
|
||||
Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта.
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
| Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом |
|
||||
| Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы |
|
||||
|
||||
## 10.2 Общие требования к экранным формам
|
||||
## 5.2 Общие требования к экранным формам
|
||||
|
||||
Экранные формы должны обеспечивать:
|
||||
|
||||
@@ -42,9 +42,9 @@
|
||||
- остатки и доступные варианты отображаются в наглядном виде
|
||||
- пользователь понимает ограничения выбора и возможность кастомизации
|
||||
|
||||
## 10.3 Клиентские экранные формы
|
||||
## 5.3 Клиентские экранные формы
|
||||
|
||||
### 10.3.1 Главная страница клиента
|
||||
### 5.3.1 Главная страница клиента
|
||||
|
||||
Назначение страницы:
|
||||
|
||||
@@ -64,7 +64,7 @@
|
||||
|
||||
|
||||
|
||||
### 10.3.2 Каталог продукции
|
||||
### 5.3.2 Каталог продукции
|
||||
|
||||
Назначение страницы:
|
||||
|
||||
@@ -83,7 +83,7 @@
|
||||
|
||||
|
||||
|
||||
### 10.3.3 Карточка товара
|
||||
### 5.3.3 Карточка товара
|
||||
|
||||
Назначение страницы:
|
||||
|
||||
@@ -124,7 +124,7 @@
|
||||
- правила по втулке с логотипом
|
||||
- правила по нанесению индивидуальной надписи
|
||||
|
||||
### 10.3.4 Корзина
|
||||
### 5.3.4 Корзина
|
||||
|
||||
Назначение страницы:
|
||||
|
||||
@@ -146,7 +146,7 @@
|
||||
|
||||
|
||||
|
||||
### 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 @@
|
||||
|
||||
|
||||
|
||||
## 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 @@
|
||||
|
||||
|
||||
|
||||
### 10.4.5 Настройки каталога
|
||||
### 5.4.5 Настройки каталога
|
||||
|
||||
Назначение страницы:
|
||||
|
||||
@@ -307,7 +307,7 @@
|
||||
- списки стандартных параметров
|
||||
- единое действие сохранения настроек
|
||||
|
||||
### 10.4.6 Настройки синхронизации и уведомлений
|
||||
### 5.4.6 Настройки синхронизации и уведомлений
|
||||
|
||||
Назначение страницы:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user