forked from admin/brencher
## 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>
14 KiB
14 KiB
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. Открыть приложение
- Пользователь открывает
/. - UI загружает HTML, CSS и JavaScript.
- UI открывает
/ws. - На экране появляются версия приложения, список branches, окружения, выбранные коммиты и Jobs.
- Если данных ещё нет, UI показывает loading/пустое состояние.
U-02. Получить начальное состояние
- После подключения сервер отправляет
version,branchesиenvironments. - UI заменяет loading данными сервера.
- Для каждого окружения отображаются desired branches/commits, deployed commit/version и pipeline status.
- Ошибки окружения показываются как состояние Jobs или error message.
U-03. Переподключиться после разрыва WebSocket
- Пользователь остаётся на странице при закрытии или ошибке сокета.
- UI показывает disconnected/reconnecting state.
- UI повторяет подключение с задержкой.
- После нового подключения сервер снова присылает initial state.
- При повторных соединениях UI не должен считать старое состояние актуальнее нового; фактические ошибки reconnect видны в логах/статусе.
U-04. Просмотреть окружения и deployed state
- Пользователь открывает список окружений.
- UI показывает название, selected/desired commit, deployed commit, version, replicas и текущий шаг pipeline, если эти данные прислал сервер.
- Пользователь сравнивает desired и deployed state.
- Недоступное окружение остаётся в списке с ошибкой, а не считается успешно развёрнутым.
U-05. Просмотреть branches и remote-контекст
- Пользователь открывает выбор branch.
- UI показывает branches, полученные от сервера.
- Одинаковые имена branches разных remotes должны отображаться с контекстом remote.
- После Git fetch сервер присылает обновлённый список, и UI перерисовывает выбор.
U-06. Отфильтровать окружения toggle-кнопками
- UI показывает toggle-кнопку для каждого доступного окружения/стэка.
- Пользователь включает одну или несколько toggle-кнопок.
- UI оставляет в branches только выбранные окружения.
- UI оставляет в Jobs/pipeline только выбранные окружения.
- Ссылки, статусы и колонки Jobs также относятся только к выбранным окружениям.
- Если все toggle-кнопки выключены, UI показывает все окружения.
- Фильтр меняет только отображение и не изменяет серверное состояние.
- Обновление состояния не должно сбрасывать активный выбор toggle-кнопок, если выбранные окружения всё ещё существуют.
- Если pipeline окружения содержит хотя бы один неуспешный (
error) или незаконченный (is_running) шаг, соответствующая toggle-кнопка получает красную рамку. - Красная рамка обновляется вместе с состоянием pipeline и не изменяет доступность или поведение toggle-кнопки.
U-06a. Отфильтровать окружения текстом
- Пользователь вводит текст фильтра.
- UI оставляет подходящие окружения/стэки.
- Фильтр меняет только отображение и не изменяет серверное состояние.
- Очистка фильтра возвращает полный список.
U-07. Обновить отображаемое состояние
- Пользователь нажимает refresh/update в UI.
- UI отправляет серверу соответствующее WebSocket-сообщение либо ожидает очередное состояние pipeline.
- Сервер присылает branches/environments/jobs.
- UI обновляет строки, статусы и ошибки.
- Автоматического UI-таймера каждые пять минут не следует предполагать; обновление может быть pipeline-driven.
U-08. Выбрать branch
- Пользователь выбирает branch для окружения.
- UI меняет локальный selection.
- При применении selection отправляется серверу через WebSocket.
- После server update UI отображает выбранное состояние и результат pipeline.
U-09. Выбрать HEAD
- Пользователь выбирает
HEADили текущую вершину branch. - UI показывает этот выбор как desired version.
- При применении сервер разрешает актуальный commit branch.
- Результат checkout/build/deploy и deployed version приходят в Jobs/state.
U-10. Выбрать исторический commit
- Пользователь открывает историю branch.
- UI показывает доступные commits.
- Пользователь выбирает конкретный commit.
- UI отправляет selection при применении.
- Ошибка отсутствующего commit или merge отображается как ошибка pipeline.
U-11. Ввести произвольный commit
- Пользователь вводит commit/ref, если такой control доступен.
- UI передаёт значение серверу.
- Сервер проверяет ref/commit и возвращает состояние.
- Неизвестный commit отображается как ошибка, а не как успешная выбранная версия.
U-12. Применить выбранное состояние
- Пользователь выбирает окружение и версию.
- Нажимает apply/update.
- UI отправляет команду через WebSocket.
- UI показывает queued/running/success/error по сообщениям сервера.
- После завершения показывает selected и deployed state отдельно.
U-13. Объединить несколько branches
- Пользователь выбирает несколько branches для одного окружения.
- UI отображает состав selection.
- При apply сервер выполняет merge.
- Успешный результат продолжает pipeline; merge conflict отображается в Jobs/error.
- Отдельного обещания автоматического разрешения конфликтов UI не даёт.
U-14. Запустить dry run
- Пользователь включает dry run.
- UI отправляет selection с dry-run параметром.
- UI показывает Git/analysis/build-preparation progress.
- UI не должен показывать dry run как выполненный deploy.
- Результат и ограничения dry run приходят от сервера; подготовительные шаги могут выполняться до финального запрета deploy.
U-15. Наблюдать Jobs и pipeline
- Пользователь раскрывает Jobs или строку окружения.
- UI получает и показывает этапы clone, state, checkout/merge, build/workflow, Swarm check и deploy.
- Для текущего шага отображаются progress/status/log message, если они пришли.
- Ошибка останавливает визуальный success flow и остаётся видимой для диагностики.
U-16. Просмотреть ссылки сервиса
- Сервер присылает
userLinksв результатах pipeline. - UI показывает ссылки на приложение/status или связанные сервисы.
- Пользователь открывает ссылку в браузере.
- Если
userLinksнет, UI не должен придумывать URL.
U-17. Увидеть автоматический deploy без действия в UI
- Пользователь не нажимает Update.
- Сервер обнаруживает, что remote HEAD отличается от deployed label.
- Сервер запускает pipeline и присылает Jobs/environments update.
- UI отображает changed desired/deployed state и progress.
- Если diff нет, UI не показывает ложный deploy.
U-18. Увидеть ошибку Git/credentials/registry/Docker/health check
- Пользователь наблюдает Jobs или error panel.
- UI показывает неуспешный шаг и текст ошибки, если он прислан сервером.
- Пользователь устраняет внешнюю причину и повторяет update.
- Наличие error state не считается успешным deploy.
U-19. Увидеть stale/conflict state
- Два клиента могут выбирать одно или разные окружения одновременно.
- Один клиент может получить состояние, устаревшее относительно другого клиента.
- Сервер может отклонить stale update.
- UI сохраняет локальный выбор до следующего обновления, если сервер не прислал отдельное conflict message.
- Structured conflict dialog текущий backend не гарантирует.
U-20. Работать с secondary Brencher
- UI получает объединённое состояние локального backend и отдельного secondary Brencher, если
SECONDARY_BRENCHERнастроен. - Пользователь видит branches/environments обоих источников согласно данным сервера.
- Обрыв secondary-соединения отображается как error/stale state.
- После reconnect UI получает новое initial/update состояние.
brencher2сам по себе является локальным профилем и не означает наличие secondary-сервера.
U-21. Просмотреть состояние через прямой REST URL
- Пользователь открывает
/stateили/branchesв браузере/инструменте. - Сервер возвращает JSON.
- Это read-only диагностика и не заменяет UI-соединение
/ws. - Изменение 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 прислал.