a.tolmachev
485 lines
18 KiB
Markdown
485 lines
18 KiB
Markdown
# Alpine UI Integration Plan
|
||
|
||
Примечание:
|
||
|
||
- разделы, где машинный доступ UI описан через `platform-api-keys`, требуют обновления на модель `agent keys -> short-lived tokens`;
|
||
- источником истины по этой части следует считать `docs/agent-auth-model.md`, `docs/admin-api.md` и `docs/mcp-interface.md`.
|
||
|
||
## 1. Назначение документа
|
||
|
||
Этот документ фиксирует, как Alpine UI в `apps/ui` подключается к реальному backend.
|
||
|
||
Его задача:
|
||
|
||
- разложить UI по страницам;
|
||
- показать, что уже поддержано текущим backend;
|
||
- зафиксировать отсутствующие endpoint-ы и контрактные разрывы;
|
||
- определить порядок интеграции без хаотичных правок.
|
||
|
||
## 2. Текущее состояние
|
||
|
||
Сейчас `apps/ui` уже является основной Alpine.js UI-кодовой базой.
|
||
|
||
Важно:
|
||
|
||
- `apps/ui` является единственной рабочей UI-кодовой базой;
|
||
- новый 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`
|
||
|
||
Что еще не хватает:
|
||
|
||
- дальнейший UX polish вокруг gRPC discovery, потому что server reflection сознательно заменен на descriptor-driven live flow;
|
||
- возможные smoke tests для `wizard`, чтобы закрепить уже подключенный live contract.
|
||
|
||
Что убрать из UI после интеграции:
|
||
|
||
- `sessionStorage`-передачу `wizard_edit`
|
||
- draft-overrides через `localStorage`
|
||
- локальное создание operation без backend
|
||
|
||
Простой итог:
|
||
|
||
- wizard почти готов для реального backend;
|
||
- текущий workspace для wizard уже приходит из auth session, а не только из client-side `localStorage`;
|
||
- это основной экран второй очереди после 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`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish`
|
||
- `POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive`
|
||
- `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/unpublish/archive работают через backend;
|
||
- `GET /agents` уже отдает `calls_today`, `key_count`, `operation_count`, `operation_ids` и `mcp_endpoint`;
|
||
- следующий реальный разрыв здесь уже не в CRUD, а в richer version lifecycle поверх этих состояний.
|
||
|
||
### 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}`
|
||
|
||
Что еще не хватает:
|
||
|
||
- если захотим richer UX, можно добавить server-side pagination и фильтрацию по статусу.
|
||
|
||
Отдельный конфликт:
|
||
|
||
- одноразовый `secret` доступен только в create-response, а list endpoint возвращает только metadata;
|
||
- это уже совпадает с backend, но UX нельзя случайно перевести в режим “показывать ключ повторно”.
|
||
|
||
Простой итог:
|
||
|
||
- страница уже сажается на текущий backend без новых ручек;
|
||
- live `list/create/revoke/delete` можно считать закрытым;
|
||
- `last_used_at` теперь обновляется через успешную machine-auth аутентификацию в `mcp-server`;
|
||
- следующий реальный шаг здесь только в polishing вокруг audit trail и richer filtering.
|
||
|
||
### 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`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}/members/{user_id}`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/members/{user_id}`
|
||
- `GET /api/admin/workspaces/{workspace_id}/invitations`
|
||
- `POST /api/admin/workspaces/{workspace_id}/invitations`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}/invitations/{invitation_id}`
|
||
- `GET /api/admin/workspaces/{workspace_id}/export`
|
||
- `DELETE /api/admin/workspaces/{workspace_id}`
|
||
|
||
Что еще не хватает:
|
||
|
||
- finer-grained permission matrix beyond current `owner/admin` management rules.
|
||
|
||
Отдельный конфликт:
|
||
|
||
- memberships, role-management и invitations уже live;
|
||
- `settings` page не должна дублировать этот flow, пока у нее нет своего backend-контракта
|
||
|
||
Простой итог:
|
||
|
||
- `workspace-setup` уже подключен к live backend;
|
||
- create/edit workspace, memberships, invitations, export и delete работают;
|
||
- текущий workspace уже синхронизируется через auth session и используется всеми live страницами.
|
||
|
||
### 4.8. Settings
|
||
|
||
UI-файлы:
|
||
|
||
- `apps/ui/html/settings.html`
|
||
- `apps/ui/js/settings.js`
|
||
|
||
Что UI хочет:
|
||
|
||
- профиль пользователя;
|
||
- security/preferences;
|
||
- workspace settings;
|
||
- language switcher.
|
||
|
||
Что уже можно подключить:
|
||
|
||
- `GET /api/auth/session`
|
||
- `GET /api/auth/profile`
|
||
- `PATCH /api/auth/profile`
|
||
- `POST /api/auth/current-workspace`
|
||
- `POST /api/auth/password`
|
||
- workspace block через `GET /api/admin/workspaces/{workspace_id}`
|
||
- `PATCH /api/admin/workspaces/{workspace_id}`
|
||
|
||
Что еще не хватает:
|
||
|
||
- preferences endpoint;
|
||
- полноценный advanced security model (`2FA`, passkeys, session inventory).
|
||
|
||
Отдельный конфликт:
|
||
|
||
- UI исторически притворялся, что `2FA`, passkeys и active sessions уже реализованы;
|
||
- backend пока дает только live `profile` и `password change`, без advanced security lifecycle;
|
||
- поэтому страница должна честно разделять:
|
||
- live `profile`;
|
||
- live `password change`;
|
||
- read-only/security roadmap блоки без fake data.
|
||
|
||
Простой итог:
|
||
|
||
- workspace block уже live;
|
||
- profile и password change уже live;
|
||
- notifications остаются локальным placeholder;
|
||
- страницу теперь можно считать частично интегрированной без ложных mock-сценариев.
|
||
|
||
### 4.9. Login
|
||
|
||
UI-файлы:
|
||
|
||
- `apps/ui/html/login.html`
|
||
- `apps/ui/js/login.js`
|
||
|
||
Что UI хочет:
|
||
|
||
- app-level sign in;
|
||
- mock SSO button;
|
||
- user session.
|
||
|
||
Что уже есть реально:
|
||
|
||
- login screen и mock redirect flow
|
||
|
||
Что уже есть:
|
||
|
||
- session auth backend;
|
||
- `POST /api/auth/login`;
|
||
- `POST /api/auth/logout`;
|
||
- `GET /api/auth/session`;
|
||
- protected page guard через backend session.
|
||
|
||
Простой итог:
|
||
|
||
- login уже перешел на live backend flow;
|
||
- защищенные страницы проверяют server-side session;
|
||
- `localStorage` больше не должен быть source of truth для auth.
|
||
|
||
## 5. Отдельные UI-vs-backend конфликты
|
||
|
||
### 5.1. Login vs Basic Auth
|
||
|
||
Конфликт закрыт. UI использует встроенный login, backend перешел на app-level session auth.
|
||
|
||
Решение:
|
||
|
||
- использовать `POST /api/auth/login`, `POST /api/auth/logout`, `GET /api/auth/session`;
|
||
- хранить auth state в `HttpOnly` cookie;
|
||
- использовать `localStorage` только как UI mirror для display state и не считать его source of truth.
|
||
|
||
### 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 в auth session и использует `localStorage` только как cache/fallback.
|
||
|
||
Решение:
|
||
|
||
- backend хранит `current_workspace_id` в user session;
|
||
- `POST /api/auth/current-workspace` переключает активный workspace;
|
||
- клиент использует `localStorage` только как cache/fallback для shell state.
|
||
|
||
## 6. Порядок интеграции
|
||
|
||
### Wave 1
|
||
|
||
- `Operations catalog` — completed
|
||
- `Wizard` — completed
|
||
|
||
### Wave 2
|
||
|
||
- `Agents` — completed
|
||
- `API Keys` — completed
|
||
|
||
### Wave 3
|
||
|
||
- `Logs` — completed
|
||
- `Usage` — completed
|
||
|
||
### Wave 4
|
||
|
||
- `Workspace setup` — completed
|
||
- частичный `Settings` — completed
|
||
|
||
### Wave 5
|
||
|
||
- `Login` — completed
|
||
- полноценный session/auth layer — completed
|
||
|
||
## 7. Ближайший практический шаг
|
||
|
||
Следующий рабочий этап:
|
||
|
||
- добить live `Settings` без заглушек для profile/security;
|
||
- закрыть `workspace access` lifecycle (`roles`, `member removal`, `delete/export workspace`);
|
||
- пройти stabilization pass по Alpine UI и убрать оставшиеся client-side fallback patterns.
|