---

[I128-2839] Реализовать WorkflowApproval для формальных согласований workflow-переходов

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2839] Реализовать WorkflowApproval для формальных согласований workflow-переходов📄 Скачать в DOCX

---

Тип	Версия	Статус	Приоритет	Исполнитель
⚙️ Новые возможности	2026.3	🔘 Завершено	Средний	Unassigned

Компоненты: Нет

Завершено: 08.09.2026 13:44

1. Цель

Нужно реализовать модуль WorkflowApproval для формальных согласований workflow-переходов в ИРБИС 128.

WorkflowApproval должен быть расширением семейства Workflow*, а не отдельным process engine. Модуль добавляет approval gate к WorkflowTransition, создает runtime request согласования, фиксирует решения участников, управляет сроками, делегированием, отказом, ошибками continuation, событиями, audit и безопасным продолжением перехода.

Финальное изменение статуса доменной записи выполняет только Workflow. WorkflowApproval не должен напрямую менять доменную запись, писать собственную альтернативную историю статусов или выполнять post-functions в обход Workflow.

1. Контекст

В промышленных workflowпроцессах часть переходов требует формального согласования: один согласующий, все участники, кворум или последовательные этапы. Это нужно задачам, сервисным заявкам, финансовым решениям, изменениям прав, рискованным массовым операциям и будущим recordbased модулям.

Если согласования реализовать отдельно в каждом доменном модуле, система получит несколько несовместимых механизмов прав, уведомлений, дедлайнов, делегирования, истории и продолжения переходов. WorkflowApproval должен стать общим модулем формальных approval gates поверх существующего Workflow runtime.

1. Что Нужно Сделать

Нужно реализовать три top-level record types первого промышленного контура:

• WorkflowApprovalGate: настройочная запись gate, на которую ссылается WorkflowTransition.
• WorkflowApprovalPolicy: настройочная запись правил принятия решения и выбора участников.
• WorkflowApprovalRequest: runtime-запись конкретного запроса согласования по запущенному переходу.

В первом контуре Step, Participant, Decision, Delegation, Deadline, Context и Audit являются вложенными секциями policy/request, а не отдельными top-level записями. Отдельный жизненный цикл этих сущностей не нужен, пока они не маршрутизируются независимо от approval request.

1. WorkflowApprovalGate

Gate должен хранить:

• стабильный key, название, описание, project key, workflow key, active/system flags, owner module, definition version и audit;
• режим gate: required, conditional, informational, disabled;
• ссылку policyKey на WorkflowApprovalPolicy;
• имя condition format для conditional gate;
• executionPrincipal override: systemContinuation, originalInitiator или manualContinuationByAuthorizedUser;
• onRejectTransitionKey для опционального проектного перехода при отказе;
• decisionScreenKey, rejectScreenKey, clarificationScreenKey и delegationScreenKey;
• deadline rule, calendar key, reminder policy и escalation policy;
• collaboration profile и event profile;
• diagnostic visibility для администратора и обычного пользователя.

WorkflowTransition должен хранить только approvalGateKey. Если approvalGateKey пустой, переход выполняется штатно. Если approvalGateKey заполнен, Workflow перед выполнением перехода обращается к WorkflowApproval.

Удаление или деактивация gate должны проверять where-used: опубликованные transitions, system JSON definitions и активные WorkflowApprovalRequest.

1. WorkflowApprovalPolicy

Policy должна поддерживать четыре модели принятия решения:

• anyOne: достаточно одного согласования;
• allParticipants: нужны решения всех обязательных участников;
• quorum: нужен заданный минимум или процент согласований;
• sequence: согласование выполняется по последовательным шагам.

Роли проекта не являются отдельной policy. Они используются как способ выбора участников.

Policy должна хранить:

• policyType;
• executionPrincipalDefault, default systemContinuation;
• failFastReject;
• abstainMode;
• allowDelegation;
• requireCommentOnApprove, requireCommentOnReject, requireCommentOnDelegate;
• repeatDecisionPolicy;
• emptyResolverPolicy;
• deduplicateParticipants;
• separationOfDuties;
• quorumMinCount, quorumPercent и quorumRounding для quorum;
• steps для sequence;
• participants.

Participant должен поддерживать sourceType:

• recordAuthor;
• currentResponsible;
• projectOwner;
• projectRole;
• projectGroup;
• explicitUser;
• explicitGroup.

Resolver текущего ответственного не должен знать номера полей Tasks. Источник ответственного должен задаваться настройками проекта, типом записи или FieldConfiguration.

1. WorkflowApprovalRequest

