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.