docs: define alpine ui integration plan

2026-03-30 00:19:07 +03:00
parent 7070231c3e
commit 4721bc1948
2 changed files with 477 additions and 0 deletions
@@ -32,6 +32,7 @@ Crank - платформа для публикации внешних API в в
 - `docs/as-is-to-be.md` - переход `as is -> to be`, page-by-page gap analysis и архитектурные конфликты.
 - `docs/backend-gap-plan.md` - конкретный backend-план: сущности, API, БД и порядок реализации.
 - `docs/operations-workspace-contracts.md` - точные `workspace-scoped` контракты для экранов `Operations` и `Wizard`.
+- `docs/alpine-ui-integration-plan.md` - постраничный план подключения нового Alpine UI к реальному backend.
 - `docs/module-decomposition.md` - декомпозиция crates и модулей.
 - `docs/data-model.md` - целевая модель данных.
 - `docs/database-schema.md` - целевая схема БД.
@@ -0,0 +1,476 @@
+# 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`
+- server-side shape для list response с готовыми agent bindings и компактными summary fields
+
+Что убрать из UI после интеграции:
+
+- `crank_ops_overrides` в `localStorage`
+- merge поверх `data/operations.json`
+- локальный tombstone/delete flow
+
+Простой итог:
+
+- эту страницу можно интегрировать первой;
+- базовые list/fetch данные backend уже умеет;
+- надо только добить update/delete/archive и перестать хранить изменения в браузере.
+
+### 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}`
+- `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}/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`
+
+Что еще не хватает:
+
+- `PATCH /api/admin/workspaces/{workspace_id}/operations/{operation_id}` для edit mode
+- `POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive`
+- единая DTO-форма для create/edit, чтобы UI не собирал разные payload вручную по шагам
+
+Что убрать из UI после интеграции:
+
+- `sessionStorage`-передачу `wizard_edit`
+- draft-overrides через `localStorage`
+- локальное создание operation без backend
+
+Простой итог:
+
+- wizard почти готов для реального backend;
+- это основной экран второй очереди после catalog;
+- ключевой разрыв сейчас только в полноценном edit/update контракте.
+
+### 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}`
+- `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`
+
+Что еще не хватает:
+
+- `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}/versions`
+- `DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}`
+- более богатый `GET /agents` response:
+  - `calls_today`
+  - `key_count`
+  - `operation_count`
+  - `mcp_endpoint`
+
+Отдельный конфликт:
+
+- UI считает, что агент можно редактировать прямо как рабочую сущность;
+- backend пока ближе к publish-модели с version snapshot;
+- нужно решить, edit агента мутирует draft напрямую или всегда создает новую version.
+
+Простой итог:
+
+- база для agents уже есть;
+- но UI требует более полного lifecycle, чем backend поддерживает сейчас.
+
+### 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}`
+
+Что еще не хватает:
+
+- финальная договоренность по scope model;
+- согласование response shape с UI:
+  - `secret`
+  - `prefix`
+  - `status`
+  - `last_used_at`
+
+Отдельный конфликт:
+
+- UI сейчас обещает scope `deploy` и формулировки про rollback/deployments;
+- backend этого продуктово не поддерживает;
+- scope-тексты надо выровнять до интеграции.
+
+Простой итог:
+
+- эта страница почти закрывается текущим backend;
+- здесь нужен не новый слой, а выравнивание payload и текстов.
+
+### 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}`
+
+Что еще не хватает:
+
+- frontend adapter с трансформацией backend response в текущую log-row форму;
+- polling strategy вместо локального seeded массива;
+- явная поддержка `debug/info/warn/error` в UI без локального seed;
+- если нужен live mode, то либо polling, либо отдельный future streaming endpoint
+
+Простой итог:
+
+- backend foundation для logs уже есть;
+- страница интегрируется быстро, если заменить seeded `LOGS` на API 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}`
+
+Что еще не хватает:
+
+- frontend mapping из backend `summary/timeline/operations/agents` в текущие widgets;
+- `CSV export` endpoint или серверная договоренность, если экспорт не хотим делать на клиенте;
+- согласование полей latency percentiles в одном формате
+
+Простой итог:
+
+- usage page можно подключать сразу после logs;
+- главная работа здесь на frontend adapter, а не на новом backend-ядре.
+
+### 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` для первых двух экранов.