Request должен создаваться при попытке выполнить WorkflowTransition с blocking gate. До завершения gate целевой статус доменной записи не меняется.

Request должен хранить:

• request key;
• status: created, waiting, approved, rejected, cancelled, expired, continuationQueued, continued, continuationError;
• project key, workflow key, transition key, gate key, policy key;
• record database, record type, record key, record SID или MFN, record version/hash;
• source status key и target status key;
• transition version, gate version, policy version, screen version;
• initiator user key;
• executionPrincipal и resolved execution user;
• trace id;
• idempotency scope, idempotency key и payload fingerprint;
• безопасный screenDataSnapshot;
• participantsSnapshot;
• decisions;
• delegations;
• deadlineState;
• collaborationThreadRef;
• continuationState, continuation attempts и безопасную последнюю ошибку;
• историю 907.

screenDataSnapshot должен хранить только нормализованные разрешенные значения, привязанные к screen key/version и transition version. Нельзя хранить секреты, cookie, пароли, токены, raw upload content или избыточный HTTP payload. Вложения хранятся как ссылки на staging/permanent file objects.

Перед continuation snapshot должен повторно валидироваться через WorkflowScreen и Workflow. Если screen, transition, gate, policy, запись или права изменились несовместимо, старое согласование нельзя применять: пользователь должен заново запустить переход.

1. Runtime Flow

Нужно реализовать следующий процесс:

• пользователь запускает workflow-переход;

• Workflow проверяет transition, status, route, condition, locks, screen и Security;

• если approvalGateKey пустой или gate отключен, переход выполняется штатно;

• если gate informational, переход выполняется штатно, но WorkflowApproval фиксирует информационный request/event согласно настройке;

• если gate required или conditional и условие включилось, WorkflowApproval создает WorkflowApprovalRequest;

• WorkflowApproval разрешает участников, сохраняет participants snapshot, screen data snapshot, trace id и idempotency data;

• EventBus публикует workflowApproval.request.created;

• Queue/EventBus создают уведомления, reminders и escalations по policy;

• согласующие принимают решения через UI/API/messenger с проверкой Security;

• request завершается approved, rejected, cancelled или expired;

• при approved WorkflowApproval ставит continuation в Queue или требует ручного continuation согласно executionPrincipal;

• Workflow перед continuation повторно проверяет актуальный статус, route, condition, locks, transition version, gate/policy version, screen snapshot и Security;

• только после повторных проверок Workflow применяет переход, меняет состояние записи, пишет 907 и выполняет post-functions;

• результат continuation публикуется через EventBus.

  1. Отказ И Ошибки Continuation

Отказ gate по умолчанию только отменяет ожидающий переход и оставляет доменную запись в текущем статусе. Если проекту нужен отдельный статус отказа, gate может задать onRejectTransitionKey. Такой переход выполняется только через обычный Workflow со всеми проверками и защитой от циклов.

Администратор может повторить continuation только для технически восстановимых ошибок: временная блокировка, transient DB/runtime failure, временная недоступность обязательной интеграции, сбой Queue/EventBus/outbox или идемпотентно повторяемая post-function.

Новый запуск перехода должен требоваться при смене текущего статуса, недоступности route, невыполнении condition, отказе Security, невалидном screen snapshot, несовместимой версии transition/gate/policy/screen или удалении/блокировке записи.

1. UI И API

Нужно реализовать административный UI для gate и policy:

• список gates и policies проекта;
• редактор gate с выбором policy, screens, condition, execution principal, onRejectTransitionKey, deadlines, reminders, escalations и event/collaboration profiles;
• редактор policy с выбором policy type, participants, steps, quorum, delegation, comments, abstain, fail-fast и repeat decision rules;
• where-used gate/policy по transitions и активным requests;
• dry-run/explain доступности gate.

Карта workflow должна показывать только конфигурационный признак approval gate на transition и открывать редактор gate/policy по правам. Runtime-состояния конкретных requests на карте не показываются.

Карточка доменной записи должна показывать runtime-состояние approval request: статус, безопасный прогресс решений, сроки, просрочку, делегирование, ссылку на discussion thread и доступные текущему пользователю действия. Пользователь не должен видеть скрытых согласующих и внутренних причин сверх своих прав.

API WorkflowApproval должен поддерживать:

• чтение доступных согласований пользователя;

• чтение request и безопасной диагностики;

• dry-run/explain gate;

• принятие решения;

• отказ;

• запрос уточнения;

• делегирование и отзыв делегирования;

• отмену request;

• административный retry continuation для восстановимых ошибок;

• экспорт/импорт gate/policy/system JSON.

  1. События

