---
doc_id: REF-CK8S-0017
type: ux-model
title: "kodex — каноническая UX-модель консоли и рабочих режимов"
status: active
owner_role: PM
created_at: 2026-04-21
updated_at: 2026-04-24
related_issues: [281, 282, 309]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave5"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Каноническая UX-модель консоли и рабочих режимов

## TL;DR
- Консоль строится не вокруг отдельной сущности инициатива или свободного полотна, а вокруг реальных сущностей платформы: проектов, репозиториев, `Issue`, `PR/MR`, agent `run`, platform `job`, агентных сессий и slot.
- Главная точка входа пользователя: командный центр с чатом и голосом для общения с agent-manager.
- Review `PR/MR` остаётся в GitHub/GitLab; консоль показывает состояние, проверки, gates и ссылки, но не пытается заменить нативный экран ревью провайдера.
- Для работы с задачами используется универсальное рабочее пространство `Issue`, а для работы с изменениями — универсальное рабочее пространство `PR/MR`.
- Конфигурирование flow, ролей, шаблонов промптов, внешних аккаунтов и каналов связи выносится в отдельный настроечный контур. Flow, роли и шаблоны сохраняются в БД как версии с аудитом, а репозиторий платформы содержит только установочные фикстуры.
- Волна 5 закрывает проблему `time to first successful run`: первый запуск должен проходить через понятный управляемый маршрут, а не через скрытую платформенную магию.
- Каноническая карта консоли сразу включает каталоги пакетов, организации и группы, контур серверов и кластеров, учёт затрат, релизную политику и правила автоматизации; детальная визуализация этих административных разделов может идти следующим UX-срезом, но сами разделы уже считаются обязательными.

Текущий пакет макетов wave 5 находится в [refactoring/images/wave5/index.md](images/wave5/index.md). Для экранов с вкладками рядом с основным состоянием лежат отдельные PNG по каждой вкладке, а незавершённые элементы wave 5.2 зафиксированы в [wave5-2-backlog.md](images/wave5/wave5-2-backlog.md).

## 1. Цель волны 5
Wave 5 должна зафиксировать не внешний стиль интерфейса, а продуктовую и операционную модель консоли:
- какие экраны вообще существуют;
- какую задачу решает каждый экран;
- на каких сущностях и проекциях он строится;
- где пользователь разговаривает с agent-manager;
- как оператор видит блокировки, уведомления, `run`, `job`, approvals и лимиты;
- как редактируются flow, роли и шаблоны промптов, если источником правды является БД платформы.

## 2. Канонические UX-принципы

### 2.1. Никаких искусственных рабочих сущностей
Консоль не должна вводить параллельный внутренний мир наподобие карточек инициатив, которыми невозможно нормально управлять через GitHub/GitLab.

Если пользователь видит в интерфейсе рабочий объект, он должен понимать, чем он является:
- проект;
- репозиторий;
- `Issue`;
- `PR/MR`;
- agent `run`;
- platform `job`;
- slot;
- approval или уведомление.

### 2.2. Чат — основной, но не единственный режим
Agent-manager — центральный способ запуска и продолжения работы, но пользователь не обязан решать всё только диалогом.

Консоль обязана давать:
- чат и голос как основной путь;
- явные кнопки запуска и создания;
- списки, фильтры и рабочие пространства для операторской навигации;
- быстрый переход в нативные для провайдера артефакты.

### 2.3. Один экран — одна доминирующая задача
Экран должен отвечать на один главный вопрос:
- что запустить;
- над чем поработать;
- что требует решения;
- что упало;
- что настроить.

Смешивать на одном уровне чат, хаотичное полотно, настройки и диагностику нельзя.

### 2.4. Review живёт у провайдера
GitHub/GitLab остаются местом, где:
- читается diff;
- пишутся review-комментарии;
- ставятся approval и merge-гейты.

Консоль должна:
- показывать сводку и блокировки;
- вести в нужный `Issue` или `PR/MR`;
- связывать review с `run`, `job`, risk class и acceptance state.

### 2.5. Операторские экраны строятся на проекциях чтения
Экран не должен собираться напрямую из нескольких случайных сервисов или из локального ad-hoc state.

