crank/docs/alpine-ui-integration-plan.md

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;
• дальше нужно убрать localStorage-состояние и посадить UI на реальные list/detail/mutation вызовы.

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;
• backend уже закрывает create/edit/archive/test/import/export, дальше нужен только аккуратный frontend adapter.

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 для первых двух экранов.