Первый пакет EventBus должен получать события:

• workflowApproval.request.created;
• workflowApproval.request.cancelled;
• workflowApproval.request.expired;
• workflowApproval.request.approved;
• workflowApproval.request.rejected;
• workflowApproval.decision.recorded;
• workflowApproval.delegation.created;
• workflowApproval.delegation.revoked;
• workflowApproval.clarification.requested;
• workflowApproval.reminder.due;
• workflowApproval.escalation.triggered;
• workflowApproval.continuation.queued;
• workflowApproval.continuation.completed;
• workflowApproval.continuation.failed.

WorkflowApproval публикует минимальный безопасный snapshot. Доставка, retries, deadletter и recipientspecific payload остаются ответственностью EventBus, Queue и Security.

1. System JSON, HealthCheck И Observability

Модуль должен поставлять системные JSON definitions для стандартных policies, gates, resolver definitions, screens, event profiles, TestA fixtures и Help metadata. System definitions защищены от редактирования без developer mode; пользовательское изменение выполняется через копию или override.

HealthCheck должен проверять:

• существование и активность approvalGateKey;
• соответствие gate проекту/workflow transition;
• существование и активность policyKey;
• корректность condition format для conditional gate;
• корректность onRejectTransitionKey и отсутствие циклов;
• существование screen keys;
• доступность participant resolver-ов;
• корректность deadline, calendar, Queue и EventBus references;
• отсутствие активных requests, несовместимых с удаляемым или изменяемым gate/policy.

Observability должен получать safe signals по созданию request, времени ожидания, числу решений, просрочкам, ошибкам resolver-а, ошибкам continuation и retry attempts. В signals нельзя передавать скрытые тексты, приватные комментарии и персональные данные сверх согласованного masking contract.

1. Границы Ответственности

WorkflowApproval владеет approval gate, policy, request lifecycle, participant snapshot, decision rules, delegation rules, deadline state, retry classification, audit approval request, публикацией фактов согласования и безопасным DTO для UI/API.

Workflow владеет состоянием доменной записи, изменением статуса, route/condition проверками, post-functions, записью итогового действия в 907 и применением continuation.

WorkflowTransition владеет transition configuration и ссылкой approvalGateKey, но не хранит policy целиком.

WorkflowScreen валидирует экраны и screenDataSnapshot. WorkflowApproval хранит snapshot, но не реализует собственный редактор полей.

Collaboration владеет тредами, комментариями, уточнениями, вложениями в коммуникационной ленте и человекочитаемым обсуждением. WorkflowApproval хранит только ссылки и формальный результат.

EventBus владеет event log, outbox/inbox, delivery, retries, deadletter, notification profiles и recipientspecific payload.

Queue владеет runtime фоновых reminders, escalations и continuation jobs.

Security владеет правами, grants/denies, field/view masking, проверкой decision/delegation/admin actions и explain доступа.

WorkCalendar владеет календарным расчетом deadlines, reminders и escalation windows.

FieldConfiguration владеет field keys и источниками доменных полей вроде текущего ответственного.

Tasks и другие доменные модули только выбирают, какие transitions требуют approval, и задают доменные последствия через обычные workflowпереходы и postfunctions. Они не реализуют частный approval engine.

1. Не Входит

В эту задачу не входит:

• самостоятельный process engine Approvals;

• прямое изменение доменных записей из WorkflowApproval;

• частная логика Tasks;

• замена WorkflowTransition, WorkflowScreen, EventBus, Queue, Security, Collaboration или WorkCalendar;

• отдельные top-level records для каждого decision/delegation/deadline;

• BI-аналитика согласований;

• финансовые budget/cost policies;

• внешние транспортные adapters уведомлений;

• сложные no-code approval матрицы за пределами четырех политик первого контура.

  1. Критерии Приемки

Администратор может создать policy anyOne, allParticipants, quorum и sequence, настроить участников, роли проекта, группы проекта, явных пользователей/группы, комментарии, delegation, abstain, fail-fast и repeat decision rules.

Администратор может создать gate, привязать его к transition через approvalGateKey, выбрать policy, screens, condition, executionPrincipal, onRejectTransitionKey, deadline/reminder/escalation settings и увидеть where-used.

Переход без approvalGateKey продолжает выполняться штатно.

Переход с required gate создает WorkflowApprovalRequest, не меняет статус доменной записи до завершения согласования и показывает пользователю состояние ожидания.

Participants snapshot создается на момент запуска request, дедуплицирует пользователей, найденных несколькими resolver-ами, и не использует hardcoded поля Tasks.

screenDataSnapshot сохраняет только безопасные нормализованные значения и повторно валидируется перед continuation.

