crank/docs/as-is-to-be.md

As Is -> To Be

Примечание:

• разделы этого документа, где машинный доступ описан через workspace-scoped platform API keys, следует считать устаревшими;
• целевая модель проекта переведена на AgentKey, короткоживущие токены доступа и при необходимости PlatformClientCredential;
• подробности переноса зафиксированы в docs/agent-auth-model.md.

1. Назначение документа

Этот документ фиксирует переход от текущего состояния проекта к целевой продуктовой модели, отраженной в текущем Alpine UI.

2. As Is

Сейчас проект умеет:

• хранить и версионировать Operation;
• выполнять REST, GraphQL, unary gRPC;
• выполнять test run;
• публиковать operations в MCP;
• импортировать и экспортировать operation-конфигурации;
• загружать samples и gRPC descriptors.

Сейчас проект не умеет как first-class product features:

• Workspace
• Agent
• platform API keys
• members / invitations
• logs API
• usage API
• agent-scoped MCP toolsets

3. To Be

Целевая система должна работать так:

• каждая команда работает в своем Workspace;
• операции создаются и тестируются внутри workspace;
• опубликованные операции привязываются к Agent;
• один Agent отдает LLM ограниченный набор tools;
• доступ к платформе контролируется через memberships и platform API keys;
• все вызовы попадают в logs и usage.

4. Page-by-page gap analysis

4.1. Operations

Что хочет UI:

• список операций;
• фильтры;
• edit/delete;
• publish/archive;
• верхние метрики;
• фильтр по agent.

Что уже есть:

• list/create/version/publish/test/export/import;
• samples и draft generation.

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

• delete operation;
• archive operation;
• usage summary для карточек;
• связь operation с agent;
• workspace scoping.

4.2. Wizard

Что хочет UI:

• create/edit operation;
• сохранить draft;
• тестировать и потом публиковать;
• работать с REST / GraphQL / gRPC;
• descriptors и schema-driven setup.

Что уже есть:

• почти весь operation lifecycle;
• samples;
• draft generation;
• gRPC descriptor workflow.

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

• нормальный update flow без local storage;
• workspace-scoped endpoints;
• единый backend contract под final wizard shape.

4.3. Agents

Что хочет UI:

• каталог агентов;
• create/edit agent;
• выбрать список operations;
• получить MCP endpoint агента.

Что уже есть:

• ничего как отдельный product layer.

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

• сущность Agent;
• AgentVersion;
• AgentOperationBinding;
• publish agent;
• agent-scoped MCP runtime.

4.4. API Keys

Что хочет UI:

• list/create/revoke/delete platform API keys;
• scopes;
• one-time reveal.

Что уже есть:

• только upstream auth_profiles.

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

• отдельная сущность PlatformApiKey;
• hashing/secrets;
• scopes model;
• endpoints и audit.

4.5. Logs

Что хочет UI:

• список логов;
• detail view;
• filters;
• live mode.

Что уже есть:

• только application logging.

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

• продуктовая сущность InvocationLog;
• storage;
• list/detail API;
• polling/live refresh strategy.

4.6. Usage

Что хочет UI:

• usage dashboard;
• p50/p95/p99;
• error rate;
• per-operation breakdown;
• CSV export.

Что уже есть:

• продуктового usage слоя нет.

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

• UsageRollup;
• aggregation jobs;
• reporting API;
• export endpoint.

4.7. Workspace / Settings

Что хочет UI:

• create/edit workspace;
• members and invitations;
• settings.

Что уже есть:

• ничего как backend model.

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

• Workspace;
• User;
• Membership;
• Invitation;
• workspace-scoped routing.

4.8. Login

Что хочет UI:

• platform sign-in flow.

Что уже есть:

• mock login.html и login.js;
• User, Membership, Invitation и PlatformApiKey как часть access layer.

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

• app-level auth/session backend;
• password hash storage;
• session cookie;
• current user endpoint.

5. Архитектурные конфликты, которые нужно разобрать отдельно

Конфликт 1. Global operations vs workspace model

Решение:

• ввести workspace_id во все продуктовые сущности.

Конфликт 2. Published operations vs agents

Решение:

• MCP публикует tools не напрямую из operations, а из published agent.

Конфликт 3. Upstream auth vs platform API keys

Решение:

• оставить AuthProfile только для upstream;
• ввести отдельную сущность PlatformApiKey.

Конфликт 4. Application logs vs product logs

Решение:

• ввести InvocationLog и UsageRollup.

Конфликт 5. Basic Auth vs login page

Решение:

• убрать внешний Basic Auth как основной способ входа;
• реализовать app-level auth/session backend;
• отделить browser session auth от PlatformApiKey.

Статус:

• закрыто в feat/auth-foundation.

6. Приоритет реализации

Wave 1

• Workspace foundation
• Operations + Wizard integration
• Agents
• Agent-scoped MCP

Wave 2

• Platform API keys
• Logs
• Usage

Wave 3

• Members / invitations
• Login / session layer

7. Короткий итог

Целевой UI не требует выбросить текущее ядро. Он требует добавить сверху:

• tenant layer;
• curated agent layer;
• observability layer;
• platform access layer.