Интеграторская консоль: обзор и маршрут просмотра

Обновлено: 28.05.2026 (K-ADM3 — refresh после live audit; уточнения по доступу, Excel импорту, troubleshooting; чётче зафиксированы текущие ограничения и отложенные фазы). Статус: wave K-ADM2 закрыта 18.05.2026 — все 6 slice'ов (Dashboard / Per-org overview / Menu Builder / Preview / Versions / Excel polish) получили ACCEPT-verdict codex. Развёрнуто на dev.antroute.pro. Это уже не «пилотный YAML-конфигуратор», а виджетный интерфейс под целевого пользователя — интегратора, который не должен видеть raw технические форматы в основном UI. Адресат: интегратор-владелец конфигурации (архитектор-пилот, замещающий технолог) и admin-пользователь, который выдаёт доступы.

Описывает интеграторскую консоль AntRoute — место, куда заходит человек, отвечающий за заведение конкретного предприятия. С K-ADM2 интерфейс полностью на виджетах: список организаций, конструктор меню, визуальный preview под ролью, версии конфигурации с восстановлением, импорт Excel.

1. Что это и зачем

AntRoute — одна сборка для всех заказчиков. Под конкретное предприятие настройки (меню, экраны, вкладки, столбцы, словари) живут в DSL-конфигурации, к которой интегратор не обращается напрямую как к файлу. Вместо этого интеграторская консоль даёт:

• Dashboard — карточки всех организаций с реальными счётчиками (изделия / РМ / материалы / операции / спецификации / кооперации);
• Карточка организации — статус, последний импорт, активная версия DSL, действия (импорт, превью, меню, экраны, доступы, версии);
• Конструктор меню — виджетный редактор секций и пунктов с выпадающим списком разрешённых экранов;
• Превью под ролью — визуальный макет боковой панели и рабочего экрана для выбранной роли в выбранной организации;
• Версии — список карточек предыдущих публикаций с кнопкой «Восстановить» (forward-publish, не destructive);
• Импорт Excel — мастер из 5 шагов под канонический шаблон Кочарина с разбивкой по 7 организациям.

Цель: интегратор ведёт DSL без переразвёртывания кода, без правки YAML, без видения raw UUID и run_id в основном интерфейсе.

2. Доступ — как получить и как зайти

Интеграторская консоль доступна только пользователю с активным IntegratorAssignment. Это сознательный выбор: правка конфигурации и импорт данных — admin-level действия.

Кто	Что видит в консоли
Глобальный integrator (IntegratorAssignment.is_global=true)	Все организации платформы на Dashboard
Scoped integrator (грант на конкретные организации)	Только разрешённые карточки + поясняющий баннер «Вам назначено N организаций»
Superuser без IntegratorAssignment	Консоль недоступна — RouteGuard возвращает на обычный дашборд /, организации не раскрываются (без leakage)
Admin/диспетчер предприятия	Раздел недоступен — RouteGuard ведёт его на обычный дашборд /
Технолог / Мастер / Оператор	Консоль скрыта целиком

Если после входа вы возвращаетесь на главный экран / вместо консоли (нет активного IntegratorAssignment) — запросите grant у admin (Vladimir): прислать username и роль (is_global для архитектора, либо список конкретных орг-кодов для scoped интегратора).

Как открыть консоль

1. Войти под аккаунтом с активным IntegratorAssignment.
2. В сайдбаре открыть /v/admin/integrator-tools (либо кликнуть пункт «Интеграторские инструменты» если он есть в вашей роли).
3. Откроется Dashboard — список карточек организаций.
4. Клик на карточку → карточка организации с действиями (Импорт Excel / Превью / Меню / Экраны / Роли / Версии).

3. Что реально на экранах

3.1. Dashboard — список организаций

Адрес — /v/admin/integrator-tools. Карточки отсортированы по числу изделий (по убыванию) с tie-break по коду организации. Каждая карточка показывает:

• статус (Действует / Триал / Приостановлено / Неактивно);
• 6 счётчиков (Изделия / Рабочие места / Материалы / Операции / Спецификации / Кооперации);
• кнопку «Импорт Excel» (ссылка на shared platform-wide мастер).

Под scoped пользователем Dashboard показывает только разрешённые карточки с пояснительным баннером:

Под superuser без активного IntegratorAssignment консоль не открывается: RouteGuard возвращает на обычный дашборд /, не раскрывая никаких организаций (без leakage). Отдельного баннера «Нет integrator-доступа» нет — это обычный redirect-guard, без crash.

3.2. Карточка организации

Адрес — /v/admin/integrator-tools/:orgCode. Клик по любой карточке Dashboard либо прямой переход по коду организации. Содержит:

