2753 lines
139 KiB
Typst
2753 lines
139 KiB
Typst
#set document(title: "Техническое задание на разработку программного продукта")
|
||
#set page(
|
||
paper: "a4",
|
||
margin: (left: 20mm, right: 18mm, top: 18mm, bottom: 18mm),
|
||
numbering: "1",
|
||
header: none,
|
||
footer: none,
|
||
)
|
||
#set text(font: "Times New Roman", size: 10.5pt, lang: "ru")
|
||
#set par(justify: true, leading: 0.58em, first-line-indent: 0pt)
|
||
#set list(indent: 13pt, body-indent: 5pt)
|
||
#set heading(numbering: "1.1")
|
||
#show link: underline
|
||
#show raw: set text(font: "Times New Roman")
|
||
#show heading.where(level: 1): set text(size: 16pt, weight: "bold")
|
||
#show heading.where(level: 2): set text(size: 13pt, weight: "bold")
|
||
#show heading.where(level: 3): set text(size: 11.5pt, weight: "bold")
|
||
#show heading: it => {
|
||
if it.level == 1 {
|
||
pagebreak(weak: true)
|
||
}
|
||
block(above: 1.15em, below: 0.55em, it)
|
||
}
|
||
|
||
#v(1fr)
|
||
|
||
#align(center)[
|
||
#text(size: 16pt, weight: "bold")[Техническое задание]
|
||
|
||
#v(2mm)
|
||
#text(size: 16pt, weight: "bold")[на разработку программного продукта]
|
||
|
||
#v(2mm)
|
||
#text(size: 16pt, weight: "bold")[«Личный кабинет Фрегат»]
|
||
]
|
||
|
||
#v(1fr)
|
||
|
||
#align(center)[
|
||
#table(
|
||
columns: (40%, 60%),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 6pt,
|
||
[Заказчик], [ООО «Фрегат Групп»],
|
||
[Исполнитель], [ИП Бакиев Р.Ш.],
|
||
[Основание], [Договор №28/04-26ПО от 28.04.2026],
|
||
)
|
||
]
|
||
|
||
#v(8mm)
|
||
|
||
#pagebreak()
|
||
|
||
#set page(
|
||
paper: "a4",
|
||
margin: (left: 20mm, right: 18mm, top: 18mm, bottom: 18mm),
|
||
numbering: "1",
|
||
header: align(right)[#text(size: 8pt, fill: rgb("#667085"))[Приложение к договору №28/04-26ПО]],
|
||
footer: align(center)[#text(size: 8pt, fill: rgb("#667085"))[#context counter(page).display("1")]],
|
||
)
|
||
|
||
#outline(title: [Содержание], depth: 2, indent: auto)
|
||
|
||
#pagebreak()
|
||
|
||
|
||
= Общие положения
|
||
|
||
|
||
Настоящее техническое задание описывает разработку программного продукта Личный кабинет Фрегат.
|
||
|
||
Документ фиксирует назначение продукта, границы разработки, основные пользовательские контуры, функциональные и технические требования, порядок выполнения работ, приемки и гарантийного сопровождения.
|
||
|
||
== Основание для разработки
|
||
|
||
|
||
Разработка программного продукта выполняется на основании следующих документов и материалов:
|
||
|
||
- договор на разработку программного продукта №28/04-26ПО от 28 апреля 2026 года
|
||
- приложение №1 к договору: спецификация основных требований к программному обеспечению Личный кабинет Фрегат
|
||
- согласованные требования заказчика к клиентскому, менеджерскому, бонусному и интеграционному контурам
|
||
|
||
== Назначение продукта
|
||
|
||
|
||
Программный продукт предназначен для организации единого цифрового канала взаимодействия между ООО Фрегат Групп и B2B-клиентами компании.
|
||
|
||
Продукт должен объединять клиентский, менеджерский, административный и интеграционный контуры в единой веб-системе. Подробный состав функций, ролей, данных, интерфейсов и интеграций установлен в последующих разделах настоящего технического задания.
|
||
|
||
Объектом автоматизации являются процессы клиентского взаимодействия по заявкам и заказам: ознакомление клиента с продуктовой онтологией, формирование заявки в личном кабинете, обработка заявки менеджером, привязка заявки к заказу 1С и дальнейшее отображение актуальных учетных данных по заказам, статусам, составу, условиям, балансу и задолженности.
|
||
|
||
== Границы продукта
|
||
|
||
|
||
В состав программного продукта входят:
|
||
|
||
- клиентский веб-интерфейс
|
||
- менеджерский веб-интерфейс
|
||
- административный контур суперменеджера
|
||
- серверная бизнес-логика
|
||
- база данных
|
||
- модуль синхронизации с внешними системами
|
||
- модуль уведомлений
|
||
- модуль бонусной программы
|
||
- модуль административных настроек
|
||
|
||
Программный продукт не предназначен для выполнения следующих функций:
|
||
|
||
- самостоятельного ценообразования клиентом
|
||
- ведения бухгалтерского учета
|
||
- выполнения функций публичного B2C-магазина
|
||
- прямого редактирования клиентом внутренних бизнес-правил компании
|
||
- замены учетной системы 1С как первичного источника учетных данных
|
||
- синхронизации и отображения складских остатков в личном кабинете
|
||
- самостоятельного оформления клиентом учетного заказа без участия менеджера и без создания заказа в 1С
|
||
|
||
== Пользовательские контуры
|
||
|
||
|
||
В системе должны быть предусмотрены следующие пользовательские контуры:
|
||
|
||
- клиентский контур
|
||
- менеджерский контур
|
||
- административный контур суперменеджера
|
||
|
||
Клиентский контур предназначен для просмотра продуктовой онтологии, формирования заявки, просмотра своих заявок и связанных с ними заказов, состава заказов, статусов, условий, баланса, задолженности, уведомлений и бонусного кабинета.
|
||
|
||
Менеджерский контур предназначен для создания и подтверждения клиентских кабинетов, отправки приглашений, обработки заявок, привязки заявок к заказам 1С, сопровождения клиентов, просмотра данных клиента и работы с бонусными операциями.
|
||
|
||
Административный контур предназначен для управления пользователями, продуктовой онтологией, уведомлениями, интеграционными параметрами и отдельными сервисными настройками системы.
|
||
|
||
== Основные принципы работы
|
||
|
||
- доступ к функциям и данным определяется ролью пользователя
|
||
- клиент работает только в пределах собственных данных и данных своего контрагента
|
||
- клиентский кабинет создается менеджером на основании ИНН и ОГРН/ОГРНИП
|
||
- подключение клиента начинается с письма-приглашения на электронную почту
|
||
- последующий вход клиента выполняется через одноразовый шестизначный код, направляемый на подтвержденную электронную почту
|
||
- клиент может сформировать заявку на основании продуктовой онтологии личного кабинета
|
||
- корзина используется как черновик состава заявки перед отправкой менеджеру
|
||
- заявка, созданная в личном кабинете, хранится и отображается клиенту до момента привязки к учетному заказу 1С
|
||
- после появления и привязки заказа 1С заявка отображается как связанная с реальным заказом, а учетные сведения обновляются из 1С
|
||
- данные из 1С загружаются только для клиентов, уже созданных и подтвержденных в личном кабинете
|
||
- история изменений по заявкам, заказам и бонусным операциям фиксируется в системе
|
||
- сведения о заказах, составе заказов, статусах, условиях, балансе и задолженности обновляются из 1С
|
||
|
||
= Функциональные требования
|
||
|
||
|
||
== Требования к подключению клиентов
|
||
|
||
|
||
Система должна поддерживать подключение клиента только по инициативе менеджера:
|
||
|
||
- менеджер создает карточку клиента и указывает ИНН и ОГРН/ОГРНИП
|
||
- менеджер направляет клиенту персональное приглашение на электронную почту
|
||
- клиент завершает подключение по персональной ссылке из письма и подтверждает электронную почту
|
||
- после первичного подключения клиент входит в личный кабинет по одноразовому шестизначному коду, направляемому на подтвержденную электронную почту
|
||
- данные из 1С сопоставляются с клиентской карточкой по ИНН и ОГРН/ОГРНИП при очередной загрузке файла обмена
|
||
|
||
Функциональные требования:
|
||
|
||
+ Менеджер должен иметь возможность направить клиенту приглашение на подключение по электронной почте.
|
||
+ Менеджер должен иметь возможность создать и подтвердить клиентскую карточку с ИНН и ОГРН/ОГРНИП.
|
||
+ Клиент должен иметь возможность завершить подключение по персональной ссылке.
|
||
+ Система должна использовать электронную почту клиента как основной подтвержденный канал доступа и юридически значимых уведомлений в рамках личного кабинета.
|
||
+ Система должна поддерживать вход клиента по одноразовому шестизначному коду, направляемому на подтвержденную электронную почту.
|
||
+ После завершения подключения клиент должен получить доступ к личному кабинету.
|
||
+ Публичная страница входа не должна содержать самостоятельную регистрацию или самостоятельную заявку на подключение.
|
||
+ Система не должна создавать клиентский кабинет автоматически на основании данных, полученных из 1С.
|
||
+ Система должна поддерживать подключение дополнительных каналов уведомлений для клиентской учетной записи только после входа клиента в личный кабинет.
|
||
|
||
== Требования к главной странице клиента
|
||
|
||
|
||
После входа клиент должен видеть сводку по своей компании, последние заявки, связанные заказы, баланс или задолженность и переход к продуктовому конструктору заявки.
|
||
|
||
Функциональные требования:
|
||
|
||
+ Система должна отображать краткую информацию о клиентской организации.
|
||
+ Система должна отображать текущий баланс или задолженность, если такие сведения получены из 1С.
|
||
+ Система должна отображать дату актуальности баланса или задолженности.
|
||
+ Система должна отображать последние заявки клиента и их текущие состояния.
|
||
+ Система должна отображать последние заказы клиента и их текущие статусы.
|
||
+ Система должна предоставлять переход к созданию новой заявки через продуктовый конструктор.
|
||
+ Система должна предоставлять переход к полному списку заказов и карточке конкретного заказа.
|
||
+ Система должна отображать уведомления, связанные с заказами, балансом, задолженностью и бонусными операциями.
|
||
+ Система не должна отображать клиенту складские остатки или форму самостоятельного создания учетного заказа.
|
||
|
||
== Требования к продуктовой онтологии и конструктору заявки
|
||
|
||
|
||
Система должна предоставлять клиенту справочник продуктовых направлений и конструктор заявки. Конструктор предназначен для описания потребности клиента и не является складским каталогом, механизмом резервирования остатков или механизмом самостоятельного оформления учетного заказа.
|
||
|
||
Функциональные требования:
|
||
|
||
+ Система должна отображать список продуктовых направлений, доступных для ознакомления и формирования заявки.
|
||
+ Для каждого продуктового направления система должна отображать описание, применимые параметры и допустимые варианты выбора.
|
||
+ Система должна позволять клиенту выбрать параметры и добавить позицию в корзину заявки.
|
||
+ Корзина должна использоваться только как черновик состава заявки перед отправкой менеджеру.
|
||
+ Корзина не должна выполнять функции интернет-магазина, резервирования товара, оплаты или подтверждения наличия.
|
||
+ Система должна позволять клиенту указать количество, комментарий и иную информацию, необходимую менеджеру для обработки заявки.
|
||
+ Система не должна отображать клиенту складские остатки и не должна обещать наличие продукции на складе.
|
||
+ Система не должна рассчитывать финальную стоимость автоматически, если стоимость должна определяться менеджером или учетной системой.
|
||
+ Продуктовая онтология должна администрироваться в системе и не должна зависеть от синхронизации складских остатков из 1С.
|
||
|
||
== Требования к заявкам клиента
|
||
|
||
|
||
Заявка является сущностью личного кабинета и фиксирует потребность клиента до создания или привязки учетного заказа в 1С.
|
||
|
||
Функциональные требования:
|
||
|
||
+ Клиент должен иметь возможность создать заявку на основании продуктового конструктора.
|
||
+ Клиент должен иметь возможность собрать состав заявки в корзине и отправить его менеджеру как единую заявку.
|
||
+ Система должна сохранять состав заявки, выбранные параметры, количество, комментарий клиента и дату создания.
|
||
+ Заявка должна отображаться клиенту до момента привязки к заказу 1С.
|
||
+ Менеджер должен видеть список заявок клиентов и карточку каждой заявки.
|
||
+ Менеджер должен иметь возможность обработать заявку и связать ее с заказом 1С по номеру или внешнему идентификатору заказа.
|
||
+ До привязки к заказу 1С заявка должна отображаться как заявка личного кабинета, а не как учетный заказ.
|
||
+ После привязки к заказу 1С карточка заявки должна отображать связь с заказом и актуальные учетные сведения, полученные из 1С.
|
||
+ Если при очередной синхронизации из 1С пришел заказ, связанный с заявкой, система должна аккуратно заменить или расширить отображение заявки данными реального заказа.
|
||
|
||
Для заявки должны поддерживаться следующие базовые состояния:
|
||
|
||
- создана
|
||
- направлена менеджеру
|
||
- в обработке
|
||
- связана с заказом 1С
|
||
- закрыта
|
||
- отменена
|
||
|
||
== Требования к заказам и их сопровождению
|
||
|
||
|
||
Система должна предоставлять клиенту и менеджеру доступ к списку заказов, карточке каждого заказа и актуальным учетным сведениям, полученным из 1С. Заказ и заявка являются разными сущностями: заявка создается в личном кабинете, заказ является учетной сущностью 1С.
|
||
|
||
Функциональные требования:
|
||
|
||
+ Система должна отображать перечень заказов клиента.
|
||
+ Система должна поддерживать фильтрацию заказов по периоду и статусу.
|
||
+ Для каждого заказа система должна предоставлять отдельную карточку.
|
||
+ В карточке заказа должны отображаться состав, статус, стоимость, условия поставки и история изменений.
|
||
+ В карточке заказа должна отображаться дата актуальности данных.
|
||
+ При наличии обновлений из внешней системы сведения по заказу должны синхронизироваться и отображаться пользователю.
|
||
+ Система должна отображать текущую задолженность клиента, если такие сведения получены из 1С.
|
||
+ Для задолженности должна отображаться дата актуальности данных.
|
||
+ Система должна показывать только заказы, сопоставленные с подтвержденной клиентской карточкой по ИНН и ОГРН/ОГРНИП.
|
||
+ Система должна поддерживать связь заказа 1С с заявкой личного кабинета, если такая связь установлена менеджером или определена по согласованному идентификатору.
|
||
+ После привязки заказа к заявке клиент должен видеть единый пользовательский сценарий: исходную заявку, номер заказа 1С, состав, статус, стоимость, условия и историю обновлений.
|
||
|
||
== Требования к уведомлениям
|
||
|
||
|
||
Система должна поддерживать уведомления по нескольким каналам связи.
|
||
|
||
Поддерживаемые каналы:
|
||
|
||
- электронная почта
|
||
- Telegram
|
||
- Max
|
||
|
||
Система должна поддерживать уведомления по следующим событиям:
|
||
|
||
- приглашение к подключению
|
||
- создание заявки клиентом
|
||
- изменение состояния заявки
|
||
- привязка заявки к заказу 1С
|
||
- изменение статуса заказа
|
||
- обновление сведений по заказу
|
||
- изменение баланса или задолженности
|
||
- изменение бонусного баланса
|
||
- обработка заявки на использование либо вывод бонусов
|
||
|
||
== Требования к бонусной и реферальной программе
|
||
|
||
|
||
Система должна включать бонусный контур как самостоятельную функциональную область с отдельным пользовательским интерфейсом.
|
||
|
||
Функциональные требования:
|
||
|
||
+ Система должна хранить правила участия клиента в бонусной программе.
|
||
+ Система должна поддерживать фиксацию реферальных связей.
|
||
+ Система должна хранить начисления, списания и текущий остаток бонусов.
|
||
+ Клиент должен видеть текущий бонусный баланс.
|
||
+ Клиент должен видеть историю бонусных операций.
|
||
+ Клиент должен иметь возможность использовать бонусы в пределах установленных правил.
|
||
+ Клиент должен иметь возможность подать заявку на вывод либо иную операцию, если это предусмотрено правилами программы.
|
||
+ Менеджер должен иметь возможность обрабатывать операции бонусного контура.
|
||
+ Система должна уведомлять клиента об изменениях бонусного состояния.
|
||
|
||
== Требования к административным настройкам
|
||
|
||
|
||
Система должна содержать административные разделы для управления следующими объектами:
|
||
|
||
- продуктовой онтологией и параметрами конструктора заявки
|
||
- шаблонами уведомлений
|
||
- параметрами синхронизации
|
||
- отдельными настройками бонусного контура
|
||
|
||
= Требования к ролям и правам доступа
|
||
|
||
|
||
== Состав ролей
|
||
|
||
|
||
В системе должны быть предусмотрены следующие роли пользователей:
|
||
|
||
- клиент
|
||
- менеджер
|
||
- суперменеджер
|
||
|
||
== Роль клиента
|
||
|
||
|
||
Пользователь с ролью Клиент представляет организацию-контрагента и работает только с данными своей компании.
|
||
|
||
Клиенту должны быть доступны следующие действия:
|
||
|
||
- завершение подключения по персональному приглашению
|
||
- вход по одноразовому шестизначному коду, направленному на подтвержденную электронную почту
|
||
- просмотр и изменение разрешенных профильных данных
|
||
- подключение доступных каналов уведомлений
|
||
- просмотр сводки по компании
|
||
- просмотр продуктовой онтологии и конструктора заявки
|
||
- сбор состава заявки в корзине-черновике
|
||
- создание заявки
|
||
- просмотр списка и карточки заявок
|
||
- просмотр баланса или задолженности
|
||
- просмотр списка заказов
|
||
- просмотр карточки заказа, состава заказа, статуса и истории изменений
|
||
- просмотр истории уведомлений
|
||
- просмотр бонусного баланса и истории бонусных операций
|
||
- подача заявки на использование либо вывод бонусов при наличии соответствующих правил
|
||
|
||
== Роль менеджера
|
||
|
||
|
||
Пользователь с ролью Менеджер представляет сотрудника компании, закрепленного за клиентами.
|
||
|
||
Менеджеру должны быть доступны следующие действия:
|
||
|
||
- создание и подтверждение клиентской карточки по ИНН и ОГРН/ОГРНИП
|
||
- назначение ответственного сопровождения
|
||
- отправка персонального приглашения клиенту
|
||
- просмотр и обработка заявок клиентов
|
||
- привязка заявки к заказу 1С по номеру или внешнему идентификатору
|
||
- просмотр карточек клиентов и заказов
|
||
- просмотр баланса, задолженности и истории заказов клиента
|
||
- просмотр клиентского представления по карточке клиента для контроля того, какие сведения доступны клиенту в личном кабинете
|
||
- контроль сопоставления данных из 1С с подтвержденными клиентскими карточками
|
||
- выполнение операций в бонусном контуре в пределах полномочий
|
||
|
||
== Роль суперменеджера
|
||
|
||
|
||
Пользователь с ролью Суперменеджер обладает всеми правами менеджера и дополнительными административными полномочиями.
|
||
|
||
Суперменеджеру должны быть доступны следующие действия:
|
||
|
||
- доступ ко всем клиентам и заказам
|
||
- управление продуктовой онтологией и параметрами конструктора заявки
|
||
- управление настройками уведомлений
|
||
- управление параметрами интеграции и синхронизации
|
||
- расширенное управление бонусным и реферальным контуром
|
||
|
||
== Матрица доступа
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Действие*],
|
||
[*Клиент*],
|
||
[*Менеджер*],
|
||
[*Суперменеджер*],
|
||
[Завершение подключения],
|
||
[Да],
|
||
[Нет],
|
||
[Нет],
|
||
[Отправка приглашения клиенту],
|
||
[Нет],
|
||
[Да],
|
||
[Да],
|
||
[Просмотр баланса и задолженности],
|
||
[Да],
|
||
[Да],
|
||
[Да],
|
||
[Просмотр списка и карточки заказов],
|
||
[Да],
|
||
[Да],
|
||
[Да],
|
||
[Просмотр продуктовой онтологии],
|
||
[Да],
|
||
[Да],
|
||
[Да],
|
||
[Создание заявки],
|
||
[Да],
|
||
[Нет],
|
||
[Нет],
|
||
[Обработка заявки],
|
||
[Нет],
|
||
[Да],
|
||
[Да],
|
||
[Привязка заявки к заказу 1С],
|
||
[Нет],
|
||
[Да],
|
||
[Да],
|
||
[Создание клиентской карточки],
|
||
[Нет],
|
||
[Да],
|
||
[Да],
|
||
[Создание заказа из личного кабинета],
|
||
[Нет],
|
||
[Нет],
|
||
[Нет],
|
||
[Контроль синхронизации с 1С],
|
||
[Нет],
|
||
[Да],
|
||
[Да],
|
||
[Управление уведомлениями],
|
||
[Нет],
|
||
[Нет],
|
||
[Да],
|
||
[Управление параметрами синхронизации],
|
||
[Нет],
|
||
[Нет],
|
||
[Да],
|
||
[Управление бонусными правилами],
|
||
[Нет],
|
||
[Да],
|
||
[Да]
|
||
)
|
||
]
|
||
|
||
|
||
== Ограничения доступа и требования к безопасности
|
||
|
||
|
||
Система должна обеспечивать:
|
||
|
||
- раздельные интерфейсы для клиентского и менеджерского контуров
|
||
- доступ клиента только к данным собственного контрагента
|
||
- ограничение административных функций в соответствии с ролью
|
||
- журналирование значимых пользовательских действий
|
||
- хранение истории изменения состояний заявок, статусов заказов и бонусных операций
|
||
|
||
= Требования к данным и сущностям
|
||
|
||
|
||
== Общие требования к данным
|
||
|
||
|
||
Основное хранилище данных программного продукта реализуется на PostgreSQL. Прикладной доступ к данным осуществляется через Prisma ORM.
|
||
|
||
Система должна обеспечивать хранение:
|
||
|
||
- пользователей и ролей
|
||
- компаний и профилей контрагентов
|
||
- адресов доставки
|
||
- продуктовой онтологии и параметров конструктора заявки
|
||
- заявок клиента и состава заявок
|
||
- заказов, полученных из 1С
|
||
- состава заказов
|
||
- событий изменения статусов
|
||
- подключений мессенджеров
|
||
- бонусных и реферальных сущностей
|
||
|
||
В прикладной реализации должны использоваться фактические сущности базы данных, определенные в schema.prisma. Наименование сущностей в документации и в базе данных должно сопоставляться однозначно.
|
||
|
||
== Справочник сущностей базы данных
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Модель в базе данных*],
|
||
[*Русское наименование*],
|
||
[*Назначение*],
|
||
[Company],
|
||
[Компания],
|
||
[Клиентская организация],
|
||
[User],
|
||
[Пользователь],
|
||
[Учетная запись клиента, менеджера или суперменеджера],
|
||
[DeliveryAddress],
|
||
[Адрес доставки],
|
||
[Справочник адресов доставки клиента],
|
||
[CounterpartyProfile],
|
||
[Профиль контрагента],
|
||
[Юридические и банковские реквизиты клиента],
|
||
[Invitation],
|
||
[Приглашение],
|
||
[Менеджерское приглашение на подключение],
|
||
[MessengerConnection],
|
||
[Подключение мессенджера],
|
||
[Связка пользователя с Telegram или MAX],
|
||
[ProductType],
|
||
[Продуктовое направление],
|
||
[Онтология продукции для конструктора заявки],
|
||
[Request],
|
||
[Заявка],
|
||
[Заявка клиента, созданная в личном кабинете],
|
||
[RequestItem],
|
||
[Позиция заявки],
|
||
[Состав и параметры заявки],
|
||
[Order],
|
||
[Заказ],
|
||
[Заказ клиента, полученный из 1С и связанный с заявкой при наличии связи],
|
||
[OrderItem],
|
||
[Позиция заказа],
|
||
[Состав заказа],
|
||
[OrderStatusEvent],
|
||
[Событие статуса заказа],
|
||
[История изменения статусов],
|
||
[ReferralLink],
|
||
[Реферальная связь],
|
||
[Связь между рекомендателем и приглашенным клиентом],
|
||
[BonusTransaction],
|
||
[Бонусная транзакция],
|
||
[Начисление или списание бонусов],
|
||
[RewardWithdrawalRequest],
|
||
[Заявка на вывод бонусов],
|
||
[Заявка клиента на использование или вывод бонусов]
|
||
)
|
||
]
|
||
|
||
|
||
== Служебные перечисления и статусы
|
||
|
||
|
||
В модели данных используются следующие перечисления:
|
||
|
||
- UserRole: CLIENT, MANAGER, SUPER_MANAGER
|
||
- RegistrationStatus: PENDING, APPROVED, REJECTED
|
||
- MessengerType: TELEGRAM, MAX
|
||
- RequestStatus: CREATED, SENT_TO_MANAGER, PROCESSING, LINKED_TO_1C_ORDER, CLOSED, CANCELED
|
||
- OrderStatus: NEW, MANAGER_PROCESSING, WAITING_DOUBLE_CONFIRM, CLIENT_REJECTED, MANAGER_REJECTED, MANAGER_BLOCKED, CONFIRMED, IN_PROGRESS, COMPLETED
|
||
- WithdrawalStatus: PENDING, APPROVED, REJECTED
|
||
|
||
== Пользователи и компании
|
||
|
||
|
||
=== Company
|
||
|
||
|
||
Русское наименование: Компания
|
||
|
||
Назначение:
|
||
|
||
- хранение клиентской организации
|
||
- объединение пользователей одной компании
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- name
|
||
- inn
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
Связи:
|
||
|
||
- одна компания связана со многими пользователями
|
||
|
||
=== User
|
||
|
||
|
||
Русское наименование: Пользователь
|
||
|
||
Назначение:
|
||
|
||
- хранение клиентской, менеджерской или административной учетной записи
|
||
- связывание пользователя с компанией, заявками, заказами, бонусами и адресами
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- email
|
||
- fullName
|
||
- role
|
||
- companyId
|
||
- defaultDeliveryAddressId
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
Связи:
|
||
|
||
- пользователь может быть связан с компанией
|
||
- пользователь может иметь профиль контрагента
|
||
- пользователь может иметь адреса доставки
|
||
- пользователь может создавать заявки
|
||
- пользователь может выступать клиентом или менеджером в заказах
|
||
- пользователь может иметь бонусные операции и заявки на вывод
|
||
|
||
=== DeliveryAddress
|
||
|
||
|
||
Русское наименование: Адрес доставки
|
||
|
||
Назначение:
|
||
|
||
- хранение адресов доставки клиента
|
||
- выбор адреса по умолчанию для заказов, если адрес используется в данных клиента
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- userId
|
||
- label
|
||
- address
|
||
- unrestrictedValue
|
||
- fiasId
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
=== CounterpartyProfile
|
||
|
||
|
||
Русское наименование: Профиль контрагента
|
||
|
||
Назначение:
|
||
|
||
- хранение полных реквизитов клиента для договоров, счетов и поставки
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- userId
|
||
- companyName
|
||
- companyFullName
|
||
- inn
|
||
- kpp
|
||
- ogrn
|
||
- legalAddress
|
||
- bankName
|
||
- bik
|
||
- correspondentAccount
|
||
- checkingAccount
|
||
- signerFullName
|
||
- signerPosition
|
||
- signerBasis
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
=== Invitation
|
||
|
||
|
||
Русское наименование: Приглашение
|
||
|
||
Назначение:
|
||
|
||
- хранение менеджерского приглашения клиента на подключение к личному кабинету
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- token
|
||
- email
|
||
- companyName
|
||
- inn
|
||
- ogrn
|
||
- managerId
|
||
- acceptedById
|
||
- expiresAt
|
||
- acceptedAt
|
||
- createdAt
|
||
|
||
=== MessengerConnection
|
||
|
||
|
||
Русское наименование: Подключение мессенджера
|
||
|
||
Назначение:
|
||
|
||
- хранение подключенного Telegram или MAX-канала пользователя
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- userId
|
||
- type
|
||
- channelId
|
||
- displayName
|
||
- username
|
||
- avatarFileId
|
||
- avatarFileUniqueId
|
||
- isActive
|
||
- createdAt
|
||
|
||
== Продуктовая онтология, заявки и данные из 1С
|
||
|
||
=== ProductType
|
||
|
||
|
||
Русское наименование: Продуктовое направление
|
||
|
||
Назначение:
|
||
|
||
- хранение продуктовой онтологии для ознакомления клиента
|
||
- хранение набора параметров, доступных в конструкторе заявки
|
||
- описание того, что клиент может запросить у менеджера
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- code
|
||
- name
|
||
- description
|
||
- parameterSchema
|
||
- isActive
|
||
- sortOrder
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
Комментарий к модели:
|
||
|
||
- продуктовое направление не является складским остатком и не подтверждает наличие продукции
|
||
- остатки по складам в личном кабинете не отображаются
|
||
|
||
=== Request
|
||
|
||
|
||
Русское наименование: Заявка
|
||
|
||
Назначение:
|
||
|
||
- хранение потребности клиента, созданной через продуктовый конструктор
|
||
- хранение состояния обработки заявки
|
||
- хранение связи с заказом 1С после обработки менеджером
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- code
|
||
- customerId
|
||
- managerId
|
||
- status
|
||
- comment
|
||
- linkedOrderId
|
||
- linkedOrderExternalId
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
Комментарий к модели:
|
||
|
||
- заявка создается в личном кабинете клиентом
|
||
- заявка не является учетным заказом до привязки к заказу 1С
|
||
- после привязки клиент видит связь заявки с заказом и актуальные сведения из 1С
|
||
|
||
=== RequestItem
|
||
|
||
|
||
Русское наименование: Позиция заявки
|
||
|
||
Назначение:
|
||
|
||
- хранение выбранного продуктового направления
|
||
- хранение параметров, количества и комментариев по позиции заявки
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- requestId
|
||
- productTypeId
|
||
- productName
|
||
- quantity
|
||
- parameters
|
||
- comment
|
||
- createdAt
|
||
|
||
=== Order
|
||
|
||
|
||
Русское наименование: Заказ
|
||
|
||
Назначение:
|
||
|
||
- хранение заказа клиента, полученного из 1С
|
||
- хранение текущего статуса, стоимости, условий, состава и служебных данных синхронизации
|
||
- хранение связи с заявкой личного кабинета, если заказ создан на основании заявки
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- code
|
||
- customerId
|
||
- deliveryAddressId
|
||
- deliveryAddress
|
||
- managerId
|
||
- requestId
|
||
- status
|
||
- deliveryTerms
|
||
- deliveryFee
|
||
- totalPrice
|
||
- externalId
|
||
- sourceUpdatedAt
|
||
- lastSyncAt
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
Комментарий к модели:
|
||
|
||
- заказ создается или обновляется на основании данных, полученных из 1С
|
||
- клиент не создает учетный заказ через личный кабинет
|
||
- учетный заказ может быть связан с заявкой клиента после обработки менеджером
|
||
|
||
=== OrderItem
|
||
|
||
|
||
Русское наименование: Позиция заказа
|
||
|
||
Назначение:
|
||
|
||
- хранение состава заказа
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- orderId
|
||
- productName
|
||
- quantity
|
||
- unit
|
||
- unitPrice
|
||
- amount
|
||
- createdAt
|
||
|
||
=== OrderStatusEvent
|
||
|
||
|
||
Русское наименование: Событие статуса заказа
|
||
|
||
Назначение:
|
||
|
||
- хранение истории изменения статусов заказа
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- orderId
|
||
- status
|
||
- actorUserId
|
||
- note
|
||
- createdAt
|
||
|
||
== Бонусный и реферальный контур
|
||
|
||
|
||
=== ReferralLink
|
||
|
||
|
||
Русское наименование: Реферальная связь
|
||
|
||
Назначение:
|
||
|
||
- фиксация связи между рекомендателем и приглашенным клиентом
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- referrerId
|
||
- refereeId
|
||
- createdById
|
||
- bonusPercent
|
||
- createdAt
|
||
|
||
=== BonusTransaction
|
||
|
||
|
||
Русское наименование: Бонусная транзакция
|
||
|
||
Назначение:
|
||
|
||
- хранение начисления или списания бонусов
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- userId
|
||
- amount
|
||
- reason
|
||
- orderId
|
||
- referralLinkId
|
||
- createdAt
|
||
|
||
=== RewardWithdrawalRequest
|
||
|
||
|
||
Русское наименование: Заявка на вывод бонусов
|
||
|
||
Назначение:
|
||
|
||
- хранение заявки клиента на использование или вывод бонусов
|
||
|
||
Основные поля:
|
||
|
||
- id
|
||
- requesterId
|
||
- amount
|
||
- status
|
||
- reviewedById
|
||
- reviewComment
|
||
- createdAt
|
||
- updatedAt
|
||
|
||
== Основные связи между сущностями
|
||
|
||
|
||
Укрупненная структура связей определяется следующими правилами:
|
||
|
||
- Company объединяет пользователей одной клиентской организации
|
||
- User связан с CounterpartyProfile, DeliveryAddress, MessengerConnection, Request, Order, BonusTransaction и RewardWithdrawalRequest
|
||
- ProductType используется в RequestItem как справочник продуктовой онтологии
|
||
- Request содержит набор RequestItem и может быть связан с Order
|
||
- Order содержит набор OrderItem и историю OrderStatusEvent
|
||
- реферальные связи реализуются через ReferralLink, связывающий одного пользователя с другим пользователем
|
||
|
||
= Требования к интерфейсу, прототипам и дизайну
|
||
|
||
|
||
== Карта экранов
|
||
|
||
|
||
Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта.
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Раздел*],
|
||
[*Маршрут*],
|
||
[*Роль*],
|
||
[*Назначение*],
|
||
[Главная страница],
|
||
[/],
|
||
[клиент],
|
||
[сводка по заявкам, заказам, балансу и задолженности],
|
||
[Продуктовый конструктор],
|
||
[/products],
|
||
[клиент],
|
||
[ознакомление с продуктовой онтологией и создание заявки],
|
||
[Карточка продуктового направления],
|
||
[/products/\[slug\]],
|
||
[клиент],
|
||
[выбор параметров заявки],
|
||
[Корзина заявки],
|
||
[/cart],
|
||
[клиент],
|
||
[проверка состава заявки перед отправкой менеджеру],
|
||
[Список заявок клиента],
|
||
[/client-requests],
|
||
[клиент],
|
||
[просмотр созданных заявок],
|
||
[Карточка заявки клиента],
|
||
[/client-requests/\[id\]],
|
||
[клиент],
|
||
[просмотр заявки и связанного заказа 1С],
|
||
[Список заказов клиента],
|
||
[/client-orders],
|
||
[клиент],
|
||
[просмотр истории заказов],
|
||
[Карточка заказа клиента],
|
||
[/client-orders/\[id\]],
|
||
[клиент],
|
||
[просмотр статуса, состава, условий и истории],
|
||
[Профиль],
|
||
[/profile],
|
||
[клиент],
|
||
[базовые данные учетной записи],
|
||
[Контрагент],
|
||
[/profile/counterparty],
|
||
[клиент],
|
||
[реквизиты и юридические данные],
|
||
[Адреса доставки],
|
||
[/profile/addresses],
|
||
[клиент],
|
||
[адресный справочник],
|
||
[Уведомления],
|
||
[/notifications],
|
||
[клиент],
|
||
[история уведомлений],
|
||
[Бонусный кабинет],
|
||
[/bonus-program],
|
||
[клиент],
|
||
[баланс, история и бонусные действия],
|
||
[Список клиентов],
|
||
[/clients],
|
||
[менеджер],
|
||
[клиентская база],
|
||
[Карточка клиента],
|
||
[/clients/\[id\]],
|
||
[менеджер],
|
||
[данные компании, заказы, бонусы],
|
||
[Приглашение клиента],
|
||
[/clients/invite],
|
||
[менеджер],
|
||
[выдача приглашения на подключение],
|
||
[Список заявок],
|
||
[/requests],
|
||
[менеджер],
|
||
[обработка заявок клиентов],
|
||
[Карточка заявки],
|
||
[/requests/\[id\]],
|
||
[менеджер],
|
||
[обработка заявки и привязка к заказу 1С],
|
||
[Список заказов],
|
||
[/orders],
|
||
[менеджер],
|
||
[просмотр заказов по клиентам],
|
||
[Карточка заказа],
|
||
[/orders/\[id\]],
|
||
[менеджер],
|
||
[просмотр состава, статуса и данных из 1С],
|
||
[Настройки синхронизации],
|
||
[/settings-sync],
|
||
[суперменеджер],
|
||
[мониторинг и управление обменом],
|
||
[Настройки конструктора],
|
||
[/catalog-settings],
|
||
[суперменеджер],
|
||
[продуктовая онтология и параметры заявок],
|
||
[Бонусная система],
|
||
[/bonus-system/\\\*],
|
||
[менеджер/суперменеджер],
|
||
[рефералы, транзакции, выводы]
|
||
)
|
||
]
|
||
|
||
|
||
== Маршруты и экранные формы
|
||
|
||
|
||
Ниже приведен перечень экранных форм, предусмотренных в составе frontend-контура программного продукта.
|
||
|
||
=== Публичные и клиентские страницы
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Маршрут*],
|
||
[*Экран*],
|
||
[*Назначение*],
|
||
[/],
|
||
[Главная страница],
|
||
[Стартовая страница личного кабинета],
|
||
[/login],
|
||
[Вход],
|
||
[Вход и первичный сценарий доступа],
|
||
[/products],
|
||
[Продуктовый конструктор],
|
||
[Справочник продуктовых направлений и создание заявки],
|
||
[/products/\[slug\]],
|
||
[Карточка продуктового направления],
|
||
[Выбор параметров заявки],
|
||
[/client-requests],
|
||
[Список заявок клиента],
|
||
[История заявок клиента],
|
||
[/client-requests/\[id\]],
|
||
[Карточка заявки клиента],
|
||
[Детали заявки и связанного заказа 1С],
|
||
[/client-orders],
|
||
[Список заказов клиента],
|
||
[История заказов клиента],
|
||
[/client-orders/\[id\]],
|
||
[Карточка заказа клиента],
|
||
[Детали конкретного заказа клиента],
|
||
[/notifications],
|
||
[Уведомления],
|
||
[Список системных уведомлений],
|
||
[/bonus-program],
|
||
[Бонусный кабинет],
|
||
[Бонусный баланс, подарочные карты и бонусные действия]
|
||
)
|
||
]
|
||
|
||
|
||
=== Профиль клиента
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Маршрут*],
|
||
[*Экран*],
|
||
[*Назначение*],
|
||
[/profile],
|
||
[Профиль],
|
||
[Основные данные пользователя],
|
||
[/profile/counterparty],
|
||
[Реквизиты контрагента],
|
||
[Юридические и банковские данные],
|
||
[/profile/addresses],
|
||
[Адреса доставки],
|
||
[Список адресов доставки],
|
||
[/profile/addresses/new],
|
||
[Новый адрес доставки],
|
||
[Создание адреса доставки],
|
||
[/profile/notifications],
|
||
[Настройки уведомлений],
|
||
[Подключение и настройка каналов уведомлений],
|
||
[/profile/notifications/success],
|
||
[Успешное подключение уведомлений],
|
||
[Финальный экран сценария подключения канала]
|
||
)
|
||
]
|
||
|
||
|
||
=== Менеджерские и административные страницы
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Маршрут*],
|
||
[*Экран*],
|
||
[*Назначение*],
|
||
[/clients],
|
||
[Клиенты],
|
||
[Список клиентских компаний и пользователей],
|
||
[/clients/\[id\]],
|
||
[Карточка клиента],
|
||
[Детали клиента, его заказы и бонусные данные],
|
||
[/clients/invite],
|
||
[Пригласить клиента],
|
||
[Создание приглашения на подключение],
|
||
[/orders],
|
||
[Список заказов],
|
||
[Заказы клиентов, полученные из 1С],
|
||
[/orders/\[id\]],
|
||
[Карточка заказа],
|
||
[Состав, статус, баланс и служебные данные синхронизации],
|
||
[/requests],
|
||
[Заявки],
|
||
[Заявки клиентов, созданные в личном кабинете],
|
||
[/requests/\[id\]],
|
||
[Карточка заявки],
|
||
[Обработка заявки и привязка к заказу 1С],
|
||
[/settings-sync],
|
||
[1С / синхронизация],
|
||
[Управление и мониторинг синхронизации],
|
||
[/messages],
|
||
[Сообщения],
|
||
[Шаблоны и тексты менеджерских сообщений]
|
||
)
|
||
]
|
||
|
||
|
||
=== Бонусный менеджерский контур
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Маршрут*],
|
||
[*Экран*],
|
||
[*Назначение*],
|
||
[/bonus-system],
|
||
[Бонусная система],
|
||
[Список клиентов и бонусных сущностей],
|
||
[/bonus-system/\[userId\]],
|
||
[Карточка бонусного счета клиента],
|
||
[История и состояние бонусного счета],
|
||
[/bonus-system/referrals/new],
|
||
[Создать бонусный счет],
|
||
[Создание реферальной связи],
|
||
[/bonus-system/transactions/new],
|
||
[Добавить бонусную транзакцию],
|
||
[Ручное начисление или списание],
|
||
[/bonus-system/withdrawals/\[id\]],
|
||
[Проверка заявки на вывод],
|
||
[Рассмотрение заявки клиента на вывод бонусов]
|
||
)
|
||
]
|
||
|
||
|
||
== Общие требования к экранным формам
|
||
|
||
|
||
Экранные формы должны обеспечивать:
|
||
|
||
- однозначное понимание текущего объекта работы
|
||
- явное отображение статуса объекта
|
||
- соответствие доступных действий роли пользователя
|
||
- единый визуальный подход для клиентского и менеджерского контуров
|
||
- понятное отображение продуктовых параметров, заявки, связи заявки с заказом, состава заказа, условий, баланса, задолженности и бонусных операций
|
||
|
||
Для экранов, связанных с заявками, заказами и задолженностью, должны выполняться дополнительные требования:
|
||
|
||
- клиент видит только данные своей подтвержденной компании
|
||
- заявка и учетный заказ 1С визуально различаются до момента связки
|
||
- сумма, условия и статусы отображаются по данным, полученным из 1С
|
||
- дата актуальности данных должна быть видна в ключевых местах интерфейса
|
||
- складские остатки в интерфейсе не отображаются
|
||
|
||
Ниже приведены низкодетализированные wireframe-прототипы. Они используются как визуальная фиксация состава страниц, ключевых блоков и пользовательских действий.
|
||
|
||
== Требования к прототипам и визуальному дизайну
|
||
|
||
|
||
Прототипы, приведенные в настоящем техническом задании, являются низкодетализированными wireframe-схемами. Они фиксируют структуру экранов, состав блоков, расположение основных элементов и пользовательские действия.
|
||
|
||
Прототипы должны выполняться в черно-белом виде либо в оттенках серого. Цвета, графические акценты, иллюстрации, финальная типографика и иные элементы визуального стиля не считаются согласованным дизайном на основании wireframe-прототипов.
|
||
|
||
Визуальный дизайн программного продукта может быть зафиксирован отдельными дизайн-материалами, изображениями или макетами, согласованными сторонами. Такие материалы уточняют внешний вид интерфейса, но не изменяют функциональные требования, состав экранов, роли, данные и интеграции, если это прямо не согласовано сторонами отдельно.
|
||
|
||
== Клиентские экранные формы
|
||
|
||
|
||
=== Главная страница клиента
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- отображение сводки по клиентской компании
|
||
- просмотр текущего баланса или задолженности
|
||
- просмотр последних заявок
|
||
- просмотр последних заказов и статусов
|
||
- переход к созданию заявки
|
||
|
||
Состав страницы:
|
||
|
||
- верхняя навигация
|
||
- карточка компании
|
||
- блок баланса или задолженности
|
||
- дата актуальности данных
|
||
- список последних заявок
|
||
- список последних заказов
|
||
- переход к продуктовому конструктору
|
||
- переход к полному списку заказов
|
||
- блок последних уведомлений
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/dashboard.svg", width: 100%),
|
||
caption: [Прототип главной страницы клиента],
|
||
)
|
||
|
||
|
||
=== Продуктовый конструктор
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- ознакомление клиента с продуктовыми направлениями
|
||
- выбор направления для формирования заявки
|
||
|
||
Состав страницы:
|
||
|
||
- список продуктовых направлений
|
||
- краткое описание направления
|
||
- доступные параметры для будущей заявки
|
||
- переход к карточке продуктового направления
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/catalog-grid.svg", width: 100%),
|
||
caption: [Прототип продуктового конструктора],
|
||
)
|
||
|
||
|
||
=== Карточка продуктового направления
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр описания продуктового направления
|
||
- выбор параметров заявки
|
||
- отправка заявки менеджеру
|
||
|
||
Состав страницы:
|
||
|
||
- заголовок направления
|
||
- описание направления
|
||
- блок выбора параметров
|
||
- количество
|
||
- комментарий клиента
|
||
- действие отправки заявки
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/product-card.svg", width: 100%),
|
||
caption: [Прототип карточки продуктового направления],
|
||
)
|
||
|
||
|
||
=== Карточка заявки
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр созданной заявки
|
||
- просмотр состояния обработки
|
||
- просмотр связанного заказа 1С после привязки
|
||
|
||
Состав страницы:
|
||
|
||
- номер заявки
|
||
- состояние заявки
|
||
- состав и параметры заявки
|
||
- комментарий клиента
|
||
- сведения о менеджере
|
||
- номер связанного заказа 1С при наличии
|
||
- ссылка на карточку заказа после привязки
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/cart.svg", width: 100%),
|
||
caption: [Прототип карточки заявки],
|
||
)
|
||
|
||
|
||
=== Карточка заказа
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр состава
|
||
- просмотр статуса
|
||
- просмотр стоимости и условий поставки
|
||
- просмотр истории изменений
|
||
- просмотр даты актуальности данных
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/client-order.svg", width: 100%),
|
||
caption: [Прототип карточки заказа],
|
||
)
|
||
|
||
|
||
Состав страницы:
|
||
|
||
- номер документа
|
||
- статус
|
||
- состав позиций
|
||
- стоимость
|
||
- условия поставки и доставки
|
||
- история статусов
|
||
- дата актуальности данных
|
||
- системные комментарии
|
||
|
||
=== Страница входа и завершения приглашения
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- запуск входа в систему
|
||
- завершение подключения по персональной ссылке из приглашения
|
||
- запуск сценариев входа через мессенджеры
|
||
|
||
Состав страницы:
|
||
|
||
- форма запроса кода входа
|
||
- форма проверки кода из письма
|
||
- кнопки входа через доступные мессенджеры
|
||
- служебное сообщение о результате входа либо привязки канала
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/login.svg", width: 100%),
|
||
caption: [Прототип страницы логина и подключения],
|
||
)
|
||
|
||
|
||
=== Список заказов
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр текущих и архивных заказов
|
||
- фильтрация по периоду и статусу
|
||
- просмотр даты актуальности списка
|
||
|
||
Состав страницы:
|
||
|
||
- фильтры
|
||
- карточки заказов
|
||
- переход в карточку конкретного заказа
|
||
|
||
=== Уведомления
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр истории уведомлений по заказам, задолженности и бонусным операциям
|
||
|
||
=== Бонусный кабинет
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр текущего бонусного баланса
|
||
- просмотр истории операций
|
||
- инициирование действий, допускаемых правилами бонусной программы
|
||
|
||
Состав страницы:
|
||
|
||
- текущий баланс
|
||
- история начислений и списаний
|
||
- связанные реферальные сведения
|
||
- форма подачи заявки на использование либо вывод бонусов
|
||
- магазин вознаграждений
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/bonus-cabinet.svg", width: 100%),
|
||
caption: [Прототип бонусного кабинета],
|
||
)
|
||
|
||
|
||
== Менеджерские экранные формы
|
||
|
||
|
||
=== Список клиентов
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр клиентской базы
|
||
- переход в карточку конкретного клиента
|
||
|
||
Состав страницы:
|
||
|
||
- поиск и фильтры
|
||
- сетка карточек клиентов
|
||
- действие приглашения нового клиента
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/client-list.svg", width: 100%),
|
||
caption: [Прототип списка клиентов],
|
||
)
|
||
|
||
|
||
=== Карточка клиента
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр сведений о компании
|
||
- просмотр заявок клиента
|
||
- просмотр истории заказов
|
||
- просмотр баланса и задолженности
|
||
|
||
Состав страницы:
|
||
|
||
- карточка компании и контактных данных
|
||
- реквизиты контрагента
|
||
- ИНН и ОГРН/ОГРНИП
|
||
- статус подтверждения клиента
|
||
- баланс или задолженность
|
||
- список заявок клиента
|
||
- список заказов клиента
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/client-card.svg", width: 100%),
|
||
caption: [Прототип карточки клиента],
|
||
)
|
||
|
||
|
||
=== Карточка заявки менеджера
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр заявки клиента
|
||
- обработка заявки менеджером
|
||
- привязка заявки к заказу 1С
|
||
|
||
Состав страницы:
|
||
|
||
- клиент и контрагент
|
||
- ИНН и ОГРН/ОГРНИП
|
||
- состав и параметры заявки
|
||
- комментарий клиента
|
||
- состояние обработки заявки
|
||
- поле номера или внешнего идентификатора заказа 1С
|
||
- история действий по заявке
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/manager-order.svg", width: 100%),
|
||
caption: [Прототип карточки заявки менеджера],
|
||
)
|
||
|
||
|
||
=== Карточка заказа менеджера
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр состава заказа
|
||
- просмотр статуса, стоимости и условий
|
||
- просмотр служебных данных синхронизации
|
||
- проверка связи заказа с клиентской карточкой и заявкой
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/manager-order.svg", width: 100%),
|
||
caption: [Прототип карточки заказа менеджера],
|
||
)
|
||
|
||
|
||
Состав страницы:
|
||
|
||
- клиент и контрагент
|
||
- ИНН и ОГРН/ОГРНИП
|
||
- связанная заявка при наличии
|
||
- состав заказа
|
||
- стоимость
|
||
- доставка
|
||
- дата актуальности данных
|
||
- история изменений
|
||
- служебные сведения о последней синхронизации
|
||
|
||
=== Список заказов менеджера
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр заказов по клиентам
|
||
- фильтрация по статусам
|
||
- переход к карточке конкретного заказа
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/manager-orders.svg", width: 100%),
|
||
caption: [Прототип списка заказов менеджера],
|
||
)
|
||
|
||
|
||
=== Настройки конструктора
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- управление продуктовой онтологией
|
||
- управление параметрами, доступными клиенту при создании заявки
|
||
|
||
Состав страницы:
|
||
|
||
- список продуктовых направлений
|
||
- карточка настроек направления
|
||
- набор параметров заявки
|
||
- порядок отображения направлений
|
||
- действие сохранения настроек
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/catalog-settings.svg", width: 100%),
|
||
caption: [Прототип настроек конструктора],
|
||
)
|
||
|
||
|
||
=== Настройки синхронизации
|
||
|
||
|
||
Назначение страницы:
|
||
|
||
- просмотр состояния интеграционного обмена
|
||
- контроль последних загрузок данных
|
||
|
||
Состав страницы:
|
||
|
||
- статусы последних синхронизаций
|
||
- количество загруженных записей
|
||
- дата последней загрузки
|
||
- примечание по каждому потоку обмена
|
||
|
||
Wireframe-прототип:
|
||
|
||
#figure(
|
||
image("public/prototypes/sync-settings.svg", width: 100%),
|
||
caption: [Прототип настроек синхронизации],
|
||
)
|
||
|
||
|
||
== Дополнительные профильные и сервисные страницы
|
||
|
||
|
||
Помимо основных клиентских и менеджерских экранов, программный продукт включает дополнительные экранные формы:
|
||
|
||
- профиль пользователя
|
||
- реквизиты контрагента
|
||
- список адресов доставки
|
||
- создание нового адреса доставки
|
||
- настройки уведомлений пользователя
|
||
- экран успешного подключения канала уведомлений
|
||
- менеджерский экран сообщений
|
||
- бонусная система для менеджера
|
||
- карточка бонусного счета клиента
|
||
- создание реферальной связи
|
||
- создание бонусной транзакции
|
||
- проверка заявки на вывод бонусов
|
||
|
||
Прототипы служебных и дополнительных экранов:
|
||
|
||
#figure(
|
||
image("public/prototypes/profile.svg", width: 100%),
|
||
caption: [Прототип профиля клиента],
|
||
)
|
||
|
||
|
||
#figure(
|
||
image("public/prototypes/bonus-manager.svg", width: 100%),
|
||
caption: [Прототип бонусной системы менеджера],
|
||
)
|
||
|
||
|
||
= Требования к интеграции с 1С и внешним интерфейсам
|
||
|
||
|
||
== Общие требования к интеграционному контуру
|
||
|
||
|
||
Интеграционный слой должен обеспечивать обмен данными между личным кабинетом и внешними системами без потери целостности внутренних сущностей и статусов.
|
||
|
||
Интеграционный контур должен обеспечивать:
|
||
|
||
- получение файлов обмена из 1С
|
||
- передачу в 1С сведений о заявках, если такой контур отдельно согласован сторонами
|
||
- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов, если такой обмен согласован сторонами
|
||
- сопоставление внутренних идентификаторов и идентификаторов внешних систем
|
||
- регистрацию входящих и исходящих операций обмена
|
||
- повторную обработку неуспешных сообщений
|
||
- хранение истории обновлений по интеграционным операциям
|
||
|
||
== Интеграция с 1С
|
||
|
||
|
||
Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения подтвержденных клиентов, связи заявок с заказами, состава заказов, статусов, условий и сведений о задолженности клиента.
|
||
|
||
Система должна обеспечивать получение из 1С следующих данных:
|
||
|
||
- сведения о контрагентах
|
||
- сведения о заказах
|
||
- состав заказов
|
||
- статусы заказов
|
||
- номер или внешний идентификатор заказа 1С, используемый для связи с заявкой личного кабинета
|
||
- изменения состава, стоимости, доставки и иных существенных параметров заказа
|
||
- текущая задолженность клиента
|
||
- дата актуальности сведений, полученных из 1С
|
||
|
||
1С рассматривается как первичный источник учетных данных по заказам, статусам, стоимости, доставке и задолженности. Личный кабинет отображает эти сведения только для клиентских карточек, заранее созданных и подтвержденных менеджером по ИНН и ОГРН/ОГРНИП, и фиксирует дату актуальности данных. Заявки, созданные в личном кабинете, остаются внутренними сущностями ЛК до момента связи с заказом 1С.
|
||
|
||
== Основной способ обмена с 1С
|
||
|
||
|
||
Основным способом интеграции является файловый обмен по FTP по согласованным структурам. 1С формирует регламентные snapshot-выгрузки с согласованным составом учетных данных, а личный кабинет принимает эти выгрузки, обновляет локальное представление данных и показывает клиентам только сведения, относящиеся к их подтвержденной клиентской карточке.
|
||
|
||
В качестве базового формата обмена используется JSON. Если на стороне 1С по техническим причинам удобнее использовать XML или CSV, стороны могут согласовать эквивалентную структуру без изменения состава передаваемых данных.
|
||
|
||
Файлы обмена могут передаваться одним из согласованных способов:
|
||
|
||
- загрузка файла в согласованное файловое хранилище
|
||
- загрузка файла на согласованный FTP/SFTP-ресурс
|
||
- передача файла через HTTP endpoint личного кабинета
|
||
- передача через иной согласованный защищенный канал, доступный заказчику и 1С
|
||
|
||
Базовая логика обмена:
|
||
|
||
+ Менеджер создает и подтверждает клиентскую карточку в личном кабинете с ИНН и ОГРН/ОГРНИП.
|
||
+ 1С формирует выгрузку контрагентов, балансов, заказов, статусов и состава заказов в согласованном объеме.
|
||
+ Личный кабинет принимает snapshot и сопоставляет данные только с клиентскими карточками, которые уже существуют в системе и подтверждены менеджером.
|
||
+ Основными ключами сопоставления являются ИНН и ОГРН/ОГРНИП; внешний идентификатор 1С используется как дополнительный технический ключ после успешного сопоставления.
|
||
+ Если в выгрузке присутствуют данные по контрагенту, который не создан и не подтвержден в личном кабинете, такие данные не загружаются в клиентский контур и не создают новый кабинет автоматически.
|
||
+ Балансы и задолженность передаются как состояние по подтвержденным клиентам на дату формирования выгрузки.
|
||
+ Заказы и статусы передаются по контрагентам за согласованный период, по умолчанию за последние 60 календарных дней, а также по активным заказам вне этого периода при необходимости отображения клиенту.
|
||
+ Если заказ 1С связан с заявкой личного кабинета по номеру, внешнему идентификатору или иному согласованному ключу, система обновляет карточку заявки данными реального заказа.
|
||
+ Если заказ 1С не связан с заявкой, но относится к подтвержденному клиенту, он отображается как самостоятельный заказ клиента.
|
||
|
||
== Состав файлов обмена
|
||
|
||
|
||
Минимальный состав файлов обмена:
|
||
|
||
- `counterparties_snapshot` — контрагенты, ИНН, ОГРН/ОГРНИП и реквизиты для сопоставления с подтвержденными клиентами личного кабинета
|
||
- `balance_snapshot` — баланс, задолженность и дата актуальности по контрагентам
|
||
- `orders_snapshot` — заказы, статусы, состав, стоимость, доставка и существенные изменения по заказам за согласованный период
|
||
|
||
Файлы `counterparties_snapshot`, `balance_snapshot` и `orders_snapshot` передаются из 1С в личный кабинет. Передача заявок из личного кабинета в 1С не входит в базовый объем, если такой контур отдельно не согласован сторонами; в базовой схеме менеджер создает заказ в 1С и связывает его с заявкой в личном кабинете.
|
||
|
||
Состав файлов может быть расширен по согласованию сторон, если в ходе интеграции появится отдельный тип данных, который нецелесообразно включать в существующие файлы обмена.
|
||
|
||
== Определение обновлений и идемпотентность
|
||
|
||
|
||
Каждый файл обмена должен содержать служебный блок с метаданными:
|
||
|
||
- `document_type` — тип файла обмена
|
||
- `schema_version` — версия структуры файла
|
||
- `snapshot_id` — уникальный идентификатор выгрузки
|
||
- `generated_at` — дата и время формирования файла
|
||
- `period_from` и `period_to` — период данных, если файл является выгрузкой за период
|
||
- `source` — источник файла
|
||
- `checksum` — контрольная сумма содержимого, если она формируется источником
|
||
|
||
Личный кабинет должен хранить журнал обработанных файлов обмена и не обрабатывать повторно файл с тем же `document_type`, `snapshot_id` и `checksum`.
|
||
|
||
Если 1С может формировать только полную выгрузку, личный кабинет должен принимать полный snapshot, но применять его только к подтвержденным клиентским карточкам, найденным по ИНН и ОГРН/ОГРНИП.
|
||
|
||
Для заказов регулярная синхронизация ограничивается согласованным периодом. По умолчанию передаются заказы за последние 60 календарных дней, а также активные заказы, если они не попадают в этот период, но должны отображаться клиенту.
|
||
|
||
== Пример counterparties_snapshot
|
||
|
||
|
||
```json
|
||
{
|
||
"document_type": "counterparties_snapshot",
|
||
"schema_version": "1.0",
|
||
"snapshot_id": "1c-counterparties-2026-05-04T10:00:00",
|
||
"generated_at": "2026-05-04T10:00:00+03:00",
|
||
"source": "1c",
|
||
"counterparties": [
|
||
{
|
||
"counterparty_external_id": "1c-counterparty-77",
|
||
"inn": "7700000000",
|
||
"ogrn": "1027700000000",
|
||
"name": "ООО Клиент",
|
||
"kpp": "770001001",
|
||
"manager_external_id": "1c-manager-12"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
== Пример balance_snapshot
|
||
|
||
|
||
```json
|
||
{
|
||
"document_type": "balance_snapshot",
|
||
"schema_version": "1.0",
|
||
"snapshot_id": "1c-balances-2026-05-04T10:00:00",
|
||
"generated_at": "2026-05-04T10:00:00+03:00",
|
||
"balance_date": "2026-05-04",
|
||
"source": "1c",
|
||
"balances": [
|
||
{
|
||
"counterparty_external_id": "1c-counterparty-77",
|
||
"inn": "7700000000",
|
||
"ogrn": "1027700000000",
|
||
"debt_amount": 125000,
|
||
"currency": "RUB"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
== Пример orders_snapshot
|
||
|
||
|
||
```json
|
||
{
|
||
"document_type": "orders_snapshot",
|
||
"schema_version": "1.0",
|
||
"snapshot_id": "1c-orders-2026-05-04T10:00:00",
|
||
"generated_at": "2026-05-04T10:00:00+03:00",
|
||
"period_from": "2026-03-05",
|
||
"period_to": "2026-05-04",
|
||
"source": "1c",
|
||
"orders": [
|
||
{
|
||
"order_external_id": "1c-order-10025",
|
||
"cabinet_order_id": "FRG-2030",
|
||
"linked_request_code": "REQ-2026-015",
|
||
"counterparty_external_id": "1c-counterparty-77",
|
||
"inn": "7700000000",
|
||
"ogrn": "1027700000000",
|
||
"status": "in_production",
|
||
"status_name": "В производстве",
|
||
"total_amount": 145000,
|
||
"currency": "RUB",
|
||
"delivery_date": "2026-05-12",
|
||
"updated_at": "2026-05-04T09:45:00+03:00",
|
||
"items": [
|
||
{
|
||
"name": "Позиция заказа",
|
||
"quantity": 10,
|
||
"unit": "шт",
|
||
"amount": 45000
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
== Интеграционные поля и служебные атрибуты
|
||
|
||
|
||
Для сущностей, участвующих в обмене, должны поддерживаться:
|
||
|
||
- внешний идентификатор учетной системы
|
||
- номер или идентификатор связанной заявки личного кабинета, если связь установлена
|
||
- дата последней синхронизации
|
||
- источник последнего обновления
|
||
- признак успешной или неуспешной обработки
|
||
- журнал интеграционных ошибок при наличии
|
||
- идентификатор последнего обработанного файла обмена
|
||
|
||
== Журналирование интеграционных операций
|
||
|
||
|
||
Для ключевых операций обмена система должна сохранять:
|
||
|
||
- тип объекта
|
||
- идентификатор объекта
|
||
- предыдущее состояние
|
||
- новое состояние
|
||
- дату и время изменения
|
||
- пользователя либо внешний источник, выполнивший изменение
|
||
- статус обработки сообщения
|
||
- текст ошибки при наличии
|
||
- идентификатор файла обмена и контрольную сумму при наличии
|
||
|
||
== Требования к защите интеграционного обмена
|
||
|
||
|
||
Интеграционные запросы должны выполняться с использованием согласованного механизма авторизации или подписи.
|
||
|
||
Система должна отклонять интеграционные запросы, если:
|
||
|
||
- отсутствуют обязательные параметры авторизации
|
||
- подпись или токен не прошли проверку
|
||
- файл обмена не соответствует согласованной структуре
|
||
- невозможно определить тип файла или объект обработки
|
||
|
||
Секреты, используемые для интеграции с 1С, должны храниться только в Vault и передаваться сервисам через runtime-конфигурацию.
|
||
|
||
== Критерии приемки интеграции с 1С
|
||
|
||
|
||
Интеграция с 1С считается готовой в согласованном объеме, если:
|
||
|
||
- данные из 1С сопоставляются только с клиентами, заранее созданными и подтвержденными менеджером
|
||
- сопоставление выполняется по ИНН и ОГРН/ОГРНИП
|
||
- данные по отсутствующим в личном кабинете клиентам не создают новый кабинет автоматически
|
||
- заявка личного кабинета может быть связана с заказом 1С по номеру или внешнему идентификатору
|
||
- заказы клиента получаются и отображаются с актуальными статусами
|
||
- состав заказов отображается в карточке заказа
|
||
- изменения заказа из 1С отображаются в карточке заказа
|
||
- текущая задолженность клиента и дата актуальности данных отображаются в предусмотренных интерфейсах
|
||
- повторная передача одного и того же файла обмена не приводит к дублированию данных
|
||
- ошибки интеграционного обмена фиксируются в журнале
|
||
- неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке
|
||
|
||
= Техническая архитектура, стек, компоненты и эксплуатационный контур
|
||
|
||
|
||
== Общая архитектурная схема
|
||
|
||
|
||
Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений.
|
||
|
||
#figure(
|
||
image("public/diagrams/architecture-overview.svg", width: 100%),
|
||
caption: [Общая архитектурная схема],
|
||
)
|
||
|
||
|
||
== Состав прикладных сервисов
|
||
|
||
|
||
Согласно действующей карте деплоя в составе проекта используются следующие сервисы:
|
||
|
||
- web-frontend — клиентский и менеджерский веб-интерфейс
|
||
- backend — сервер GraphQL и бизнес-логика
|
||
- vault — централизованное хранилище секретов
|
||
- tg-bot — Telegram-контур
|
||
- max-bot — MAX-контур
|
||
- bonus-bot — бонусный мессенджерный контур
|
||
- hatchet-worker — прикладной worker-контур
|
||
|
||
Основные прикладные сервисы разворачиваются через Dokploy на сервере заказчика. Исходный код размещается в Gitea, доступной по адресу `git.fregat.org`.
|
||
|
||
== Технологический стек фронтенда
|
||
|
||
|
||
Клиентская часть программного продукта реализуется на следующих технологиях:
|
||
|
||
- Nuxt 4 — прикладной веб-фреймворк
|
||
- Vue 3 — библиотека пользовательского интерфейса
|
||
- \@nuxtjs/apollo и \@vue/apollo-composable — работа с GraphQL
|
||
- GraphQL Code Generator — генерация типизированных GraphQL-документов
|
||
- Tailwind CSS и daisyUI — базовая стилизация интерфейсов
|
||
- Storybook — контур изоляционного просмотра компонентов
|
||
- VitePress — подготовка проектной документации
|
||
|
||
== Технологический стек серверной части
|
||
|
||
|
||
Серверная часть программного продукта реализуется на следующих технологиях:
|
||
|
||
- Node.js — среда выполнения
|
||
- Express 5 — HTTP-сервер
|
||
- Apollo Server 5 — GraphQL-сервер
|
||
- Prisma 7 — доступ к данным и ORM-слой
|
||
- PostgreSQL — основное хранилище данных
|
||
- Zod — валидация структур данных в прикладных сценариях
|
||
- Nodemailer — отправка уведомлений по электронной почте
|
||
|
||
== Архитектура клиентской части
|
||
|
||
|
||
Клиентская часть организована по следующим слоям:
|
||
|
||
- страницы app/pages — входные экранные формы
|
||
- компоненты app/components — переиспользуемые элементы интерфейса
|
||
- composables app/composables — клиентская логика и представление данных
|
||
- GraphQL-документы graphql/operations — отдельные запросы и мутации
|
||
- сгенерированная типизированная схема app/composables/graphql/generated.ts
|
||
- серверные proxy и интеграционные обработчики server/api
|
||
|
||
Ключевые экранные маршруты текущей реализации:
|
||
|
||
- `/` — клиентская сводка по заявкам, заказам, балансу и задолженности
|
||
- `/products` и `/products/[slug]` — продуктовый конструктор и карточка направления
|
||
- `/cart` — корзина-черновик заявки перед отправкой менеджеру
|
||
- `/client-requests` и `/client-requests/[id]` — клиентские заявки
|
||
- `/client-orders` и `/client-orders/[id]` — клиентские заказы
|
||
- `/clients` и `/clients/[id]` — менеджерский контур клиентов
|
||
- `/requests` и `/requests/[id]` — менеджерский контур заявок
|
||
- `/orders` и `/orders/[id]` — менеджерский контур заказов
|
||
- `/catalog-settings` — настройки продуктовой онтологии и конструктора заявки
|
||
- `/settings-sync` — настройки и мониторинг синхронизации
|
||
- `/bonus-program`, `/bonus-system/*` — бонусный контур
|
||
|
||
== Карта слоев и компонентов
|
||
|
||
|
||
#figure(
|
||
image("public/diagrams/component-map.svg", width: 100%),
|
||
caption: [Карта слоев и компонентов],
|
||
)
|
||
|
||
|
||
== Архитектура серверной части
|
||
|
||
|
||
Серверная часть организована по следующим основным модулям:
|
||
|
||
- 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 — мессенджерный контур и мини-приложения
|
||
|
||
== Взаимодействие фронтенда и backend
|
||
|
||
|
||
Взаимодействие клиентской и серверной части строится через GraphQL API.
|
||
|
||
На стороне Nuxt используется серверный proxy-маршрут /api/graphql, который:
|
||
|
||
- принимает запросы браузера
|
||
- прокидывает cookie и авторизационные заголовки
|
||
- перенаправляет запрос в backend
|
||
- возвращает результат в клиентское приложение
|
||
|
||
Такой подход позволяет:
|
||
|
||
- изолировать прямой backend endpoint от браузерного клиента
|
||
- централизованно передавать авторизационные данные
|
||
- поддерживать единый клиентский GraphQL endpoint
|
||
|
||
== Интеграционные и вспомогательные HTTP-точки
|
||
|
||
|
||
Помимо GraphQL API, во фронтенд-контуре реализованы вспомогательные серверные маршруты:
|
||
|
||
- /api/graphql — proxy в backend GraphQL API
|
||
- /api/auth/messenger-start — запуск сценариев messenger login / connect
|
||
- /api/dadata/address — подсказки адресов
|
||
- /api/dadata/bank — подсказки банковских реквизитов
|
||
- /api/dadata/party — подсказки контрагентов
|
||
- /api/messenger-avatar/[connectionId] — выдача изображений, связанных с мессенджерными подключениями
|
||
|
||
== Компонентные требования к реализации
|
||
|
||
|
||
Архитектура программного продукта должна сохранять следующие правила:
|
||
|
||
- экранная логика должна находиться на уровне страниц и composables
|
||
- переиспользуемые элементы интерфейса должны быть вынесены в компоненты
|
||
- каждый GraphQL-документ должен храниться в отдельном .graphql файле
|
||
- клиентский код должен использовать сгенерированные типизированные документы
|
||
- серверная логика доступа к данным должна проходить через Prisma
|
||
- бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом
|
||
|
||
== Требования к конфигурации и секретам
|
||
|
||
|
||
Сервисы программного продукта должны получать прикладные секреты из Vault.
|
||
|
||
В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения.
|
||
|
||
== Инфраструктура, деплой и эксплуатационный контур
|
||
|
||
|
||
Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур.
|
||
|
||
#figure(
|
||
image("public/diagrams/infrastructure-topology.svg", width: 100%),
|
||
caption: [Инфраструктура, деплой и эксплуатационный контур],
|
||
)
|
||
|
||
|
||
Сервисы проекта и способ их развёртывания:
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Сервис*],
|
||
[*Путь в репозитории*],
|
||
[*Роль*],
|
||
[*Deploy mode*],
|
||
[*Сервер*],
|
||
[web-frontend],
|
||
[web-frontend],
|
||
[клиентский и менеджерский веб-интерфейс],
|
||
[dokploy_webhook],
|
||
[main],
|
||
[backend],
|
||
[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]
|
||
)
|
||
]
|
||
|
||
|
||
Публичные домены эксплуатационного контура:
|
||
|
||
- `dokploy.fregat.org` — панель Dokploy
|
||
- `git.fregat.org` — Gitea, размещенная внутри Dokploy
|
||
- `lk.fregat.org` — пользовательский и менеджерский веб-интерфейс
|
||
- `api.fregat.org` — внешний endpoint backend при необходимости прямого обращения
|
||
- `hatchet.fregat.org` — интерфейс мониторинга worker-контура
|
||
|
||
Прямой доступ к сервисам снаружи не предусматривается: внешний HTTP/HTTPS-доступ выполняется через reverse proxy Dokploy/Traefik, а прикладные сервисы взаимодействуют между собой во внутренней Docker-сети.
|
||
|
||
== Dokploy и цепочка развёртывания
|
||
|
||
|
||
Для основных сервисов проекта используется режим dokploy_webhook.
|
||
|
||
Это означает следующую последовательность:
|
||
|
||
+ изменения фиксируются в Git-репозитории;
|
||
+ изменения публикуются в main;
|
||
+ Gitea отправляет webhook-событие в Dokploy;
|
||
+ Dokploy выполняет сборку соответствующего сервиса;
|
||
+ сервис перезапускается с загрузкой секретов из Vault;
|
||
+ после старта выполняются bootstrap-действия, предусмотренные образом и entrypoint-командой.
|
||
|
||
Текущие особенности прикладных сервисов:
|
||
|
||
- web-frontend стартует через загрузку Vault env и запуск .output/server/index.mjs
|
||
- backend стартует через загрузку Vault env, prisma migrate deploy и запуск src/server.js
|
||
- bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск node src/server.js
|
||
- hatchet-worker стартует через загрузку Vault env и подключается к Hatchet engine во внутренней сети
|
||
|
||
== Vault и хранение секретов
|
||
|
||
|
||
Сервис vault развернут как отдельное приложение на базе образа hashicorp/vault:1.21.3.
|
||
|
||
Текущие инфраструктурные правила работы Vault:
|
||
|
||
- используется raft storage
|
||
- данные Vault сохраняются в /vault/data
|
||
- конфигурация сервиса хранится в vault/config/vault.hcl
|
||
- при старте выполняется проверка и, при необходимости, автоматический unseal из переменных окружения
|
||
- прикладные сервисы подключаются к Vault через bootstrap-переменные VAULT_ADDR, VAULT_TOKEN, VAULT_KV_MOUNT, VAULT_SHARED_PATH, VAULT_PROJECT_PATH, VAULT_ENABLED
|
||
|
||
Прикладные сервисы используют общий shell-bootstrap load-vault-env.sh, который:
|
||
|
||
- ожидает доступность Vault по health endpoint
|
||
- загружает shared secrets
|
||
- загружает project secrets
|
||
- экспортирует секреты в runtime environment процесса
|
||
|
||
== Структура сервисных директорий
|
||
|
||
|
||
Текущая сервисная структура репозитория:
|
||
|
||
- web-frontend — Nuxt-приложение, GraphQL operations, VitePress-документация
|
||
- backend — Apollo Server, Prisma schema, миграции, интеграционная обработка данных
|
||
- tg-bot — Telegram-сервис
|
||
- max-bot — MAX-сервис
|
||
- bonus-bot — бонусный сервис
|
||
- hatchet-worker — worker-контур
|
||
- vault — Dockerfile, конфигурация и entrypoint Vault
|
||
- hatchet — docker-compose инфраструктурного контура Hatchet
|
||
|
||
== Контур фоновых процессов
|
||
|
||
|
||
В проекте присутствует отдельный контур фонового исполнения задач:
|
||
|
||
- hatchet-worker как прикладной worker
|
||
- hatchet-engine как движок исполнения
|
||
- hatchet-dashboard как интерфейс мониторинга
|
||
- отдельный postgres для Hatchet-контура
|
||
|
||
Конфигурация этого контура находится в hatchet/docker-compose.yml.
|
||
|
||
== Зафиксированные runtime-версии и технологические зависимости
|
||
|
||
|
||
=== Базовые runtime и контейнерные образы
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Компонент*],
|
||
[*Текущая версия*],
|
||
[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]
|
||
)
|
||
]
|
||
|
||
|
||
=== Основные зависимости фронтенда
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Библиотека*],
|
||
[*Версия*],
|
||
[*Назначение*],
|
||
[\\\@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
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Библиотека*],
|
||
[*Версия*],
|
||
[*Назначение*],
|
||
[\\\@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]
|
||
)
|
||
]
|
||
|
||
|
||
=== Основные зависимости worker-контура
|
||
|
||
|
||
#text(size: 7.6pt)[
|
||
#table(
|
||
columns: (1fr, 1fr, 1fr),
|
||
stroke: rgb("#d0d7de"),
|
||
inset: 4pt,
|
||
align: horizon + left,
|
||
[*Библиотека*],
|
||
[*Версия*],
|
||
[*Назначение*],
|
||
[\\\@hatchet-dev/typescript-sdk],
|
||
[1.19.0],
|
||
[worker runtime],
|
||
[dotenv],
|
||
[17.3.1],
|
||
[env bootstrap in local/runtime layers]
|
||
)
|
||
]
|
||
|
||
|
||
== Технические конфигурационные файлы
|
||
|
||
|
||
Ключевые технические файлы текущей реализации:
|
||
|
||
- deploy-map.toml — карта сервисов, deploy mode и серверов
|
||
- web-frontend/nuxt.config.ts — конфигурация Nuxt и Apollo
|
||
- web-frontend/codegen.ts — конфигурация GraphQL codegen
|
||
- backend/prisma.config.ts — конфигурация Prisma
|
||
- backend/prisma/schema.prisma — модель данных
|
||
- web-frontend/scripts/load-vault-env.sh — Vault bootstrap frontend
|
||
- backend/scripts/load-vault-env.sh — Vault bootstrap backend
|
||
- vault/config/vault.hcl — конфигурация Vault
|
||
- vault/entrypoint.sh — startup/unseal логика Vault
|
||
|
||
= Нефункциональные требования
|
||
|
||
|
||
== Общие требования к архитектуре
|
||
|
||
|
||
Программный продукт должен быть реализован как веб-система с разделением клиентского и менеджерского контуров, серверной бизнес-логикой, постоянным хранением данных и возможностью интеграционного обмена с внешними системами.
|
||
|
||
== Требования к доступности интерфейсов
|
||
|
||
|
||
Система должна обеспечивать корректную работу:
|
||
|
||
- в десктопных браузерах
|
||
- в мобильных браузерах
|
||
- на основных пользовательских разрешениях экрана
|
||
|
||
Интерфейсы должны сохранять работоспособность и читаемость при адаптивном отображении.
|
||
|
||
== Требования к производительности
|
||
|
||
|
||
При штатной эксплуатации система должна обеспечивать:
|
||
|
||
- приемлемое время открытия основных экранов
|
||
- приемлемое время выполнения пользовательских действий
|
||
- отображение клиентской сводки, конструктора заявки, карточек заявок, карточек заказов и истории заказов без заметных задержек при типовом объеме данных
|
||
|
||
Точные количественные показатели производительности подлежат фиксации в рабочей документации по инфраструктуре и тестированию.
|
||
|
||
== Требования к безопасности
|
||
|
||
|
||
Система должна обеспечивать:
|
||
|
||
- аутентификацию пользователей
|
||
- авторизацию по ролям
|
||
- ограничение доступа клиента только к данным своего контрагента
|
||
- хранение и передачу чувствительных данных с использованием защищенных механизмов
|
||
- исключение несанкционированного доступа к административным функциям
|
||
|
||
== Требования к надежности и журналированию
|
||
|
||
|
||
Система должна обеспечивать:
|
||
|
||
- сохранность пользовательских данных
|
||
- сохранность истории изменений по заявкам, заказам и бонусным операциям
|
||
- фиксацию ошибок интеграционного обмена
|
||
- фиксацию значимых системных и пользовательских событий
|
||
|
||
== Требования к сопровождаемости
|
||
|
||
|
||
Реализация должна обеспечивать возможность:
|
||
|
||
- сопровождения и развития клиентского контура
|
||
- сопровождения и развития менеджерского контура
|
||
- изменения продуктовой онтологии и параметров конструктора без переработки базовой структуры системы
|
||
- изменения параметров уведомлений без переработки базовой структуры системы
|
||
- расширения интеграционного обмена с 1С и иными внешними системами
|
||
|
||
== Требования к данным и актуальности сведений
|
||
|
||
|
||
Система должна обеспечивать:
|
||
|
||
- хранение актуального состояния пользовательских данных
|
||
- отображение даты актуальности сведений, полученных из внешних систем, когда это применимо
|
||
- защиту от потери данных при обновлении заказов и балансов из файлов обмена
|
||
- защиту заявок личного кабинета от потери при привязке и обновлении связанных заказов 1С
|
||
|
||
== Требования к документации
|
||
|
||
|
||
По результатам выполнения работ должна быть сформирована документация, достаточная для:
|
||
|
||
- приемки результата работ
|
||
- дальнейшего сопровождения программного продукта
|
||
- понимания состава функций, данных, ролей и интеграций
|
||
|
||
= Требования к программной документации
|
||
|
||
|
||
== Общий подход
|
||
|
||
|
||
Настоящее техническое задание является основным техническим документом программного продукта.
|
||
|
||
В составе настоящего технического задания фиксируются:
|
||
|
||
- назначение и границы продукта
|
||
- функциональные требования
|
||
- роли пользователей и права доступа
|
||
- требования к данным, сущностям и модели базы данных
|
||
- требования к интерфейсам
|
||
- требования к интеграциям
|
||
- архитектура, стек, компоненты и эксплуатационный контур
|
||
- нефункциональные требования
|
||
- порядок контроля, приемки и гарантийного сопровождения
|
||
|
||
Отдельные документы не должны дублировать техническое задание. Дополнительная документация должна описывать только то, что необходимо для использования, эксплуатации или интеграции программного продукта и не раскрыто в настоящем документе в достаточном объеме.
|
||
|
||
== Пользовательская документация
|
||
|
||
|
||
Пользовательская документация должна быть подготовлена в объеме, достаточном для работы пользователей в предусмотренных ролях:
|
||
|
||
- клиент
|
||
- менеджер
|
||
- суперменеджер
|
||
|
||
Пользовательская документация должна описывать:
|
||
|
||
- вход в личный кабинет и завершение подключения по приглашению
|
||
- работу с профилем и каналами уведомлений
|
||
- просмотр клиентской сводки
|
||
- работу с продуктовым конструктором
|
||
- создание и просмотр заявок
|
||
- просмотр баланса и задолженности
|
||
- просмотр заказов, статусов, условий и истории изменений
|
||
- работу с бонусным кабинетом, бонусным балансом и заявками на вывод
|
||
- действия менеджера по созданию клиентов, приглашению клиентов, обработке заявок, привязке заявок к заказам 1С, контролю заказов и бонусным операциям
|
||
- действия суперменеджера в административных разделах, если они отличаются от действий менеджера
|
||
|
||
Документация должна быть написана прикладным языком и ориентирована на выполнение пользовательских сценариев, а не на описание внутренней реализации.
|
||
|
||
== Эксплуатационная документация
|
||
|
||
|
||
Эксплуатационная документация должна быть подготовлена в объеме, достаточном для сопровождения программного продукта после передачи результата работ.
|
||
|
||
Эксплуатационная документация должна описывать:
|
||
|
||
- состав сервисов и их назначение
|
||
- порядок запуска и перезапуска сервисов через согласованный контур деплоя
|
||
- используемые окружения и общие принципы конфигурации
|
||
- порядок загрузки секретов из Vault
|
||
- порядок просмотра логов и диагностики типовых сбоев
|
||
- порядок проверки работоспособности клиентского, менеджерского и интеграционного контуров
|
||
- порядок обновления приложения через Git и Dokploy
|
||
- перечень технических контактов или зон ответственности, если они согласованы сторонами
|
||
|
||
Эксплуатационная документация не должна содержать бизнес-секреты, токены, пароли и иные чувствительные значения. Для секретов указываются только имена переменных, назначение и источник получения.
|
||
|
||
== Интеграционная документация
|
||
|
||
|
||
Для интеграции с 1С должна быть подготовлена интеграционная спецификация либо отдельный раздел настоящего технического задания, если к моменту согласования ТЗ формат обмена уже определен.
|
||
|
||
Интеграционная документация должна описывать:
|
||
|
||
- состав файлов обмена, передаваемых между 1С и личным кабинетом
|
||
- структуру каждого файла обмена
|
||
- формат обмена: JSON, XML или CSV
|
||
- обязательные и необязательные поля
|
||
- правила сопоставления идентификаторов
|
||
- требования к авторизации, подписи или иному механизму защиты обмена
|
||
- порядок обработки дублей
|
||
- порядок фиксации ошибок и повторной обработки сообщений
|
||
- критерии приемки интеграционного обмена
|
||
|
||
Если точный формат обмена с 1С не определен на момент утверждения ТЗ, он фиксируется отдельной согласованной интеграционной спецификацией до начала завершающего этапа интеграции.
|
||
|
||
== Перечень сторонних компонентов
|
||
|
||
|
||
Перечень сторонних компонентов формируется на основании фактических файлов проекта, включая package.json, lock-файлы, Dockerfile и конфигурационные файлы сервисов.
|
||
|
||
Перечень должен содержать:
|
||
|
||
- наименование компонента
|
||
- версию или диапазон версий
|
||
- назначение компонента в продукте
|
||
- источник установки или репозиторий, если он отличается от стандартного пакетного менеджера
|
||
|
||
Ключевые сторонние компоненты, используемые в текущей реализации, перечислены в разделе технической архитектуры настоящего технического задания.
|
||
|
||
= Стадии и этапы разработки
|
||
|
||
|
||
== Общий порядок выполнения работ
|
||
|
||
|
||
Настоящее техническое задание уже фиксирует согласованный состав требований к программному продукту. Разработка и согласование настоящего технического задания не выделяются в качестве отдельного этапа выполнения работ в рамках данного раздела.
|
||
|
||
Работы по созданию программного продукта выполняются в два основных этапа:
|
||
|
||
- реализация рабочего контура программного продукта без интеграции с 1С
|
||
- интеграция с 1С, отладка обмена, передача результата и приемка
|
||
|
||
Отдельный этап UX/UI не выделяется: интерфейсные требования, карта экранов, wireframe-прототипы и требования к визуальному дизайну фиксируются в составе настоящего технического задания.
|
||
|
||
Переход к следующему этапу выполняется после согласования сторонами результата предыдущего этапа либо после фиксации замечаний, не препятствующих продолжению работ.
|
||
|
||
== Этап 1. Реализация программного продукта без интеграции с 1С
|
||
|
||
|
||
На этапе реализуются основные пользовательские, менеджерские, административные и бонусные функции программного продукта без подключения обмена с 1С.
|
||
|
||
В состав этапа входят:
|
||
|
||
- подключение клиентов по приглашению менеджера
|
||
- создание и подтверждение клиентских карточек по ИНН и ОГРН/ОГРНИП
|
||
- роли и разграничение доступа
|
||
- продуктовая онтология и конструктор заявки без складских остатков
|
||
- создание и просмотр заявок клиентом
|
||
- обработка заявок менеджером
|
||
- клиентская сводка по заявкам, заказам, балансу и задолженности
|
||
- просмотр списка и карточек заказов
|
||
- статусы и история изменений
|
||
- уведомления в согласованном объеме
|
||
- бонусный и реферальный контур
|
||
- административные настройки, необходимые для работы продукта
|
||
|
||
Результат этапа:
|
||
|
||
- работоспособный программный продукт с основным функционалом без интеграции с 1С
|
||
- возможность проверки клиентских, менеджерских, административных и бонусных сценариев
|
||
- готовность программного продукта к подключению интеграционного обмена с 1С
|
||
|
||
Критерий завершения этапа: готовность рабочего контура программного продукта без интеграции с 1С к проверке заказчиком.
|
||
|
||
== Этап 2. Интеграция с 1С, отладка обмена и приемка
|
||
|
||
|
||
На этапе выполняются подключение, настройка и отладка интеграционного обмена с 1С, проверка сценариев, зависящих от данных 1С, передача результата и приемка выполненных работ.
|
||
|
||
В состав этапа входят:
|
||
|
||
- сопоставление клиентских карточек с данными 1С по ИНН и ОГРН/ОГРНИП
|
||
- настройка приема файлов обмена от 1С через согласованный FTP/SFTP-ресурс или иной согласованный канал
|
||
- проверка получения заказов, состава заказов, статусов, баланса и задолженности
|
||
- проверка связи заявки личного кабинета с заказом 1С по номеру или внешнему идентификатору
|
||
- проверка обновления карточки заявки после поступления связанного заказа из 1С
|
||
- проверка игнорирования данных по клиентам, не созданным и не подтвержденным в личном кабинете
|
||
- проверка обработки дублей и ошибок обмена
|
||
- проверка отображения даты актуальности данных
|
||
- итоговая проверка программного продукта в согласованном эксплуатационном контуре
|
||
- устранение критичных замечаний, препятствующих приемке
|
||
- передача пользовательской и эксплуатационной документации в согласованном объеме
|
||
- передача перечня ключевых сторонних компонентов
|
||
- оформление результата приемки
|
||
|
||
Результат этапа:
|
||
|
||
- работоспособный интеграционный обмен с 1С в согласованном объеме, если необходимые доступы и параметры обмена предоставлены заказчиком
|
||
- журналирование ключевых интеграционных событий
|
||
- размещенный программный продукт в согласованном эксплуатационном контуре
|
||
- пользовательская и эксплуатационная документация в согласованном объеме
|
||
- перечень ключевых сторонних компонентов
|
||
- акт приемки выполненных работ
|
||
|
||
Критерий завершения этапа: подписание акта приемки либо наступление условий приемки, предусмотренных договором.
|
||
|
||
= Порядок контроля, приемки и гарантийного сопровождения
|
||
|
||
|
||
== Общие положения приемки
|
||
|
||
|
||
Приемка результата работ должна подтверждать соответствие программного продукта требованиям настоящего технического задания, условиям договора и согласованным требованиям заказчика.
|
||
|
||
При приемке подлежат проверке:
|
||
|
||
- клиентский контур
|
||
- менеджерский контур
|
||
- создание и приглашение клиентов менеджером
|
||
- продуктовый конструктор и создание заявки
|
||
- обработка заявки менеджером
|
||
- привязка заявки к заказу 1С
|
||
- сопоставление клиентов по ИНН и ОГРН/ОГРНИП
|
||
- сопровождение заказов
|
||
- отображение баланса и задолженности
|
||
- уведомления
|
||
- бонусный и реферальный контур
|
||
- интеграционный обмен с 1С в согласованном объеме
|
||
- пользовательская и эксплуатационная документация в согласованном объеме
|
||
|
||
== Виды проверок
|
||
|
||
|
||
Для контроля результата работ используются следующие виды проверок:
|
||
|
||
- функциональная проверка основных пользовательских сценариев
|
||
- проверка разграничения ролей и прав доступа
|
||
- проверка корректности данных, статусов и истории изменений
|
||
- проверка интерфейсов на desktop и mobile
|
||
- проверка уведомлений по согласованным каналам
|
||
- проверка интеграционного обмена с 1С
|
||
- проверка запуска и работы сервисов в согласованном эксплуатационном контуре
|
||
|
||
== Критерии приемки
|
||
|
||
|
||
Программный продукт считается соответствующим требованиям, если:
|
||
|
||
- обязательные пользовательские сценарии выполняются корректно
|
||
- разграничение ролей и прав доступа реализовано корректно
|
||
- заявкам, заказам и бонусным операциям присваиваются и отображаются корректные статусы
|
||
- клиент видит только данные своей подтвержденной компании
|
||
- клиент может создать заявку через продуктовый конструктор без отображения складских остатков
|
||
- заявка сохраняется и отображается до привязки к заказу 1С
|
||
- после привязки заявки к заказу 1С клиент видит номер заказа, состав, статус, стоимость, условия и историю обновлений
|
||
- данные по неподтвержденным клиентам из 1С не создают кабинеты и не отображаются клиентам
|
||
- история изменений сохраняется и доступна в предусмотренных сценариях
|
||
- сведения из 1С отображаются в согласованном объеме
|
||
- текущая задолженность клиента и дата актуальности данных отображаются при наличии этих сведений из 1С
|
||
- критичные дефекты, препятствующие выполнению основных сценариев, устранены до передачи результата
|
||
|
||
== Передаваемые материалы
|
||
|
||
|
||
В состав передаваемых заказчику материалов входят:
|
||
|
||
- программный продукт, размещенный в согласованном эксплуатационном контуре
|
||
- исходный код разработанных компонентов в репозитории проекта
|
||
- согласованная редакция настоящего технического задания
|
||
- пользовательская документация в согласованном объеме
|
||
- эксплуатационная документация в согласованном объеме
|
||
- интеграционная спецификация 1С, если точные форматы обмена фиксируются отдельно от настоящего технического задания
|
||
- перечень ключевых сторонних компонентов, сформированный на основании фактических файлов проекта
|
||
|
||
Технические схемы, модель данных, роли, архитектура, стек, состав сервисов и требования к интеграциям являются частью настоящего технического задания и не дублируются в отдельных документах без отдельного согласования сторон.
|
||
|
||
== Порядок фиксации замечаний
|
||
|
||
|
||
Каждое замечание, выявленное при приемке, должно содержать:
|
||
|
||
- описание проблемы
|
||
- сценарий воспроизведения
|
||
- ожидаемый результат
|
||
- фактический результат
|
||
- уровень критичности
|
||
- статус устранения
|
||
|
||
Замечания, не препятствующие выполнению основных пользовательских и интеграционных сценариев, могут быть зафиксированы сторонами для последующего устранения в согласованном порядке.
|
||
|
||
== Гарантийный срок
|
||
|
||
|
||
Гарантийный срок на разработанные модули, сервисы и дополнительный функционал составляет 6 месяцев с даты подписания акта приемки выполненных работ, если иной порядок не согласован сторонами.
|
||
|
||
Гарантия распространяется на дефекты разработанного программного продукта, проявившиеся при штатной эксплуатации и относящиеся к функционалу, реализованному исполнителем.
|
||
|
||
== Первичная проверка гарантийного случая заказчиком
|
||
|
||
|
||
До направления гарантийного обращения заказчик выполняет первичную проверку на своей стороне и исключает причины, не относящиеся к разработанному программному продукту.
|
||
|
||
В рамках первичной проверки заказчик проверяет:
|
||
|
||
- доступность сервера, контейнеров, базы данных и сетевой инфраструктуры, на которых размещен программный продукт
|
||
- работоспособность домена, DNS, TLS-сертификатов, reverse proxy и иных инфраструктурных компонентов заказчика
|
||
- наличие необходимых ресурсов сервера, включая доступное место, память и процессорную нагрузку
|
||
- корректность переменных окружения, секретов, токенов и доступов, которые находятся в зоне ответственности заказчика
|
||
- доступность и корректную работу 1С, внешних API, почтового сервиса, Telegram, Max и иных внешних систем
|
||
- отсутствие изменений в форматах, правах доступа, настройках интеграций и учетных данных внешних систем
|
||
- отсутствие самостоятельных изменений кода, конфигурации, базы данных или инфраструктуры без согласования с исполнителем
|
||
- воспроизводимость проблемы на конкретном пользовательском сценарии
|
||
|
||
Если по итогам первичной проверки заказчик предполагает, что причина относится к разработанному исполнителем функционалу, заказчик направляет гарантийное обращение исполнителю.
|
||
|
||
== Порядок гарантийного обращения
|
||
|
||
|
||
Гарантийное обращение должно быть передано исполнителю в письменной форме или иным согласованным сторонами способом после первичной проверки на стороне заказчика.
|
||
|
||
В обращении должны быть указаны:
|
||
|
||
- описание дефекта
|
||
- пользовательская роль или контур, в котором проявляется дефект
|
||
- шаги воспроизведения
|
||
- ожидаемый результат
|
||
- фактический результат
|
||
- дата и время обнаружения
|
||
- результат первичной проверки на стороне заказчика
|
||
- сведения о состоянии сервера, контейнеров, базы данных и внешних систем, если они связаны с проявлением дефекта
|
||
- дополнительные материалы, если они нужны для диагностики
|
||
|
||
Исполнитель выполняет диагностику обращения в пределах разработанного им функционала. Если по результатам диагностики дефект относится к гарантийной зоне ответственности исполнителя, исполнитель устраняет его без дополнительной оплаты.
|
||
|
||
Если по результатам диагностики причина связана с инфраструктурой заказчика, внешними системами, изменением доступов, изменением форматов обмена, настройками 1С, почтовыми или мессенджерными сервисами, такое обращение не считается гарантийным дефектом программного продукта.
|
||
|
||
Срок устранения гарантийного дефекта составляет не более 3 дней с даты получения полного обращения, содержащего сведения, достаточные для воспроизведения и диагностики дефекта, либо иной срок, согласованный сторонами с учетом критичности и характера дефекта.
|
||
|
||
== Ограничения гарантийного сопровождения
|
||
|
||
|
||
Гарантийное сопровождение не распространяется на случаи, когда некорректная работа вызвана:
|
||
|
||
- самостоятельным изменением программного продукта заказчиком или третьими лицами без согласования с исполнителем
|
||
- ошибками сервера, хостинга, инфраструктуры или базы данных, не связанными с разработанным функционалом
|
||
- атакой, компрометацией доступа или нарушением требований информационной безопасности со стороны заказчика
|
||
- некорректной работой стороннего программного обеспечения
|
||
- недоступностью или некорректной работой внешних систем, включая 1С, Telegram, Max, почтовые сервисы и иные внешние API
|
||
- изменением форматов или правил работы внешних систем без предварительного согласования и обновления интеграционной спецификации
|
||
|
||
Если дефект связан с внешней системой или инфраструктурой, исполнитель фиксирует результат диагностики и передает заказчику сведения, достаточные для дальнейшего устранения причины на стороне соответствующей системы или поставщика.
|