github-ops
229 lines
11 KiB
Markdown
229 lines
11 KiB
Markdown
# План реализации
|
||
|
||
## 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 поставки.
|
||
- `crank-runtime` уже имеет feature seams для premium protocol adapters, так что Community base можно собирать как `REST-only` runtime foundation.
|
||
|
||
## 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. Разделение репозиториев
|
||
|
||
### Цель
|
||
|
||
Вести развитие продукта уже в трех отдельных repositories без возврата к модели общего source of truth.
|
||
|
||
### Текущий статус
|
||
|
||
Разделение репозиториев уже выполнено:
|
||
|
||
- `crank-community` — public Community repository;
|
||
- `crank-enterprise` — private self-hosted commercial repository;
|
||
- `crank-cloud` — private hosted/control-plane repository.
|
||
|
||
### Следствие
|
||
|
||
Дальнейшая работа строится так:
|
||
|
||
1. общие open-core улучшения сначала оформляются в `crank-community`;
|
||
2. затем тот же change set переносится в `crank-enterprise`;
|
||
3. затем переносится в `crank-cloud`;
|
||
4. cleanup и ограничение Community выполняются только в `crank-community`.
|
||
|
||
### Результат
|
||
|
||
- `crank-community` остается source base для общей открытой логики;
|
||
- private repositories держат только свой delta и коммерческие расширения;
|
||
- старый общий репозиторий больше не рассматривается как главный источник изменений.
|
||
|
||
## 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`,
|
||
но не зависела от него для базового запуска, и при этом закрыть первые коммерчески ценные cache hot paths.
|
||
|
||
### 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.
|
||
- cache namespaces документированы так, чтобы:
|
||
- platform / coordination state не смешивался с response cache;
|
||
- response cache по умолчанию изолировался по `workspace + agent + operation + operation version + request fingerprint`;
|
||
- внешний cache backend можно было безопасно шарить между несколькими рабочими областями и агентами.
|
||
- shared coordination cache уже применяется не только для rate limiting, но и для multi-instance snapshots published MCP catalogs.
|
||
- response cache уже покрывает:
|
||
- `REST GET` как Community baseline;
|
||
- `GraphQL query` как первый коммерчески ценный read-only protocol path.
|
||
- `gRPC unary` для явно read-only операций через `GrpcTarget.read_only`.
|
||
- дальнейшее расширение response cache идет только по отдельно обоснованным read-only сценариям, а не как общий cache для всех протоколов подряд.
|
||
|
||
## 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`
|