diff --git a/README.md b/README.md index 06d0dae..7bf1314 100644 --- a/README.md +++ b/README.md @@ -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` - целевая схема БД. diff --git a/TASKS.md b/TASKS.md index 34298d1..c5ba907 100644 --- a/TASKS.md +++ b/TASKS.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` diff --git a/docs/backend-gap-plan.md b/docs/backend-gap-plan.md new file mode 100644 index 0000000..1083d3d --- /dev/null +++ b/docs/backend-gap-plan.md @@ -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.