Канонический путь:
- owner-сервисы владеют состоянием;
- `operations-hub` и другие проекционные контуры отдают готовые проекции чтения;
- `web-console` использует их как экранные модели.

### 2.6. Целостность выбранной локали
Пользовательские названия экранов, действий и статусов должны быть оформлены в выбранной пользователем локали без хаотичной смеси двух языков в пределах одного интерфейсного состояния.

Для русской локали это означает:
- писать по-русски там, где мысль можно выразить без потери точности;
- английский оставлять только для точных технических идентификаторов и нативных имён внешних систем.

Для любой другой локали действует тот же принцип: интерфейс остаётся цельным и не распадается на смесь локализованного и нелокализованного текста без причины.

## 3. Каноническая карта экранов

### 3.1. Верхний уровень навигации

| Раздел | Главный вопрос | Основные сущности |
|---|---|---|
| Командный центр | что запустить, что требует моего решения, что сказал agent-manager | agent-manager, запросы пользователя, approvals, уведомления |
| Проекты и репозитории | какими проектами и репозиториями я управляю, готовы ли они к работе и к релизу | проект, репозиторий, release policy, preflight, rights |
| Работа | какие `Issue` и `PR/MR` сейчас идут, заблокированы или ждут действия | `Issue`, `PR/MR`, risk class, gates, relationships |
| Исполнения и среда | какие agent `run`, platform `job`, slot и операции кластера выполняются или упали | `run`, `job`, slot, кластерный контур, хвост лога |
| Каталоги и расширения | какие плагины, пакеты руководящей документации, роли и шаблоны доступны и разрешены | запись каталога пакетов, пакет-плагин, пакет руководящей документации, профиль роли, шаблон промпта |
| Организации и доступы | кто к чему допущен и как устроены пользователи, группы и организационные контуры | user, group, organization, membership, access policy |
| Инфраструктура | где живёт платформа и куда могут уходить slots и workloads | server, cluster, placement policy, runtime-контур |
| Биллинг и учёт | сколько стоит работа платформы и что выставляется клиентам | биллинговый аккаунт, запись затрат, основа для выставления счетов |
| Настройка и automation | как заданы flow, release policy, правила расписания, triggers и каналы | flow, release line, automation rule, внешний аккаунт, канал, версия шаблона |

### 3.2. Что запрещено выводить в отдельный верхнеуровневый раздел
Не должно быть самостоятельных верхнеуровневых экранов:
- для абстрактной инициативы как отдельной сущности;
- для свободного полотна как главного способа управления платформой;
- для документации как отдельного рабочего мира вне `Issue/PR/MR` и репозиториев.

Проектная документация должна быть видна через проект, репозиторий, workspace задачи и связанные `PR/MR`, но не как отдельная параллельная система документов внутри UI.

## 4. Глобальные UX-примитивы

### 4.1. Глобальный контекст
На уровне приложения должны существовать:
- текущий пользователь;
- текущий проект или режим все доступные проекты;
- универсальный поиск по задачам, `PR/MR`, `run`, `job` и репозиториям;
- глобальный центр внимания с непрочитанными решениями и ошибками.

На уровне wave 5 поиск фиксируется как обязательная возможность консоли, но не как жёстко заданная граница сервиса.

Архитектурно это может быть:
- отдельный поисковый контур чтения;
- выделенный поисковый сервис;
- специализированная поисковая проекция внутри уже существующего сервиса-владельца или read-сервиса.

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

### 4.2. Быстрые действия запуска
Вместо большого постоянного composer в центре экрана и отдельной доминирующей кнопки `Создать` в верхней панели консоль использует компактный блок быстрых действий внутри рабочего полотна командного центра.

Блок быстрых действий должен уметь:
- создать обычный `Issue`;
- создать `Issue` типа `initiative`;
- выбрать flow и запустить управляемое создание;
- открыть диалог с agent-manager в нужном контексте;
- инициировать репозиторный onboarding или adoption.

### 4.3. Голос как действие внутри диалогового контура
Голосовой запуск — не отдельный экран и не дублирующая кнопка в шапке.