• заголовок и статус организации;
• блок «Наполненность данными» с теми же 6 счётчиками крупным шрифтом;
• «Последний импорт» (дата / тип / статус — без UUID);
• «Активная DSL-конфигурация» (номер версии / дата публикации / автор);
• блок «Действия»: Импорт Excel · Превью под ролью · Меню роли · Экраны · Роли и доступ · Версии конфига.

Для триал-организации статус-бейдж жёлтый:

Для организации без импортов и DSL — пустые состояния «Импорта ещё не было» и «Конфигурация ещё не создана»:

Если organization не в скоупе текущего integrator-гранта — generic banner «Организация не найдена или недоступна» (тот же текст что для несуществующих org — анти-leak):

Действия «Экраны» (C5) и «Роли и доступ» (C6) в текущей волне открывают информационный toast «Появится в следующих фазах K-ADM2». См. §4 ниже. Остальные четыре действия (Импорт Excel, Превью, Меню, Версии) — рабочие routes.

3.3. Конструктор меню

Адрес — /v/admin/integrator-tools/:orgCode/menu. Виджетный редактор без YAML/JSON:

• секции — карточки с заголовком (id + русское название в Input), кнопки «↑/↓» для перестановки, «Пункт» (Add Item) и «Удалить»;
• пункты внутри секций — пары screen → русское название, плюс «↑/↓» и «Удалить»;
• «Добавить секцию» — модальное окно с двумя полями (latin id, русское название);
• «Добавить пункт» — модальное окно с Select разрешённых экранов (allowed_screens из effective_json.screens) и полем подписи;
• «Сохранить» — отправляет PATCH /api/v1/integrator/orgs/<org_id>/menu/ с заголовком If-Match, на успех показывает toast «Меню сохранено. Версия N» и обновляет ETag;
• «Отменить изменения» — возвращает draft к серверному состоянию;
• 412 → жёлтый banner «Кто-то изменил конфигурацию параллельно. Обновите страницу.»

«Добавить секцию» открывает модальное окно с виджетной формой (а не raw JSON-редактор):

Сохранение переименованной секции:

Откат изменений:

Добавление пункта (Select разрешённых экранов):

Сервер хранит каждую публикацию как TenantConfigVersion с YAML snapshot, обновляет tc.published_yaml/draft_yaml/published_at. AuditLog payload_summary.diff фиксирует added_sections / removed_sections / total_sections / total_items.

Текущее ограничение (K-ADM2 wave): Конструктор меню работает с плоской структурой menu.sections. Если ваш tenant использует per-role меню (menu: { technologist: [...], constructor: [...] }), Конструктор покажет «Меню пустое» — это не баг данных, а текущий scope. Per-role редактирование меню запланировано в волне K-ADM3 (internal tracking: docs/sprint_2026_may/active/K-ADM3-integrator-console-docs-refresh.md в репозитории). Превью под ролью (§3.4) уже понимает per-role меню корректно — оно сразу показывает финальный вид сайдбара по выбранной роли.

3.4. Превью под ролью

Адрес — /v/admin/integrator-tools/:orgCode/preview. Визуальный макет: слева — карточка-эмулятор боковой панели, справа — макет рабочего экрана.

• Select роли с шестью вариантами (Технолог / Диспетчер / Конструктор / Поставщик / ОТК / Суперпользователь);
• по умолчанию — Технолог. При смене роли секции пересчитываются: если у роли в DSL есть свой menu, показываем его; иначе fallback на глобальное menu.sections;
• секции без пунктов — «Без пунктов»;
• информационный alert на каждой странице — «Это структурное превью, бизнес-данные не подтягиваются».

Смена роли на «Диспетчер»:

В этой версии нет ни YAML дампа, ни JSON-сниппетов, ни таблиц routes (всё это было в K-ADM1 viewer):

3.5. Версии конфигурации

Адрес — /v/admin/integrator-tools/:orgCode/versions. Список карточек предыдущих публикаций, новейшие сверху.

• каждая карточка — номер версии, дата, автор (display name / username), note;
• активная версия помечена зелёным бейджом «Текущая», её кнопка «Восстановить» disabled;
• «Восстановить» открывает confirm-модалку, при подтверждении: запрашивает свежий ETag со /integrator/tenant-config/<org_id>/status/, шлёт POST /rollback/ с version_number, note, If-Match. Бэкенд использует forward-publish — старая версия не теряется, создаётся новая запись с содержимым выбранной;
• успех → toast «Версия N восстановлена», список обновляется.

Restore-confirm:

3.6. Импорт Excel (Slice 6 polish)

Адрес — /v/admin/integrator-tools/imports/kocharin. Мастер из 5 шагов под канонический шаблон Кочарина:

