# Alpine UI Integration Plan

## 1. Назначение документа

Этот документ фиксирует, как переносимый Alpine UI из `apps/ui` должен подключаться к реальному backend.

Его задача:

- разложить UI по страницам;
- показать, что уже поддержано текущим backend;
- зафиксировать отсутствующие endpoint-ы и контрактные разрывы;
- определить порядок интеграции без хаотичных правок.

## 2. Текущее состояние

Сейчас `apps/ui` уже заменен на Alpine.js UI, перенесенный из `test-ui`.

Важно:

- `apps/ui` теперь является основной UI-кодовой базой;
- `test-ui` остается fallback-источником и не должен использоваться как рабочая папка интеграции;
- новый UI пока опирается на `localStorage`, mock JSON и локальные сценарии;
- backend уже поддерживает `workspace`, `operations`, `agents`, `platform access`, `logs`, `usage`, но не все UI-flow закрыты полностью.

## 3. Принципы интеграции

- сначала подключаем страницы, уже совпадающие с текущим backend-контрактом;
- затем добавляем недостающие endpoint-ы под уже существующие UI-flow;
- только после этого убираем mock JSON и `localStorage`-костыли;
- если UI противоречит текущему backend, приоритет у целевой продуктовой модели, но конфликт должен быть разобран явно.

## 4. Page-by-page integration matrix

### 4.1. Operations catalog

UI-файлы:

- `apps/ui/index.html`
- `apps/ui/js/catalog.js`

Что UI хочет:

- список операций;
- фильтры по protocol/category/agent/status;
- карточки верхних метрик;
- переход в wizard create/edit;
- удаление/архивирование;
- отображение агентных привязок.

Что уже можно подключить:

- `GET /api/admin/workspaces/{workspace_id}/operations`
- `GET /api/admin/workspaces/{workspace_id}/agents`
- `GET /api/admin/workspaces/{workspace_id}/usage`
- `PATCH /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
- `DELETE /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive`

Что еще не хватает:

- frontend data adapter, который заменит mock merge на реальные `items/page/page_size/total`;
- wiring server-side filters `protocol/category/agent/status/search`;
- переключение карточек верхних метрик с seeded summary на реальный usage payload.

Что убрать из UI после интеграции:

- `crank_ops_overrides` в `localStorage`
- merge поверх `data/operations.json`
- локальный tombstone/delete flow

Простой итог:

- эту страницу можно интегрировать первой;
- backend уже отдает server-side category, usage summary и agent refs;
- каталог уже может работать через реальные `list/delete/edit` вызовы;
- следующий шаг здесь только в server-side paging и остальных catalog actions; `target_url` и `target_action` теперь должны приходить из backend summary.

### 4.2. Wizard

UI-файлы:

- `apps/ui/html/wizard/index.html`
- `apps/ui/html/wizard/step*.html`
- `apps/ui/js/wizard.js`

Что UI хочет:

- create operation;
- edit operation;
- draft/save flow;
- test run;
- publish;
- загрузку samples;
- генерацию draft mapping;
- gRPC descriptor upload;
- import/export.

Что уже можно подключить:

- `POST /api/admin/workspaces/{workspace_id}/operations`
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
- `PATCH /api/admin/workspaces/{workspace_id}/operations/{operation_id}`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions`
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/proto`
- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/descriptor-set`
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/grpc/services`
- `GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/export`
- `POST /api/admin/workspaces/{workspace_id}/operations/import`

Что еще не хватает:

- frontend adapter поверх `OperationDetail` и `OperationVersionDocument`, чтобы wizard перестал хранить edit-state в браузере;
- финальное выравнивание step payload c canonical DTO, чтобы create/edit/export/import использовали одну модель на фронте.

Что убрать из UI после интеграции:

- `sessionStorage`-передачу `wizard_edit`
- draft-overrides через `localStorage`
- локальное создание operation без backend

Простой итог:

- wizard почти готов для реального backend;
- это основной экран второй очереди после catalog;
- базовый create/edit draft flow уже можно посадить на live `create/get version/update` endpoints;
- следующий разрыв здесь - test/publish/import/export wiring и полноценный gRPC descriptor-set lifecycle.

### 4.3. Agents

UI-файлы:

- `apps/ui/html/agents.html`
- `apps/ui/js/agents.js`

Что UI хочет:

- список агентов;
- create/edit agent;
- выбор операций для агента;
- publish agent;
- MCP endpoint на агента;
- calls today / operation count / key count.

Что уже можно подключить:

- `GET /api/admin/workspaces/{workspace_id}/agents`
- `POST /api/admin/workspaces/{workspace_id}/agents`
- `GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
- `PATCH /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}`
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings`
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish`
- `GET /api/admin/workspaces/{workspace_id}/usage`

