docs: redesign architecture around workspaces and agents

docs/as-is-to-be.md

@@ -0,0 +1,264 @@
+# As Is -> To Be
+
+## 1. Назначение документа
+
+Этот документ фиксирует переход от текущего состояния проекта к целевой продуктовой модели, которую задает `test-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.
+
+Что уже есть:
+
+- внешний `Basic Auth` на уровне `nginx`.
+
+Чего не хватает:
+
+- либо собственный auth/session backend;
+- либо временный согласованный bridge, если login screen оставляем как demo flow.
+
+## 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
+
+Решение:
+
+- зафиксировать временную и целевую auth model отдельно.
+
+## 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.