1. Upload — выберите XLSX-файл (полный канонический шаблон + 7 листов по орг-кодам). Backend валидирует формат сразу.
2. Plan preview — показ что будет загружено: сколько объектов, какие листы попадают в какую орг, dry-run без записи.
3. Confirm — финальное подтверждение применения.
4. Apply — backend bulk-load в транзакции; статус по каждой орг обновляется в реальном времени.
5. Summary — итоги: успехи / ошибки / число обработанных строк. На этом шаге блок «Подробнее (для разработчика)» по умолчанию свёрнут — обычный пользователь не видит JSON-дамп, но при необходимости (отладка/CI) разработчик может его раскрыть.

Полная документация на отдельной странице — Импорт Excel: схема и шаги.

Принцип Slice 6: raw технические форматы прячутся за дисклоузерами или вовсе отсутствуют. Виджеты ведут пользователя.

4. Что отложено (placeholder в карточке организации)

Кнопки «Экраны» (C5) и «Роли и доступ» (C6) в карточке организации открывают информационный toast «Появится в следующих фазах K-ADM2», без перехода на отдельную страницу. По плану:

• Редактор экранов (C5) — drag-drop layout виджетов внутри одного screen, выбор виджет-варианта (tabbed-card / crud-list / dashboard-grid), привязка к классификаторам;
• Матрица доступа (C6) — таблица ролей × секции/пункты/экраны с галочками «видит / редактирует».

Обе фазы предполагают тот же widget-first принцип: никаких YAML, только визуальные таблицы и формы. Сроки — см. roadmap волн K-ADM3 / K-ADM4.

Если эти возможности нужны прямо сейчас — настройка делается через kocharin.yaml напрямую с командой dev-team (через feedback FAB или Telegram).

5. Troubleshooting

После входа возвращает на главный экран / вместо консоли

Нет активного IntegratorAssignment (даже у superuser). RouteGuard возвращает на обычный дашборд / — это ожидаемое поведение, не ошибка, организации не раскрываются. Запросите grant у admin/Vladimir: укажите username и нужный scope (is_global для архитектора любых орг, либо список орг-кодов для scoped доступа).

Меню пустое в Конструкторе, хотя в Превью под ролью секции есть

Текущая волна K-ADM2 редактирует только flat menu.sections. Если ваш tenant использует per-role меню (menu.{technologist,constructor,...}) — Конструктор покажет «Меню пустое». См. §3.3 примечание. Per-role редактирование — в K-ADM3.

412 Precondition Failed на сохранении меню

Кто-то изменил конфигурацию параллельно с вами. Обновите страницу (Конструктор перечитает свежий ETag) и повторите ваши правки. Это не баг; так работает optimistic locking.

«Версия N восстановлена», но Превью / Sidebar показывают старое

Версия восстановлена корректно (forward-publish). Frontend может закешировать старое effective_json — обновите страницу (F5). Если проблема осталась — это уже инфра-инцидент.

Импорт Excel застрял на шаге Apply

Импорт идёт в фоне; шаг Apply поллит статус. Если таймаут / прервалось — статус виден на Карточке организации в блоке «Последний импорт». Failures имеют summary с конкретной строкой/листом, повтор после правки XLSX безопасен.

6. Контракт «no JSON/YAML/CodeMirror в primary UI»

Это инвариант K-ADM2, прописанный в гейте codex-ревью и автоматических проверках walkthrough'ов:

• grep гейт — frontend/src/features/integrator/v2/** не содержит JSON.stringify, <pre, CodeMirror, yaml в primary surface;
• DOM гейт walkthrough — Playwright проверяет на каждой странице: pre count = 0, .cm-editor count = 0, body innerText не содержит YAML/JSON/raw UUID-паттерн;
• vitest гейт — screen.queryByTestId('apply-summary-json') либо отсутствует, либо находится внутри неоткрытого Collapse.

Это снимает прежнее замечание (K-ADM1 показывал YAML-редактор и таблицы routes с UUID в адресе) и приводит интерфейс к виджетному виду.

7. Источники истины

• K-ADM2 closure — docs/sprint_2026_may/closed/2026-05/K-ADM2-closure-2026-05-18.md (все 6 slice'ов ACCEPTED).
• K-ADM3 (текущая волна доводки) — docs/sprint_2026_may/active/K-ADM3-integrator-console-docs-refresh.md.
• Backend mutation — antroute_backend/screens/views_integrator_menu.py (GET/PATCH menu), views_integrator.py (publish/rollback/versions), views_integrator_summary.py (Dashboard).
• Frontend pages — frontend/src/features/integrator/v2/*.tsx.
• Walkthrough evidence — docs/sprint_2026_may/active/K-ADM2-evidence/sliceN/summary.json (overall_pass=true с machine_assertions).