Канонический паттерн:
- на экранах с agent-manager голос живёт внутри блока ввода сообщения;
- кнопка микрофона располагается в правой части поля ввода, рядом с отправкой;
- голос открывает тот же диалоговый контур agent-manager, что и текстовый ввод;
- голосовое действие не должно перекрывать полезный контент отдельной плавающей кнопкой на уровне всего экрана.

### 4.4. Центр внимания
Пользователь должен в любой момент видеть:
- pending approvals;
- запросы обратной связи;
- упавшие `run` и `job`;
- лимиты провайдера и ошибки авторизации;
- проблемы housekeeping и cleanup;
- важные завершения этапов.

Это не отдельная сводка ради сводки, а слой навигации с явными действиями.

### 4.5. Активная работа и мои проверки
Командный центр должен разделять общий поток живой работы и персональную очередь решений текущего пользователя.

Канонические правила:
- `Активная работа` показывает свежие живые объекты в рамках текущего проектного контура: `Issue`, `PR/MR`, `run`, `job`;
- `Мои проверки` показывает только объекты, по которым текущее лицо должно принять решение, дать ответ или поставить review/approval;
- один и тот же объект не должен одновременно жить в обеих колонках;
- если объект требует действия именно от текущего пользователя, он попадает только в `Мои проверки`.

### 4.6. Активные элементы внутри сообщений
Сообщения agent-manager и других ролей могут содержать не только текст, но и встраиваемые action badges.

Канонические типы:
- badge-ссылка на `Issue` или `PR/MR` с иконкой перехода во внешнюю систему;
- badge-действие запуска или продолжения работы с иконкой запуска;
- badge-действие подтверждения или ответа, если оно не требует полного перехода в отдельный экран.

### 4.7. Каноническая модель вкладок
Вкладки используются как второй уровень навигации внутри уже выбранной сущности или категории, а не как способ смешивать несколько контекстов на одном полотне.

Канонические правила:
- вкладки переключают только центральную рабочую поверхность;
- выбранная сущность, категория и правая панель контекста остаются стабильными;
- контент одной вкладки не должен визуально смешиваться с контентом другой;
- названия вкладок должны описывать устойчивые срезы данных (`Аккаунты`, `Права`, `Ограничения`, `История`), а не действия;
- на одном уровне допустимо держать 3-6 вкладок, иначе экран должен распадаться на отдельные страницы;
- активная вкладка должна быть понятна по самому содержимому экрана, а не только по подсветке label.

Для wave 5 это означает:
- рабочие поверхности `Issue` и `PR/MR` используют вкладки для артефактов, проверок, связей и истории;
- настроечные экраны используют вкладки для реестра, политик, ограничений, использования и истории внутри одной сущности.

## 5. Командный центр как домашний экран
Командный центр — это главный домашний экран платформы.

Его состав:
1. центральный диалог с agent-manager;
2. блок быстрых действий для типовых сценариев запуска;
3. виджеты центра внимания;
4. отдельные колонки `Активная работа` и `Мои проверки` без дублей;
5. быстрые переходы к проектам, репозиториям и рабочим пространствам.

Командный центр не должен:
- показывать свободное полотно;
- дублировать полное содержимое рабочих пространств;
- быть второй версией GitHub board.

## 6. Универсальные рабочие пространства

### 6.1. Рабочее пространство `Issue`
Один канонический экран для любой задачи:
- `initiative`;
- этапная задача;
- follow-up;
- `risk`;
- `incident`;
- `self-improve`.

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

### 6.2. Рабочее пространство `PR/MR`
Отдельный канонический экран нужен только потому, что `PR/MR` имеет другой цикл:
- review;
- merge readiness;
- связи с `Issue`;
- связь с `run`, `job`, risk class, release и acceptance evidence.

### 6.3. Рабочее пространство исполнения
Agent `run` и platform `job` не становятся предметом управления на домашнем экране, но у них должен быть собственный диагностический экран:
- статус;
- контекст;
- причина ошибки;
- короткий хвост лога;
- ссылка на первоисточник;
- следующий ожидаемый action.

## 7. Что фронтенд обязан помнить об источнике истины

### 7.1. Что является первичным
Первичными остаются:
- нативные для провайдера артефакты в GitHub/GitLab;
- owner-сервисы платформы;
- репозитории проектной документации, указанные в `services.yaml`.
- БД `agent-manager` для flow, профилей ролей и шаблонов промптов.

