a.tolmachev
427 lines
12 KiB
Markdown
427 lines
12 KiB
Markdown
# План реализации
|
||
|
||
## 1. Назначение документа
|
||
|
||
Этот документ фиксирует порядок реализации модулей и фич. Он нужен затем, чтобы разработка шла последовательно, а не параллельно во все стороны сразу.
|
||
|
||
Принцип:
|
||
|
||
- сначала фундамент;
|
||
- потом минимальный end-to-end сценарий;
|
||
- потом расширение протоколов;
|
||
- потом polish и demo readiness.
|
||
|
||
## 2. Этап 0. Scaffold проекта
|
||
|
||
Цель:
|
||
|
||
- создать `cargo workspace`;
|
||
- создать приложения и crates;
|
||
- подключить базовый CI/test workflow;
|
||
- зафиксировать структуру каталогов.
|
||
|
||
Состав:
|
||
|
||
- `apps/admin-api`
|
||
- `apps/mcp-server`
|
||
- `apps/ui`
|
||
- `crates/mcpaas-core`
|
||
- `crates/mcpaas-schema`
|
||
- `crates/mcpaas-mapping`
|
||
- `crates/mcpaas-proto`
|
||
- `crates/mcpaas-registry`
|
||
- `crates/mcpaas-runtime`
|
||
- `crates/mcpaas-adapter-rest`
|
||
- `crates/mcpaas-adapter-graphql`
|
||
- `crates/mcpaas-adapter-grpc`
|
||
|
||
Результат:
|
||
|
||
- проект собирается;
|
||
- тестовый pipeline запускается;
|
||
- есть пустые crate boundaries.
|
||
|
||
DoD:
|
||
|
||
- создан `cargo workspace`;
|
||
- все crates и apps объявлены в workspace;
|
||
- проект собирается без бизнес-логики;
|
||
- базовые test targets запускаются;
|
||
- сделан атомарный commit со scaffold.
|
||
|
||
## 3. Этап 1. Базовая доменная модель
|
||
|
||
Цель:
|
||
|
||
- реализовать типы из `data-model`.
|
||
|
||
Фичи:
|
||
|
||
- `Operation`
|
||
- `Target`
|
||
- `Schema`
|
||
- `MappingSet`
|
||
- `ExecutionConfig`
|
||
- `ToolDescription`
|
||
- `AuthProfile`
|
||
|
||
Параллельно:
|
||
|
||
- unit tests на доменные типы;
|
||
- базовая сериализация `JSON`/`YAML`.
|
||
|
||
Результат:
|
||
|
||
- модель данных существует как код;
|
||
- нет инфраструктурных зависимостей внутри домена.
|
||
|
||
DoD:
|
||
|
||
- типы из `data-model` реализованы;
|
||
- базовая сериализация `JSON` и `YAML` проходит тесты;
|
||
- доменные `impl` не содержат инфраструктурной логики;
|
||
- unit tests на ключевые типы проходят;
|
||
- изменения зафиксированы через один или несколько `RGR + commit`.
|
||
|
||
## 4. Этап 2. Schema engine
|
||
|
||
Цель:
|
||
|
||
- реализовать `mcpaas-schema`.
|
||
|
||
Фичи:
|
||
|
||
- model полей и типов;
|
||
- schema validation;
|
||
- field traversal;
|
||
- нормализация JSON samples;
|
||
- protobuf -> schema bridge contracts.
|
||
|
||
Результат:
|
||
|
||
- можно описывать и валидировать вход/выход.
|
||
|
||
DoD:
|
||
|
||
- реализована схема полей и типов;
|
||
- работает schema validation;
|
||
- JSON sample normalization покрыт тестами;
|
||
- контракты protobuf -> schema зафиксированы;
|
||
- нет смешивания schema logic с adapter logic.
|
||
|
||
## 5. Этап 3. Mapping engine
|
||
|
||
Цель:
|
||
|
||
- реализовать `mcpaas-mapping`.
|
||
|
||
Фичи:
|
||
|
||
- `JSONPath` parsing и validation;
|
||
- input mapping;
|
||
- output mapping;
|
||
- transforms;
|
||
- generation draft mapping из samples.
|
||
|
||
Результат:
|
||
|
||
- можно преобразовывать MCP input в request model и response в output model.
|
||
|
||
DoD:
|
||
|
||
- `JSONPath` parsing и validation работают;
|
||
- input/output mapping проходят unit tests;
|
||
- generation draft mapping покрыта фикстурами;
|
||
- transforms ограничены и задокументированы;
|
||
- mapping engine не знает о конкретных protocol adapters.
|
||
|
||
## 6. Этап 4. Registry и БД
|
||
|
||
Цель:
|
||
|
||
- реализовать `mcpaas-registry` и миграции.
|
||
|
||
Фичи:
|
||
|
||
- таблицы из `database-schema`;
|
||
- version snapshots;
|
||
- published operations;
|
||
- auth profiles;
|
||
- sample metadata;
|
||
- descriptor metadata;
|
||
- YAML import job log.
|
||
|
||
Результат:
|
||
|
||
- конфигурации можно хранить и версионировать.
|
||
|
||
DoD:
|
||
|
||
- миграции создают таблицы из `database-schema`;
|
||
- version snapshots работают корректно;
|
||
- publish linkage реализован;
|
||
- auth profiles и artifact metadata сохраняются;
|
||
- integration tests на registry проходят на реальной БД.
|
||
|
||
## 7. Этап 5. REST vertical slice
|
||
|
||
Цель:
|
||
|
||
- получить первый рабочий end-to-end сценарий.
|
||
|
||
Фичи:
|
||
|
||
- `mcpaas-adapter-rest`
|
||
- `mcpaas-runtime` для REST
|
||
- REST test run
|
||
- создание REST operation
|
||
- publish REST operation
|
||
- вызов published REST tool из MCP слоя
|
||
|
||
Результат:
|
||
|
||
- MVP работает хотя бы для REST.
|
||
|
||
DoD:
|
||
|
||
- REST operation можно создать, протестировать и опубликовать;
|
||
- runtime исполняет REST operation end-to-end;
|
||
- published REST tool вызывается через MCP слой;
|
||
- negative tests на mapping и external errors существуют;
|
||
- есть демонстрационный REST сценарий.
|
||
|
||
## 8. Этап 6. Admin API v1
|
||
|
||
Цель:
|
||
|
||
- дать 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 без ручных правок кода.
|
||
|
||
DoD:
|
||
|
||
- доступны CRUD, versioning, publish, samples, draft generation, test runs;
|
||
- доступны auth profiles и YAML import/export;
|
||
- API контракты соответствуют документации;
|
||
- integration tests на ключевые endpoints проходят;
|
||
- нет скрытой бизнес-логики в handlers.
|
||
|
||
## 9. Этап 7. UI v1
|
||
|
||
Цель:
|
||
|
||
- собрать рабочую административную консоль.
|
||
|
||
Фичи:
|
||
|
||
- список операций;
|
||
- мастер создания операции;
|
||
- sample upload;
|
||
- schema viewer;
|
||
- mapping editor;
|
||
- test run screen;
|
||
- publish flow;
|
||
- YAML import/export screen.
|
||
|
||
Результат:
|
||
|
||
- есть демонстрируемый пользовательский интерфейс.
|
||
|
||
DoD:
|
||
|
||
- UI покрывает основной сценарий от создания operation до publish;
|
||
- sample upload и mapping editor работают;
|
||
- YAML import/export доступен из UI;
|
||
- нет блокирующих заглушек на критическом пути демо;
|
||
- основные пользовательские сценарии проверены вручную или integration tests.
|
||
|
||
## 10. Этап 8. MCP server
|
||
|
||
Цель:
|
||
|
||
- публиковать 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
|
||
|
||
Цель:
|
||
|
||
- добавить второй протокол без разрушения архитектуры.
|
||
|
||
Фичи:
|
||
|
||
- `mcpaas-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.
|
||
|
||
Фичи:
|
||
|
||
- `mcpaas-proto`
|
||
- descriptor loading;
|
||
- service/method discovery;
|
||
- protobuf normalization;
|
||
- `mcpaas-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.
|
||
|
||
Такой порядок минимизирует архитектурный риск и дает ранний рабочий результат.
|