docs: define backend gap plan for target ui

2026-03-29 21:15:01 +03:00
parent 2219d1249b
commit c78b949050
3 changed files with 350 additions and 6 deletions
@@ -30,6 +30,7 @@ Crank - платформа для публикации внешних API в в

 - `docs/architecture.md` - целевая архитектура системы.
 - `docs/as-is-to-be.md` - переход `as is -> to be`, page-by-page gap analysis и архитектурные конфликты.
+- `docs/backend-gap-plan.md` - конкретный backend-план: сущности, API, БД и порядок реализации.
 - `docs/module-decomposition.md` - декомпозиция crates и модулей.
 - `docs/data-model.md` - целевая модель данных.
 - `docs/database-schema.md` - целевая схема БД.
@@ -2,23 +2,23 @@

 ## Current

-### `feat/as-is-to-be-docs`
+### `feat/backend-gap-plan`

 Status: completed

 DoD:

- `as is -> to be` зафиксирован в документации
- разобраны page-by-page backend gaps для `test-ui`
- workspace/agent/access/observability модель синхронизирована в архитектурных документах
+- page-by-page backend gaps переведены в конкретный plan of work
+- определены новые сущности, таблицы, API-группы и MCP changes
+- зафиксирован порядок реализации по волнам

 ## Next

- `feat/backend-gap-plan`
+- `feat/operations-workspace-contracts`

 ## Backlog

- `feat/backend-gap-plan`
+- `feat/operations-workspace-contracts`
 - `feat/workspace-foundation`
 - `feat/agent-publishing`
 - `feat/platform-access`
@@ -0,0 +1,343 @@
+# Backend Gap Plan
+
+## 1. Назначение документа
+
+Этот документ превращает `test-ui` и `docs/as-is-to-be.md` в конкретный backend-план.
+
+Его задача:
+
+- зафиксировать, чего именно не хватает в backend;
+- разделить доработки на новые сущности, новые API и изменения существующего ядра;
+- определить порядок реализации без расползания scope.
+
+## 2. Принципы
+
+- текущее ядро `Operation + adapters + runtime` сохраняется;
+- новая функциональность наращивается слоями сверху;
+- сначала вводятся tenant boundary и agent publishing;
+- потом access layer и observability;
+- перенос `test-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
+- перенести `test-ui` в `apps/ui`
+- пройти e2e сценарии
+
+## 11. Что делаем следующим шагом
+
+Следующий практический шаг:
+
+1. зафиксировать DTO и response shapes для `Operations` и `Wizard`;
+2. затем спроектировать `Workspace` и `Agent` storage/API;
+3. после этого начинать backend implementation wave 1.