Пользовательские задачи (User Task)

Пользовательские задачи — это единицы работы, которые должны быть выполнены в рамках бизнес-процесса по заявке.

Ключевые принципы

Пользовательские задачи создаются процессным движком в соответствии с моделью процесса.
При наступлении события задачи процессный движок публикует в Kafka сообщение TaskDto с данными задачи.
UniBPM находит заявку по businessKey, а пользователя-исполнителя — по assignee.
Новая задача привязывается к найденной заявке, исполнителю и пространству заявки.
Существующая задача обновляется по последнему событию процессного движка.

Топик должен совпадать в конфигурации производителя и потребителя:

unibpm.user-task-event-topic — публикация событий в unibpm-engine;
camunda-kafka-import.user-task-event-topic — импорт событий в unibpm.

Значение, используемое в конфигурации по умолчанию: reunico.unibpm.task.events.prod.

Основные атрибуты

Атрибут	Тип	Источник и назначение
`id`	`String`	Идентификатор задачи в процессном движке
`name`	`String`	Название задачи
`description`	`String`	Описание задачи
`priority`	`Integer`	Приоритет задачи
`processInstanceId`	`String`	Идентификатор экземпляра процесса
`taskDefinitionKey`	`String`	Ключ User Task в BPMN-модели
`assignee`	`User`	Текущий исполнитель
`ticket`	`Ticket`	Родительская заявка, найденная по `businessKey`
`workflow`	`Workflow`	Пространство задачи; при создании копируется из `ticket.workflow`
`dueDate`	`Instant`	Срок выполнения задачи, полученный из Camunda
`completedTime`	`Instant`	Время перехода задачи в конечное состояние
`variables`	`Map<String, Object>`	Переменные экземпляра процесса
`localVariables`	`Map<String, Object>`	Локальные переменные задачи
`availability`	`TaskAvailability`	Вычисляемая доступность задачи для текущего пользователя

Значения dueDate и completedTime в REST API передаются в ISO 8601, например 2026-08-25T15:30:00Z. dueDate может отсутствовать (null), если срок не задан в процессном движке.

Поле availability не хранится в базе данных и не передаётся процессным движком. UniBPM вычисляет его при формировании REST-ответа относительно текущего пользователя.

Правила синхронизации срока и пространства

dueDate управляется процессным движком. Если Camunda изменяет срок, следующее событие задачи обновляет Task.dueDate в UniBPM.
workflow определяется только при создании задачи как task.ticket.workflow.
После создания связь задачи с пространством не изменяется событиями Camunda или REST-операциями. На уровне ORM колонка workflow_id запрещена к обновлению.

Такая денормализованная связь позволяет непосредственно фильтровать задачи по пространству и применять ограничения доступа без дополнительного перехода через заявку.

Контракт события `TaskDto`

Сообщение пользовательской задачи содержит в том числе следующие поля:

{
  "id": "8f45d5c2-...",
  "name": "Согласовать заявку",
  "eventName": "create",
  "assignee": "user-id",
  "businessKey": "bd7f1b04-...",
  "processInstanceId": "f5c03be9-...",
  "taskDefinitionKey": "Activity_approve",
  "dueDate": "2026-08-25T15:30:00Z"
}

workflow в TaskDto не передаётся: UniBPM определяет его по пространству родительской заявки.

Статусы задачи

Событие процессного движка преобразуется в статус UniBPM:

Событие	Статус
`create`	`NEW` — новая задача
`assignment`	`ASSIGNED` — назначена
`complete`	`COMPLETED` — завершена
`delete`	`DELETED` — удалена

Пользовательская задача может иметь связанную экранную форму в формате Camunda Forms. Шаблоны экранных форм хранятся в артефактах пространства.

Доступность задачи для текущего пользователя

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

Возможные значения:

Значение	Условия
`ASSIGNEE`	Задача находится в статусе `ASSIGNED`, а `task.assignee` совпадает с текущим пользователем
`CANDIDATE`	Задача находится в статусе `NEW`, исполнитель отсутствует, а текущий пользователь указан среди кандидатов непосредственно или входит хотя бы в одну группу-кандидата
`NONE`	Ни одно из перечисленных условий не выполнено

Кандидаты пользователя и группы из события TaskDto.candidateUsers и TaskDto.candidateGroups материализуются в UniBPM как записи TaskPermission. При вычислении CANDIDATE учитываются как персональные записи текущего пользователя, так и записи его групп.

Если одновременно выполняется несколько условий, применяется следующий приоритет:

ASSIGNEE > CANDIDATE > NONE

Таким образом:

кандидат после назначения задачи на себя получает ASSIGNEE;
кандидат после назначения задачи другому пользователю получает NONE, даже если запись TaskPermission ещё существует;
для задач в статусах COMPLETED и DELETED обычный пользователь получает NONE.

availability является контекстом для пользовательского интерфейса, а не самостоятельной границей безопасности. Видимость задачи и разрешение на выполнение REST-операций по-прежнему проверяются сервером через PermissionService.

Получение и фильтрация задач

Список задач возвращает GET /api/task. Помимо стандартных критериев поддерживаются:

workflowId — фильтр по идентификатору пространства;
dueDate — диапазонный фильтр по сроку выполнения.
availability — фильтр по вычисляемой доступности задачи для текущего пользователя.

Примеры:

GET /api/task?workflowId.equals=9d3d80a3-5e6d-4ccd-a85f-9d40aaf83b21

GET /api/task?dueDate.greaterThanOrEqual=2026-08-10T00:00:00Z&dueDate.lessThan=2026-09-01T00:00:00Z

GET /api/task?availability.equals=CANDIDATE

GET /api/task?availability.in=ASSIGNEE,CANDIDATE

Фильтрация по availability выполняется в базе данных до пагинации. Поэтому размер страницы и totalElements соответствуют уже отфильтрованной выборке. Значение вычисляется в контексте текущего пользователя: например, availability.equals=NONE возвращает видимые задачи, для которых пользователь не является исполнителем или кандидатом. Административная роль не кодируется в availability и проверяется клиентским приложением отдельно.

Критерии можно комбинировать между собой и с параметрами пагинации. Полное описание операторов приведено в разделе Фильтры.

Доступные операции с задачей

assign — назначить задачу на пользователя;
claim — назначить задачу на себя;
unassign — убрать исполнителя задачи;
complete — завершить задачу.

При выполнении операции complete в процессный движок отправляется запрос, завершающий задачу.