Что еще не хватает:

- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions`
- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}`

Отдельный конфликт:

- UI считает, что агент можно редактировать прямо как рабочую сущность;
- backend пока ближе к publish-модели с version snapshot;
- нужно решить, edit агента мутирует draft напрямую или всегда создает новую version.

Простой итог:

- базовый live flow уже закрыт: list/create/edit/delete/bind/publish работают через backend;
- `GET /agents` уже отдает `calls_today`, `key_count`, `operation_count`, `operation_ids` и `mcp_endpoint`;
- следующий реальный разрыв здесь уже не в CRUD, а в version lifecycle и явном unpublish/archive flow для агентов.

### 4.4. API Keys

UI-файлы:

- `apps/ui/html/api-keys.html`
- `apps/ui/js/api-keys.js`

Что UI хочет:

- список platform API keys;
- create;
- one-time reveal;
- revoke;
- delete;
- scopes.

Что уже можно подключить:

- `GET /api/admin/workspaces/{workspace_id}/platform-api-keys`
- `POST /api/admin/workspaces/{workspace_id}/platform-api-keys`
- `POST /api/admin/workspaces/{workspace_id}/platform-api-keys/{key_id}/revoke`
- `DELETE /api/admin/workspaces/{workspace_id}/platform-api-keys/{key_id}`

Что еще не хватает:

- отдельный usage/last-used update flow, когда ключи реально начнут использоваться в runtime;
- если захотим richer UX, можно добавить server-side pagination и фильтрацию по статусу.

Отдельный конфликт:

- одноразовый `secret` доступен только в create-response, а list endpoint возвращает только metadata;
- это уже совпадает с backend, но UX нельзя случайно перевести в режим “показывать ключ повторно”.

Простой итог:

- страница уже сажается на текущий backend без новых ручек;
- live `list/create/revoke/delete` можно считать закрытым;
- следующий реальный шаг здесь только в polishing вокруг usage и audit trail.

### 4.5. Logs

UI-файлы:

- `apps/ui/html/logs.html`
- `apps/ui/js/logs.js`

Что UI хочет:

- список invocation logs;
- фильтры;
- detail row expansion;
- live refresh;
- status/error/duration.

Что уже можно подключить:

- `GET /api/admin/workspaces/{workspace_id}/logs`
- `GET /api/admin/workspaces/{workspace_id}/logs/{log_id}`

Что еще не хватает:

- optional pagination и server-driven cursor, если логи начнут расти;
- отдельный streaming endpoint, если polling перестанет устраивать;
- richer detail metadata, если захотим показывать trace/request ids отдельными виджетами

Простой итог:

- страница уже подключена к live `logs` API;
- текущий `live mode` реализован через polling и этого достаточно для текущего этапа.

### 4.6. Usage

UI-файлы:

- `apps/ui/html/usage.html`
- `apps/ui/js/usage.js`

Что UI хочет:

- верхние summary cards;
- timeline;
- breakdown по operations;
- p50/p95/p99;
- breakdown по agents;
- CSV export.

Что уже можно подключить:

- `GET /api/admin/workspaces/{workspace_id}/usage`
- `GET /api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}`
- `GET /api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}`

Что еще не хватает:

- если понадобится agent-specific usage drilldown, для него нужен отдельный экран или таб;
- если понадобится server-side export, можно добавить отдельный CSV endpoint позже;
- quota/limits пока не являются частью backend модели, поэтому страница честно показывает traffic share

Простой итог:

- usage page уже подключена к live `usage` API;
- CSV export сейчас делается на клиенте и этого достаточно для текущего этапа.

### 4.7. Workspace setup

UI-файлы:

- `apps/ui/html/workspace-setup.html`
- `apps/ui/js/workspace-setup.js`
- `apps/ui/js/workspace.js`

Что UI хочет:

- create workspace;
- edit workspace;
- список участников;
- приглашения;
- смену текущего workspace.