После approved gate Workflow повторно проверяет актуальный статус, route, condition, locks, transition/gate/policy/screen versions и Security. Только после этого меняет статус записи и выполняет post-functions.

Отказ gate по умолчанию отменяет pending transition и не меняет доменную запись. onRejectTransitionKey, если задан, выполняется только через обычный Workflow.

Retry continuation разрешен только для восстановимых технических ошибок и каждый раз повторяет проверки Workflow, WorkflowScreen и Security.

Карта workflow показывает configuration marker approval gate на transition. Карточка записи показывает runtime request, прогресс решений, сроки, просрочку, delegation и доступные действия с учетом прав.

EventBus получает события lifecycle request, decisions, delegation, clarification, reminders, escalations и continuation result.

HealthCheck блокирует публикацию workflow-конфигурации при битом approvalGateKey, policyKey, condition, screen, resolver, deadline, calendar, Queue/EventBus profile или небезопасном onRejectTransitionKey.

System JSON definitions импортируются воспроизводимо, поддерживают dry-run/conflict report и защищены от ручного изменения без developer mode.

1. Проверки И Документация

Нужно подготовить TestA-сценарии:

• transition без gate;
• required gate с anyOne;
• allParticipants;
• quorum;
• sequence;
• conditional gate;
• informational gate;
• disabled gate;
• participants resolver: author, currentResponsible, projectOwner, projectRole, projectGroup, explicitUser, explicitGroup;
• empty resolver policy;
• deduplication participants;
• approve, reject, abstain, clarification, delegation, revoke delegation;
• screenDataSnapshot validation;
• continuation success;
• continuation retryable technical error;
• semanticRequiresNewTransitionRun;
• onRejectTransitionKey;
• Security denial for decision/delegation/admin retry;
• EventBus events;
• Queue reminders/escalations;
• 907 history and audit;
• HealthCheck provider checks;
• system JSON import/update/delete.

В Help должны быть подготовлены:

• руководство администратора по настройке gate, policy, participants, deadlines, delegation и rejection transition;
• руководство пользователя по согласованию, отказу, уточнению, делегированию и просмотру состояния request;
• руководство разработчика по API WorkflowApproval, approvalGateKey, event payload, DTO и integration boundaries;
• эксплуатационный runbook по зависшим requests, retry continuation, HealthCheck diagnostics, Queue/EventBus dead-letter и безопасному исправлению system definitions.

-

I128-2839: первый контрактный срез WorkflowApproval.

Состав изменений:

• добавлен модуль WorkflowApproval с записями WorkflowApprovalGate, WorkflowApprovalPolicy и WorkflowApprovalRequest;
• основная логика вынесена в __call функции: создание gate/policy/request, решения, делегирование, уточнение, отмена, retry continuation, диагностика, where-used и HealthCheck;
• api.php модуля содержит ObjectDataклассы, системные overrides и PHPDoc; публичная бизнеслогика находится в __call;
• WorkflowTransition получил поле approvalGateKey и индекс WFTRANSITIONAPPROVALGATE;
• Workflow перед применением перехода с approvalGateKey создает request согласования и не меняет статус записи до continuation;
• импорт и sync системных workflow definitions поддерживают approvalGateKey;
• добавлены system JSON, Help и TestA safe-read сценарий WorkflowApproval.

Проверки:

• php -l по всем файлам modules/WorkflowApproval и измененным Workflow/WorkflowTransition/WorkflowProject файлам;
• JSON parse modules/WorkflowApproval/system/workflow_approval.json: policies=2, gates=2;
• TestA WorkflowApproval safe-read: passed;
• TestA structural: WorkflowApproval 26/26, WorkflowTransition 3/3, Workflow 45/45, WorkflowProject 10/10;
• git diff -check: без whitespaceошибок.

1. Связанные задачи

1.1. 🔗 blocks: I128-2804

1.2. 🔗 blocks: I128-2840

1.3. 🔗 blocks: I128-2790

1.4. 🔗 blocks: I128-2791

1.5. 🔗 blocks: I128-2793

1.6. 🔗 blocks: I128-2794

1.7. 🔗 blocks: I128-2795

1.8. 🔗 blocks: I128-2797

1.9. 🔗 blocks: I128-2798

1.10. 🔗 blocks: I128-2799

1.11. 🔗 blocks: I128-2806

1.12. 🔗 blocks: I128-2813

1.13. 🔗 blocks: I128-2817

1.14. 🔗 blocks: I128-2818

1.15. 🔗 blocks: I128-2825

1.16. 🔗 blocks: I128-2826