# Описание функциональных характеристик

Программное обеспечение «Универсальная платформа-конструктор сбора, обработки и согласования данных»

Редакция документа: 1.1. Дата: 21.09.2026.

## Перечень принятых сокращений

| Обозначение | Значение |
| --- | --- |
| ПО, Система | Программное обеспечение «Универсальная платформа-конструктор сбора, обработки и согласования данных» |
| БД | База данных |
| API | Программный интерфейс серверной части |
| ACL | Правила предоставления доступа пользователям и ролям |
| Схема | Описание полей, групп и визуальных элементов формы |
| Иерархия | Уровни и связанные родительскими отношениями элементы формы |
| Запись | Введенные пользователем данные в выбранном контексте |
| Маршрут | Последовательность действий согласования |

## 1. Описание программного обеспечения

### 1.1. Назначение

«Универсальная платформа-конструктор сбора, обработки и согласования данных» — веб-приложение для создания настраиваемых форм, сбора структурированных данных, организации этих данных по иерархии и выполнения последовательных действий согласования. Пользователь работает через браузер. Конфигурация форм, учетные записи и данные хранятся в PostgreSQL.

Система позволяет администратору определять состав полей и контекст ввода без изменения программного кода для каждой новой формы. Например, одна форма может организовывать данные по регионам и мероприятиям, другая — по подразделениям и объектам учета. Эти наименования задаются при настройке и не являются обязательными справочниками продукта.

### 1.2. Цели и задачи

- Создание форм с текстовыми, числовыми, логическими полями и датами.
- Единообразный ввод и просмотр данных по настраиваемой структуре.
- Использование вычисляемых полей на основе JSON Logic.
- Разделение доступа к записям между учетными записями и ролями.
- Настройка очередности действий и исполнителей согласования.
- Централизованное администрирование пользователей и параметров форм.

### 1.3. Границы описания

Документ составлен по текущему исходному коду репозитория. В манифестах backend, frontend и библиотеки интерфейса указана версия 0.1.0.

## 2. Функции системы

### 2.1. Учетные записи и сеансы

Реализованы вход по логину и паролю, выход из системы, получение сведений о текущем пользователе, управление учетными записями и ролями. Администратор может создавать пользователей, изменять их данные и роли, отключать учетные записи и сбрасывать пароли. Системная роль admin защищена от удаления. Обычная роль с похожим названием не становится административной.

Пароли обрабатываются средствами pwdlib с Argon2. Браузерный сеанс использует HTTP-only cookie. Срок действия, имя cookie, SameSite и признак Secure задаются настройками серверной части. Создание начального администратора выполняется при запуске с установленными параметрами bootstrap.

### 2.2. Конструктор форм и схем

Администратор создает формы и схемы, задает типы схем и редактирует их содержимое. В конструкторе доступны короткий и многострочный текст, числа, дата, одиночный и множественный выбор, чекбокс, переключатель и формула. Структуру дополняют заголовки, подзаголовки, разделители и группы элементов.

Для поля задаются название, уникальный номер и поддерживаемые выбранным типом параметры, включая обязательность. Уникальные номера используются как ключи данных и переменные формул. Вычисление формул реализовано в клиентской части; оно не является подтверждением серверной проверки всех расчетов.

### 2.3. Иерархия и конфигурация

У формы могут быть уровни с системным именем, отображаемым названием, порядком и способом размещения. Элементы уровней имеют название, порядок, внешний ключ и при необходимости ссылку на родителя. Настройка ввода определяет, создаются ли записи в корне формы или на выбранном уровне. Сервер операций с записями определяет уровень ввода по признаку is_data_entry_allowed и отклоняет конфигурацию с несколькими такими уровнями.

В конфигурации формы сохраняются параметры согласования, стартового уровня маршрута и флаги Excel. Наличие параметра в настройках само по себе не означает наличие соответствующей пользовательской операции.

### 2.4. Работа с записями

Реализованы создание, получение, изменение и удаление записей через API. Рабочий интерфейс позволяет создавать записи по основной схеме, открывать их для просмотра и редактирования, отправлять и в предусмотренном интерфейсом случае возвращать в черновик. При изменении содержимого сервер сохраняет непосредственно предыдущее значение в previous_data, автора и время изменения. Это не полный журнал всех редакций.

Интерфейс различает статусы draft, submitted, signed и rejected. Редактирование через интерфейс доступно для черновика и отклоненной записи; другие состояния открываются для просмотра. В текущем серверном сервисе нет эквивалентной полной блокировки изменения содержимого по статусу, поэтому ограничение интерфейса не следует трактовать как неизменность подписанных данных.

### 2.5. Разграничение доступа

Правила ACL связывают пользователя или роль с областью формы, уровня либо элемента. Для операций с записями сервер проверяет read и write. Доступ ко всей форме распространяется на ее записи; для записи на уровне также проверяется разрешение на соответствующий уровень. Автоматическое наследование правила от родительского элемента ко всем потомкам не реализовано.

