docs: redesign architecture around workspaces and agents
This commit is contained in:
a.tolmachev
+51
-355
@@ -2,425 +2,121 @@
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует порядок реализации модулей и фич. Он нужен затем, чтобы разработка шла последовательно, а не параллельно во все стороны сразу.
|
||||
Этот документ фиксирует порядок перехода от текущего состояния проекта к целевой модели, заданной `test-ui`.
|
||||
|
||||
Принцип:
|
||||
|
||||
- сначала фундамент;
|
||||
- потом минимальный end-to-end сценарий;
|
||||
- потом расширение протоколов;
|
||||
- сначала перепроектирование `as is -> to be`;
|
||||
- потом foundation под workspace/agent model;
|
||||
- потом возврат к end-to-end UI сценариям;
|
||||
- потом observability и access layer;
|
||||
- потом polish и demo readiness.
|
||||
|
||||
## 2. Этап 0. Scaffold проекта
|
||||
## 2. Этап 1. Перепроектирование `As Is -> To Be`
|
||||
|
||||
Цель:
|
||||
|
||||
- создать `cargo workspace`;
|
||||
- создать приложения и crates;
|
||||
- подключить базовый CI/test workflow;
|
||||
- зафиксировать структуру каталогов.
|
||||
|
||||
Состав:
|
||||
|
||||
- `apps/admin-api`
|
||||
- `apps/mcp-server`
|
||||
- `apps/ui`
|
||||
- `crates/crank-core`
|
||||
- `crates/crank-schema`
|
||||
- `crates/crank-mapping`
|
||||
- `crates/crank-proto`
|
||||
- `crates/crank-registry`
|
||||
- `crates/crank-runtime`
|
||||
- `crates/crank-adapter-rest`
|
||||
- `crates/crank-adapter-graphql`
|
||||
- `crates/crank-adapter-grpc`
|
||||
|
||||
Результат:
|
||||
|
||||
- проект собирается;
|
||||
- тестовый pipeline запускается;
|
||||
- есть пустые crate boundaries.
|
||||
- зафиксировать новую доменную модель и page-driven backend contract.
|
||||
|
||||
DoD:
|
||||
|
||||
- создан `cargo workspace`;
|
||||
- все crates и apps объявлены в workspace;
|
||||
- проект собирается без бизнес-логики;
|
||||
- базовые test targets запускаются;
|
||||
- сделан атомарный commit со scaffold.
|
||||
- зафиксирован `as is -> to be` план;
|
||||
- page-by-page gap analysis покрывает все целевые экраны;
|
||||
- разобраны все архитектурные конфликты UI vs current backend;
|
||||
- документы `architecture`, `data-model`, `database-schema`, `admin-api`, `mcp-interface` синхронизированы.
|
||||
|
||||
## 3. Этап 1. Базовая доменная модель
|
||||
## 3. Этап 2. Workspace foundation
|
||||
|
||||
Цель:
|
||||
|
||||
- реализовать типы из `data-model`.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `Operation`
|
||||
- `Target`
|
||||
- `Schema`
|
||||
- `MappingSet`
|
||||
- `ExecutionConfig`
|
||||
- `ToolDescription`
|
||||
- `AuthProfile`
|
||||
|
||||
Параллельно:
|
||||
|
||||
- unit tests на доменные типы;
|
||||
- базовая сериализация `JSON`/`YAML`.
|
||||
|
||||
Результат:
|
||||
|
||||
- модель данных существует как код;
|
||||
- нет инфраструктурных зависимостей внутри домена.
|
||||
- перевести хранение и API на workspace-scoped модель.
|
||||
|
||||
DoD:
|
||||
|
||||
- типы из `data-model` реализованы;
|
||||
- базовая сериализация `JSON` и `YAML` проходит тесты;
|
||||
- доменные `impl` не содержат инфраструктурной логики;
|
||||
- unit tests на ключевые типы проходят;
|
||||
- изменения зафиксированы через один или несколько `RGR + commit`.
|
||||
- операции и auth profiles принадлежат workspace;
|
||||
- registry умеет фильтровать данные по workspace;
|
||||
- есть default workspace migration path.
|
||||
|
||||
## 4. Этап 2. Schema engine
|
||||
## 4. Этап 3. Agent publishing foundation
|
||||
|
||||
Цель:
|
||||
|
||||
- реализовать `crank-schema`.
|
||||
|
||||
Фичи:
|
||||
|
||||
- model полей и типов;
|
||||
- schema validation;
|
||||
- field traversal;
|
||||
- нормализация JSON samples;
|
||||
- protobuf -> schema bridge contracts.
|
||||
|
||||
Результат:
|
||||
|
||||
- можно описывать и валидировать вход/выход.
|
||||
- ввести `Agent` и agent-scoped MCP publishing.
|
||||
|
||||
DoD:
|
||||
|
||||
- реализована схема полей и типов;
|
||||
- работает schema validation;
|
||||
- JSON sample normalization покрыт тестами;
|
||||
- контракты protobuf -> schema зафиксированы;
|
||||
- нет смешивания schema logic с adapter logic.
|
||||
- можно создать agent и привязать к нему published operations;
|
||||
- `mcp-server` выдает tools в контексте конкретного agent;
|
||||
- один agent видит только свой curated toolset.
|
||||
|
||||
## 5. Этап 3. Mapping engine
|
||||
## 5. Этап 4. Operations and wizard integration
|
||||
|
||||
Цель:
|
||||
|
||||
- реализовать `crank-mapping`.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `JSONPath` parsing и validation;
|
||||
- input mapping;
|
||||
- output mapping;
|
||||
- transforms;
|
||||
- generation draft mapping из samples.
|
||||
|
||||
Результат:
|
||||
|
||||
- можно преобразовывать MCP input в request model и response в output model.
|
||||
- посадить operations catalog и wizard на реальные backend contracts.
|
||||
|
||||
DoD:
|
||||
|
||||
- `JSONPath` parsing и validation работают;
|
||||
- input/output mapping проходят unit tests;
|
||||
- generation draft mapping покрыта фикстурами;
|
||||
- transforms ограничены и задокументированы;
|
||||
- mapping engine не знает о конкретных protocol adapters.
|
||||
- каталог операций и wizard работают без `localStorage` overrides;
|
||||
- operation edit/delete/publish/test выполняются через backend;
|
||||
- все протоколы работают в рамках одного UI flow.
|
||||
|
||||
## 6. Этап 4. Registry и БД
|
||||
## 6. Этап 5. Agents UI and backend
|
||||
|
||||
Цель:
|
||||
|
||||
- реализовать `crank-registry` и миграции.
|
||||
|
||||
Фичи:
|
||||
|
||||
- таблицы из `database-schema`;
|
||||
- version snapshots;
|
||||
- published operations;
|
||||
- auth profiles;
|
||||
- sample metadata;
|
||||
- descriptor metadata;
|
||||
- YAML import job log.
|
||||
|
||||
Результат:
|
||||
|
||||
- конфигурации можно хранить и версионировать.
|
||||
- реализовать agent-centric слой.
|
||||
|
||||
DoD:
|
||||
|
||||
- миграции создают таблицы из `database-schema`;
|
||||
- version snapshots работают корректно;
|
||||
- publish linkage реализован;
|
||||
- auth profiles и artifact metadata сохраняются;
|
||||
- integration tests на registry проходят на реальной БД.
|
||||
- agent CRUD работает;
|
||||
- binding operations к agent работает;
|
||||
- published agent появляется в MCP runtime.
|
||||
|
||||
## 7. Этап 5. REST vertical slice
|
||||
## 7. Этап 6. Platform access
|
||||
|
||||
Цель:
|
||||
|
||||
- получить первый рабочий end-to-end сценарий.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `crank-adapter-rest`
|
||||
- `crank-runtime` для REST
|
||||
- REST test run
|
||||
- создание REST operation
|
||||
- publish REST operation
|
||||
- вызов published REST tool из MCP слоя
|
||||
|
||||
Результат:
|
||||
|
||||
- MVP работает хотя бы для REST.
|
||||
- реализовать workspace access и platform API keys.
|
||||
|
||||
DoD:
|
||||
|
||||
- REST operation можно создать, протестировать и опубликовать;
|
||||
- runtime исполняет REST operation end-to-end;
|
||||
- published REST tool вызывается через MCP слой;
|
||||
- negative tests на mapping и external errors существуют;
|
||||
- есть демонстрационный REST сценарий.
|
||||
- UI screens `API Keys`, `Settings`, `Workspace` имеют backend-контракт;
|
||||
- platform API keys не смешиваются с upstream auth profiles;
|
||||
- tenant boundary выражен в access layer.
|
||||
|
||||
## 8. Этап 6. Admin API v1
|
||||
## 8. Этап 7. Observability
|
||||
|
||||
Цель:
|
||||
|
||||
- дать UI полный backend-контракт для базового сценария.
|
||||
|
||||
Фичи:
|
||||
|
||||
- CRUD operations;
|
||||
- create version;
|
||||
- publish;
|
||||
- upload input/output JSON samples;
|
||||
- generate draft;
|
||||
- test run;
|
||||
- auth profiles CRUD;
|
||||
- YAML import/export.
|
||||
|
||||
Результат:
|
||||
|
||||
- UI может полностью управлять REST operation без ручных правок кода.
|
||||
- реализовать логи и usage.
|
||||
|
||||
DoD:
|
||||
|
||||
- доступны CRUD, versioning, publish, samples, draft generation, test runs;
|
||||
- доступны auth profiles и YAML import/export;
|
||||
- API контракты соответствуют документации;
|
||||
- integration tests на ключевые endpoints проходят;
|
||||
- нет скрытой бизнес-логики в handlers.
|
||||
- `Logs` page и `Usage` page работают на реальных данных;
|
||||
- есть продуктовые endpoints, а не только application logs;
|
||||
- rollups и detail views согласованы с UI.
|
||||
|
||||
## 9. Этап 7. UI v1
|
||||
## 9. Этап 8. Alpine UI integration
|
||||
|
||||
Цель:
|
||||
|
||||
- собрать рабочую административную консоль.
|
||||
|
||||
Фичи:
|
||||
|
||||
- список операций;
|
||||
- мастер создания операции;
|
||||
- sample upload;
|
||||
- schema viewer;
|
||||
- mapping editor;
|
||||
- test run screen;
|
||||
- publish flow;
|
||||
- YAML import/export screen.
|
||||
|
||||
Результат:
|
||||
|
||||
- есть демонстрируемый пользовательский интерфейс.
|
||||
- перенести `test-ui` в `apps/ui` и подключить его к реальному backend.
|
||||
|
||||
DoD:
|
||||
|
||||
- UI покрывает основной сценарий от создания operation до publish;
|
||||
- sample upload и mapping editor работают;
|
||||
- YAML import/export доступен из UI;
|
||||
- нет блокирующих заглушек на критическом пути демо;
|
||||
- основные пользовательские сценарии проверены вручную или integration tests.
|
||||
- `apps/ui` содержит целевой Alpine.js UI;
|
||||
- mock JSON больше не используется на критическом пути;
|
||||
- UI, backend и docs синхронизированы.
|
||||
|
||||
## 10. Этап 8. MCP server
|
||||
## 10. Этап 9. Hardening and demo readiness
|
||||
|
||||
Цель:
|
||||
|
||||
- публиковать published operations как MCP tools.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `Streamable HTTP`;
|
||||
- list tools;
|
||||
- call tool;
|
||||
- reload published tools;
|
||||
- error mapping MCP layer.
|
||||
|
||||
Результат:
|
||||
|
||||
- REST operation доступна как полноценный MCP tool.
|
||||
- довести продукт до стабильного демо-сценария.
|
||||
|
||||
DoD:
|
||||
|
||||
- `Streamable HTTP` transport работает;
|
||||
- list tools и call tool реализованы;
|
||||
- reload published tools работает без перезапуска;
|
||||
- ошибки runtime корректно транслируются в MCP слой;
|
||||
- есть end-to-end test или demo flow вызова published REST tool.
|
||||
|
||||
## 11. Этап 9. GraphQL support
|
||||
|
||||
Цель:
|
||||
|
||||
- добавить второй протокол без разрушения архитектуры.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `crank-adapter-graphql`
|
||||
- GraphQL target support;
|
||||
- variables mapping;
|
||||
- `response_path`;
|
||||
- GraphQL test runs;
|
||||
- publish и вызов через MCP.
|
||||
|
||||
Результат:
|
||||
|
||||
- второй end-to-end сценарий.
|
||||
|
||||
DoD:
|
||||
|
||||
- GraphQL operation можно создать, протестировать и опубликовать;
|
||||
- variables mapping и `response_path` работают;
|
||||
- GraphQL `errors` корректно обрабатываются;
|
||||
- published GraphQL tool вызывается через MCP слой;
|
||||
- есть demo fixture или integration scenario.
|
||||
|
||||
## 12. Этап 10. gRPC support
|
||||
|
||||
Цель:
|
||||
|
||||
- добавить unary gRPC.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `crank-proto`
|
||||
- descriptor loading;
|
||||
- service/method discovery;
|
||||
- protobuf normalization;
|
||||
- `crank-adapter-grpc`
|
||||
- unary test runs;
|
||||
- publish и вызов через MCP.
|
||||
|
||||
Результат:
|
||||
|
||||
- третий end-to-end сценарий.
|
||||
|
||||
DoD:
|
||||
|
||||
- `.proto` или descriptor set можно загрузить;
|
||||
- unary method discovery работает;
|
||||
- JSON <-> protobuf conversion покрыта тестами;
|
||||
- gRPC operation можно протестировать и опубликовать;
|
||||
- published gRPC tool вызывается через MCP слой.
|
||||
|
||||
## 13. Этап 11. Harden и demo readiness
|
||||
|
||||
Цель:
|
||||
|
||||
- довести проект до стабильного demo state.
|
||||
|
||||
Фичи:
|
||||
|
||||
- логирование и tracing;
|
||||
- улучшение ошибок;
|
||||
- фикстуры и demo scenarios;
|
||||
- polish UI;
|
||||
- документация по запуску;
|
||||
- проверка YAML roundtrip;
|
||||
- проверка publish/reload flow.
|
||||
|
||||
DoD:
|
||||
|
||||
- демонстрационные сценарии воспроизводимы;
|
||||
- логирование и ошибки читаемы;
|
||||
- YAML roundtrip проверен;
|
||||
- publish/reload flow стабилен;
|
||||
- документация по запуску достаточна для повторения демо.
|
||||
|
||||
## 14. Этап 12. Deployment и CD
|
||||
|
||||
Цель:
|
||||
|
||||
- сделать повторяемый production-like запуск проекта.
|
||||
|
||||
Фичи:
|
||||
|
||||
- `Dockerfile` для приложений;
|
||||
- `docker-compose.yml`;
|
||||
- `.env.example`;
|
||||
- reverse proxy examples;
|
||||
- health endpoints;
|
||||
- CD workflow для `main`.
|
||||
|
||||
Результат:
|
||||
|
||||
- проект можно развернуть на Linux-хосте без ручной сборки бинарей и без ad-hoc shell-скриптов.
|
||||
|
||||
DoD:
|
||||
|
||||
- backend приложения собираются в контейнеры;
|
||||
- есть production-like compose конфигурация;
|
||||
- reverse proxy examples задокументированы;
|
||||
- CI и CD разделены;
|
||||
- deployment проверяется healthchecks.
|
||||
|
||||
## 15. Приоритеты по реализации
|
||||
|
||||
Если времени не хватает, сохраняется такой приоритет:
|
||||
|
||||
1. REST end-to-end
|
||||
2. Registry + versioning
|
||||
3. YAML import/export
|
||||
4. MCP server
|
||||
5. GraphQL
|
||||
6. gRPC
|
||||
|
||||
Причина:
|
||||
|
||||
- диплом должен показать работающую платформу;
|
||||
- лучше один полный вертикальный сценарий, чем три недоделанных адаптера.
|
||||
|
||||
## 16. Разбиение по фичам
|
||||
|
||||
Каждый этап желательно бить на маленькие фичи:
|
||||
|
||||
- `schema-field-model`
|
||||
- `schema-validator`
|
||||
- `jsonpath-parser`
|
||||
- `input-mapping-engine`
|
||||
- `output-mapping-engine`
|
||||
- `registry-create-version`
|
||||
- `registry-publish`
|
||||
- `rest-adapter-post-json`
|
||||
- `yaml-export-portable`
|
||||
- `mcp-list-tools`
|
||||
|
||||
Для каждой такой фичи локальный `DoD` должен быть записан до начала реализации хотя бы в рабочем описании задачи или ветки.
|
||||
|
||||
## 17. Практический итог
|
||||
|
||||
Правильная последовательность для проекта:
|
||||
|
||||
- сначала домен и фундамент;
|
||||
- потом registry;
|
||||
- потом один полный REST vertical slice;
|
||||
- потом admin-ui и MCP слой;
|
||||
- только после этого расширение на GraphQL и gRPC.
|
||||
|
||||
Такой порядок минимизирует архитектурный риск и дает ранний рабочий результат.
|
||||
- end-to-end demo воспроизводим;
|
||||
- deployment и healthchecks стабильно зелёные;
|
||||
- документация и продуктовый сценарий совпадают.
|
||||
|
||||
Reference in New Issue
Block a user