Представление процесса

Каждый воркфлоу, объявляющий progress, Moira показывает как представление процесса: короткую цепочку блоков, которую новичок прочитает, не зная лежащего под ней графа. То же представление показывает запуск этого воркфлоу: какие блоки завершены, какой активен, какие повторялись или были пропущены, и какой маршрут запуск прошёл на самом деле. Этот раздел объясняет словарь и то, как строится каждая картина.

Словарь

• Блок. Один этап процесса, как назвал бы его человек: «Набросать план», «Независимое ревью плана», «Выполнить шаги плана». Массив progress.nodes перечисляет блоки в порядке процесса; у каждого есть подпись и описание в одно предложение (content.summary).
• Шаг. Одна нода графа воркфлоу: директива, которую выполняет агент, условие или выражение, которое маршрутизирует, старт или завершение. Каждый шаг принадлежит ровно одному блоку через progressNodeId, включая ноды маршрутизации, поэтому ничто из происходящего в запуске не выпадает из картины.
• Свидетельство. То, что шаг обязан вернуть, чтобы завершиться, — его input schema. Текст результата блока (content.outcome) — шаблон над переменными, которые записывают его шаги, поэтому запуск показывает, к чему блок пришёл, а не только что он выполнялся.
• Переход. Связь, которая уходит из блока в другой блок. У каждой есть короткая подпись из connectionLabels на ноде, например «план одобрен» или «ревью нашло дефекты», так что стрелка объясняет себя сама.
• Цикл. Переход назад к более раннему блоку или к тому же блоку. Его подпись также называет причину повторения и то, что его завершает (cycle.cause, cycle.exit); представление помечает такую стрелку как возврат.
• Хаб. Блок, в который ведут несколько других блоков (перепланирование или остановка). Он размещается после блоков, которые в него ведут, чтобы процесс читался слева направо, и каждое представление рисует от каждого источника в него по одной связанной в пучок линии, а источник называет его в чипе.
• Запуск. Одно выполнение воркфлоу. Движок записывает его маршрут: каждый выполненный шаг, связь, через которую он вышел, изменённые переменные и места ожидания.

Страница флоу: процесс без запуска

Процесс выводится только из определения воркфлоу: блоки из progress.nodes, принадлежность из progressNodeId, переходы и циклы из подписанных связей. Ничто в нём не рисуется отдельно, поэтому картина не может разойтись с графом. Валидация отвергает воркфлоу, чей процесс был бы нечитаемым: шаг без блока (unowned-node), блок без описания (empty-description) или без шагов (empty-block), граничная связь без подписи (unlabeled-edge), возврат без причины и выхода (unexplained-cycle), шаблон результата на блоке, которому не принадлежит ни одна нода, записывающая его переменную (outcome-unowned), или на двух блоках (outcome-duplicate), блок без перехода в другой блок или из него (unconnected-block; блок, владеющий стартовой нодой, не проверяется, а возврат в себя ничего не связывает). moira-workflow <file> derive печатает выведенный процесс с любыми из этих диагностик, а set-block, add-block, edit-block, set-label и clear-label редактируют его по одному изменению за раз.

Веб-интерфейс показывает этот вывод на странице флоу (/workflows/<id>, см. руководство «Чтение и правка флоу»): конспект, карта, дорожки и разворот блоков против их шагов, а также технический граф нод. Владелец может править определение прямо там — блоки, подписи переходов и циклы, принадлежность и текст шагов, реестр переменных — с диагностикой выше, показываемой по мере ввода, и сохранением, которое отклоняется для невалидного определения или устаревшей ревизии.

Страница запуска: процесс с маршрутом

Запуск проецируется на процесс из записанного маршрута и никогда не угадывается по порядку блоков:

• active — блок последнего шага, которого запуск достиг; waiting — когда этот шаг приостановлен в ожидании ввода человека или агента;
• done — посещённый блок, чьи рабочие шаги выполнились один раз; repeated ×n — то же после n проходов через его рабочие шаги (ревью, прошедшее дважды, показывает ×2);
• skipped — блок, который запуск обошёл или в который вошёл, не выполняя его работы (выполнились только ноды маршрутизации);
• pending — ещё не достигнут.

Непосещённый блок никогда не показывается завершённым. Сам маршрут доступен как упорядоченный список с отметками циклов, у каждой переменной есть история значений, а значение, заданное извне флоу (корректировка во время запуска), показано как таковое вместе с тем, кто его задал. Курсор маршрута показывает запуск на момент любого более раннего визита, а владелец выполнения может ответить ожидающему шагу прямо со страницы; ответ проверяется как ответ агента и записывается как корректировка (см. руководство «Чтение запуска»). Запуск, записанный до появления маршрутов, показывает только свой текущий блок и сообщает, что маршрут не записан.

Как сделать воркфлоу читаемым

Называйте блоки так, как человек назвал бы этап, держите описания в одно предложение, подписывайте каждую граничную связь решением, которое она выражает, и объясняйте каждый возврат причиной и выходом. Предпочитайте от трёх до пятнадцати блоков; ноды маршрутизации кладите в блок, чьё решение они маршрутизируют. Workflow Management Flow требует всего этого при создании и редактировании воркфлоу, а session({ action: "progress" }) или GET /api/executions/:id/progress возвращают представление запуска.