AleksDi

Тогда зачем нам PLANKA?

Ответ у нас не технический, а поведенческий. OpenProject —  тяжёлый интерфейс, спроектированный вокруг пакета работ со всеми его полями. Разработчик, которому нужно за день десять раз что-то передвинуть и оставить комментарий, туда просто не заходит. PLANKA открывается, обновляется по вебсокету в реальном времени, и порог входа у неё нулевой —  человек, который умеет пользоваться Trello(или аналогом), умеет пользоваться PLANKA.

Если ваша команда охотно работает в OpenProject —  не городите огород, оставайтесь в одной системе. Связка из двух инструментов оправдана ровно в одном случае: когда доска в основной системе стоит пустая, а реальная работа всё равно ведётся где-то ещё (как в нашем случаи :-) ).

Разделение зон

Принцип простой: OpenProject отвечает на вопрос: «Что и к какому сроку», а PLANKA: «Как и кто прямо сейчас». Микрозадача не должна попадать в OpenProject никогда. Как только она туда попадает, РП начинает управлять задачами вместо сроков, и вся затея теряет смысл.

Что обе системы реально умеют

Здесь начинается место, где большинство статей на эту тему врут по недосмотру. Разберём по фактам.

OpenProject. API v3 —  гипермедийный REST, документация написана по спецификации OpenAPI 3.1, интерактивная версия доступна прямо в вашей инсталляции по адресу /api/docs, а исходник спецификации по /api/v3/spec.json. Аутентификация API-токеном в виде bearer. Вебхуки настраиваются администратором в разделе «API и вебхуки». Всё зрелое, всё предсказуемое.

PLANKA. Здесь надо быть аккуратнее. Официальной документации API у проекта долгое время не существовало вовсе — мейнтейнер прямо признавал, что генерация через Sails-хук для Swagger получалась кривой и до дела не доходили руки. То, что сегодня лежит в разделе API Reference документации PLANKA —  работа сообщества по v2, а не вендорский контракт. Практический вывод: закладывайте, что при мажорном обновлении что-то может поехать, и покрывайте интеграцию тестами.

Дальше два пункта, которые определяют, возможна ли автоматизация вообще:

• Вебхуки появились только в v2. В релизе 2.0 их конфигурацию перенесли из переменной окружения в интерфейс, заявлено более пятидесяти типов событий. На первой версии автоматической синхронизации не будет, только опрос по расписанию.

• Персональные API-ключи тоже из v2. До этого единственным способом авторизоваться программно был запрос POST /api/access-tokens с логином и паролем, в ответ —  JWT. Люди в issue-трекере доходили до того, что вручную подписывали долгоживущий токен и клали его в базу. Сейчас можно завести ключ пользователю и передавать его заголовком X-Api-Key.

  Мы работаем на 2.1.1, так что оба механизма доступны. Если у вас v1, то сначала обновляйтесь, потом стройте интеграцию, иначе вы построите её дважды.

Готового коннектора между системами нет. Ни встроенного, ни коммерческого. В n8n есть community-ноды и для PLANKA, и для OpenProject, но это отдельные ноды от независимых авторов с очень скромной аудиторией. Они снимают часть рутины, но не отменяют необходимость самому продумать маппинг. В Make или другом low-code проще сразу собирать на HTTP-модулях: контроля больше, сюрпризов меньше.

Где эта схема ломается

Грабли, на которые мы наступили. Обидно было бы, если бы вы наступили на те же.

1. Процент выполнения в OpenProject больше не «просто поле». Начиная с версии 14.0, % Complete связан с полями Work и Remaining work формулой: работа выполненная делится на работу общую. Свободно редактируемым вручную поле остаётся только тогда, когда Work и Remaining work не заполнены. Если задать процент и одно из двух других полей - третье вычислится само. У родительского пакета значения работ агрегируются отдельно из дочерних, и записать туда своё число не выйдет.

Отсюда практическое правило. Эпик, в который вы пишете прогресс из PLANKA, должен быть в OpenProject листовым узлом, без дочерних пакетов работ. Либо, что надёжнее, не трогайте нативный % Complete вовсе, а заведите отдельное пользовательское поле «Прогресс по доске» и пишите в него. Родная логика прогресса останется нетронутой, а РП увидит ровно то число, которое пришло от команды.

2. В PLANKA нет иерархии карточек. Карточка не может быть родителем другой карточки. Поля прогресса тоже нет. Поэтому сценарий: «Эпик пересчитывается по дочерним задачам» в лоб не собирается. Два рабочих варианта, либо эпик — это отдельная доска, и прогресс считается как доля карточек, доехавших до закрывающей колонки, либо эпик —  одна карточка, а задачи внутри неё оформлены чек-листом, и тогда процент берётся из него. Первый вариант честнее для команды, второй проще для интеграции. Мы выбрали первый.

3. Связь между сущностями надо где-то хранить. В v2 у карточек есть пользовательские поля, туда и кладите идентификатор пакета работ OpenProject, не в описание карточки. Описание редактируют люди, и рано или поздно кто-то сотрёт вашу служебную строчку вместе с лишним абзацем.

Как это выглядит в движении

Обычный понедельник. Открываю диаграмму Ганта, вижу, что этап «Ядро» подъедает буфер. Смотрю на эпик «Профили пользователей» —  прогресс 30%, число пришло с доски автоматически. Раньше я бы на этом месте написал в чат: «Что там по профилям?» и получил бы ответ через два часа. Сейчас открываю доску и вижу сам, три карточки стоят в «Заблокировано», у всех одна причина, не готовы макеты. Вопрос решается разговором с дизайнером, а не встречей на шесть человек.

Со стороны команды это выглядит ещё скучнее, и это хорошо. Разработчик двигает карточку в «На ревью». Больше он не делает ничего: ни отчёта, ни обновления статуса в другой системе. Пересчёт и передача наверх —  забота интеграции.

Тимлид на стендапе открывает доску, а не презентацию. Обсуждают только заблокированное. Десять минут вместо получаса.

Экономия времени тут вторична. Первично то, что исчезает двойной ввод, а вместе с ним исчезает и главный источник расхождения между тем, что видит заказчик, и тем, что происходит на самом деле.

Как начинать

Не с интеграции, а с договорённости.

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

Вторая неделя —  доска, две, а то и три карточки эпиков, синхронизация руками. Да, руками. Раз в пару дней РП обновляет процент. Это неприятно ровно настолько, чтобы через две недели стало понятно, стоит ли овчинка выделки.

Третья и четвёртая недели —  команда живёт на доске, РП смотрит из OpenProject, собираем, что раздражает.

И только после этого код. Небольшой сервис-прослойка слушает вебхуки PLANKA, пересчитывает прогресс, дёргает API OpenProject. Базовая версия —  несколько человеко-дней, если структура эпиков к этому моменту устоялась. Если не устоялась, срок можно смело умножать на два, и виновата будет не разработка.

Что в сухом остатке

Связка работает не потому, что в ней есть API, а потому, что она разводит два способа думать о проекте по разным инструментам и перестаёт заставлять людей переключаться. РП не лезет в задачи, команда не пишет отчёты, обе стороны смотрят на одни и те же данные.

Цена —  необходимость написать и потом сопровождать интеграцию, у которой на одном конце API без вендорских гарантий. Это осознанный размен, и он окупается не на любом масштабе. На команде из трёх человек — нет, а на нескольких параллельных проектах с внешней отчётностью, то вполне.

И самое главное, что не чинится никаким кодом — если команда не ведёт доску, связка не работает. Это вопрос дисциплины, а не архитектуры.