docs: consolidate product roadmap and source docs
This commit is contained in:
a.tolmachev
@@ -143,6 +143,8 @@ AI-агент не должен:
|
||||
- статический ключ AI-агента как режим совместимости;
|
||||
- короткоживущие токены по OAuth 2.0 как рекомендуемый режим.
|
||||
|
||||
Реализация этого режима должна рассматриваться как коммерческий контур и не должна требовать размещения private token-issuer logic в public repository.
|
||||
|
||||
Соответственно, платформа может обслуживать операции уровня:
|
||||
|
||||
- `standard`;
|
||||
@@ -156,6 +158,8 @@ AI-агент не должен:
|
||||
- короткоживущий токен;
|
||||
- одноразовый токен.
|
||||
|
||||
Enterprise-реализация должна поставляться через private delivery и опираться на capability-gated integrations в public codebase.
|
||||
|
||||
Соответственно, допускаются операции уровня:
|
||||
|
||||
- `standard`;
|
||||
|
||||
@@ -218,6 +218,28 @@ Crank - платформа для публикации внешних API в в
|
||||
- request headers
|
||||
- operation template
|
||||
- variables mapping
|
||||
|
||||
## 8. Open-core граница
|
||||
|
||||
Crank развивается как open-core продукт.
|
||||
|
||||
Это означает:
|
||||
|
||||
- `Community` должна полностью собираться из этого репозитория;
|
||||
- коммерческие возможности не должны храниться здесь как рабочий private code;
|
||||
- различия между редакциями должны отражаться в capability model, API, UI и delivery pipeline.
|
||||
|
||||
Ключевые продуктовые различия зафиксированы в `docs/product-editions.md`.
|
||||
|
||||
## 9. Коммерческий контур
|
||||
|
||||
Коммерческий контур не должен защищаться "скрытием" уже опубликованного исходного кода. Правильная архитектурная граница выглядит так:
|
||||
|
||||
- в public repo остается Community runtime и extension seams;
|
||||
- коммерческие реализации поставляются из private repositories или private artifacts;
|
||||
- критичные правила лицензирования, metering и token issuance исполняются на серверной стороне.
|
||||
|
||||
Практические правила зафиксированы в `docs/commercial-boundaries.md`.
|
||||
- извлечение результата из `data`
|
||||
|
||||
GraphQL в MCP публикуется как фиксированная операция с предсказуемой структурой ответа.
|
||||
|
||||
@@ -0,0 +1,196 @@
|
||||
# Границы open-core и защита коммерческого кода
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ определяет:
|
||||
|
||||
- как разделять открытый и коммерческий функционал;
|
||||
- какие части должны оставаться в публичном репозитории;
|
||||
- какие части должны выноситься в private delivery;
|
||||
- как защищать коммерческий код без ложной ставки на обфускацию и "антидекомпиляцию".
|
||||
|
||||
## 2. Базовый принцип
|
||||
|
||||
Коммерческий код нужно защищать не попытками спрятать уже опубликованный исходный код, а правильной границей поставки.
|
||||
|
||||
Принцип:
|
||||
|
||||
- открытый код остается действительно открытым;
|
||||
- коммерческий код не попадает в public repository;
|
||||
- коммерческие сервисы и модули поставляются из приватного контура;
|
||||
- критичные правила лицензирования, metering и security policy исполняются на серверной стороне.
|
||||
|
||||
## 3. Что считается открытым контуром
|
||||
|
||||
В публичном репозитории должны оставаться:
|
||||
|
||||
- доменная модель Community;
|
||||
- `admin-api`, `mcp-server` и `ui`, необходимые для Community;
|
||||
- `REST`, `GraphQL` и `gRPC unary` в открытой редакции;
|
||||
- секреты, auth profiles, agent publishing, logs и usage;
|
||||
- статический ключ AI-агента;
|
||||
- контейнерное развертывание Community;
|
||||
- документация, тесты и демо-сценарии Community.
|
||||
|
||||
## 4. Что считается коммерческим контуром
|
||||
|
||||
В приватный контур должны выноситься:
|
||||
|
||||
- short-lived token service;
|
||||
- one-time token service;
|
||||
- `SSO`, `2FA`, расширенная `RBAC`, `audit log`;
|
||||
- `WebSocket`, `SOAP`, `gRPC streaming`, если они не включаются в Community;
|
||||
- advanced streaming execution modes;
|
||||
- metering и billing;
|
||||
- cloud control plane;
|
||||
- enterprise licensing and entitlement checks;
|
||||
- private operational tooling and support tooling.
|
||||
|
||||
## 5. Модель разделения репозиториев
|
||||
|
||||
### 5.1. Public repository
|
||||
|
||||
Этот репозиторий должен содержать только:
|
||||
|
||||
- Community runtime;
|
||||
- extension points;
|
||||
- capability model;
|
||||
- честные product contracts для открытой редакции.
|
||||
|
||||
### 5.2. Private repositories
|
||||
|
||||
Коммерческие возможности должны жить отдельно:
|
||||
|
||||
- либо в приватных crates;
|
||||
- либо в приватных приложениях и сервисах;
|
||||
- либо в отдельных private repositories с собственной поставкой.
|
||||
|
||||
Рекомендуемая схема:
|
||||
|
||||
- `crank` — public Community repo;
|
||||
- `crank-enterprise` — private self-hosted extensions;
|
||||
- `crank-cloud` — private cloud control plane и hosted-only logic.
|
||||
|
||||
## 6. Техническая стратегия разделения
|
||||
|
||||
### 6.1. Capability-first design
|
||||
|
||||
Открытый код должен опираться на capability model:
|
||||
|
||||
- edition capabilities;
|
||||
- protocol capabilities;
|
||||
- auth capabilities;
|
||||
- security capabilities.
|
||||
|
||||
Это позволяет:
|
||||
|
||||
- скрывать недоступные функции в UI;
|
||||
- не смешивать Community и commercial code paths;
|
||||
- добавлять private implementations без форка всей архитектуры.
|
||||
|
||||
### 6.2. Extension seams
|
||||
|
||||
В public repo должны быть только контракты и точки расширения:
|
||||
|
||||
- trait boundaries;
|
||||
- service contracts;
|
||||
- edition flags;
|
||||
- protocol registry abstraction;
|
||||
- token issuer abstraction;
|
||||
- feature availability checks.
|
||||
|
||||
Private code должен подключаться как реализация этих контрактов, а не как условные ветки по всему коду Community.
|
||||
|
||||
### 6.3. Server-side enforcement
|
||||
|
||||
Критичные коммерческие ограничения должны исполняться только на сервере:
|
||||
|
||||
- edition capabilities;
|
||||
- token issuance policy;
|
||||
- licensing checks;
|
||||
- metering;
|
||||
- protocol availability;
|
||||
- per-operation security rules.
|
||||
|
||||
Фронтенд может только отображать состояние. Он не должен быть единственным местом, где проверяется "можно / нельзя".
|
||||
|
||||
## 7. Что не является реальной защитой
|
||||
|
||||
Нельзя считать надежной защитой:
|
||||
|
||||
- минификацию frontend-кода;
|
||||
- обфускацию JavaScript;
|
||||
- "сложность" Rust binary как основную линию защиты;
|
||||
- попытку скрыть коммерческую логику в публичном репозитории через feature flags, если исходный код уже доступен.
|
||||
|
||||
Все это может немного повысить порог извлечения, но не решает задачу защиты коммерческого IP.
|
||||
|
||||
## 8. Реальная защита коммерческого кода
|
||||
|
||||
### 8.1. Не публиковать исходный код
|
||||
|
||||
Основное правило:
|
||||
|
||||
- коммерческий исходный код не должен попадать в public repo.
|
||||
|
||||
### 8.2. Поставлять private artifacts
|
||||
|
||||
Коммерческий контур должен поставляться как:
|
||||
|
||||
- private container images;
|
||||
- private binary artifacts;
|
||||
- private `Helm` charts;
|
||||
- private configuration bundles.
|
||||
|
||||
### 8.3. Подписывать артефакты
|
||||
|
||||
Для коммерческой поставки должны использоваться:
|
||||
|
||||
- подписанные контейнерные образы;
|
||||
- проверяемая provenance metadata;
|
||||
- versioned private releases.
|
||||
|
||||
### 8.4. Хранить ключевую логику на сервере
|
||||
|
||||
Наиболее чувствительные части должны оставаться на серверной стороне:
|
||||
|
||||
- licensing;
|
||||
- token issuance;
|
||||
- cloud metering;
|
||||
- enterprise access policy;
|
||||
- hosted control plane logic.
|
||||
|
||||
### 8.5. Не включать private UI в OSS bundle
|
||||
|
||||
Если функция коммерческая, ее UI не должен полноценно поставляться в Community build.
|
||||
|
||||
Допустимы:
|
||||
|
||||
- capability-driven hiding;
|
||||
- ограниченный teaser copy.
|
||||
|
||||
Недопустимы:
|
||||
|
||||
- полностью рабочие commercial screens в open-source bundle;
|
||||
- наличие private API contracts без server-side gating.
|
||||
|
||||
## 9. Что нужно сделать в кодовой базе
|
||||
|
||||
Для подготовки к коммерческой реализации в open-source коде должны появиться:
|
||||
|
||||
- edition capability model;
|
||||
- protocol capability model;
|
||||
- auth capability model;
|
||||
- интерфейсы для token issuer и enterprise access services;
|
||||
- server-side policy checks;
|
||||
- UI gating по capability flags;
|
||||
- отдельные delivery manifests для Community.
|
||||
|
||||
## 10. Связанные документы
|
||||
|
||||
- `docs/product-editions.md`
|
||||
- `docs/agent-auth-model.md`
|
||||
- `docs/module-decomposition.md`
|
||||
- `docs/frontend-roadmap.md`
|
||||
- `docs/refactoring-roadmap.md`
|
||||
- `docs/implementation-plan.md`
|
||||
@@ -174,6 +174,15 @@
|
||||
- домен не знает про HTTP, SQL, storage и transport;
|
||||
- adapters и repositories реализуют контракты, заданные ближе к домену.
|
||||
|
||||
## 7.4. Open-core правило
|
||||
|
||||
Для проекта фиксируется дополнительное правило:
|
||||
|
||||
- код `Community` живет в public repository;
|
||||
- коммерческий код не должен попадать в public repository "на будущее";
|
||||
- в public code допустимы только extension seams, capability flags и контракты для private implementations;
|
||||
- edition gating должно проверяться на серверной стороне, а не только в UI.
|
||||
|
||||
## 8. Git workflow
|
||||
|
||||
## 8.1. Remote
|
||||
|
||||
@@ -0,0 +1,133 @@
|
||||
# Frontend roadmap
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует оставшийся фронтенд-backlog после уже выполненных крупных cleanup и refactoring slices.
|
||||
|
||||
Он заменяет старые review-документы и должен использоваться вместе с `TASKS.md`.
|
||||
|
||||
## 2. Что уже считается закрытым
|
||||
|
||||
Выполненными считаются следующие большие треки:
|
||||
|
||||
- базовая локализация и plural rules;
|
||||
- XSS hardening основных dynamic render paths;
|
||||
- template safety cleanup;
|
||||
- CSS state cleanup;
|
||||
- frontend build pipeline;
|
||||
- wizard modularization;
|
||||
- базовая frontend observability and testability;
|
||||
- websocket test-run polish;
|
||||
- command palette removal;
|
||||
- settings honesty initial pass.
|
||||
|
||||
## 3. Что остается актуальным
|
||||
|
||||
### 3.1. Product gating by edition
|
||||
|
||||
UI должен честно отражать различия редакций:
|
||||
|
||||
- Community не должен показывать доступные к настройке `WebSocket`, `SOAP`, `gRPC streaming`, если они не входят в открытую поставку;
|
||||
- `security_level = elevated` и `security_level = strict` не должны выглядеть рабочими в Community;
|
||||
- multi-user и enterprise controls должны скрываться или отображаться как capability-locked.
|
||||
|
||||
Основные файлы:
|
||||
|
||||
- `apps/ui/js/wizard.js`
|
||||
- `apps/ui/js/operations.js`
|
||||
- `apps/ui/js/agents.js`
|
||||
- `apps/ui/js/api-keys.js`
|
||||
- `apps/ui/js/settings.js`
|
||||
- `apps/ui/js/i18n.js`
|
||||
|
||||
### 3.2. Agent key UX
|
||||
|
||||
После перехода от platform/workspace keys к agent keys UI должен быть доведен до продуктового состояния:
|
||||
|
||||
- список ключей должен уметь показывать привязку к AI-агенту;
|
||||
- модалка создания ключа должна позволять выбрать режим и область применения;
|
||||
- copy должен объяснять, зачем нужен agent-scoped key и чем он отличается от будущих токенных режимов.
|
||||
|
||||
Основные файлы:
|
||||
|
||||
- `apps/ui/js/api-keys.js`
|
||||
- `apps/ui/js/agents.js`
|
||||
- `apps/ui/html/api-keys.html`
|
||||
- `apps/ui/html/agents.html`
|
||||
- `apps/ui/js/i18n.js`
|
||||
|
||||
### 3.3. Mobile-first restructuring for data-heavy pages
|
||||
|
||||
На мобильных экранах нужно убрать desktop-table anti-pattern для:
|
||||
|
||||
- `API Keys`
|
||||
- `Secrets`
|
||||
- `Usage`
|
||||
- частично `Agents`
|
||||
|
||||
Целевой подход:
|
||||
|
||||
- карточки вместо широких таблиц;
|
||||
- постоянная видимость primary actions;
|
||||
- отсутствие скрытого горизонтального скролла как обязательного пути.
|
||||
|
||||
Основные файлы:
|
||||
|
||||
- `apps/ui/js/api-keys.js`
|
||||
- `apps/ui/js/secrets.js`
|
||||
- `apps/ui/js/usage.js`
|
||||
- `apps/ui/js/agents.js`
|
||||
- `apps/ui/css/*`
|
||||
|
||||
### 3.4. Workspace and settings polish
|
||||
|
||||
Остаются открытые UI/UX-проблемы:
|
||||
|
||||
- глобальная терминология `workspace` против `пространство`;
|
||||
- структура `Account Settings`;
|
||||
- честное состояние раздела `Notifications`;
|
||||
- mobile navigation overlap / sticky bug;
|
||||
- выравнивание dropdown и workspace switcher behavior.
|
||||
|
||||
Основные файлы:
|
||||
|
||||
- `apps/ui/js/settings.js`
|
||||
- `apps/ui/js/workspace-setup.js`
|
||||
- `apps/ui/js/auth.js`
|
||||
- `apps/ui/index.html`
|
||||
- `apps/ui/css/*`
|
||||
|
||||
### 3.5. Agent creation and operations wizard clarity
|
||||
|
||||
Нужно добить:
|
||||
|
||||
- copy для причин существования отдельных agent endpoints;
|
||||
- empty states без багов с пустыми запросами;
|
||||
- пояснения вокруг `slug`;
|
||||
- более явное описание security level на операции;
|
||||
- capability-based hiding недоступных протоколов и execution modes.
|
||||
|
||||
Основные файлы:
|
||||
|
||||
- `apps/ui/js/agents.js`
|
||||
- `apps/ui/js/wizard.js`
|
||||
- `apps/ui/js/wizard-live.js`
|
||||
- `apps/ui/js/wizard-model.js`
|
||||
- `apps/ui/js/i18n.js`
|
||||
|
||||
## 4. Глобальные правила для UI
|
||||
|
||||
- никакой developer-facing copy в пользовательском интерфейсе;
|
||||
- capability-locked функция либо скрыта, либо помечена честно;
|
||||
- мобильная версия не должна требовать обязательного горизонтального скролла для primary actions;
|
||||
- действия создания должны жить в одном месте и не дублироваться в пустом состоянии без причины;
|
||||
- все новые user-facing строки должны обновляться одновременно в `EN` и `RU`.
|
||||
|
||||
## 5. Правила приемки
|
||||
|
||||
Frontend-задача считается закрытой только если:
|
||||
|
||||
- измененный UI соответствует capability model редакции;
|
||||
- строка есть в `EN` и `RU`;
|
||||
- мобильный сценарий проверен вручную или через e2e;
|
||||
- не остались старые product contradictions в copy.
|
||||
+110
-159
@@ -2,217 +2,168 @@
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует порядок перехода от текущего состояния проекта к целевой product-ready integration platform модели.
|
||||
Этот документ фиксирует актуальный порядок подготовки Crank к коммерческой реализации как open-core продукта.
|
||||
|
||||
Документ не повторяет уже выполненные исторические этапы. Он описывает только тот план, по которому проект должен двигаться дальше.
|
||||
|
||||
## 2. Базовый принцип
|
||||
|
||||
Работа делится на два контура:
|
||||
|
||||
1. завершение и hardening открытой редакции `Community`;
|
||||
2. подготовка архитектурных, продуктовых и delivery-границ для `Enterprise` и `Cloud`.
|
||||
|
||||
Принцип:
|
||||
|
||||
- сначала перепроектирование `as is -> to be`;
|
||||
- потом foundation под workspace/agent model;
|
||||
- потом возврат к end-to-end UI сценариям;
|
||||
- потом observability и access layer;
|
||||
- потом polish и demo readiness;
|
||||
- потом расширение до полного protocol platform scope.
|
||||
- сначала нужно сделать честную и законченную `Community`-основу;
|
||||
- затем нужно отделить commercial seams и private delivery;
|
||||
- только после этого имеет смысл реализовывать коммерческие расширения.
|
||||
|
||||
## 2. Этап 1. Перепроектирование `As Is -> To Be`
|
||||
## 3. Этап 1. Open-core product boundary
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- зафиксировать новую доменную модель и page-driven backend contract.
|
||||
Зафиксировать, что входит в `Community`, а что уходит в `Enterprise` и `Cloud`.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- зафиксирован `as is -> to be` план;
|
||||
- page-by-page gap analysis покрывает все целевые экраны;
|
||||
- разобраны все архитектурные конфликты UI vs current backend;
|
||||
- документы `architecture`, `data-model`, `database-schema`, `admin-api`, `mcp-interface` синхронизированы.
|
||||
- документы `product-editions`, `commercial-boundaries`, `architecture`, `module-decomposition` синхронизированы;
|
||||
- в кодовой базе определена capability model по редакциям;
|
||||
- UI и API не обещают Community-функции, которых там не должно быть;
|
||||
- старые review-файлы не требуются как отдельный источник истины.
|
||||
|
||||
## 3. Этап 2. Workspace foundation
|
||||
## 4. Этап 2. Community machine access completion
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- перевести хранение и API на workspace-scoped модель.
|
||||
Довести базовую модель машинного доступа Community до полностью рабочего состояния.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- операции и auth profiles принадлежат workspace;
|
||||
- registry умеет фильтровать данные по workspace;
|
||||
- есть default workspace migration path.
|
||||
- у AI-агента есть собственный ключ;
|
||||
- UI умеет выпускать, показывать, отзывать и удалять agent keys;
|
||||
- `mcp-server` использует agent-scoped machine access;
|
||||
- Community поддерживает только `security_level = standard`;
|
||||
- в системе не остается product-facing assumptions про workspace-wide machine key как основной способ вызова.
|
||||
|
||||
## 4. Этап 3. Agent publishing foundation
|
||||
## 5. Этап 3. Edition capability model
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- ввести `Agent` и agent-scoped MCP publishing.
|
||||
Подготовить инфраструктуру, которая позволит одной кодовой базе честно различать редакции продукта.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- можно создать agent и привязать к нему published operations;
|
||||
- `mcp-server` выдает tools в контексте конкретного agent;
|
||||
- один agent видит только свой curated toolset.
|
||||
- существует server-side capability model:
|
||||
- protocols
|
||||
- auth modes
|
||||
- security levels
|
||||
- workspace/user limits
|
||||
- `admin-api` возвращает capability flags для UI;
|
||||
- UI скрывает или честно блокирует premium functionality;
|
||||
- Community build не содержит ложных "почти доступных" product paths.
|
||||
|
||||
## 5. Этап 4. Operations and wizard integration
|
||||
## 6. Этап 4. Private auth-service seam
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- посадить operations catalog и wizard на реальные backend contracts.
|
||||
Подготовить публичный код к private реализации короткоживущих и одноразовых токенов.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- каталог операций и wizard работают без `localStorage` overrides;
|
||||
- operation edit/delete/publish/test выполняются через backend;
|
||||
- все протоколы работают в рамках одного UI flow.
|
||||
- зафиксированы контракты для:
|
||||
- `POST /mcp-auth/v1/token`
|
||||
- `POST /mcp-auth/v1/token/one-time`
|
||||
- в `mcp-server` существует abstraction для проверки токенов;
|
||||
- `admin-api` и `mcp-interface` знают про эти контракты документированно;
|
||||
- Community при этом остается полностью работоспособной без private token service.
|
||||
|
||||
## 6. Этап 5. Agents UI and backend
|
||||
## 7. Этап 5. Commercial protocol split
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- реализовать agent-centric слой.
|
||||
Перестать считать весь текущий protocol surface частью открытой редакции.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- agent CRUD работает;
|
||||
- binding operations к agent работает;
|
||||
- published agent появляется в MCP runtime.
|
||||
- определен canonical Community protocol set;
|
||||
- premium protocol families и premium execution modes вынесены в коммерческий план;
|
||||
- UI capability-gated по протоколам;
|
||||
- release model для Community не требует shipping premium flow как рабочей open-source функции.
|
||||
|
||||
## 7. Этап 6. Agent-scoped machine access
|
||||
## 8. Этап 6. Frontend launch readiness
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- реализовать machine access на уровне AI-агента и ввести обязательный уровень защиты операции.
|
||||
Довести UI до коммерчески пригодного состояния для `Community` и подготовить edition-aware product surface.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- UI умеет выпускать и отзывать ключи конкретного AI-агента;
|
||||
- длинноживущий машинный доступ больше не описывается ключом рабочей области;
|
||||
- у операции появляется обязательный `security_level`;
|
||||
- machine access не смешивается с upstream auth profiles;
|
||||
- Community поддерживает базовый режим со статическим ключом AI-агента.
|
||||
- agent key UX доведен до продукта;
|
||||
- mobile layouts для data-heavy страниц больше не ломают primary actions;
|
||||
- terminology и localization согласованы;
|
||||
- settings и workspace flows не содержат misleading или half-functional sections;
|
||||
- UI понимает разницу между Community и premium capabilities.
|
||||
|
||||
## 8. Этап 7. Token exchange and short-lived auth
|
||||
## 9. Этап 7. Enterprise access and governance
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- внедрить расширенные режимы доступа для операций повышенной чувствительности.
|
||||
Реализовать коммерческий access/governance слой в private delivery.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- существует конечная точка выдачи токена по ключу агента;
|
||||
- есть модель одноразового токена для чувствительных вызовов;
|
||||
- токены ограничены по сроку жизни, области действия и числу использований;
|
||||
- операции уровня `elevated` нельзя вызвать по статическому ключу;
|
||||
- операции уровня `strict` можно вызвать только по одноразовому токену.
|
||||
- есть `SSO`;
|
||||
- есть `2FA`;
|
||||
- есть расширенная `RBAC`;
|
||||
- есть `audit log`;
|
||||
- существует private delivery path для self-hosted customers.
|
||||
|
||||
## 9. Этап 8. Observability
|
||||
## 10. Этап 8. Cloud control plane
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- реализовать логи и usage.
|
||||
Подготовить hosted-редакцию как отдельный продуктовый контур.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- `Logs` page и `Usage` page работают на реальных данных;
|
||||
- есть продуктовые endpoints, а не только application logs;
|
||||
- rollups и detail views согласованы с UI.
|
||||
- есть metering;
|
||||
- есть billing integration;
|
||||
- есть hosted tenant model;
|
||||
- есть cloud deployment and support tooling;
|
||||
- capability model синхронизирована с hosted plans.
|
||||
|
||||
## 10. Этап 9. Alpine UI integration
|
||||
## 11. Этап 9. Release and distribution hardening
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- довести `apps/ui` до полной работы на реальном backend.
|
||||
Подготовить безопасную поставку открытой и коммерческой редакций.
|
||||
|
||||
DoD:
|
||||
### DoD
|
||||
|
||||
- `apps/ui` содержит целевой Alpine.js UI;
|
||||
- mock JSON больше не используется на критическом пути;
|
||||
- UI, backend и docs синхронизированы.
|
||||
- Community публикуется из public GitHub repository;
|
||||
- Enterprise поставляется через private container registry и private manifests;
|
||||
- Cloud использует отдельный private operational contour;
|
||||
- build provenance и подпись артефактов документированы;
|
||||
- коммерческий код не требуется публиковать в public repository.
|
||||
|
||||
## 11. Этап 10. Secret store and upstream auth
|
||||
## 12. Этап 10. Live staging and demo readiness
|
||||
|
||||
Цель:
|
||||
### Цель
|
||||
|
||||
- заменить UI placeholder-модель `${secrets.*}` на рабочий backend/runtime слой secrets.
|
||||
Поддерживать реальный стенд и демонстрационный сценарий в состоянии, пригодном для продажи и демонстрации.
|
||||
|
||||
DoD:
|
||||
### 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.
|
||||
- live authenticated staging pass воспроизводим;
|
||||
- deploy smoke и operator docs совпадают с реальной поставкой;
|
||||
- demo user flow подтвержден на реальном окружении;
|
||||
- регрессии в publish/call/auth flow ловятся до релиза.
|
||||
|
||||
## 12. Этап 11. Hardening and demo readiness
|
||||
## 13. Связанные документы
|
||||
|
||||
Цель:
|
||||
|
||||
- довести продукт до стабильного демо-сценария.
|
||||
|
||||
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 зафиксированы явно.
|
||||
- `docs/product-editions.md`
|
||||
- `docs/commercial-boundaries.md`
|
||||
- `docs/frontend-roadmap.md`
|
||||
- `docs/refactoring-roadmap.md`
|
||||
- `docs/agent-auth-model.md`
|
||||
|
||||
@@ -110,6 +110,11 @@
|
||||
- операция задает обязательный `security_level`, и `mcp-server` обязан отклонять вызов, если представленный credential слабее требуемого уровня;
|
||||
- детальная модель уровней зафиксирована в `docs/agent-auth-model.md`.
|
||||
|
||||
Важно:
|
||||
|
||||
- Community-сборка должна работать полностью без private token services;
|
||||
- commercial token flows должны подключаться через capability-gated server-side integrations.
|
||||
|
||||
Уровни защиты операции:
|
||||
|
||||
- `standard`
|
||||
|
||||
@@ -159,3 +159,41 @@
|
||||
Антипаттерн:
|
||||
|
||||
не превращать `mcp-server` во второй `admin-api`.
|
||||
|
||||
## 5. Разделение open-source и commercial модулей
|
||||
|
||||
### 5.1. Что остается в public repository
|
||||
|
||||
В этом репозитории должны жить:
|
||||
|
||||
- Community domain model;
|
||||
- Community runtime;
|
||||
- Community UI;
|
||||
- extension seams для коммерческих возможностей;
|
||||
- capability model по редакциям.
|
||||
|
||||
### 5.2. Что должно выноситься в private delivery
|
||||
|
||||
За пределами public repo должны жить:
|
||||
|
||||
- short-lived и one-time token issuers;
|
||||
- enterprise access services;
|
||||
- `SSO`, `2FA`, `RBAC`, `audit log`;
|
||||
- metering и billing;
|
||||
- cloud control plane;
|
||||
- premium protocol families, если они не входят в Community edition.
|
||||
|
||||
### 5.3. Техническое правило
|
||||
|
||||
Public code не должен содержать скрытую private business logic.
|
||||
|
||||
Допустимо:
|
||||
|
||||
- trait boundaries;
|
||||
- capability flags;
|
||||
- edition-aware service contracts.
|
||||
|
||||
Недопустимо:
|
||||
|
||||
- полноценная коммерческая реализация в open-source исходниках;
|
||||
- UI, который реально включает premium flow без server-side gating.
|
||||
|
||||
@@ -0,0 +1,192 @@
|
||||
# Редакции продукта
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует продуктовую модель Crank как open-core платформы и определяет, какие возможности входят в открытую редакцию, а какие относятся к коммерческим редакциям.
|
||||
|
||||
Документ нужен для трех целей:
|
||||
|
||||
- не смешивать в одном репозитории открытый и коммерческий контур без явных границ;
|
||||
- синхронизировать продуктовые ограничения с архитектурой, API и UI;
|
||||
- дать реализации четкий ориентир по edition gating и delivery model.
|
||||
|
||||
## 2. Базовая модель
|
||||
|
||||
Crank развивается как три редакции:
|
||||
|
||||
1. `Community` — открытая self-hosted редакция;
|
||||
2. `Enterprise` — коммерческая self-hosted редакция;
|
||||
3. `Cloud` — коммерческая vendor-hosted редакция.
|
||||
|
||||
Принцип:
|
||||
|
||||
- открытая редакция должна быть самодостаточной и полезной сама по себе;
|
||||
- коммерческие редакции должны расширять продукт, а не ломать открытую основу;
|
||||
- различия между редакциями должны быть видны в capability model, документации, UI и delivery pipeline.
|
||||
|
||||
## 3. Community
|
||||
|
||||
### 3.1. Целевая аудитория
|
||||
|
||||
`Community` предназначена для:
|
||||
|
||||
- индивидуального пользователя;
|
||||
- AI-энтузиаста;
|
||||
- небольшой команды, которой нужен один рабочий MCP endpoint без enterprise-функций.
|
||||
|
||||
### 3.2. Что входит
|
||||
|
||||
- self-hosted развертывание;
|
||||
- одна рабочая область;
|
||||
- один пользователь;
|
||||
- один AI-агент;
|
||||
- протоколы:
|
||||
- `REST / HTTP`
|
||||
- `GraphQL`
|
||||
- `gRPC unary`
|
||||
- создание и публикация операций;
|
||||
- журналы вызовов и метрики использования;
|
||||
- секреты и профили аутентификации для внешних сервисов;
|
||||
- статический ключ AI-агента;
|
||||
- только `security_level = standard`;
|
||||
- контейнерное развертывание;
|
||||
- документация, демо-сценарий и базовый CI.
|
||||
|
||||
### 3.3. Что не входит
|
||||
|
||||
- несколько рабочих областей;
|
||||
- несколько пользователей;
|
||||
- `SSO`, `2FA`, развитая `RBAC`, `audit log`;
|
||||
- короткоживущие и одноразовые машинные токены;
|
||||
- `WebSocket`, `SOAP`, `gRPC streaming`;
|
||||
- режимы `window`, `session`, `async_job`;
|
||||
- биллинг и usage metering для SaaS;
|
||||
- cloud control plane.
|
||||
|
||||
## 4. Enterprise
|
||||
|
||||
### 4.1. Целевая аудитория
|
||||
|
||||
`Enterprise` предназначена для компаний, которые:
|
||||
|
||||
- разворачивают Crank на своей инфраструктуре;
|
||||
- хотят полный набор протоколов;
|
||||
- требуют усиленную безопасность, командный доступ и аудит;
|
||||
- готовы платить за сопровождение и коммерческие расширения.
|
||||
|
||||
### 4.2. Что добавляется к Community
|
||||
|
||||
- несколько рабочих областей;
|
||||
- несколько пользователей;
|
||||
- `SSO`, `2FA`, расширенная `RBAC`, `audit log`;
|
||||
- короткоживущие машинные токены;
|
||||
- одноразовые токены для критичных операций;
|
||||
- `security_level = elevated` и `security_level = strict`;
|
||||
- `WebSocket`, `SOAP`, `gRPC streaming`;
|
||||
- streaming execution modes;
|
||||
- расширенные административные и эксплуатационные функции;
|
||||
- поставка через приватные образы и `Helm`-чарты.
|
||||
|
||||
## 5. Cloud
|
||||
|
||||
### 5.1. Целевая аудитория
|
||||
|
||||
`Cloud` предназначена для команд, которым нужна:
|
||||
|
||||
- готовая размещенная платформа;
|
||||
- минимизация собственной эксплуатационной нагрузки;
|
||||
- SaaS-модель с управляемыми обновлениями и платными лимитами.
|
||||
|
||||
### 5.2. Что добавляется к Enterprise
|
||||
|
||||
- vendor-hosted развертывание;
|
||||
- usage metering;
|
||||
- тарифы и лимиты;
|
||||
- cloud control plane;
|
||||
- эксплуатационный мониторинг и обновления со стороны поставщика;
|
||||
- биллинг и tenant-oriented support tooling.
|
||||
|
||||
## 6. Матрица возможностей
|
||||
|
||||
| Возможность | Community | Enterprise | Cloud |
|
||||
| --- | --- | --- | --- |
|
||||
| Hosting | self-hosted | self-hosted | vendor-hosted |
|
||||
| Workspace count | 1 | many | many |
|
||||
| User count | 1 | many | many |
|
||||
| Agent count | 1 | many | many |
|
||||
| REST / GraphQL / gRPC unary | yes | yes | yes |
|
||||
| WebSocket / SOAP / gRPC streaming | no | yes | yes |
|
||||
| Streaming modes | no | yes | yes |
|
||||
| Static agent key | yes | yes | yes |
|
||||
| Short-lived MCP token | no | yes | yes |
|
||||
| One-time MCP token | no | yes | selectively |
|
||||
| `security_level = standard` | yes | yes | yes |
|
||||
| `security_level = elevated` | no | yes | yes |
|
||||
| `security_level = strict` | no | yes | limited by policy |
|
||||
| Logs and usage | yes | yes | yes |
|
||||
| SSO / 2FA / RBAC / audit | no | yes | yes |
|
||||
| Billing / metering | no | no | yes |
|
||||
|
||||
## 7. Правила для реализации
|
||||
|
||||
### 7.1. Community не должен зависеть от private code
|
||||
|
||||
Открытая редакция должна:
|
||||
|
||||
- собираться из этого репозитория полностью;
|
||||
- иметь завершенный сценарий демо и эксплуатации;
|
||||
- не требовать закрытых сервисов для базового машинного доступа.
|
||||
|
||||
### 7.2. Коммерческие возможности должны быть явно отделены
|
||||
|
||||
Коммерческие функции не должны появляться в Community как полурабочие заглушки. Для каждой такой функции требуется одно из двух:
|
||||
|
||||
- capability flag с честным недоступным состоянием;
|
||||
- полное отсутствие функции из open-source сборки.
|
||||
|
||||
### 7.3. Различия по редакциям должны быть зафиксированы в четырех местах
|
||||
|
||||
1. в продуктовой документации;
|
||||
2. в архитектурной декомпозиции;
|
||||
3. в административном API и MCP-контрактах;
|
||||
4. в UI через capability gating и честный copy.
|
||||
|
||||
## 8. Правила для машинной аутентификации
|
||||
|
||||
Продуктовые редакции различаются и по входящему машинному доступу:
|
||||
|
||||
- `Community`:
|
||||
- только статический ключ AI-агента;
|
||||
- только операции уровня `standard`;
|
||||
- `Enterprise`:
|
||||
- статический ключ AI-агента;
|
||||
- короткоживущий токен;
|
||||
- одноразовый токен;
|
||||
- `Cloud`:
|
||||
- статический ключ как режим совместимости;
|
||||
- короткоживущий токен как основной режим;
|
||||
- одноразовый токен — только там, где это поддерживается продуктовой политикой.
|
||||
|
||||
Подробная модель описана в `docs/agent-auth-model.md`.
|
||||
|
||||
## 9. Правила для UI
|
||||
|
||||
Открытый UI не должен:
|
||||
|
||||
- обещать недоступные в Community возможности как почти готовые;
|
||||
- показывать enterprise/cloud controls без capability gating;
|
||||
- использовать ложные CTA для недоступных функций.
|
||||
|
||||
Если функция не входит в текущую редакцию, UI должен делать одно из двух:
|
||||
|
||||
- не показывать ее вовсе;
|
||||
- показывать ее как явно недоступную и документированно требующую другую редакцию.
|
||||
|
||||
## 10. Связанные документы
|
||||
|
||||
- `docs/architecture.md`
|
||||
- `docs/module-decomposition.md`
|
||||
- `docs/agent-auth-model.md`
|
||||
- `docs/frontend-roadmap.md`
|
||||
- `docs/refactoring-roadmap.md`
|
||||
- `docs/implementation-plan.md`
|
||||
@@ -0,0 +1,111 @@
|
||||
# Refactoring roadmap
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует оставшийся технический backlog после уже выполненных больших backend и frontend refactoring tracks.
|
||||
|
||||
Он не повторяет уже завершенные изменения, а описывает то, что еще нужно для product-ready open-core платформы.
|
||||
|
||||
## 2. Что уже считается выполненным
|
||||
|
||||
Закрытыми считаются следующие крупные инженерные направления:
|
||||
|
||||
- модульное разбиение `crank-registry`;
|
||||
- compile-time SQL verification для статических запросов;
|
||||
- `HKDF` вместо прямого `SHA-256` derivation;
|
||||
- typed timestamps;
|
||||
- `Display` для typed ids;
|
||||
- explicit PostgreSQL pool configuration;
|
||||
- structured runtime and registry errors;
|
||||
- correlation IDs;
|
||||
- runtime backpressure и request throttling;
|
||||
- distributed transport session store;
|
||||
- frontend build pipeline и wizard modularization.
|
||||
|
||||
## 3. Оставшиеся технические треки
|
||||
|
||||
### 3.1. Open-core boundary extraction
|
||||
|
||||
Цель:
|
||||
|
||||
- отделить Community runtime от будущих commercial implementations.
|
||||
|
||||
Что нужно:
|
||||
|
||||
- capability model по редакциям;
|
||||
- protocol gating;
|
||||
- auth gating;
|
||||
- extension seams для private implementations;
|
||||
- отдельные delivery manifests для Community.
|
||||
|
||||
Ключевые места:
|
||||
|
||||
- `crates/crank-core`
|
||||
- `apps/admin-api`
|
||||
- `apps/mcp-server`
|
||||
- `apps/ui`
|
||||
- `docs/product-editions.md`
|
||||
- `docs/commercial-boundaries.md`
|
||||
|
||||
### 3.2. Agent-scoped machine auth completion
|
||||
|
||||
Цель:
|
||||
|
||||
- довести current docs-first auth model до рабочего Community implementation.
|
||||
|
||||
Что нужно:
|
||||
|
||||
- полноценный `AgentKey` lifecycle в `admin-api` и UI;
|
||||
- отказ от remaining workspace/platform-key assumptions;
|
||||
- enforcement `security_level = standard` в Community flow;
|
||||
- capability scaffolding для `elevated` и `strict`.
|
||||
|
||||
### 3.3. Private token-service seam
|
||||
|
||||
Цель:
|
||||
|
||||
- подготовить публичный код к private реализации short-lived и one-time token flows.
|
||||
|
||||
Что нужно:
|
||||
|
||||
- stable HTTP contracts;
|
||||
- server-side trait boundary;
|
||||
- token verification abstraction in `mcp-server`;
|
||||
- capability-aware UI contract.
|
||||
|
||||
### 3.4. Commercial protocol split
|
||||
|
||||
Цель:
|
||||
|
||||
- перестать считать все уже написанные protocol families частью Community surface.
|
||||
|
||||
Что нужно:
|
||||
|
||||
- определить Community-supported protocol set;
|
||||
- вынести premium protocols и premium execution modes в private delivery plan;
|
||||
- синхронизировать UI, docs и release process.
|
||||
|
||||
### 3.5. Release and distribution hardening
|
||||
|
||||
Цель:
|
||||
|
||||
- подготовить reproducible public Community release и private commercial delivery.
|
||||
|
||||
Что нужно:
|
||||
|
||||
- public release flow for GitHub;
|
||||
- private image flow for Enterprise;
|
||||
- artifact signing / provenance;
|
||||
- clear packaging split for Community vs commercial.
|
||||
|
||||
## 4. Правила приоритизации
|
||||
|
||||
Сначала выполняются треки, которые формируют границу продукта:
|
||||
|
||||
1. open-core boundary extraction;
|
||||
2. Community agent-scoped auth completion;
|
||||
3. private token-service seam;
|
||||
4. frontend edition gating;
|
||||
5. release and distribution hardening.
|
||||
|
||||
После этого уже можно безопасно идти в enterprise/cloud-specific implementation.
|
||||
Reference in New Issue
Block a user