crank/docs/implementation-plan.md

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

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

Этот документ фиксирует актуальный порядок подготовки Crank к коммерческой реализации как open-core продукта.

Документ не повторяет уже выполненные исторические этапы. Он описывает только тот план, по которому проект должен двигаться дальше.

2. Базовый принцип

Работа делится на два контура:

1. завершение и hardening открытой редакции Community;
2. подготовка архитектурных, продуктовых и delivery-границ для Enterprise и Cloud.

Принцип:

• сначала нужно сделать честную и законченную Community-основу;
• затем нужно отделить commercial seams и private delivery;
• только после этого имеет смысл реализовывать коммерческие расширения.

3. Этап 1. Open-core product boundary

Цель

Зафиксировать, что входит в Community, а что уходит в Enterprise и Cloud.

DoD

• документы product-editions, commercial-boundaries, architecture, module-decomposition синхронизированы;
• в кодовой базе определена capability model по редакциям;
• UI и API не обещают Community-функции, которых там не должно быть;
• старые review-файлы не требуются как отдельный источник истины.
• canonical Community deployment manifest и env template вынесены в deploy/community/*;
• public CI/CD delivery path использует именно deploy/community/* как source of truth для Community поставки.

4. Этап 2. Community machine access completion

Цель

Довести базовую модель машинного доступа Community до полностью рабочего состояния.

DoD

• у AI-агента есть собственный ключ;
• UI умеет выпускать, показывать, отзывать и удалять agent keys;
• mcp-server использует agent-scoped machine access;
• Community поддерживает только security_level = standard;
• в системе не остается product-facing assumptions про workspace-wide machine key как основной способ вызова.

5. Этап 3. Edition capability model

Цель

Подготовить инфраструктуру, которая позволит одной кодовой базе честно различать редакции продукта.

DoD

• существует server-side capability model:
  • protocols
  • auth modes
  • security levels
  • workspace/user limits
• admin-api возвращает capability flags для UI;
• UI скрывает или честно блокирует premium functionality;
• Community build не содержит ложных "почти доступных" product paths.

6. Этап 4. Private auth-service seam

Цель

Подготовить публичный код к private реализации короткоживущих и одноразовых токенов.

DoD

• зафиксированы контракты для:
  • POST /mcp-auth/v1/token
  • POST /mcp-auth/v1/token/one-time
• в mcp-server существует abstraction для проверки токенов;
• admin-api и mcp-interface знают про эти контракты документированно;
• Community при этом остается полностью работоспособной без private token service.

7. Этап 5. Commercial protocol split

Цель

Перестать считать весь текущий protocol surface частью открытой редакции.

DoD

• определен canonical Community protocol set;
• premium protocol families и premium execution modes вынесены в коммерческий план;
• UI capability-gated по протоколам;
• release model для Community не требует shipping premium flow как рабочей open-source функции.

8. Этап 6. Frontend launch readiness

Цель

Довести UI до коммерчески пригодного состояния для Community и подготовить edition-aware product surface.

DoD

• agent key UX доведен до продукта;
• mobile layouts для data-heavy страниц больше не ломают primary actions;
• terminology и localization согласованы;
• settings и workspace flows не содержат misleading или half-functional sections;
• UI понимает разницу между Community и premium capabilities.

9. Этап 7. Enterprise access and governance

Цель

Реализовать коммерческий access/governance слой в private delivery.

DoD

• есть SSO;
• есть 2FA;
• есть расширенная RBAC;
• есть audit log;
• существует private delivery path для self-hosted customers.

10. Управленческий рубеж: физическое разделение репозиториев

Цель

Не начинать вынос private functionality хаотично, пока не завершены public seams и capability split.

Условие входа

К этому рубежу можно переходить только после того, как завершены:

• open-core product boundary;
• edition capability model;
• private auth-service seam;
• documentation sync по Community / Enterprise / Cloud.

Действие

На этом этапе нужно создать 3 целевых repositories:

• crank-community
• crank-enterprise
• crank-cloud

Результат

• crank-community становится public Community repository;
• crank-enterprise становится private self-hosted commercial repository;
• crank-cloud становится private hosted/control-plane repository;
• только после этого начинается физическое вынесение Community и коммерческого кода из текущего репозитория по новым delivery boundaries.

11. Этап 8. Cloud control plane

Цель

Подготовить hosted-редакцию как отдельный продуктовый контур.

DoD

• есть metering;
• есть billing integration;
• есть hosted tenant model;
• есть cloud deployment and support tooling;
• capability model синхронизирована с hosted plans.

12. Этап 9. Release and distribution hardening

Цель

Подготовить безопасную поставку открытой и коммерческой редакций.

DoD

• Community публикуется из crank-community;
• Enterprise поставляется через private container registry и private manifests;
• Cloud использует отдельный private operational contour;
• build provenance и подпись артефактов документированы;
• коммерческий код не требуется публиковать в public repository.

13. Этап 10. Optional cache and coordination layer

Цель

Подготовить optional cache/coordination layer так, чтобы платформа могла использовать Valkey/Redis, но не зависела от него для базового запуска.

DoD

• определены абстракции для cache/coordination state;
• Community может запускаться без внешнего cache store;
• Community deployment path умеет поднимать optional Valkey;
• Cloud использует shared cache layer как default managed runtime component;
• Enterprise может подключать свой Valkey/Redis на уровне single-node или cluster deployment.

14. Этап 11. Live staging and demo readiness

Цель

Поддерживать реальный стенд и демонстрационный сценарий в состоянии, пригодном для продажи и демонстрации.

DoD

• live authenticated staging pass воспроизводим;
• deploy smoke и operator docs совпадают с реальной поставкой;
• demo user flow подтвержден на реальном окружении;
• регрессии в publish/call/auth flow ловятся до релиза.

15. Связанные документы

• docs/product-editions.md
• docs/commercial-boundaries.md
• docs/community-release-checklist.md
• docs/repository-split-map.md
• docs/frontend-roadmap.md
• docs/refactoring-roadmap.md
• docs/agent-auth-model.md