bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3065b3100b308009948b3e2286cffdec97a50702
crank/docs/alpine-ui-integration-plan.md
T
a.tolmachev 44363c0b1c feat: connect settings live flow to auth api
2026-03-31 02:21:31 +03:00

18 KiB
Raw Blame History

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

Что еще не хватает:

  • server-side current workspace model вместо client-side localStorage;
  • дальнейший 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;
  • это основной экран второй очереди после 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 все еще живет на клиенте, а не в session/backend;
  • endpoint на удаление участника или изменение роли, если UI хочет это поддерживать;
  • delete/export workspace lifecycle пока не реализован на backend

Отдельный конфликт:

  • current workspace по-прежнему client-side;
  • memberships и invitations уже live, но role-management пока read-only;
  • settings page не должна дублировать этот flow, пока у нее нет своего backend-контракта

Простой итог:

  • workspace-setup уже подключен к live backend;
  • create/edit workspace, refresh списка workspace и invitations работают;
  • role management и workspace deletion остаются отдельным следующим этапом.

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/password
  • workspace block через GET /api/admin/workspaces/{workspace_id}
  • PATCH /api/admin/workspaces/{workspace_id}

Что еще не хватает:

  • preferences endpoint;
  • полноценный advanced security model (2FA, passkeys, session inventory);
  • session-aware current workspace model вместо client-side localStorage.

Отдельный конфликт:

  • 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 в localStorage.

Решение:

  • на ближайшем этапе оставить client-side current workspace;
  • данные workspace брать с backend;
  • позже заменить на session-aware current workspace model.

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