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.