Что уже можно подключить:

- `GET /api/admin/workspaces`
- `POST /api/admin/workspaces`
- `GET /api/admin/workspaces/{workspace_id}`
- `PATCH /api/admin/workspaces/{workspace_id}`
- `GET /api/admin/workspaces/{workspace_id}/members`
- `GET /api/admin/workspaces/{workspace_id}/invitations`
- `POST /api/admin/workspaces/{workspace_id}/invitations`
- `DELETE /api/admin/workspaces/{workspace_id}/invitations/{invitation_id}`

Что еще не хватает:

- `switch current workspace` как backend-aware UI state, а не `localStorage`;
- нормальная серверная модель current user + memberships;
- endpoint на удаление участника или изменение роли, если UI хочет это поддерживать

Отдельный конфликт:

- UI создает workspace локально и сразу считает его текущим;
- backend уже умеет создавать workspace, но у нас нет полноценной user-session модели;
- значит выбор текущего workspace пока придется держать на клиенте, но список и metadata брать с сервера.

Простой итог:

- create/edit workspace уже можно подключать;
- members/invites тоже частично готовы;
- но полноценный switch и role management еще не закрыты.

### 4.8. Settings

UI-файлы:

- `apps/ui/html/settings.html`
- `apps/ui/js/settings.js`

Что UI хочет:

- профиль пользователя;
- security/preferences;
- workspace settings;
- language switcher.

Что уже можно подключить:

- частично `GET /api/admin/workspaces/{workspace_id}`
- `PATCH /api/admin/workspaces/{workspace_id}`

Что еще не хватает:

- current user endpoint;
- user profile update endpoint;
- preferences endpoint;
- security/auth settings model

Отдельный конфликт:

- UI считает, что у нас уже есть app-level user profile;
- backend пока не имеет session/user profile API;
- страницу стоит разбить:
  - workspace settings подключать раньше;
  - profile/security оставить временно mock или read-only.

Простой итог:

- эту страницу нельзя подключать целиком сразу;
- сначала надо отделить workspace settings от пользовательского профиля.

### 4.9. Login

UI-файлы:

- `apps/ui/html/login.html`
- `apps/ui/js/login.js`

Что UI хочет:

- app-level sign in;
- mock SSO button;
- user session.

Что уже есть реально:

- внешний `Basic Auth` на `nginx`

Что отсутствует:

- session auth backend;
- login endpoint;
- logout endpoint;
- current user endpoint

Отдельный конфликт:

- это не баг реализации, а отсутствие целого auth слоя;
- login page пока не должна позиционироваться как production-ready flow.

Простой итог:

- пока не интегрировать как реальный backend flow;
- оставить как временный mock screen до отдельного решения по auth.

## 5. Отдельные UI-vs-backend конфликты

### 5.1. Login vs Basic Auth

UI предполагает встроенный login, backend сейчас защищен внешним `Basic Auth`.

Решение:

- не делать вид, что login уже рабочий;
- отложить интеграцию login до отдельного auth этапа.

### 5.2. Agent draft/edit lifecycle

UI редактирует агента напрямую, backend идет к version/publish модели.

Решение:

- зафиксировать draft agent как редактируемую сущность;
- publish должен фиксировать snapshot;
- UI не должен скрывать разницу между draft и published.

### 5.3. API key scopes

UI вводит scope `deploy`, backend пока не отражает полноценную deploy-подсистему.

Решение:

- либо урезать scope-тексты;
- либо позже расширять platform access под реальный deploy scope.

### 5.4. Workspace switching

UI хранит current workspace в `localStorage`.

Решение:

- на ближайшем этапе оставить client-side current workspace;
- данные workspace брать с backend;
- позже заменить на session-aware current workspace model.

## 6. Порядок интеграции

### Wave 1

- `Operations catalog`
- `Wizard`

### Wave 2

- `Agents`
- `API Keys`

### Wave 3

- `Logs`
- `Usage`

### Wave 4

- `Workspace setup`
- частичный `Settings`

### Wave 5

- `Login`
- полноценный session/auth layer

## 7. Ближайший практический шаг

Следующий рабочий этап:

- реализовать frontend adapters для `Operations catalog` и `Wizard`;
- добить backend `PATCH/DELETE/archive` по operations;
- убрать `localStorage` overrides и mock `operations.json` для первых двух экранов.