a.tolmachev
473 lines
17 KiB
Markdown
473 lines
17 KiB
Markdown
# 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` для первых двух экранов.
|