bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
17d9c4252182f92ac8dba416654306db95e4764d
crank/docs/alpine-ui-integration-plan.md
T
a.tolmachev 2d43db69c9 docs: align agent auth model and fix session test
2026-05-03 10:38:12 +00:00

18 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink