Files
brencher/docs/USE_CASES_UI.md
T
hermesandadmin 83b50af9b3 feat(ui): mark unhealthy environment toggles (#82)
## Use case

Environment toggle buttons get a red border when the environment pipeline contains a failed or unfinished step. The state updates with WebSocket environment updates and does not disable the toggle.

## Verification

- `node --check frontend/app.js`
- `git diff --check`
- `27 passed, 1 skipped`; 4 Playwright tests blocked by unavailable `/var/run/docker.sock`

---------

Co-authored-by: rudolf <rudolfss13@gmail.com>
Reviewed-on: admin/brencher#82
Co-authored-by: hermes <rudolfss13+hermes@gmail.com>
2026-10-07 23:03:16 +02:00

14 KiB
Raw Blame History

Brencher — UI use cases

Цель приложения

Brencher показывает оператору состояние Git-источников и Docker Swarm, позволяет выбрать версию окружения и наблюдать pipeline. Этот файл описывает только пользовательские действия в UI и состояние, которое UI получает от сервера.

Канал состояния

  • После открытия страницы UI устанавливает один WebSocket /ws.
  • Сервер присылает version, branches и environments, затем рассылает изменения Jobs/pipeline и окружений.
  • UI отображает полученное состояние; REST /state и /branches являются backend read API и не заменяют realtime WebSocket.
  • Отдельной UI-кнопки rollback в текущей реализации нет.

UI use cases

U-01. Открыть приложение

  1. Пользователь открывает /.
  2. UI загружает HTML, CSS и JavaScript.
  3. UI открывает /ws.
  4. На экране появляются версия приложения, список branches, окружения, выбранные коммиты и Jobs.
  5. Если данных ещё нет, UI показывает loading/пустое состояние.

U-02. Получить начальное состояние

  1. После подключения сервер отправляет version, branches и environments.
  2. UI заменяет loading данными сервера.
  3. Для каждого окружения отображаются desired branches/commits, deployed commit/version и pipeline status.
  4. Ошибки окружения показываются как состояние Jobs или error message.

U-03. Переподключиться после разрыва WebSocket

  1. Пользователь остаётся на странице при закрытии или ошибке сокета.
  2. UI показывает disconnected/reconnecting state.
  3. UI повторяет подключение с задержкой.
  4. После нового подключения сервер снова присылает initial state.
  5. При повторных соединениях UI не должен считать старое состояние актуальнее нового; фактические ошибки reconnect видны в логах/статусе.

U-04. Просмотреть окружения и deployed state

  1. Пользователь открывает список окружений.
  2. UI показывает название, selected/desired commit, deployed commit, version, replicas и текущий шаг pipeline, если эти данные прислал сервер.
  3. Пользователь сравнивает desired и deployed state.
  4. Недоступное окружение остаётся в списке с ошибкой, а не считается успешно развёрнутым.

U-05. Просмотреть branches и remote-контекст

  1. Пользователь открывает выбор branch.
  2. UI показывает branches, полученные от сервера.
  3. Одинаковые имена branches разных remotes должны отображаться с контекстом remote.
  4. После Git fetch сервер присылает обновлённый список, и UI перерисовывает выбор.

U-06. Отфильтровать окружения toggle-кнопками

  1. UI показывает toggle-кнопку для каждого доступного окружения/стэка.
  2. Пользователь включает одну или несколько toggle-кнопок.
  3. UI оставляет в branches только выбранные окружения.
  4. UI оставляет в Jobs/pipeline только выбранные окружения.
  5. Ссылки, статусы и колонки Jobs также относятся только к выбранным окружениям.
  6. Если все toggle-кнопки выключены, UI показывает все окружения.
  7. Фильтр меняет только отображение и не изменяет серверное состояние.
  8. Обновление состояния не должно сбрасывать активный выбор toggle-кнопок, если выбранные окружения всё ещё существуют.
  9. Если pipeline окружения содержит хотя бы один неуспешный (error) или незаконченный (is_running) шаг, соответствующая toggle-кнопка получает красную рамку.
  10. Красная рамка обновляется вместе с состоянием pipeline и не изменяет доступность или поведение toggle-кнопки.

U-06a. Отфильтровать окружения текстом

  1. Пользователь вводит текст фильтра.
  2. UI оставляет подходящие окружения/стэки.
  3. Фильтр меняет только отображение и не изменяет серверное состояние.
  4. Очистка фильтра возвращает полный список.

U-07. Обновить отображаемое состояние

  1. Пользователь нажимает refresh/update в UI.
  2. UI отправляет серверу соответствующее WebSocket-сообщение либо ожидает очередное состояние pipeline.
  3. Сервер присылает branches/environments/jobs.
  4. UI обновляет строки, статусы и ошибки.
  5. Автоматического UI-таймера каждые пять минут не следует предполагать; обновление может быть pipeline-driven.

U-08. Выбрать branch

  1. Пользователь выбирает branch для окружения.
  2. UI меняет локальный selection.
  3. При применении selection отправляется серверу через WebSocket.
  4. После server update UI отображает выбранное состояние и результат pipeline.

U-09. Выбрать HEAD

  1. Пользователь выбирает HEAD или текущую вершину branch.
  2. UI показывает этот выбор как desired version.
  3. При применении сервер разрешает актуальный commit branch.
  4. Результат checkout/build/deploy и deployed version приходят в Jobs/state.

U-10. Выбрать исторический commit

  1. Пользователь открывает историю branch.
  2. UI показывает доступные commits.
  3. Пользователь выбирает конкретный commit.
  4. UI отправляет selection при применении.
  5. Ошибка отсутствующего commit или merge отображается как ошибка pipeline.

U-11. Ввести произвольный commit

  1. Пользователь вводит commit/ref, если такой control доступен.
  2. UI передаёт значение серверу.
  3. Сервер проверяет ref/commit и возвращает состояние.
  4. Неизвестный commit отображается как ошибка, а не как успешная выбранная версия.

U-12. Применить выбранное состояние

  1. Пользователь выбирает окружение и версию.
  2. Нажимает apply/update.
  3. UI отправляет команду через WebSocket.
  4. UI показывает queued/running/success/error по сообщениям сервера.
  5. После завершения показывает selected и deployed state отдельно.

U-13. Объединить несколько branches

  1. Пользователь выбирает несколько branches для одного окружения.
  2. UI отображает состав selection.
  3. При apply сервер выполняет merge.
  4. Успешный результат продолжает pipeline; merge conflict отображается в Jobs/error.
  5. Отдельного обещания автоматического разрешения конфликтов UI не даёт.

U-14. Запустить dry run

  1. Пользователь включает dry run.
  2. UI отправляет selection с dry-run параметром.
  3. UI показывает Git/analysis/build-preparation progress.
  4. UI не должен показывать dry run как выполненный deploy.
  5. Результат и ограничения dry run приходят от сервера; подготовительные шаги могут выполняться до финального запрета deploy.

U-15. Наблюдать Jobs и pipeline

  1. Пользователь раскрывает Jobs или строку окружения.
  2. UI получает и показывает этапы clone, state, checkout/merge, build/workflow, Swarm check и deploy.
  3. Для текущего шага отображаются progress/status/log message, если они пришли.
  4. Ошибка останавливает визуальный success flow и остаётся видимой для диагностики.

U-16. Просмотреть ссылки сервиса

  1. Сервер присылает userLinks в результатах pipeline.
  2. UI показывает ссылки на приложение/status или связанные сервисы.
  3. Пользователь открывает ссылку в браузере.
  4. Если userLinks нет, UI не должен придумывать URL.

U-17. Увидеть автоматический deploy без действия в UI

  1. Пользователь не нажимает Update.
  2. Сервер обнаруживает, что remote HEAD отличается от deployed label.
  3. Сервер запускает pipeline и присылает Jobs/environments update.
  4. UI отображает changed desired/deployed state и progress.
  5. Если diff нет, UI не показывает ложный deploy.

U-18. Увидеть ошибку Git/credentials/registry/Docker/health check

  1. Пользователь наблюдает Jobs или error panel.
  2. UI показывает неуспешный шаг и текст ошибки, если он прислан сервером.
  3. Пользователь устраняет внешнюю причину и повторяет update.
  4. Наличие error state не считается успешным deploy.

U-19. Увидеть stale/conflict state

  1. Два клиента могут выбирать одно или разные окружения одновременно.
  2. Один клиент может получить состояние, устаревшее относительно другого клиента.
  3. Сервер может отклонить stale update.
  4. UI сохраняет локальный выбор до следующего обновления, если сервер не прислал отдельное conflict message.
  5. Structured conflict dialog текущий backend не гарантирует.

U-20. Работать с secondary Brencher

  1. UI получает объединённое состояние локального backend и отдельного secondary Brencher, если SECONDARY_BRENCHER настроен.
  2. Пользователь видит branches/environments обоих источников согласно данным сервера.
  3. Обрыв secondary-соединения отображается как error/stale state.
  4. После reconnect UI получает новое initial/update состояние.
  5. brencher2 сам по себе является локальным профилем и не означает наличие secondary-сервера.

U-21. Просмотреть состояние через прямой REST URL

  1. Пользователь открывает /state или /branches в браузере/инструменте.
  2. Сервер возвращает JSON.
  3. Это read-only диагностика и не заменяет UI-соединение /ws.
  4. Изменение selection через эти GET endpoint-ы не выполняется.

Ограничения UI

  • UI не предоставляет отдельного rollback control.
  • UI не делает постоянное хранилище: после перезапуска backend in-memory state может исчезнуть.
  • Реальный deploy зависит от Git, credentials, Docker socket, registry, Swarm и настроек pipeline.
  • В web layer нет встроенной authentication/authorization; безопасность UI должна обеспечиваться внешним reverse proxy или сетью.
  • Разные профили запускаются через backend configuration; UI отображает только состояние, которое backend прислал.