#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
- изменением форматов или правил работы внешних систем без предварительного согласования и обновления интеграционной спецификации

Если дефект связан с внешней системой или инфраструктурой, исполнитель фиксирует результат диагностики и передает заказчику сведения, достаточные для дальнейшего устранения причины на стороне соответствующей системы или поставщика.
