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. Live staging and demo readiness

### Цель

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

### DoD

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

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

- `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`