В интерфейсе ACL присутствуют также configure, assign и sign. Административные операции и выполнение шага маршрута имеют самостоятельные проверки: настройка требует административного доступа, действие маршрута — совпадения с назначенным пользователем или ролью либо статуса администратора. Нельзя описывать все права интерфейса как универсально действующую модель авторизации всех API.

### 2.6. Согласование

Маршрут содержит последовательно пронумерованные шаги начиная с 1. Для каждого шага задаются действие approve, sign или reject и исполнитель — пользователь либо роль. Запуск создает процесс со статусом on_assignment. Повторный запуск активного процесса для того же контекста отклоняется.

Действие должно совпадать с типом текущего шага. Успешный промежуточный шаг переводит процесс к следующему; последний шаг завершает его статусом signed, а шаг reject — статусом rejected. Для действия сохраняются исполнитель, комментарий, строка подписи и переданный снимок данных.

Подпись является необязательным текстовым значением. Проверки криптографического сертификата и криптографической подписи в рассмотренном процессе нет. Интерфейс передает пустые объекты payload и payload_snapshot; автоматическая фиксация всего содержимого записей при запуске и автоматическое изменение их статусов по завершении процесса не реализованы. Отправка записи и запуск процесса — разные операции.

## 3. Функциональные модули ПО

| Функциональный модуль | Назначение и основные функции |
| --- | --- |
| Учетные записи и сеансы | Вход и выход пользователей; получение сведений о текущем пользователе; создание и изменение учетных записей; назначение ролей; отключение учетных записей и сброс паролей. |
| Конструктор форм и схем | Создание и редактирование форм и схем; настройка типов полей, обязательности и параметров элементов; использование формул и групп элементов. |
| Иерархия и конфигурация | Настройка уровней формы и связанных элементов; определение контекста ввода записей; настройка параметров формы и параметров маршрута согласования. |
| Работа с записями | Создание, просмотр, редактирование, отправка и удаление записей в пределах реализованных интерфейсных и серверных операций; сохранение предыдущего значения при изменении данных. |
| Разграничение доступа | Настройка и проверка прав пользователей и ролей на чтение и изменение данных с учетом формы и уровня, к которому относятся записи. |
| Согласование | Настройка последовательности шагов согласования и назначение исполнителей; запуск процесса; выполнение предусмотренных действий approve, sign и reject; сохранение сведений о выполненных действиях. |

Перечисленные функциональные модули образуют единую систему и совместно обеспечивают настройку форм, ввод и обработку данных, управление доступом пользователей и выполнение процедур согласования. Технологическая среда и используемые программные средства указаны в разделе 4 настоящего документа.

## 4. Информация для установки и эксплуатации

### 4.1. Программная среда

Система разворачивается через Docker Compose. В промышленной эксплуатации backend, frontend, PostgreSQL и Redis работают в контейнерах; на хосте требуется Docker с Compose. Python версии не ниже 3.13 и uv находятся в образе backend, PostgreSQL — в отдельном контейнере. Зависимости и сборка frontend, включая предварительную сборку @docomo/ui, выполняются внутри сборочного образа. Миграции и административные команды backend выполняются через docker compose run или exec.

Только при разработке frontend запускается локально; для него на машине разработчика нужны Node.js и pnpm. В проекте указаны Node.js 22.13.1 в Dockerfile frontend и pnpm 10.11.0 в package.json. Backend, PostgreSQL и Redis и в этой среде работают в Docker. Браузер обращается к API по http://localhost:8010, backend к БД — по docomo-postgres:5432. Подготовка производственной контейнерной сборки описана в инструкции по установке.

Клиенту нужен браузер с включенными JavaScript и cookie и сетевым доступом к адресу приложения и API. Подтвержденной матрицы версий браузеров и сертифицированных ОС в репозитории нет.

### 4.2. Ресурсы и режим работы

Минимальные и рекомендуемые CPU, RAM, объем хранилища, число одновременных пользователей и гарантированное время отклика не установлены нагрузочными испытаниями в рамках этого комплекта. Ресурсы выбираются после проверки характерного числа форм, записей и пользователей. Дисковое пространство рассчитывают с учетом БД, журналов и резервных копий.

Для постоянной эксплуатации назначаются ответственные за контейнеры приложения и БД, Docker-хост, HTTPS, резервное копирование и обновления. Режим и допустимая длительность простоя определяются условиями конкретного внедрения.

### 4.3. Ограничения текущей поставки

- Импорт и экспорт Excel представлены флагами конфигурации; завершенный пользовательский сценарий обмена файлами в текущем API не подтвержден.
- Не реализован полноценный пользовательский список ранее запущенных процессов и восстановление процесса в панели после перезагрузки страницы.
- Отдельного механизма активации лицензии и контроля числа лицензируемых экземпляров в рассмотренном коде нет.
- Имеющиеся производственные Docker-настройки требуют согласования с текущей структурой проекта; порядок запуска описан в инструкции по установке.

## 5. Документы комплекта

Эксплуатация описана в руководстве пользователя; подготовка среды — в инструкции по установке; обслуживание и развитие — в регламенте сопровождения и описании жизненного цикла. Условия предоставления прав отражаются в описании лицензирования после заполнения сведений правообладателем.
