crank/docs/backend-gap-plan.md

# Backend Gap Plan

Примечание:

- пункты этого плана, относящиеся к `PlatformApiKey` как основной машинной модели доступа, рассматриваются как переходные;
- актуальная целевая схема машинной аутентификации описана в `docs/agent-auth-model.md`.

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

Этот документ превращает целевой Alpine UI и `docs/as-is-to-be.md` в конкретный backend-план.

Его задача:

- зафиксировать, чего именно не хватает в backend;
- разделить доработки на новые сущности, новые API и изменения существующего ядра;
- определить порядок реализации без расползания scope.

## 2. Принципы

- текущее ядро `Operation + adapters + runtime` сохраняется;
- новая функциональность наращивается слоями сверху;
- сначала вводятся tenant boundary и agent publishing;
- потом access layer и observability;
- UI развивается в `apps/ui` после фиксации backend-контрактов.

## 3. Что сохраняем без переписывания

- `Operation` как базовый интеграционный контракт;
- versioning операций;
- adapters `REST / GraphQL / unary gRPC`;
- schema engine;
- mapping engine;
- YAML import/export для operations;
- test-run flow;
- `Streamable HTTP` transport.

## 4. Что меняется принципиально

### 4.1. Global model -> workspace-scoped model

Нужно добавить `workspace_id` в:

- `operations`
- `auth_profiles`
- published runtime views
- будущие logs и usage

### 4.2. Operation publishing -> agent publishing

Нужно перестроить MCP publishing:

- было: published operation = MCP tool
- будет: published operation = reusable building block
- MCP endpoint публикует published bindings внутри конкретного agent

### 4.3. Upstream auth -> platform access separation

Нужно разделить:

- `AuthProfile` для внешних API;
- `PlatformApiKey` для доступа к Crank.

### 4.4. Application logs -> product observability

Нужно ввести:

- `InvocationLog`
- `UsageRollup`

## 5. Page-by-page backend plan

## 5.1. Operations page

### Уже есть

- `GET /operations`
- `POST /operations`
- `GET /operations/{id}`
- `POST /operations/{id}/versions`
- `POST /operations/{id}/publish`
- `POST /operations/{id}/test-runs`
- import/export

### Не хватает

- `PATCH /operations/{id}`
- `DELETE /operations/{id}`
- `POST /operations/{id}/archive`
- workspace scoping
- summary metrics для карточек
- фильтр/lookup по agent bindings

### Backend changes

- добавить update/delete/archive use case;
- добавить `workspace_id` в operation queries;
- добавить lightweight stats response для operations list.

## 5.2. Wizard page

### Уже есть

- create operation
- create version
- samples
- draft generation
- test run
- gRPC descriptor flow

### Не хватает

- единый update contract для edit mode;
- стабильный draft-save contract;
- workspace-scoped endpoints;
- final DTO shape под новый Alpine wizard.

### Backend changes

- нормализовать create/update/version payload;
- добавить `PATCH /operations/{id}`;
- оставить `POST /versions` как explicit publishable snapshot flow.

## 5.3. Agents page

### Уже есть

- ничего

### Не хватает

- `Agent`
- `AgentVersion`
- `AgentOperationBinding`
- `published_agents`
- MCP metadata per agent

### Backend changes

- CRUD agents;
- publish agent;
- bind/unbind operations;
- list agent operations;
- agent-scoped tool catalog in MCP.

## 5.4. API Keys page

### Уже есть

- upstream `auth_profiles`, но это другая сущность

### Не хватает

- `PlatformApiKey`
- scopes model
- one-time reveal on create
- revoke/delete

### Backend changes

- новая таблица и новый service;
- hash secret вместо хранения в открытом виде;
- endpoint create/list/revoke/delete;
- timestamp `last_used_at`.

## 5.5. Logs page

### Уже есть

- только application logs

### Не хватает

- список invocation logs
- log detail
- фильтры
- live refresh strategy

### Backend changes

- логирование каждого tool call;
- storage для invocation logs;
- list/detail API;
- query params: level, operation, agent, range, search.

## 5.6. Usage page

### Уже есть

- ничего как продуктовый API

### Не хватает

- aggregates
- per-agent breakdown
- per-operation breakdown
- CSV export

### Backend changes

- `UsageRollup`;
- background aggregation или on-write update strategy;
- reporting endpoints;
- CSV export endpoint.

## 5.7. Workspace and Settings

### Уже есть

- ничего

### Не хватает

- `Workspace`
- `User`
- `Membership`
- `Invitation`
- settings model

### Backend changes

- workspace CRUD;
- members list;
- invitations;
- current workspace settings read/update.

## 5.8. Login

### Уже есть

- только внешний `Basic Auth` на `nginx`

### Не хватает

- app-level auth model

### Решение на ближайший этап

- пока не строить full auth subsystem;
- сначала сделать workspace/access model и platform API keys;
- login page оставить как отдельный вопрос после backend foundation.

## 6. Новые доменные сущности

Нужно добавить:

- `Workspace`
- `User`
- `Membership`
- `Invitation`
- `Agent`
- `AgentVersion`
- `AgentOperationBinding`
- `PlatformApiKey`
- `InvocationLog`
- `UsageRollup`

## 7. Новые таблицы

Нужно добавить:

- `workspaces`
- `users`
- `memberships`
- `invitation_tokens`
- `agents`
- `agent_versions`
- `agent_operation_bindings`
- `published_agents`
- `platform_api_keys`
- `invocation_logs`
- `usage_rollups`

Нужно изменить:

- `operations`
- `auth_profiles`
- `published_operations`

## 8. Новые admin-api группы

Нужно добавить группы:

- `workspaces`
- `memberships`
- `invitations`
- `agents`
- `platform-api-keys`
- `logs`
- `usage`

Нужно расширить:

- `operations`
- `auth-profiles`

## 9. MCP-server изменения

Нужно изменить:

- routing model: `/mcp/v1/{workspace_slug}/{agent_slug}`
- runtime catalog source: `published_agents`, а не глобальные operations
- tool resolution через binding
- labels для logs и usage: `workspace`, `agent`, `operation`

## 10. Порядок реализации

### Wave 1. Foundation

- `Workspace`
- workspace scope в operations/auth profiles
- `PATCH/DELETE/ARCHIVE` для operations
- update contracts для wizard

### Wave 2. Agent publishing

- `Agent`
- `AgentVersion`
- bindings
- published agents
- MCP server v2

### Wave 3. Platform access

- `PlatformApiKey`
- memberships
- invitations
- workspace settings

### Wave 4. Observability

- invocation logs
- usage rollups
- logs API
- usage API

### Wave 5. UI integration

- заменить mock data реальными API
- развивать и полировать Alpine UI в `apps/ui`
- пройти e2e сценарии

## 11. Что делаем следующим шагом

Следующий практический шаг:

1. зафиксировать DTO и response shapes для `Operations` и `Wizard`;
2. затем спроектировать `Workspace` и `Agent` storage/API;
3. после этого начинать backend implementation wave 1.