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 зафиксированы явно.