### 7.2. Что хранится только как экранная проекция
Фронтенд работает с:
- проекциями чтения для экранов;
- агрегированными сводками;
- статусными проекциями;
- поисковыми индексами;
- локальным экранным state.

## 8. Обязательные административные разделы
Следующие экранные направления считаются обязательными, даже если их детальный пакет макетов будет вынесен в следующий UX-срез:
- каталог пакетов для плагинов и пакетов руководящей документации;
- поверхности установки, импорта и верификации пакетов;
- организации, группы и наследуемые права;
- реестр серверов и кластеров и политика размещения;
- сводки по затратам, распределение потребления и основа для выставления счетов;
- релизная политика, релизные линии и правила автоматизации.

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

Он не создаёт собственную канонику поверх этих данных.

## 8. Ограничения на визуальную модель

### 8.1. Canvas не является главным способом управления
Свободное перемещение нод и хаотичный граф не могут быть источником истины для работы пользователя.

Canvas допускается только как:
- вспомогательный просмотр потока;
- объясняющая схема;
- вспомогательный режим анализа.

### 8.2. Flow-редактор не должен требовать рисовать схему руками
Для настройки flow и ролей каноническим считается последовательный UX, а не произвольный редактор нод.

## 9. Импликации для frontend-реализации

### 9.1. Базовый UI-kit
Для новой версии `web-console` базовым UI-kit считается PrimeVue.

Это решение означает:
- повторно используемые примитивы должны быть собраны поверх PrimeVue в `shared/ui`;
- экранная логика и доменные модели не должны смешиваться с конкретными компонентами библиотеки;
- визуальный слой можно менять без перелома продуктовой модели экранов.

### 9.2. Роуты и stores
Frontend обязан отражать каноническую карту экранов:
- route-level страницы на уровне разделов;
- stores по конкретным рабочим поверхностям;
- typed mappings между API DTO и UI-моделями;
- единый error model и единый notification model.

Для данных, которые должны обновляться максимально динамично, канонический путь для `web-console` — push-модель через WebSocket или эквивалентный поток серверных событий с резервными дозапросами только там, где постоянное соединение недоступно или избыточно.

## 10. Текущий макет командного центра

Для текущей итерации wave 5 каноническим базовым направлением считается макет командного центра с:
- верхней лентой решений и активной работы;
- основным диалогом слева;
- правой колонкой `Активная работа` и `Мои проверки` без дублей;
- отдельным блоком быстрых действий внутри основного рабочего полотна;
- action badges внутри сообщений agent-manager вместо лишних глобальных кнопок в шапке.

![Текущий макет командного центра](images/wave5/01-command-center/screen.png)

Спецификация экрана: [screen.md](images/wave5/01-command-center/screen.md)

## 11. Текущий макет проектов и репозиториев

Для текущей итерации wave 5 базовым направлением считается экран проектов и репозиториев с:
- верхней лентой summary-card по числу проектов, репозиториев кода, источников документации и проблем синхронизации;
- таблицей проектов как основным рабочим списком;
- правой панелью деталей выбранного проекта;
- отдельным блоком репозиториев и источников документации выбранного проекта;
- вкладками репозиториев, документации, рабочей области и релизной политики;
- явными действиями подключения репозитория, проверки доступов, сборки `workspace` и проверки релизной политики.

![Текущий макет проектов и репозиториев](images/wave5/08-projects-and-repositories/screen.png)

Спецификация экрана: [screen.md](images/wave5/08-projects-and-repositories/screen.md)

## 12. Что wave 5 intentionally не фиксирует
В этой волне не фиксируются:
- финальный визуальный стиль и язык анимаций;
- точная сетка компонентов PrimeVue;
- окончательный OpenAPI экранных ручек;
- детали реализации голосового распознавания;
- детальный onboarding runtime и bootstrap-контур.

Но любая последующая реализация `web-console` обязана соответствовать канонике этой волны: командный центр как главный вход, универсальные рабочие пространства, операторские поверхности на реальных сущностях и БД-ориентированная настройка flow/ролей/шаблонов с установочными фикстурами в репозитории платформы.
