crank/docs/implementation-plan.md

# План реализации

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

Этот документ фиксирует порядок перехода от текущего состояния проекта к целевой product-ready integration platform модели.

Принцип:

- сначала перепроектирование `as is -> to be`;
- потом foundation под workspace/agent model;
- потом возврат к end-to-end UI сценариям;
- потом observability и access layer;
- потом polish и demo readiness;
- потом расширение до полного protocol platform scope.

## 2. Этап 1. Перепроектирование `As Is -> To Be`

Цель:

- зафиксировать новую доменную модель и page-driven backend contract.

DoD:

- зафиксирован `as is -> to be` план;
- page-by-page gap analysis покрывает все целевые экраны;
- разобраны все архитектурные конфликты UI vs current backend;
- документы `architecture`, `data-model`, `database-schema`, `admin-api`, `mcp-interface` синхронизированы.

## 3. Этап 2. Workspace foundation

Цель:

- перевести хранение и API на workspace-scoped модель.

DoD:

- операции и auth profiles принадлежат workspace;
- registry умеет фильтровать данные по workspace;
- есть default workspace migration path.

## 4. Этап 3. Agent publishing foundation

Цель:

- ввести `Agent` и agent-scoped MCP publishing.

DoD:

- можно создать agent и привязать к нему published operations;
- `mcp-server` выдает tools в контексте конкретного agent;
- один agent видит только свой curated toolset.

## 5. Этап 4. Operations and wizard integration

Цель:

- посадить operations catalog и wizard на реальные backend contracts.

DoD:

- каталог операций и wizard работают без `localStorage` overrides;
- operation edit/delete/publish/test выполняются через backend;
- все протоколы работают в рамках одного UI flow.

## 6. Этап 5. Agents UI and backend

Цель:

- реализовать agent-centric слой.

DoD:

- agent CRUD работает;
- binding operations к agent работает;
- published agent появляется в MCP runtime.

## 7. Этап 6. Agent-scoped machine access

Цель:

- реализовать machine access на уровне AI-агента и ввести обязательный уровень защиты операции.

DoD:

- UI умеет выпускать и отзывать ключи конкретного AI-агента;
- длинноживущий машинный доступ больше не описывается ключом рабочей области;
- у операции появляется обязательный `security_level`;
- machine access не смешивается с upstream auth profiles;
- Community поддерживает базовый режим со статическим ключом AI-агента.

## 8. Этап 7. Token exchange and short-lived auth

Цель:

- внедрить расширенные режимы доступа для операций повышенной чувствительности.

DoD:

- существует конечная точка выдачи токена по ключу агента;
- есть модель одноразового токена для чувствительных вызовов;
- токены ограничены по сроку жизни, области действия и числу использований;
- операции уровня `elevated` нельзя вызвать по статическому ключу;
- операции уровня `strict` можно вызвать только по одноразовому токену.

## 9. Этап 8. Observability

Цель:

- реализовать логи и usage.

DoD:

- `Logs` page и `Usage` page работают на реальных данных;
- есть продуктовые endpoints, а не только application logs;
- rollups и detail views согласованы с UI.

## 10. Этап 9. Alpine UI integration

Цель:

- довести `apps/ui` до полной работы на реальном backend.

DoD:

- `apps/ui` содержит целевой Alpine.js UI;
- mock JSON больше не используется на критическом пути;
- UI, backend и docs синхронизированы.

## 11. Этап 10. Secret store and upstream auth

Цель:

- заменить UI placeholder-модель `${secrets.*}` на рабочий backend/runtime слой secrets.

DoD:

- есть workspace-scoped `Secrets` resource;
- secret values хранятся только в зашифрованном виде;
- `AuthProfile` ссылается на `secret_id`, а не на строковый placeholder;
- runtime умеет применять bearer/basic/api-key auth к реальному upstream request;
- wizard имеет auth selector и quick-create flow для secrets/auth profiles.

## 12. Этап 11. Hardening and demo readiness

Цель:

- довести продукт до стабильного демо-сценария.

DoD:

- end-to-end demo воспроизводим;
- deployment и healthchecks стабильно зелёные;
- документация и продуктовый сценарий совпадают.

## 13. Этап 12. MCP streaming proxy support

Цель:

- довести Crank до controlled streaming model поверх MCP `Streamable HTTP`.

DoD:

- `mcp-server` соответствует transport semantics `2025-06-18`;
- execution modes `window`, `session`, `async_job` формально описаны и реализованы;
- REST SSE и gRPC server-streaming поддерживаются в bounded форме;
- UI умеет конфигурировать streaming limits, aggregation и lifecycle;
- e2e сценарии покрывают window/session/job calls.

## 14. Этап 13. WebSocket upstream support

Цель:

- добавить полноценный WebSocket upstream adapter в общую execution model.

DoD:

- есть WebSocket target model;
- runtime поддерживает bounded `window`, `session` и `async_job`;
- heartbeat, reconnect и subscription lifecycle конфигурируются явно;
- docs, UI и e2e синхронизированы.

## 15. Этап 14. SOAP support

Цель:

- добавить SOAP как enterprise-oriented protocol family.

DoD:

- есть WSDL/XSD-driven target model;
- runtime умеет строить SOAP envelopes и нормализовать SOAP Faults;
- operator может выбрать service, port и operation;
- test-run, publish и observability работают так же, как для остальных протоколов.

## 16. Этап 15. Detailed streaming specs

Цель:

- довести streaming-docs до function-level и field-level design спецификации.

DoD:

- есть отдельные docs для streaming admin-api, runtime, UI и capability matrix;
- protocol docs не противоречат общей execution model;
- roadmap и `TASKS.md` синхронизированы с full-detail architecture.

## 17. Этап 16. Streaming implementation slices

Цель:

- перевести streaming design в agent-friendly execution plan по файлам, тестам и DoD.

DoD:

- есть отдельный implementation spec по всем streaming slices;
- указаны file-level changes;
- указаны обязательные тесты и acceptance criteria;
- state transitions и sequence outlines зафиксированы явно.